@homeflare/alchemy 0.20.0 → 0.22.0

package/src/release/binary-form.ts

@@ -0,0 +1,229 @@
+/**
+ * Release.Binary's props, attributes and validation — the pure half of the provider.
+ *
+ * ★ THE PINNED ARCHIVE IS A PROP, NOT A LOOKUP. Repository, tag, exact asset name, size, the
+ *   archive's SHA-256, the member and the member's SHA-256 all arrive as props — usually spread from
+ *   a vendor data set (victoria.ts) by `catalogBinary()`. So the resource knows no vendor at all: a
+ *   second vendor is a second data module, never a change here, and the resource is the shape
+ *   Alchemy could accept (docs/release-binary-upstream.md).
+ * ⛔ NOTHING ESTATE-SPECIFIC IS A CONSTANT HERE. The install directory, owner, group and mode are
+ *   the consuming stack's props. A stack that keeps binaries under `/opt/<estate>/obs/bin` says so
+ *   in its own code.
+ * ⛔ EVERY PIN IS REQUIRED, AND WELL-FORMED OR REFUSED. There is no "latest", no optional digest and
+ *   no fallback to a checksum file fetched at apply — see victoria.ts for why a pin beats a fetch.
+ */
+import type { HostFileAttributes } from '../launchd/host-file-form.ts';
+import { identityProblems, pathProblems } from '../launchd/host-file-form.ts';
+
+/** One release archive, pinned: where it is published, and the bytes it must be. */
+export interface ReleaseArchive {
+  /** The GitHub repository that publishes it, `owner/name`: `'VictoriaMetrics/VictoriaMetrics'`. */
+  readonly repo: string;
+  /** The release tag, exactly as published: `'v1.151.0'`. */
+  readonly tag: string;
+  /**
+   * The asset's file name, whole: `'vmutils-darwin-arm64-v1.151.0.tar.gz'`. ⛔ Never a prefix or a
+   * pattern — `-enterprise` and `-cluster` siblings share every prefix with it.
+   */
+  readonly asset: string;
+  /** Bytes, per the release API. A download that runs past this is cut off and refused. */
+  readonly size: number;
+  /** The archive's SHA-256, lower-case hex, as the vendor's checksum file lists it. */
+  readonly sha256: string;
+}
+
+export interface ReleaseBinaryProps {
+  /** The pinned archive the binary comes out of. `catalogBinary()` fills it from a data set. */
+  archive: ReleaseArchive;
+  /** The archive member to extract, by its exact name: `'vmalert-prod'`. Nothing else is unpacked. */
+  member: string;
+  /** The member's own SHA-256 — what the installed file must hash to. */
+  sha256: string;
+  /**
+   * The installed file name: `'vmalert'`. ★ Separate from `member` on purpose — VictoriaMetrics
+   * names every member `<binary>-prod`, and a job's argv[0] should not carry that.
+   */
+  name: string;
+  /**
+   * The directory the binary is written into. ⛔ It must already exist — declare it with
+   * `HostDirectory` and pass that resource's `path`, which also orders it first. ★ Give each
+   * version its own directory (`catalogDirectory()`): an upgrade is then a new path — a
+   * create-before-delete replace, never an overwrite under a running daemon — and a rollback is a
+   * path. A new pin at the SAME path is refused (binary-diff.ts).
+   */
+  directory: string;
+  /**
+   * Permission bits. ⛔ Owner-readable and -executable, never group- or world-writable, never
+   * setuid, setgid or sticky — a writable binary is whoever-can-write's code, run as whoever runs
+   * the daemon. Its directory must not be group- or world-writable either (binary-lifecycle.ts).
+   * @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 directory's default group. */
+  group?: string | number;
+}
+
+export interface ReleaseBinaryAttributes extends HostFileAttributes {
+  /** The archive the bytes came from, whole. */
+  url: string;
+  /** The archive member installed, by its exact name: `vmalert-prod`. */
+  member: string;
+}
+
+/** Everything a download and its two checks need: one archive, one member, both digests. */
+export type PinnedDownload = {
+  readonly url: string;
+  readonly size: number;
+  /** The archive's pinned SHA-256. */
+  readonly sha256: string;
+  /** The archive member to extract, by exact name. */
+  readonly member: string;
+  /** The member's pinned SHA-256. */
+  readonly memberSha256: string;
+};
+
+export const DEFAULT_BINARY_MODE = 0o755;
+
+/**
+ * The release-asset URL. ★ GITHUB'S DOWNLOAD PATH, NOT THE API: it needs no token and spends no rate
+ *   limit (it redirects to a signed CDN URL — measured 2026-09-22 with HEAD). Every consumer the
+ *   estate census found publishes on GitHub except Grafana (grafana.com), which is not a
+ *   single-binary consumer anyway (docs/release-binary-catalogs.md). A second source kind arrives
+ *   with its first consumer, not before.
+ */
+export const releaseUrl = (repo: string, tag: string, asset: string): string =>
+  `https://github.com/${repo}/releases/download/${tag}/${asset}`;
+
+/** Where a declaration puts its binary: `<directory>/<name>`. */
+export const releaseBinaryPath = (props: {
+  readonly directory: string;
+  readonly name: string;
+}): string => `${props.directory}/${props.name}`;
+
+/** The download a declaration means. ⚠️ Validate first (binaryProblems): this trusts its input. */
+export const pinnedDownload = (props: ReleaseBinaryProps): PinnedDownload => ({
+  member: props.member,
+  memberSha256: props.sha256,
+  sha256: props.archive.sha256,
+  size: props.archive.size,
+  url: releaseUrl(props.archive.repo, props.archive.tag, props.archive.asset),
+});
+
+export const modeProblems = (mode: number): string[] => {
+  if (!Number.isSafeInteger(mode) || mode < 0 || mode > 0o7777) return ['mode must be 0–0o7777'];
+  const found: string[] = [];
+  if ((mode & 0o7000) !== 0) found.push('mode must not set setuid, setgid or sticky');
+  if ((mode & 0o022) !== 0) found.push('mode must not be group- or world-writable');
+  if ((mode & 0o100) === 0) found.push('mode must let the owner execute it');
+  // ⛔ AND READ IT: every plan re-hashes the binary, and a write is read back. MEASURED 2026-09-22,
+  //   an execute-only 0111 written by a non-root operator failed its read-back with EACCES.
+  if ((mode & 0o400) === 0) found.push('mode must let the owner read it (it is re-hashed)');
+  return found;
+};
+
+const HEX64 = /^[0-9a-f]{64}$/;
+export const MAX_ARCHIVE = 1 << 30;
+// ⛔ Strict on purpose: each is written into a URL or a path. GitHub's own owner and name alphabet.
+const REPO = /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?\/[A-Za-z0-9._-]+$/;
+const SEGMENT = /^[A-Za-z0-9._-]+$/;
+// ★ ONLY WHAT THE READER HANDLES: a gzipped tar. A `.zip` or a bare binary is a new capability
+//   with its own walk-down, not a name this should accept and then fail to unpack.
+const TARBALL = /\.(tar\.gz|tgz)$/;
+
+/** A single path segment that cannot climb, hide or name the directory itself. */
+const segmentProblem = (what: string, value: string): string | undefined =>
+  !SEGMENT.test(value) || value === '.' || value === '..'
+    ? `${what} must be one path segment of letters, digits, '.', '_' or '-': ${JSON.stringify(value)}`
+    : undefined;
+
+/** Everything wrong with the pins alone — plain strings in any declaration, resolved or not. */
+export const pinProblems = (props: {
+  readonly archive?: Partial<ReleaseArchive>;
+  readonly member?: unknown;
+  readonly sha256?: unknown;
+  readonly name?: unknown;
+}): string[] => {
+  const archive = props.archive ?? {};
+  const found: string[] = [];
+  const text = (what: string, value: unknown): string | undefined => {
+    if (typeof value === 'string') return value;
+    found.push(`${what} is required, as a plain string`);
+    return undefined;
+  };
+  const repo = text('archive.repo', archive.repo);
+  // ⚠️ `owner/..` passes the alphabet, and a URL parser normalises it away: the request would go
+  //   to `github.com/releases/…`, somewhere nobody pinned. Refused by name.
+  const repoName = repo?.slice(repo.indexOf('/') + 1);
+  if (repo !== undefined && (!REPO.test(repo) || repoName === '.' || repoName === '..'))
+    found.push(`archive.repo must be "owner/name": ${JSON.stringify(repo)}`);
+  for (const [what, value] of [
+    ['archive.tag', archive.tag],
+    ['name', props.name],
+  ] as const) {
+    const given = text(what, value);
+    const problem = given === undefined ? undefined : segmentProblem(what, given);
+    if (problem !== undefined) found.push(problem);
+  }
+  const asset = text('archive.asset', archive.asset);
+  if (asset !== undefined) {
+    const problem = segmentProblem('archive.asset', asset);
+    if (problem !== undefined) found.push(problem);
+    else if (!TARBALL.test(asset))
+      found.push(`archive.asset must be a .tar.gz or .tgz: "${asset}"`);
+  }
+  // ⛔ THE SIZE IS ALLOCATED UP FRONT (download.ts fills one buffer of exactly this many bytes), so
+  //   a typo'd size is a memory bomb in the deploying process. vmutils, the largest archive pinned,
+  //   is 123.6 MB; a gibibyte is a ceiling nothing single-binary should reach.
+  const size = archive.size;
+  if (typeof size !== 'number' || !Number.isSafeInteger(size) || size <= 0 || size > MAX_ARCHIVE) {
+    found.push(`archive.size must be the asset's byte count, 1 to ${String(MAX_ARCHIVE)}`);
+  }
+  for (const [what, value] of [
+    ['archive.sha256', archive.sha256],
+    ['sha256', props.sha256],
+  ] as const) {
+    const given = text(what, value);
+    if (given !== undefined && !HEX64.test(given))
+      found.push(`${what} must be 64 lower-case hex digits`);
+  }
+  const member = text('member', props.member);
+  // ⛔ The tar reader refuses these entries anyway; asking for one is a mistake to name at plan.
+  if (
+    member !== undefined &&
+    (member === '' || member.startsWith('/') || member.split('/').includes('..'))
+  ) {
+    found.push(`member must be a relative name inside the archive: ${JSON.stringify(member)}`);
+  }
+  return found;
+};
+
+const ARCHIVE_KEYS = ['repo', 'tag', 'asset', 'size', 'sha256'] as const;
+
+type Pins = Pick<ReleaseBinaryProps, 'archive' | 'member' | 'sha256'>;
+
+/** Whether two declarations pin different bytes: another archive, member or member digest. */
+export const pinsMoved = (olds: Pins, news: Pins): boolean =>
+  olds.member !== news.member ||
+  olds.sha256 !== news.sha256 ||
+  ARCHIVE_KEYS.some((key) => olds.archive[key] !== news.archive[key]);
+
+/**
+ * ⛔ A NEW PIN IS A NEW PATH. The same path with other bytes would overwrite a binary under the
+ *   daemon running it, and leave no rollback but a re-download — so it is refused, at plan when the
+ *   path is resolved (binary-diff.ts) and at apply otherwise (binary-lifecycle.ts).
+ */
+export const inPlaceRefusal = (olds: Pins, news: Pins): string =>
+  `a new pin (${news.archive.tag} ${news.member} ${news.sha256}) at the path of the installed ` +
+  `one (${olds.archive.tag} ${olds.member} ${olds.sha256}) would overwrite it in place; give each ` +
+  'version its own directory (catalogDirectory), so an upgrade is a new path';
+
+/** Everything wrong with a declaration, before any host or network is asked anything. */
+export const binaryProblems = (props: ReleaseBinaryProps): string[] => [
+  ...pinProblems(props),
+  ...pathProblems(props.directory).map((problem) => `directory: ${problem}`),
+  ...modeProblems(props.mode ?? DEFAULT_BINARY_MODE),
+  ...identityProblems('owner', props.owner),
+  ...identityProblems('group', props.group),
+];

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

