@homeflare/alchemy 0.20.0 → 0.22.0

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

package/src/release/binary.ts

@@ -0,0 +1,181 @@
+/**
+ * `Release.Binary` — one binary out of a pinned release archive, written onto a host and verified
+ * twice: the archive against its pinned SHA-256, then the binary against its own.
+ *
+ * - reconcile — validate every prop; download the archive by its exact URL; verify it; unpack ONLY
+ *   the declared member; verify that; write it atomically through the HostRunner; read it back. A
+ *   file already holding the pinned bytes is never downloaded again.
+ * - read — lstat plus the SHA-256 of the bytes; never runs the binary.
+ * - diff — the pins, the path, then mode and owner against the live file (binary-diff.ts).
+ * - replace — when the path moves (a new version is a new directory): create-before-delete.
+ * - delete — removes the file, never the directory.
+ *
+ * ★ VENDOR-NEUTRAL. The pinned archive arrives as props, usually from a data set beside this
+ *   (victoria.ts) through `catalogBinary()`; nothing here knows a vendor, a package or a version.
+ * ⛔ IT INSTALLS; IT NEVER STARTS. No launchctl, no systemctl, no restart: the job that runs the
+ *   binary is the stack's own `LaunchdJob`, which puts this resource's `path` in its argv so the
+ *   engine installs first and restarts the job when the path moves.
+ * ⚠️ NOTHING IS ADOPTED WITHOUT `--adopt`, AT PLAN OR AT APPLY: the probe reads a file already at
+ *   the path as `Unowned` — even one holding exactly the pinned bytes (docs/ownership.md) — and
+ *   where the probe never ran (a prop was an Output) reconcile refuses it the same way. With
+ *   `--adopt`, a file holding the pinned bytes is recognised by its digest and taken over without
+ *   a download. ⛔ A file with OTHER bytes is never adopted, `--adopt` or not: that would be an
+ *   overwrite in place that the plan prints as `adopted` (binary-claim.ts, both halves).
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
+import { lift } from '../launchd/host-effect.ts';
+import { HostRunnerService } from '../launchd/runner.ts';
+import { adoptsAtApply } from '../ownership/adopt.ts';
+import { noteUnfinished } from '../ownership/resume.ts';
+import { diffBinary } from './binary-diff.ts';
+import {
+  type ReleaseBinaryAttributes,
+  type ReleaseBinaryProps,
+  releaseBinaryPath,
+} from './binary-form.ts';
+import {
+  NOTHING,
+  deleteBinary,
+  reconcileBinary,
+  refreshBinary,
+  refuse,
+} from './binary-lifecycle.ts';
+import { readWithoutState } from './binary-read.ts';
+import { declaredPinProblems } from './declared-pins.ts';
+import { type DownloadPolicy, httpFetchArchive, sharingInFlight } from './download.ts';
+
+export type { ReleaseBinaryAttributes, ReleaseBinaryProps } from './binary-form.ts';
+
+export interface ReleaseBinary extends Resource<
+  'Release.Binary',
+  ReleaseBinaryProps,
+  ReleaseBinaryAttributes
+> {}
+
+/**
+ * One binary from a pinned release archive, installed onto a host and verified against digests
+ * the stack pins in code — the archive's, then the binary's own.
+ *
+ * ### Installing a binary
+ *
+ * The directory is declared first and passed by its `path`, which orders the two; the job that
+ * runs the binary references the binary's `path`, which orders the job after it.
+ *
+ * **Example:**
+ *
+ * ```ts
+ * const vmalertOf = { package: 'vmutils', version: '1.151.0', platform: 'darwin-arm64', binary: 'vmalert' };
+ * const dir = yield* HostDirectory('vmutils-1.151.0', {
+ *   path: catalogDirectory('/opt/example/bin', vmalertOf),
+ *   mode: 0o755,
+ * });
+ * const vmalert = yield* ReleaseBinary('vmalert', {
+ *   ...catalogBinary(VICTORIA_RELEASES, vmalertOf),
+ *   directory: dir.path,
+ * });
+ * // LaunchdJob(…, { programArguments: [vmalert.path, '--httpListenAddr=127.0.0.1:8880'] })
+ * ```
+ *
+ * @resource
+ */
+export const ReleaseBinary = Resource<ReleaseBinary>('Release.Binary');
+
+/** Test seams — NOT on the barrel. Every caller outside tests uses the defaults. */
+export type ReleaseBinaryInternals = { readonly download?: DownloadPolicy };
+
+export const makeReleaseBinaryProvider = (internals: ReleaseBinaryInternals = {}) =>
+  Provider.effect(
+    ReleaseBinary,
+    Effect.gen(function* () {
+      const runner = yield* HostRunnerService;
+      const client = yield* HttpClient.HttpClient;
+      const fetch = sharingInFlight(httpFetchArchive(client, internals.download));
+      /**
+       * ⛔ ONE PATH, ONE DECLARATION. MEASURED 2026-09-22 (binary-claims.test.ts, before this): two
+       *   resources installing one path in one deploy both planned `create`, shared one download,
+       *   and both recorded the file as theirs. Dropping either later — gating vmalert-logs off
+       *   along with its own ReleaseBinary, say — deleted the file the other still declared, and
+       *   that deploy reported the survivor `noop`. So a second resource claiming a path in the
+       *   same run is refused before it touches anything. Two jobs that run one binary share ONE
+       *   ReleaseBinary. ⚠️ Keyed by spelling: one file under two spellings is not caught here.
+       */
+      const claims = new Map<string, string>();
+      const claim = (fqn: string, props: ReleaseBinaryProps): void => {
+        const path = releaseBinaryPath(props);
+        const holder = claims.get(path);
+        if (holder !== undefined && holder !== fqn) {
+          throw refuse(
+            path,
+            `is already installed by ${holder} in this deploy; declare each binary path once, ` +
+              `and let every job that runs it share that one resource. ${NOTHING}`,
+          );
+        }
+        claims.set(path, fqn);
+      };
+      return ReleaseBinary.Provider.of({
+        list: () => Effect.succeed([]),
+
+        // ⛔ The probe (no `output`) validates every prop first, so a malformed pin fails the plan
+        //   here — before any host call, let alone a download. A recovery read never fails its
+        //   caller (binary-read.ts): its props are the failed deploy's.
+        read: ({ fqn, instanceId, olds, output }) =>
+          output === undefined
+            ? readWithoutState(runner, { fqn, instanceId, olds })
+            : lift(() => refreshBinary(runner, output)),
+
+        diff: ({ instanceId, news, olds, output }) =>
+          output === undefined
+            ? noteUnfinished(instanceId)
+            : lift(() => diffBinary(runner, news, olds, output)),
+
+        // ★ `--adopt` reaches the apply too: the probe never ran for a create with an Output prop.
+        // ⛔ So do the pins AS DECLARED: `news` is resolved by now, and a first deploy is never
+        //   diffed, so only the stack's own record can show a digest that was an Output.
+        reconcile: ({ fqn, instanceId, news, olds, output, session }) =>
+          Effect.gen(function* () {
+            const declared = yield* declaredPinProblems(fqn);
+            const adopt = yield* adoptsAtApply({ fqn, instanceId, output });
+            return yield* lift(async () => {
+              claim(fqn, news);
+              return reconcileBinary(runner, fetch, news, {
+                adopt,
+                declared,
+                note: (message) => Effect.runPromise(session.note(message)),
+                olds,
+                output,
+              });
+            });
+          }),
+
+        /**
+         * ⛔ NEVER REMOVE A FILE ANOTHER DECLARATION INSTALLED IN THIS DEPLOY. Alchemy runs every
+         *   delete (Apply.ts collectGarbage, Phase 2) only after every reconcile has succeeded, so a
+         *   claim by another name means the file is that resource's now, verified as its pin.
+         *   🔴 MEASURED 2026-09-22 (adopt-parity.test.ts): a rename under --adopt — the new name
+         *   claimed the file, the old name's orphan delete removed it, and the deploy succeeded
+         *   with the binary gone. ★ Left in place rather than removed: a stray file is a tidy-up, a
+         *   missing binary is an outage. ⚠️ Keyed by spelling, like the claims themselves.
+         * ★ A deleted resource gives its claim back, so a provider that outlives one deploy never
+         *   refuses the next resource declared at that path.
+         */
+        delete: ({ fqn, output, session }) =>
+          lift(async () => {
+            const holder = claims.get(output.path);
+            if (holder !== undefined && holder !== fqn) {
+              await Effect.runPromise(
+                session.note(`${output.path} was installed by ${holder} in this deploy; kept`),
+              );
+              return;
+            }
+            await deleteBinary(runner, output);
+            if (holder === fqn) claims.delete(output.path);
+          }),
+      });
+    }),
+  );
+
+/** The provider, as a stack uses it. It needs a HostRunnerService and an HttpClient. */
+export const ReleaseBinaryProvider = () => makeReleaseBinaryProvider();

