@homeflare/alchemy 0.20.0 → 0.21.0

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);
+  });

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

@@ -0,0 +1,192 @@
+/**
+ * Every refusal of the install lifecycle, each asserted by what it LEFT (fake-install.ts): the
+ * transport's request log, the host's write log, and the host's paths before and after.
+ */
+import { describe, expect, test } from 'bun:test';
+import { sha256Hex } from '../launchd/job-form.ts';
+import type { ReleaseBinaryProps } from './binary-form.ts';
+import { reconcileBinary } from './binary-lifecycle.ts';
+import {
+  BINARY,
+  VMUTILS_DIR,
+  VMUTILS_ENTRIES,
+  VMUTILS_URL,
+  bytesOf,
+  fakeTransport,
+  gzip,
+  pathsOn,
+  tarOf,
+} from './fake-release.ts';
+import { PATH, refused, setup } from './fake-install.ts';
+import { ArchiveRefused, BinaryRefused, ChecksumMismatch, DownloadFailed } from './refused.ts';
+
+describe('refusals leave the host exactly as it was', () => {
+  test('a wrong archive hash', async () => {
+    const s = setup();
+    const tampered = gzip(tarOf(VMUTILS_ENTRIES.map((e) => ({ ...e, bytes: bytesOf('evil') }))));
+    const transport = fakeTransport({ [VMUTILS_URL]: tampered });
+    const error = await refused(s, () =>
+      reconcileBinary(s.fake.runner, transport.fetch, s.props()),
+    );
+    expect(error).toBeInstanceOf(ChecksumMismatch);
+    expect(error.message).toContain(`Release.Binary ${PATH}: ${VMUTILS_URL} hashes to`);
+    expect(error.message).toContain('Nothing was written.');
+  });
+
+  test('the right archive with a wrong binary pin', async () => {
+    const s = setup();
+    const error = await refused(s, () => s.install(s.props({ sha256: 'f'.repeat(64) })));
+    expect(error).toBeInstanceOf(ChecksumMismatch);
+    expect(error.message).toContain(`member "vmalert-prod" hashes to ${sha256Hex(BINARY.vmalert)}`);
+  });
+
+  test('a tar-slip entry beside the declared member, in a correctly pinned archive', async () => {
+    const s = setup([
+      ...VMUTILS_ENTRIES,
+      { bytes: bytesOf('pwn'), name: '../../../etc/sudoers.d/x' },
+    ]);
+    const error = await refused(s, () => s.install());
+    expect(error).toBeInstanceOf(ArchiveRefused);
+    expect(error.message).toContain('climbs out');
+  });
+
+  test('the declared member as a symlink', async () => {
+    const s = setup([{ name: 'vmalert-prod', type: '2' }]);
+    expect(await refused(s, () => s.install())).toBeInstanceOf(ArchiveRefused);
+  });
+
+  test('the declared member missing from a correctly pinned archive', async () => {
+    const s = setup([{ bytes: BINARY.vmagent, name: 'vmagent-prod' }]);
+    const error = await refused(s, () => s.install());
+    expect(error.message).toContain(
+      'no member named exactly "vmalert-prod" (it has "vmagent-prod")',
+    );
+  });
+
+  test('a failed download', async () => {
+    const s = setup();
+    const error = await refused(s, () =>
+      reconcileBinary(s.fake.runner, fakeTransport({}).fetch, s.props()),
+    );
+    expect(error).toBeInstanceOf(DownloadFailed);
+    expect(error.message).toContain(`Release.Binary ${PATH}:`);
+  });
+
+  const archive = (more: object) => (p: ReleaseBinaryProps) => ({
+    archive: { ...p.archive, ...more },
+  });
+  test.each([
+    ['an archive digest that is not hex', archive({ sha256: 'abc' })],
+    ['an asset given as a glob', archive({ asset: 'vmutils-darwin-arm64-*.tar.gz' })],
+    ['an asset that is not a tarball', archive({ asset: 'vmutils-darwin-arm64-v1.151.0.zip' })],
+    ['a repo that climbs', archive({ repo: '../VictoriaMetrics' })],
+    ['a tag with a slash', archive({ tag: 'v1.151.0/../x' })],
+    ['no size', archive({ size: 0 })],
+    ['a size past the one-gibibyte ceiling', archive({ size: 2 ** 30 + 1 })],
+    ['a repo named ..', archive({ repo: 'VictoriaMetrics/..' })],
+    ['an upper-case member digest', () => ({ sha256: 'A'.repeat(64) })],
+    ['an absolute member', () => ({ member: '/vmalert-prod' })],
+    ['a member that climbs', () => ({ member: '../vmalert-prod' })],
+    ['a name with a slash', () => ({ name: 'bin/vmalert' })],
+    ['a relative directory', () => ({ directory: 'bin/vmutils-1.151.0' })],
+    ['a setuid mode', () => ({ mode: 0o4755 })],
+    ['a group-writable mode', () => ({ mode: 0o775 })],
+    // Measured 2026-09-22 before the fix: written, then EACCES on the read-back, left with no state.
+    ['an execute-only mode its owner cannot re-hash', () => ({ mode: 0o111 })],
+  ])('%s: refused before any host call or download', async (_, change) => {
+    const s = setup();
+    s.fake.calls.length = 0;
+    const base = s.props();
+    const error = await refused(s, () =>
+      s.install({ ...base, ...change(base) } as ReleaseBinaryProps),
+    );
+    expect(error).toBeInstanceOf(BinaryRefused);
+    expect(s.transport.requests).toEqual([]);
+    expect(s.fake.calls).toEqual([]);
+  });
+
+  test('a new pin at the same path: refused, the installed binary untouched', async () => {
+    const s = setup();
+    const olds = s.props();
+    const output = await s.install(olds);
+    s.transport.requests.length = 0;
+    s.fake.calls.length = 0;
+    const bumped = s.props({
+      archive: { ...olds.archive, tag: 'v1.152.0' },
+      sha256: 'e'.repeat(64),
+    });
+    const error = await refused(s, () => s.install(bumped, { olds, output }));
+    expect(error.message).toContain('would overwrite it in place');
+    expect(s.transport.requests).toEqual([]);
+    expect(s.fake.files.get(PATH)?.bytes).toEqual(BINARY.vmalert);
+  });
+
+  test('a missing directory: refused before the download', async () => {
+    const s = setup();
+    s.fake.dirs.delete(VMUTILS_DIR);
+    const error = await refused(s, () => s.install());
+    expect(error.message).toContain(`directory ${VMUTILS_DIR} does not exist`);
+    expect(s.transport.requests).toEqual([]);
+  });
+
+  test('⛔ a directory others may write: refused before the download', async () => {
+    const s = setup();
+    const stat = s.fake.runner.stat;
+    s.fake.runner.stat = async (path) => {
+      const found = await stat(path);
+      return path === VMUTILS_DIR && found !== undefined ? { ...found, mode: 0o777 } : found;
+    };
+    const error = await refused(s, () => s.install());
+    expect(error.message).toContain('is writable by group or other (mode 0777)');
+    expect(s.transport.requests).toEqual([]);
+  });
+
+  test('a file this resource does not own, without --adopt: refused before the download', async () => {
+    const s = setup();
+    s.fake.files.set(PATH, { bytes: bytesOf('theirs'), gid: 0, kind: 'file', mode: 0o755, uid: 0 });
+    const error = await refused(s, () => s.install());
+    expect(error.message).toContain('already exists and is not this resource');
+    expect(s.transport.requests).toEqual([]);
+  });
+
+  // ⛔ binary-claim.ts: with no state, only the pinned binary, and only under --adopt.
+  test('the pinned bytes at the path with no state, without --adopt: refused, not claimed', async () => {
+    const s = setup();
+    s.fake.files.set(PATH, { bytes: BINARY.vmalert, gid: 0, kind: 'file', mode: 0o755, uid: 0 });
+    const error = await refused(s, () => s.install());
+    expect(error.message).toContain('it holds the pinned binary, but this stack holds no state');
+    expect(s.transport.requests).toEqual([]);
+  });
+
+  test('other bytes at the path under --adopt: refused before the download, their file kept', async () => {
+    const s = setup();
+    const theirs = bytesOf('theirs');
+    s.fake.files.set(PATH, { bytes: theirs, gid: 0, kind: 'file', mode: 0o755, uid: 0 });
+    const error = await refused(s, () => s.install(s.props(), { adopt: true }));
+    expect(error.message).toContain(`a file hashing to ${sha256Hex(theirs)} is there`);
+    expect(s.transport.requests).toEqual([]);
+    expect(s.fake.files.get(PATH)?.bytes).toEqual(theirs);
+  });
+
+  test('a write that does not read back as declared: the create is rolled back', async () => {
+    const s = setup();
+    const write = s.fake.runner.writeFileAtomic;
+    s.fake.runner.writeFileAtomic = (path, bytes, options) =>
+      write(path, bytes, { ...options, mode: 0o700 });
+    const before = pathsOn(s.fake);
+    await expect(s.install()).rejects.toThrow('does not match the declaration');
+    expect(pathsOn(s.fake)).toEqual(before);
+  });
+
+  test('⛔ a read-back that THROWS rolls the create back too, as a refusal', async () => {
+    const s = setup();
+    const read = s.fake.runner.readFile;
+    s.fake.runner.readFile = async (path) => {
+      if (s.fake.files.has(path)) throw Object.assign(new Error('EACCES'), { code: 'EACCES' });
+      return read(path);
+    };
+    const before = pathsOn(s.fake);
+    await expect(s.install()).rejects.toThrow(`Release.Binary ${PATH}: the write returned but`);
+    expect(pathsOn(s.fake)).toEqual(before);
+  });
+});

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