@@ -0,0 +1,90 @@
+/**
+ * The install lifecycle over a fake host (launchd/fake-runner.ts) and a fake transport — no network,
+ * no real filesystem: what an install writes, what a matching host costs (nothing), and read and
+ * delete. Every refusal: binary-refusals.test.ts.
+ */
+import { describe, expect, test } from 'bun:test';
+import { sha256Hex } from '../launchd/job-form.ts';
+import { deleteBinary, readBinary } from './binary-lifecycle.ts';
+import { PATH, setup, writes } from './fake-install.ts';
+import { BINARY, ENTERPRISE_URL, VMUTILS_URL, bytesOf, pathsOn } from './fake-release.ts';
+
+describe('installing', () => {
+  test('the declared member, from the plain archive only, verified, at <directory>/<name>', async () => {
+    const s = setup();
+    const notes: string[] = [];
+    const attrs = await s.install(s.props(), { note: async (m: string) => void notes.push(m) });
+    // ⛔ The enterprise sibling was served too, under its real name; it was never asked for.
+    expect(s.transport.requests).toEqual([VMUTILS_URL]);
+    expect(s.transport.requests).not.toContain(ENTERPRISE_URL);
+    expect(s.fake.files.get(PATH)?.bytes).toEqual(BINARY.vmalert);
+    expect(attrs).toMatchObject({
+      member: 'vmalert-prod',
+      mode: 0o755,
+      path: PATH,
+      url: VMUTILS_URL,
+    });
+    expect(attrs.sha256).toBe(sha256Hex(BINARY.vmalert));
+    expect(notes[0]).toContain('downloading');
+  });
+
+  test('⛔ an undeclared member is never written: vmagent-prod and vmauth-prod stay in the archive', async () => {
+    const s = setup();
+    await s.install();
+    expect(pathsOn(s.fake)).toEqual([PATH]);
+    expect(writes(s.fake).map((c) => c[1])).toEqual([PATH]);
+  });
+
+  test('already installed and matching: no download, no write', async () => {
+    const s = setup();
+    const output = await s.install();
+    s.transport.requests.length = 0;
+    s.fake.calls.length = 0;
+    await s.install(s.props(), { olds: s.props(), output });
+    expect([s.transport.requests, writes(s.fake)]).toEqual([[], []]);
+  });
+
+  test('the right bytes with the wrong mode: re-written from disk, not downloaded', async () => {
+    const s = setup();
+    const output = await s.install();
+    s.transport.requests.length = 0;
+    const fixed = await s.install(s.props({ mode: 0o555 }), { olds: s.props(), output });
+    expect(fixed.mode).toBe(0o555);
+    expect(s.transport.requests).toEqual([]);
+  });
+
+  // ⚠️ Only under --adopt (binary-claim.ts); without it, binary-refusals.test.ts refuses the same file.
+  test('unprobed, the pinned bytes at the path, under --adopt: kept, not fetched', async () => {
+    const s = setup();
+    s.fake.files.set(PATH, { bytes: BINARY.vmalert, gid: 0, kind: 'file', mode: 0o755, uid: 0 });
+    expect((await s.install(s.props(), { adopt: true })).sha256).toBe(sha256Hex(BINARY.vmalert));
+    expect([s.transport.requests, writes(s.fake)]).toEqual([[], []]);
+  });
+
+  test('a new version is a new path: written, then the old one removed', async () => {
+    const s = setup();
+    const old = { ...(await s.install()), path: '/opt/example/bin/vmutils-1.150.0/vmalert' };
+    s.fake.files.set(old.path, {
+      bytes: bytesOf('old'),
+      gid: 0,
+      kind: 'file',
+      mode: 0o755,
+      uid: 0,
+    });
+    await s.install(s.props(), { output: old });
+    expect(s.fake.files.has(old.path)).toBe(false);
+    expect(s.fake.files.has(PATH)).toBe(true);
+  });
+});
+
+describe('read and delete', () => {
+  test('read reports the file at the path by its digest; delete removes it, twice', async () => {
+    const s = setup();
+    expect(await readBinary(s.fake.runner, s.props())).toBeUndefined();
+    const output = await s.install();
+    expect((await readBinary(s.fake.runner, s.props()))?.sha256).toBe(output.sha256);
+    await deleteBinary(s.fake.runner, output);
+    await deleteBinary(s.fake.runner, output);
+    expect(s.fake.files.has(PATH)).toBe(false);
+  });
+});