package/src/release/catalog.test.ts

@@ -0,0 +1,167 @@
+/**
+ * A catalog request → pinned props, or a refusal — pure, over the REAL Victoria data set. Every
+ * refusal here happens in the stack's own program, so it fails the plan before any resource runs
+ * (plan.test.ts proves that through the engine).
+ */
+import { describe, expect, test } from 'bun:test';
+import { binaryProblems } from './binary-form.ts';
+import type { ReleaseCatalog } from './catalog.ts';
+import { catalogBinary, catalogDirectory, catalogProblems, identifyBinary } from './catalog.ts';
+import { OPENBAO_RELEASES } from './openbao.ts';
+import { BinaryRefused } from './refused.ts';
+import { VICTORIA_RELEASES } from './victoria.ts';
+
+const VMALERT = {
+  binary: 'vmalert',
+  package: 'vmutils',
+  platform: 'darwin-arm64',
+  version: '1.151.0',
+};
+
+describe('refusing what the catalog does not pin', () => {
+  test.each([
+    [
+      'a version the catalog does not pin',
+      { version: '1.152.0' },
+      'vmutils 1.152.0 is not in the catalog',
+    ],
+    ['the tag spelling', { version: 'v1.151.0' }, 'is not in the catalog'],
+    ['an enterprise version', { version: '1.151.0-enterprise' }, 'is not in the catalog'],
+    [
+      'a cluster package',
+      { package: 'victoria-metrics-cluster' },
+      'package "victoria-metrics-cluster"',
+    ],
+    ['the vendor member name', { binary: 'vmalert-prod' }, 'that is the archive member'],
+    ['a binary vmutils does not ship', { binary: 'vminsert' }, 'has no binary "vminsert"'],
+    ['another platform', { platform: 'linux-amd64' }, 'not pinned for platform "linux-amd64"'],
+    ['an inherited key', { package: 'constructor' }, 'package "constructor"'],
+  ])('refuses %s', (_, change, message) => {
+    const request = { ...VMALERT, ...change };
+    expect(catalogProblems(VICTORIA_RELEASES, request).join('; ')).toContain(message);
+    expect(() => catalogBinary(VICTORIA_RELEASES, request)).toThrow(message);
+  });
+
+  test('the refusal is typed, names the binary, and says nothing was fetched', () => {
+    let caught: unknown;
+    try {
+      catalogBinary(VICTORIA_RELEASES, { ...VMALERT, version: '1.152.0' });
+    } catch (cause) {
+      caught = cause;
+    }
+    expect(caught).toBeInstanceOf(BinaryRefused);
+    expect((caught as Error).message).toMatch(
+      /^Release\.Binary vmalert: .* Nothing was fetched\.$/,
+    );
+  });
+});
+
+describe('what a pinned request becomes', () => {
+  test('props that validate once the stack adds a directory', () => {
+    const pinned = catalogBinary(VICTORIA_RELEASES, VMALERT);
+    const directory = catalogDirectory('/opt/example/bin', VMALERT);
+    expect(directory).toBe('/opt/example/bin/vmutils-1.151.0');
+    expect(binaryProblems({ ...pinned, directory })).toEqual([]);
+  });
+
+  test('every binary of every pinned archive resolves to valid props', () => {
+    for (const [pkg, entry] of Object.entries(VICTORIA_RELEASES.packages)) {
+      for (const [version, platforms] of Object.entries(entry.versions)) {
+        for (const platform of Object.keys(platforms)) {
+          for (const binary of Object.keys(entry.binaries)) {
+            const request = { binary, package: pkg, platform, version };
+            const props = { ...catalogBinary(VICTORIA_RELEASES, request), directory: '/x/y' };
+            expect(binaryProblems(props)).toEqual([]);
+          }
+        }
+      }
+    }
+  });
+});
+
+describe('identifying an installed file', () => {
+  test('by its digest alone', () => {
+    const pin = '4759ec89a466129b9eefc22244a111e1f489739340747805fd93b58fd0f7b2dd';
+    expect(identifyBinary([VICTORIA_RELEASES], pin)).toEqual({
+      binary: 'victoria-traces',
+      package: 'victoria-traces',
+      platform: 'darwin-arm64',
+      vendor: 'VictoriaMetrics',
+      version: '0.10.0',
+    });
+  });
+
+  test("an archive's digest is not a binary's: identity is by the member's own line", () => {
+    const archive = 'cbe83f1d409cbb85fbf1c890c4a9b7fd34c1d74acec4dce2e0ebe46fcb260e38';
+    expect(identifyBinary([VICTORIA_RELEASES], archive)).toBeUndefined();
+  });
+
+  test('by a COMPUTED digest, same as a vendor one — OpenBao pins bao only there', () => {
+    const computed = 'd476d17e81a35e6d70dd7e86a8ab2a3664313525118f1f1cfe0130e7a2b95f3a';
+    expect(identifyBinary([VICTORIA_RELEASES, OPENBAO_RELEASES], computed)).toEqual({
+      binary: 'bao',
+      package: 'openbao',
+      platform: 'darwin_arm64',
+      vendor: 'OpenBao',
+      version: '2.6.2',
+    });
+  });
+});
+
+/** A fabricated one-entry catalog, only to exercise the `computed`/`members` overlap refusal. */
+const doubled = (extra: {
+  members?: Record<string, string>;
+  computed?: Record<string, { sha256: string; recorded: string }>;
+}): ReleaseCatalog => ({
+  packages: {
+    thing: {
+      binaries: { thing: 'thing-bin' },
+      versions: {
+        '1.0.0': {
+          any: {
+            asset: 'thing-1.0.0.tar.gz',
+            checksums: {
+              recorded: '2026-09-23',
+              sha256: 'a'.repeat(64),
+              url: 'https://example.invalid/checksums.txt',
+            },
+            // ⚠️ Spread, not a plain key: `exactOptionalPropertyTypes` treats an explicit
+            //   `computed: undefined` as different from the key being absent.
+            ...(extra.computed !== undefined ? { computed: extra.computed } : {}),
+            members: extra.members ?? {},
+            repo: 'example/thing',
+            sha256: 'b'.repeat(64),
+            size: 1,
+            tag: 'v1.0.0',
+          },
+        },
+      },
+    },
+  },
+  vendor: 'Example',
+});
+
+const THING = { binary: 'thing', package: 'thing', platform: 'any', version: '1.0.0' };
+
+describe('a member pinned twice, once vendor and once computed', () => {
+  test('catalogProblems names it, rather than silently preferring one', () => {
+    const catalog = doubled({
+      computed: { 'thing-bin': { recorded: '2026-09-23', sha256: 'c'.repeat(64) } },
+      members: { 'thing-bin': 'c'.repeat(64) },
+    });
+    const problems = catalogProblems(catalog, THING);
+    expect(problems.join('; ')).toContain('pinned twice');
+    expect(() => catalogBinary(catalog, THING)).toThrow('pinned twice');
+  });
+
+  test('computed alone resolves; vendor alone resolves; neither refuses "no digest"', () => {
+    const computedOnly = doubled({
+      computed: { 'thing-bin': { recorded: '2026-09-23', sha256: 'c'.repeat(64) } },
+    });
+    expect(catalogBinary(computedOnly, THING).sha256).toBe('c'.repeat(64));
+    const vendorOnly = doubled({ members: { 'thing-bin': 'd'.repeat(64) } });
+    expect(catalogBinary(vendorOnly, THING).sha256).toBe('d'.repeat(64));
+    const neither = doubled({});
+    expect(() => catalogBinary(neither, THING)).toThrow('pins no digest');
+  });
+});