@@ -0,0 +1,93 @@
+/**
+ * The install through the kit's REAL sudoRunner over its fake host (launchd/fake-sudo.ts), so what
+ * is asserted is the runner's own staging, not a fake's: the verified bytes reach root's directory
+ * as one `install -S` of one staged file, and no failure — before the write or during it — leaves a
+ * staged file behind.
+ *
+ * ★ WHY THIS IS THE STAGING TEST. Release.Binary stages nothing itself: the archive and the member
+ *   live in memory (archive.ts). The only staged file in an install is the runner's — local-runner's
+ *   same-directory temp file (local-runner.test.ts: "leaves no temp file behind") or, here,
+ *   sudoRunner's 0600 file in a 0700 directory.
+ */
+import { describe, expect, test } from 'bun:test';
+import { fakeSudoHost } from '../launchd/fake-sudo.ts';
+import { INSTALL } from '../launchd/sudo-allowlist.ts';
+import type { ReleaseBinaryProps } from './binary-form.ts';
+import { reconcileBinary } from './binary-lifecycle.ts';
+import {
+  BINARY,
+  type TarEntry,
+  VMUTILS_ENTRIES,
+  VMUTILS_URL,
+  bytesOf,
+  fakeTransport,
+  gzip,
+  syntheticRelease,
+  tarOf,
+  vmalertProps,
+} from './fake-release.ts';
+
+const DIR = '/opt/example/app/vmutils-1.151.0';
+const PATH = `${DIR}/vmalert`;
+
+type Setup = {
+  /** What the transport serves at the vmutils URL; undefined serves nothing (a 404). */
+  readonly served?: (release: ReturnType<typeof syntheticRelease>) => Uint8Array | undefined;
+  readonly entries?: readonly TarEntry[];
+  readonly declare?: Partial<ReleaseBinaryProps>;
+};
+
+const setup = ({ declare = {}, entries, served = (r) => r.vmutils }: Setup = {}) => {
+  const release = syntheticRelease(entries);
+  const host = fakeSudoHost();
+  host.fake.dirs.set(DIR, 0);
+  const bytes = served(release);
+  const transport = fakeTransport(bytes === undefined ? {} : { [VMUTILS_URL]: bytes });
+  const props = vmalertProps(release.catalog, { directory: DIR, group: 0, owner: 0, ...declare });
+  const install = () => reconcileBinary(host.runner, transport.fetch, props);
+  return { host, install, transport };
+};
+
+describe('Release.Binary through sudoRunner', () => {
+  test('one staged file, one exact install, and the staged file removed', async () => {
+    const { host, install } = setup();
+    const attrs = await install();
+    expect(host.privileged()).toEqual([
+      [INSTALL, '-S', '-m', '0755', '-o', '0', '-g', '0', expect.any(String), PATH],
+    ]);
+    expect(host.fake.files.get(PATH)?.bytes).toEqual(BINARY.vmalert);
+    expect(attrs).toMatchObject({ gid: 0, mode: 0o755, uid: 0 });
+    expect(host.state.stagedCount).toBe(1);
+    expect(host.staged.size).toBe(0);
+  });
+
+  test('a failed install throws and leaves no staged file and no binary', async () => {
+    const { host, install } = setup();
+    host.state.installFailure = { exitCode: 71, stderr: 'install: disk full', stdout: '' };
+    await expect(install()).rejects.toThrow('disk full');
+    expect(host.state.stagedCount).toBe(1);
+    expect(host.staged.size).toBe(0);
+    expect(host.fake.files.has(PATH)).toBe(false);
+  });
+
+  // ⛔ EVERY failure before the write: nothing is staged at all, sudo is never asked, no binary.
+  const tampered = () =>
+    gzip(tarOf(VMUTILS_ENTRIES.map((e) => ({ ...e, bytes: bytesOf('evil') }))));
+  test.each<[string, Setup]>([
+    ['a wrong archive hash', { served: tampered }],
+    ['a wrong binary hash', { declare: { sha256: 'f'.repeat(64) } }],
+    ['a tar-slip entry', { entries: [...VMUTILS_ENTRIES, { bytes: bytesOf('x'), name: '../x' }] }],
+    ['the member as a symlink', { entries: [{ name: 'vmalert-prod', type: '2' }] }],
+    ['the member missing', { entries: [{ bytes: BINARY.vmagent, name: 'vmagent-prod' }] }],
+    ['a failed download', { served: () => undefined }],
+    ['a malformed pin', { declare: { sha256: 'not-a-digest' } }],
+    ['an unwritable mode', { declare: { mode: 0o777 } }],
+  ])('%s stages nothing, asks sudo nothing, writes nothing', async (_, how) => {
+    const { host, install } = setup(how);
+    await expect(install()).rejects.toThrow();
+    expect(host.state.stagedCount).toBe(0);
+    expect(host.staged.size).toBe(0);
+    expect(host.sudoCalls).toEqual([]);
+    expect(host.fake.files.has(PATH)).toBe(false);
+  });
+});