package/src/release/binary-lifecycle.ts

@@ -0,0 +1,202 @@
+/**
+ * Release.Binary's read / reconcile / delete as plain async functions over a HostRunner and a
+ * FetchArchive, so the lifecycle runs against fakes of both in tests. (diff: binary-diff.ts.)
+ *
+ * ⛔ ONE WRITER. The verified bytes reach the host through file-converge.ts — the path Host.File's
+ *   bytes take — and so through `HostRunner.writeFileAtomic` alone: a temp file in the same
+ *   directory, mode and owner set, rename. Under sudoRunner that is its staged `install -S`.
+ *   Nothing here opens a file, spawns `tar`, or stages a download on disk.
+ * ★ REFUSE BEFORE TOUCHING ANYTHING. Validation runs before the first host call, the host checks
+ *   run before the first download, and the digest checks run before the one write — so every
+ *   refusal but a failed read-back can say "Nothing was written."
+ * ★ AN INSTALLED BINARY IS RECOGNISED BY ITS DIGEST. A file whose SHA-256 is the pin needs no
+ *   download to confirm, and a mode or owner fix re-writes the bytes already on disk.
+ */
+import {
+  type FileTarget,
+  convergeFile,
+  readFileAttributes,
+  removeWholeFile,
+  resolveIds,
+} from '../launchd/file-converge.ts';
+import type { HostFileAttributes } from '../launchd/host-file-form.ts';
+import { sha256Hex } from '../launchd/job-form.ts';
+import type { HostRunner } from '../launchd/runner.ts';
+import { verifiedMember } from './archive.ts';
+import { claimProblem } from './binary-claim.ts';
+import {
+  DEFAULT_BINARY_MODE,
+  type PinnedDownload,
+  type ReleaseBinaryAttributes,
+  type ReleaseBinaryProps,
+  binaryProblems,
+  inPlaceRefusal,
+  pinnedDownload,
+  pinsMoved,
+  releaseBinaryPath,
+} from './binary-form.ts';
+import type { FetchArchive } from './download.ts';
+import { ArchiveRefused, BinaryRefused, ChecksumMismatch, DownloadFailed } from './refused.ts';
+
+export const NOTHING = 'Nothing was written.';
+
+export const refuse = (path: string, message: string): BinaryRefused =>
+  new BinaryRefused({ message: `Release.Binary ${path}: ${message}` });
+
+/** Re-say a download or archive failure as this resource's, keeping its tag. */
+const restated = (path: string, cause: unknown): unknown => {
+  const say = (message: string) => `Release.Binary ${path}: ${message}. ${NOTHING}`;
+  if (cause instanceof ChecksumMismatch) {
+    const { actual, expected, subject } = cause;
+    return new ChecksumMismatch({ actual, expected, message: say(cause.message), subject });
+  }
+  if (cause instanceof ArchiveRefused) return new ArchiveRefused({ message: say(cause.message) });
+  if (cause instanceof DownloadFailed) {
+    return new DownloadFailed({ message: say(cause.message), retryable: cause.retryable });
+  }
+  return cause;
+};
+
+export type Desired = { readonly want: FileTarget; readonly download: PinnedDownload };
+
+/** Validate every prop, then resolve owner and group through the runner. */
+export const desiredBinary = async (
+  runner: HostRunner,
+  props: ReleaseBinaryProps,
+): Promise<Desired> => {
+  const path = releaseBinaryPath(props);
+  const problems = binaryProblems(props);
+  if (problems.length > 0) throw refuse(path, `${problems.join('; ')}. ${NOTHING}`);
+  const ids = await resolveIds(runner, props, path, refuse);
+  const mode = props.mode ?? DEFAULT_BINARY_MODE;
+  return { download: pinnedDownload(props), want: { mode, path, sha256: props.sha256, ...ids } };
+};
+
+const withSource = (
+  found: HostFileAttributes,
+  download: PinnedDownload,
+): ReleaseBinaryAttributes => ({ ...found, member: download.member, url: download.url });
+
+/**
+ * The file at the declaration's path, or undefined when absent — the adoption probe's answer.
+ * ★ Its `sha256` is the digest of the bytes on disk, so a caller sees at once whether it is the
+ *   pinned binary (equal to `props.sha256`) without anything being executed.
+ */
+export const readBinary = async (
+  runner: HostRunner,
+  props: ReleaseBinaryProps,
+): Promise<ReleaseBinaryAttributes | undefined> => {
+  const { download, want } = await desiredBinary(runner, props);
+  const found = await readFileAttributes(runner, want.path);
+  return found === undefined ? undefined : withSource(found, download);
+};
+
+/** An owned binary as it is now, at the path state recorded — no pins needed to find it. */
+export const refreshBinary = async (
+  runner: HostRunner,
+  output: ReleaseBinaryAttributes,
+): Promise<ReleaseBinaryAttributes | undefined> => {
+  const found = await readFileAttributes(runner, output.path);
+  return found === undefined ? undefined : { ...found, member: output.member, url: output.url };
+};
+
+/**
+ * ⛔ THE DIRECTORY IS DECLARED, NEVER INVENTED. Checked before any download: a missing directory
+ *   would otherwise cost 123 MB and then fail at the write. A symlink is refused as well — the
+ *   write would land wherever it points, under an owner nobody declared.
+ */
+const directoryReady = async (runner: HostRunner, props: ReleaseBinaryProps): Promise<void> => {
+  const stat = await runner.stat(props.directory);
+  /**
+   * ⛔ AND ONE ONLY ITS OWNER MAY WRITE. The mode rule (binary-form.ts modeProblems) refuses a
+   *   group- or world-writable binary because its writers could change the code a daemon runs. A
+   *   directory they may write gives them the same power by another call: rename(2) their own file
+   *   over the binary, and the next launchd start runs theirs. The sticky bit is no excuse — a
+   *   binary directory has no business being shared.
+   */
+  if (stat?.kind === 'directory' && (stat.mode & 0o022) !== 0) {
+    throw refuse(
+      releaseBinaryPath(props),
+      `directory ${props.directory} is writable by group or other (mode ` +
+        `${stat.mode.toString(8).padStart(4, '0')}), so whoever may write it may replace the ` +
+        `binary; declare it 0755 or narrower. ${NOTHING}`,
+    );
+  }
+  if (stat?.kind === 'directory') return;
+  const why = stat === undefined ? 'does not exist' : `is a ${stat.kind}, not a directory`;
+  throw refuse(
+    releaseBinaryPath(props),
+    `directory ${props.directory} ${why}; declare it (HostDirectory) and pass its path. ${NOTHING}`,
+  );
+};
+
+export type ReconcileOptions = {
+  /** The attributes state holds; undefined on a create. */
+  readonly output?: ReleaseBinaryAttributes | undefined;
+  /** The props state holds; undefined on a create and on an adoption. */
+  readonly olds?: ReleaseBinaryProps | undefined;
+  /** adoptsAtApply's answer. What it may take over is convergeFile's ⛔. @default false */
+  readonly adopt?: boolean;
+  /** Progress for the deploy log — the engine's `session.note`. */
+  readonly note?: (message: string) => Promise<void>;
+  /**
+   * What is wrong with the pins as the stack program DECLARED them (declared-pins.ts) — an Output
+   * there resolves to a plausible plain string by the time it reaches `props`. @default []
+   */
+  readonly declared?: readonly string[];
+};
+
+/** Install the declared binary unless it is already there, and return it as read back. */
+export const reconcileBinary = async (
+  runner: HostRunner,
+  fetch: FetchArchive,
+  props: ReleaseBinaryProps,
+  options: ReconcileOptions = {},
+): Promise<ReleaseBinaryAttributes> => {
+  const { adopt = false, declared = [], note = async () => undefined } = options;
+  // ⛔ FIRST, before any host call: a digest the deploy computed is a fetch by another name.
+  if (declared.length > 0) {
+    throw refuse(
+      releaseBinaryPath(props),
+      `${declared.join('; ')}. A pin is copied into reviewed code, never computed during the ` +
+        `deploy (declared-pins.ts). ${NOTHING}`,
+    );
+  }
+  const { download, want } = await desiredBinary(runner, props);
+  // ⛔ The apply-time half of binary-diff.ts's in-place refusal, for an update whose `olds` say so.
+  const olds = options.olds;
+  if (olds !== undefined && releaseBinaryPath(olds) === want.path && pinsMoved(olds, props)) {
+    throw refuse(want.path, `${inPlaceRefusal(olds, props)}. ${NOTHING}`);
+  }
+  await directoryReady(runner, props);
+  // ⛔ WITH NO STATE, ONLY THE PINNED BINARY UNDER --adopt (binary-claim.ts).
+  // ⚠️ NOT an update across a move (`output` at another path): --adopt can never speak for one, so
+  //   refusing identical bytes there would strand the resume of our own interrupted move with no
+  //   remedy but a hand removal. Other bytes there stay refused (file-converge.ts).
+  if (options.output === undefined) {
+    const problem = await claimProblem(runner, want, adopt);
+    if (problem !== undefined) throw refuse(want.path, `${problem}. ${NOTHING}`);
+  }
+  const bytesFor = async (before: HostFileAttributes | undefined): Promise<Uint8Array> => {
+    // ★ The right bytes with the wrong mode or owner: re-write what is there, re-hashed, rather
+    //   than download 123 MB to get the same bytes back.
+    if (before?.sha256 === want.sha256) {
+      const local = await runner.readFile(want.path);
+      if (local !== undefined && sha256Hex(local) === want.sha256) return local;
+    }
+    await note(`downloading ${download.url} (${String(download.size)} bytes)`);
+    try {
+      const bytes = await verifiedMember(await fetch(download.url, download.size), download);
+      await note(`verified ${download.member} ${download.memberSha256}`);
+      return bytes;
+    } catch (cause) {
+      throw restated(want.path, cause);
+    }
+  };
+  const spec = { bytesFor, owner: props.owner, refuse, want };
+  return withSource(await convergeFile(runner, spec, options.output, adopt), download);
+};
+
+/** Remove the binary. Idempotent. ⛔ Refuses a path that has since become a symlink or directory. */
+export const deleteBinary = (runner: HostRunner, output: ReleaseBinaryAttributes): Promise<void> =>
+  removeWholeFile(runner, output, refuse);

package/src/release/binary-read.ts

@@ -0,0 +1,55 @@
+/**
+ * Release.Binary's `read` with no attributes. Alchemy asks it twice over (ownership/probe.ts): as
+ * the ADOPTION PROBE (no row; `olds` is the declaration, `instanceId` fresh) and as the RECOVERY
+ * READ of a row whose create never recorded attributes (`olds` and `instanceId` are the row's —
+ * Plan.ts for a `creating` row, Apply.ts for such a row it must delete).
+ *
+ * ⛔ THE PROBE VALIDATES; THE RECOVERY READ NEVER FAILS ITS CALLER. The probe's `olds` is today's
+ *   declaration, so a malformed prop fails the plan there, before anything is touched. The recovery
+ *   read's `olds` is the FAILED deploy's props, and with `directory: dir.path` — the documented
+ *   usage — a first deploy commits its `creating` row while the directory is still an Output, so
+ *   the row has no `directory` at all. 🔴 MEASURED 2026-09-22 (adopt-parity.test.ts): after ANY
+ *   failed first install — a 404, a checksum mismatch, a mode refused at apply — every later plan
+ *   died with `TypeError: undefined is not an object (evaluating 'path.startsWith')`, the fixed
+ *   declaration included, and removing the declaration failed too (DestroyError: the orphan's
+ *   recovery read crashed the same way). The stage was bricked until a hand `alchemy state delete`.
+ *   ownership/probe.ts states the rule this broke: the recovery read "NEVER FAILS THE CALLER".
+ * ★ "NOTHING RECOVERED" IS THE SAFE ANSWER, NOT `Unowned`. The plan then re-drives the create, and
+ *   reconcile looks at the path itself with every prop resolved: a file there is refused unless
+ *   `--adopt` (binary-claim.ts), exactly as ownership.md says a create interrupted while a prop was
+ *   an Output resumes. An orphan's row is dropped and its path left alone — a leak at worst, never
+ *   a delete of something unproven.
+ * ★ THE ROW, NOT THE SHAPE OF `olds`, SAYS WHICH READ THIS IS: a probe's instance id is minted for
+ *   the probe, so no row holds it (ownership/rows.ts). Without a Stack or State in context a row
+ *   reads as absent, and this validates as the probe does — the behaviour before this file.
+ */
+import { Unowned } from 'alchemy/AdoptPolicy';
+import * as Effect from 'effect/Effect';
+import { lift } from '../launchd/host-effect.ts';
+import type { HostRunner } from '../launchd/runner.ts';
+import { recordedGeneration } from '../ownership/rows.ts';
+import type { ReleaseBinaryProps } from './binary-form.ts';
+import { readBinary } from './binary-lifecycle.ts';
+
+type Ask = { readonly fqn: string; readonly instanceId: string; readonly olds: unknown };
+
+/** The file a declaration (or a row) names, as `Unowned` — or undefined when there is none. */
+export const readWithoutState = (runner: HostRunner, ask: Ask) =>
+  Effect.gen(function* () {
+    const recovering = (yield* recordedGeneration(ask.fqn, ask.instanceId)) !== undefined;
+    const read = lift(() => readBinary(runner, ask.olds as ReleaseBinaryProps));
+    const found = recovering
+      ? yield* read.pipe(
+          Effect.catch((cause) =>
+            Effect.as(
+              Effect.logWarning(
+                `${ask.fqn}: the interrupted create's row cannot locate its binary (${cause.message}); ` +
+                  'nothing is recovered, and the create is re-driven with the declaration as it is now',
+              ),
+              undefined,
+            ),
+          ),
+        )
+      : yield* read;
+    return found === undefined ? undefined : Unowned(found);
+  });