@homeflare/alchemy 0.20.0 → 0.22.0

package/src/release/fixtures/victoria/darwin-arm64-assets.txt

@@ -0,0 +1,22 @@
+victoria-logs-darwin-arm64-v1.52.0-enterprise.tar.gz
+victoria-logs-darwin-arm64-v1.52.0-enterprise_checksums.txt
+victoria-logs-darwin-arm64-v1.52.0.tar.gz
+victoria-logs-darwin-arm64-v1.52.0_checksums.txt
+victoria-metrics-darwin-arm64-v1.151.0-cluster.tar.gz
+victoria-metrics-darwin-arm64-v1.151.0-cluster_checksums.txt
+victoria-metrics-darwin-arm64-v1.151.0-enterprise-cluster.tar.gz
+victoria-metrics-darwin-arm64-v1.151.0-enterprise-cluster_checksums.txt
+victoria-metrics-darwin-arm64-v1.151.0-enterprise.tar.gz
+victoria-metrics-darwin-arm64-v1.151.0-enterprise_checksums.txt
+victoria-metrics-darwin-arm64-v1.151.0.tar.gz
+victoria-metrics-darwin-arm64-v1.151.0_checksums.txt
+victoria-traces-darwin-arm64-v0.10.0.tar.gz
+victoria-traces-darwin-arm64-v0.10.0_checksums.txt
+vlutils-darwin-arm64-v1.52.0-enterprise.tar.gz
+vlutils-darwin-arm64-v1.52.0-enterprise_checksums.txt
+vlutils-darwin-arm64-v1.52.0.tar.gz
+vlutils-darwin-arm64-v1.52.0_checksums.txt
+vmutils-darwin-arm64-v1.151.0-enterprise.tar.gz
+vmutils-darwin-arm64-v1.151.0-enterprise_checksums.txt
+vmutils-darwin-arm64-v1.151.0.tar.gz
+vmutils-darwin-arm64-v1.151.0_checksums.txt

package/src/release/fixtures/victoria/victoria-logs-darwin-arm64-v1.52.0_checksums.txt

@@ -0,0 +1,2 @@
+3157d4b6181d8a7e3e30918e2cbfcd4cc4cb66263e3ef21ea91e4f20f8980883  victoria-logs-darwin-arm64-v1.52.0.tar.gz
+9e48809e314902782959b3a4e683a3087476759d0293791a0564921c676ca7be  victoria-logs-prod

package/src/release/fixtures/victoria/victoria-metrics-darwin-arm64-v1.151.0_checksums.txt

@@ -0,0 +1,2 @@
+8792437c4c0b63719fed7b44ad18d4b4167bbe6861ab3e84c7bb010c922e7582  victoria-metrics-darwin-arm64-v1.151.0.tar.gz
+3c493a95ac1e9034a3261b230c4d62f3b186a04aafcdbacc99bfc110dc5de6a1  victoria-metrics-prod

package/src/release/fixtures/victoria/victoria-traces-darwin-arm64-v0.10.0_checksums.txt

@@ -0,0 +1,2 @@
+cbe83f1d409cbb85fbf1c890c4a9b7fd34c1d74acec4dce2e0ebe46fcb260e38  victoria-traces-darwin-arm64-v0.10.0.tar.gz
+4759ec89a466129b9eefc22244a111e1f489739340747805fd93b58fd0f7b2dd  victoria-traces-prod

package/src/release/fixtures/victoria/vmutils-darwin-arm64-v1.151.0_checksums.txt

@@ -0,0 +1,8 @@
+27d68bac90e28929214091ed9d27f2e9fef25a080407e2c8661ea9b52dd6b183  vmutils-darwin-arm64-v1.151.0.tar.gz
+d3b6fa1f71ef48beac619f15f8adfa7610e76605caf37db1ebfbb379b6692329  vmagent-prod
+62845795167e9ff47890e83ac4ac5934693c105767db88591c95a08f3c4fb354  vmalert-prod
+cbffb9495e4bb1457c9d45e0a7064b3a3a29b2cfd1ae24bfe8f00ec327c26998  vmalert-tool-prod
+398df9e0f5b7035d037e39ee9ff66a10ddde5333d832602463aa4d2865fdb508  vmauth-prod
+1974a2ee211b49bf581287808e010846f6c47ff135276214c6da628567777b9e  vmbackup-prod
+fc824df7215b01b57921ed46afde7fea6b6698adf13d9ea8e3fe36e194ef8190  vmrestore-prod
+998b111eee206b98e6d25fdf2fbaa455ecc17c7f9e7c3b2373e127cef762459f  vmctl-prod

package/src/release/index.ts

@@ -0,0 +1,44 @@
+/**
+ * Release binaries for Alchemy — one binary out of a pinned release archive, installed onto a host
+ * and verified against digests the stack pins in code, plus the vendor data sets those pins come
+ * from (VictoriaMetrics' is the first).
+ *
+ * ⛔ THIS BARREL IS THE PUBLIC API, AND IT IS DELIBERATELY SMALLER THAN THE DIRECTORY. The tar
+ *   reader, the downloader, the checksum parser, the lifecycle and the test seams are internals; an
+ *   `export *` would publish them as API and make the next refactor a breaking change.
+ * ⛔ IT INSTALLS; IT NEVER STARTS. Run the binary with `LaunchdJob` (the launchd subpath) or a
+ *   systemd unit, putting `ReleaseBinary`'s `path` in its argv. See docs/release-binary.md.
+ * ★ THE SEAM IS SHARED, NOT COPIED. `HostRunner` is re-exported so a stack types its runner without
+ *   importing from another subpath.
+ */
+export type {
+  PinnedDownload,
+  ReleaseArchive,
+  ReleaseBinaryAttributes,
+  ReleaseBinaryProps,
+} from './binary-form.ts';
+export { releaseBinaryPath, releaseUrl } from './binary-form.ts';
+export { ReleaseBinary, ReleaseBinaryProvider } from './binary.ts';
+export type {
+  CatalogPackage,
+  CatalogRequest,
+  ChecksumSignature,
+  ComputedDigest,
+  IdentifiedBinary,
+  PinnedArchive,
+  PinnedBinary,
+  ReleaseCatalog,
+} from './catalog.ts';
+export { catalogBinary, catalogDirectory, catalogProblems, identifyBinary } from './catalog.ts';
+export { OPENBAO_RELEASES } from './openbao.ts';
+export { releaseProviders } from './providers.ts';
+export { ArchiveRefused, BinaryRefused, ChecksumMismatch, DownloadFailed } from './refused.ts';
+export { VICTORIA_RELEASES } from './victoria.ts';
+export type {
+  ExecResult,
+  FileStat,
+  HostRunner,
+  HostUser,
+  WriteOptions,
+} from '../launchd/runner.ts';
+export { HostRunnerService, hostRunnerLayer } from '../launchd/runner.ts';

package/src/release/openbao.test.ts

@@ -0,0 +1,120 @@
+/**
+ * The REAL OpenBao data set against the vendor's own files — no network: fixtures/openbao/ holds
+ * checksums.txt, its detached GPG signature and the signing key byte-for-byte as fetched
+ * 2026-09-23 (each one's SHA-256 equals GitHub's / openbao.org's digest for it that day).
+ *
+ * ★ THE CHAIN THIS PROVES: fixture bytes = the recorded digest → the strict parser reads exactly
+ *   its 83 lines → none of them names `bao` → the pin is filed under `computed`, never `members`.
+ *   The GPG check is NOT re-run here (gpgv needs a binary this repo does not vendor); it is a
+ *   recorded one-time measurement (docs/release-binary-openbao.md), same status as Victoria's
+ *   "consistency, not provenance" note.
+ */
+import { describe, expect, test } from 'bun:test';
+import { sha256Hex } from '../launchd/job-form.ts';
+import { releaseUrl } from './binary-form.ts';
+import { catalogBinary } from './catalog.ts';
+import { parseChecksums } from './checksums.ts';
+import { OPENBAO_RELEASES } from './openbao.ts';
+
+const fixture = (name: string) => Bun.file(new URL(`fixtures/openbao/${name}`, import.meta.url));
+const PLATFORM = 'darwin_arm64';
+const archive = OPENBAO_RELEASES.packages.openbao?.versions['2.6.2']?.[PLATFORM];
+if (archive === undefined)
+  throw new Error('fixture setup: OPENBAO_RELEASES has no darwin_arm64 pin');
+
+describe('the OpenBao data set is the vendor checksum file', () => {
+  test('one package, one version, one platform', () => {
+    expect(Object.keys(OPENBAO_RELEASES.packages)).toEqual(['openbao']);
+    expect(Object.keys(OPENBAO_RELEASES.packages.openbao?.versions ?? {})).toEqual(['2.6.2']);
+    expect(Object.keys(OPENBAO_RELEASES.packages.openbao?.versions['2.6.2'] ?? {})).toEqual([
+      PLATFORM,
+    ]);
+  });
+
+  test('archive pin: repo, tag, asset, URL', () => {
+    expect([archive.repo, archive.tag, archive.asset]).toEqual([
+      'openbao/openbao',
+      'v2.6.2',
+      'openbao_2.6.2_darwin_arm64.tar.gz',
+    ]);
+    expect(releaseUrl(archive.repo, archive.tag, archive.asset)).toBe(
+      `https://github.com/openbao/openbao/releases/download/v2.6.2/openbao_2.6.2_darwin_arm64.tar.gz`,
+    );
+  });
+
+  test('checksums.txt: 83 lines, byte-identical to the recorded digest, archive line equals the pin', async () => {
+    const bytes = new Uint8Array(await fixture('checksums.txt').arrayBuffer());
+    expect(sha256Hex(bytes)).toBe(archive.checksums.sha256);
+    expect(archive.checksums.url).toBe(
+      'https://github.com/openbao/openbao/releases/download/v2.6.2/checksums.txt',
+    );
+    const lines = parseChecksums(new TextDecoder().decode(bytes));
+    expect(lines.size).toBe(83);
+    expect(lines.get(archive.asset)).toBe(archive.sha256);
+  });
+
+  test('no line names the `bao` member — it is not a vendor fact', async () => {
+    const bytes = new Uint8Array(await fixture('checksums.txt').arrayBuffer());
+    const lines = parseChecksums(new TextDecoder().decode(bytes));
+    expect(lines.has('bao')).toBe(false);
+    expect(archive.members).toEqual({});
+  });
+
+  test('the member digest is filed under `computed`, dated, not under `members`', () => {
+    expect(archive.computed?.bao).toEqual({
+      recorded: '2026-09-23',
+      sha256: 'd476d17e81a35e6d70dd7e86a8ab2a3664313525118f1f1cfe0130e7a2b95f3a',
+    });
+  });
+
+  test('the checksums file is GPG-signed, and the signature and key are pinned', async () => {
+    const sigBytes = new Uint8Array(await fixture('checksums.txt.gpgsig').arrayBuffer());
+    const keyBytes = new Uint8Array(await fixture('openbao-gpg-pub-20240618.asc').arrayBuffer());
+    const sig = archive.checksums.signature;
+    if (sig === undefined) throw new Error('fixture setup: no checksums.signature pinned');
+    expect(sig.kind).toBe('openpgp');
+    expect(sha256Hex(sigBytes)).toBe(sig.sha256);
+    expect(sha256Hex(keyBytes)).toBe(sig.key.sha256);
+    expect(sig.key.fingerprint).toBe('66D15FDD87287219C8E15478D200CD702853E6D0');
+  });
+
+  test('the asset is in the committed darwin listing, and no sibling is pinned', async () => {
+    const assets = (await fixture('darwin-assets.txt').text()).trim().split('\n');
+    expect(assets).toContain(archive.asset);
+    // ★ Every OTHER darwin asset (the amd64 archive, and every .sbom.json / .gpgsig / .sigstore.json
+    //   next to both) is listed here so a reviewer can see what was excluded, but pinned nowhere.
+    const siblings = assets.filter((name) => name !== archive.asset);
+    expect(siblings).toEqual([
+      'openbao_2.6.2_darwin_amd64.tar.gz',
+      'openbao_2.6.2_darwin_amd64.tar.gz.gpgsig',
+      'openbao_2.6.2_darwin_amd64.tar.gz.sbom.json',
+      'openbao_2.6.2_darwin_amd64.tar.gz.sbom.json.gpgsig',
+      'openbao_2.6.2_darwin_amd64.tar.gz.sbom.json.sigstore.json',
+      'openbao_2.6.2_darwin_amd64.tar.gz.sigstore.json',
+      'openbao_2.6.2_darwin_arm64.tar.gz.gpgsig',
+      'openbao_2.6.2_darwin_arm64.tar.gz.sbom.json',
+      'openbao_2.6.2_darwin_arm64.tar.gz.sbom.json.gpgsig',
+      'openbao_2.6.2_darwin_arm64.tar.gz.sbom.json.sigstore.json',
+      'openbao_2.6.2_darwin_arm64.tar.gz.sigstore.json',
+    ]);
+    expect(siblings.some((name) => name.startsWith('openbao-hsm_'))).toBe(false);
+    const pinnedPlatforms = Object.keys(OPENBAO_RELEASES.packages.openbao?.versions['2.6.2'] ?? {});
+    expect(pinnedPlatforms).not.toContain('darwin_amd64');
+  });
+
+  test('bao out of the data set: the computed member of the one pinned archive', () => {
+    const request = { binary: 'bao', package: 'openbao', platform: PLATFORM, version: '2.6.2' };
+    expect(catalogBinary(OPENBAO_RELEASES, request)).toEqual({
+      archive: {
+        asset: 'openbao_2.6.2_darwin_arm64.tar.gz',
+        repo: 'openbao/openbao',
+        sha256: '4e495376174accc0e014d31e9901f518a974f966850c839f626347eaac05fd52',
+        size: 76_833_570,
+        tag: 'v2.6.2',
+      },
+      member: 'bao',
+      name: 'bao',
+      sha256: 'd476d17e81a35e6d70dd7e86a8ab2a3664313525118f1f1cfe0130e7a2b95f3a',
+    });
+  });
+});

package/src/release/openbao.ts

@@ -0,0 +1,86 @@
+/**
+ * OpenBao's release archives, pinned — the second data set for Release.Binary, walked down
+ * 2026-09-23 (packages/alchemy/docs/release-binary-openbao.md has every command).
+ *
+ * ★ THE MEMBER DIGEST IS OURS, NOT THE VENDOR'S. `checksums.txt` lists 83 lines: every archive and
+ *   every `.sbom.json`, never `bao` itself (measured 2026-09-23 — see checksums.ts's header on why
+ *   that is normal for this vendor). So `bao`'s SHA-256 sits under `computed`, hashed from the one
+ *   archive whose OWN SHA-256 already matched the checksums-file pin — never filed under `members`,
+ *   which is vendor lines only.
+ * ★ PLATFORM KEY IS THE VENDOR'S OWN SPELLING: `darwin_arm64`, underscore — OpenBao's asset names
+ *   read `openbao_2.6.2_darwin_arm64.tar.gz`. Victoria's catalog spells the same idea
+ *   `darwin-arm64`, hyphen, because THAT vendor's asset names use a hyphen. Nothing here picks one
+ *   estate-wide convention; a consumer names the platform its data set actually uses. If a reviewer
+ *   would rather the estate pick one spelling, that is a one-line change to this rule, not to any
+ *   consumer, made in the same PR that adds the second spelling.
+ * ★ GPG, MEASURED, TWO INDEPENDENT CHANNELS: `gpgv` against the dearmored key from openbao.org
+ *   returned "Good signature from OpenBao <openbao@lists.lfedge.org>" over `checksums.txt` using
+ *   subkey E617DCD4065C2AFC0B2CF7A7BA8BC08C0F691F94 of primary 66D15FDD87287219C8E15478D200CD702853E6D0
+ *   (both fingerprints published in OpenBao's own install.mdx at this tag). ⚠️ TRUST ON FIRST USE
+ *   ACROSS TWO CHANNELS ONE PROJECT RUNS: the release asset and openbao.org are both OpenBao's own
+ *   infrastructure, so this is not a third party attesting to the key — it raises the bar over no
+ *   check at all (a swap needs both channels, not one), it does not reach independent provenance.
+ * ⛔ SIGSTORE WAS NOT CHECKED: `cosign` is not installed on the mini (measured 2026-09-23). The
+ *   bundle's certificate SAN (read, not verified) names
+ *   `https://github.com/openbao/openbao/.github/workflows/release.yml@refs/heads/release/2.6.x`,
+ *   issuer `https://token.actions.githubusercontent.com` — recorded here as an UNVERIFIED identity,
+ *   never as a passing check. "GPG or Sigstore" is met by the GPG half alone.
+ * ⚠️ THE BUILD THIS PINS IS NOT THE ONE THE VAULT SERVER RUNS. Read from goreleaser.other.yaml at
+ *   v2.6.2: `CGO_ENABLED=0`, build tag `ui`. Expected to differ from the Nix build in nothing an
+ *   agent (approle auto-auth, templates, exec) depends on; nobody has run this binary to confirm —
+ *   docs/release-binary-openbao.md says so and stops there, by house rule (never execute `bao`).
+ */
+import type { ReleaseCatalog } from './catalog.ts';
+
+const RECORDED = '2026-09-23';
+const REPO = 'openbao/openbao';
+const TAG = 'v2.6.2';
+const DOWNLOAD = `https://github.com/${REPO}/releases/download/${TAG}`;
+
+export const OPENBAO_RELEASES: ReleaseCatalog = {
+  packages: {
+    openbao: {
+      // ★ The member is named `bao` itself — no `-prod`-style suffix; the vendor tarball unpacks
+      //   CHANGELOG.md, LICENSE, README.md and `bao` at its root (measured, full stream, 2026-09-23).
+      binaries: { bao: 'bao' },
+      versions: {
+        '2.6.2': {
+          darwin_arm64: {
+            asset: 'openbao_2.6.2_darwin_arm64.tar.gz',
+            checksums: {
+              recorded: RECORDED,
+              sha256: '3d4a19fdc54a86fd94ce59ea91316dbf4304180bb27ae818e78e85c7f2164645',
+              signature: {
+                kind: 'openpgp',
+                key: {
+                  fingerprint: '66D15FDD87287219C8E15478D200CD702853E6D0',
+                  sha256: '1862a196422947124282e026ea4e09d6f7c5d383b628d90c17906936e6e5a8e0',
+                  url: 'https://openbao.org/assets/openbao-gpg-pub-20240618.asc',
+                },
+                sha256: '40f294d642a2b4e9adac766ca6b8b2633e15b3dbfdf63969dedbf46d94df53e8',
+                url: `${DOWNLOAD}/checksums.txt.gpgsig`,
+                verified: RECORDED,
+              },
+              url: `${DOWNLOAD}/checksums.txt`,
+            },
+            // ★ NOT a vendor fact — see the header. Hashed from THIS archive after its own SHA-256
+            //   (below) already matched the checksums.txt pin; confirmed two ways
+            //   (extractMembers and `tar -xzOf … bao | shasum -a 256`) and against `tar -tvzf -`.
+            computed: {
+              bao: {
+                recorded: RECORDED,
+                sha256: 'd476d17e81a35e6d70dd7e86a8ab2a3664313525118f1f1cfe0130e7a2b95f3a',
+              },
+            },
+            members: {},
+            repo: REPO,
+            sha256: '4e495376174accc0e014d31e9901f518a974f966850c839f626347eaac05fd52',
+            size: 76_833_570,
+            tag: TAG,
+          },
+        },
+      },
+    },
+  },
+  vendor: 'OpenBao',
+};

package/src/release/plan.test.ts

@@ -0,0 +1,189 @@
+/**
+ * Release.Binary through Alchemy's OWN Plan and Apply (openbao/fake-stack.ts, in-memory state), with
+ * `HostDirectory` declared in front of it, over a fake host that models mkdir/rmdir
+ * (linux/fake-linux-host.ts) and a fake HttpClient. No network, no real filesystem.
+ *
+ * ★ WHAT ONLY THE ENGINE CAN SAY. A handler test shows what `diff` answers; this shows what the
+ *   engine then DOES with it, in which order: that `directory: dir.path` orders the directory
+ *   first; that a version bump writes the new binary before the old one goes; that a version
+ *   outside the catalog fails the plan with nothing fetched and nothing touched.
+ */
+import { describe, expect, test } from 'bun:test';
+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 { releaseUrl } from './binary-form.ts';
+import { ReleaseBinary, makeReleaseBinaryProvider } from './binary.ts';
+import { type PinnedBinary, catalogBinary, catalogDirectory } from './catalog.ts';
+import {
+  BINARY,
+  VMALERT_REQUEST,
+  VMUTILS_URL,
+  bytesOf,
+  gzip,
+  syntheticRelease,
+  tarOf,
+} from './fake-release.ts';
+import { VICTORIA_RELEASES } from './victoria.ts';
+
+const ROOT = '/opt/example/bin';
+const NEXT = bytesOf('#!fake vmalert 1.152.0\n');
+
+/** vmutils 1.151.0 (synthetic, at its real URL) and a synthetic 1.152.0 beside it. */
+const releases = () => {
+  const current = syntheticRelease();
+  const next = gzip(tarOf([{ bytes: NEXT, name: 'vmalert-prod' }]));
+  const nextPins: PinnedBinary = {
+    archive: {
+      asset: 'vmutils-darwin-arm64-v1.152.0.tar.gz',
+      repo: 'VictoriaMetrics/VictoriaMetrics',
+      sha256: sha256Hex(next),
+      size: next.length,
+      tag: 'v1.152.0',
+    },
+    member: 'vmalert-prod',
+    name: 'vmalert',
+    sha256: sha256Hex(NEXT),
+  };
+  const nextUrl = releaseUrl(nextPins.archive.repo, nextPins.archive.tag, nextPins.archive.asset);
+  const served: Record<string, Uint8Array> = { [VMUTILS_URL]: current.vmutils, [nextUrl]: next };
+  return { current: catalogBinary(current.catalog, VMALERT_REQUEST), next: nextPins, served };
+};
+
+/** One fake host and one fake server; `events` is every host change and request, in order. */
+const harness = () => {
+  const { current, next, served } = releases();
+  const fake = fakeLinuxHost({ dirs: { [ROOT]: 0 }, euid: 0 });
+  const events: string[] = [];
+  const base = fake.runner;
+  const runner: HostRunner = {
+    ...base,
+    exec: (argv) => {
+      events.push(argv.filter((arg) => arg !== '--').join(' '));
+      return base.exec(argv);
+    },
+    removeFile: (path) => {
+      events.push(`remove ${path}`);
+      return base.removeFile(path);
+    },
+    writeFileAtomic: (path, bytes, options) => {
+      events.push(`write ${path}`);
+      return base.writeFileAtomic(path, bytes, options);
+    },
+  };
+  const client = HttpClient.make((request, url) => {
+    events.push(`GET ${url.toString()}`);
+    const bytes = served[url.toString()];
+    const body = bytes === undefined ? null : new Blob([bytes.slice()]);
+    return Effect.succeed(
+      HttpClientResponse.fromWeb(request, new Response(body, { status: body ? 200 : 404 })),
+    );
+  });
+  const providers = Layer.mergeAll(makeReleaseBinaryProvider(), HostDirectoryProvider()).pipe(
+    Layer.provide(
+      Layer.mergeAll(hostRunnerLayer(runner), Layer.succeed(HttpClient.HttpClient, client)),
+    ),
+  );
+  const stack = fakeStack(providers, {}, 'ReleaseStack');
+  /** The stack body: one versioned directory and the binary in it, ordered by `dir.path`. */
+  const declare = (pins: PinnedBinary, version: string) =>
+    Effect.gen(function* () {
+      const path = catalogDirectory(ROOT, { package: 'vmutils', version });
+      const dir = yield* HostDirectory(`vmutils-${version}`, { mode: 0o755, path });
+      yield* ReleaseBinary('vmalert', { ...pins, directory: dir.path });
+    });
+  return { current, declare, events, fake, next, stack };
+};
+
+const OLD = `${ROOT}/vmutils-1.151.0`;
+const NEW = `${ROOT}/vmutils-1.152.0`;
+
+describe('through the engine', () => {
+  test('a version outside the catalog fails the plan: nothing fetched, nothing touched', async () => {
+    const h = harness();
+    const body = Effect.gen(function* () {
+      const pins = catalogBinary(VICTORIA_RELEASES, { ...VMALERT_REQUEST, version: '1.152.0' });
+      yield* ReleaseBinary('vmalert', { ...pins, directory: OLD });
+    });
+    await expect(h.stack.deploy(body)).rejects.toThrow('vmutils 1.152.0 is not in the catalog');
+    expect(h.events).toEqual([]);
+  });
+
+  test('the directory first, then one download, then the one write', async () => {
+    const h = harness();
+    const planned = await h.stack.deploy(h.declare(h.current, '1.151.0'));
+    expect(planned).toEqual({ vmalert: 'create', 'vmutils-1.151.0': 'create' });
+    expect(h.events).toEqual([`mkdir -m 755 ${OLD}`, `GET ${VMUTILS_URL}`, `write ${OLD}/vmalert`]);
+    expect(h.fake.files.get(`${OLD}/vmalert`)?.bytes).toEqual(BINARY.vmalert);
+  });
+
+  test('a second deploy of the same declaration changes nothing and fetches nothing', async () => {
+    const h = harness();
+    await h.stack.deploy(h.declare(h.current, '1.151.0'));
+    h.events.length = 0;
+    await h.stack.deploy(h.declare(h.current, '1.151.0'));
+    expect(h.events).toEqual([]);
+  });
+
+  test('a version bump: the new binary is written BEFORE the old one goes, then the old directory', async () => {
+    const h = harness();
+    await h.stack.deploy(h.declare(h.current, '1.151.0'));
+    h.events.length = 0;
+    const planned = await h.stack.deploy(h.declare(h.next, '1.152.0'));
+    expect(planned).toEqual({
+      vmalert: 'replace',
+      'vmutils-1.151.0': 'delete',
+      'vmutils-1.152.0': 'create',
+    });
+    // ★ MEASURED HERE, not reasoned from Apply.ts: create-before-delete, and the old directory
+    //   only once it is empty — a job whose argv holds `vmalert.path` moves before its file goes.
+    expect(h.events).toEqual([
+      `mkdir -m 755 ${NEW}`,
+      `GET ${releaseUrl(h.next.archive.repo, h.next.archive.tag, h.next.archive.asset)}`,
+      `write ${NEW}/vmalert`,
+      `remove ${OLD}/vmalert`,
+      `rmdir ${OLD}`,
+    ]);
+    expect(h.fake.files.get(`${NEW}/vmalert`)?.bytes).toEqual(NEXT);
+    expect([...h.fake.files.keys()]).toEqual([`${NEW}/vmalert`]);
+  });
+
+  test('a new pin in the SAME directory fails the plan; the installed binary is untouched', async () => {
+    const h = harness();
+    await h.stack.deploy(h.declare(h.current, '1.151.0'));
+    h.events.length = 0;
+    await expect(h.stack.deploy(h.declare(h.next, '1.151.0'))).rejects.toThrow(
+      'would overwrite it in place',
+    );
+    // ★ Refused by diff, at plan: the directory was already created, so its path is resolved.
+    expect(h.events).toEqual([]);
+    expect(h.fake.files.get(`${OLD}/vmalert`)?.bytes).toEqual(BINARY.vmalert);
+  });
+
+  test('the same bytes re-pinned while the directory is updated: refused at apply, binary kept', async () => {
+    const h = harness();
+    const body = (mode: number, tag: string) =>
+      Effect.gen(function* () {
+        const dir = yield* HostDirectory('vmutils-1.151.0', { mode, path: OLD });
+        const archive = { ...h.current.archive, tag };
+        yield* ReleaseBinary('vmalert', { ...h.current, archive, directory: dir.path });
+      });
+    await h.stack.deploy(body(0o755, 'v1.151.0'));
+    h.events.length = 0;
+    // The directory's update leaves its path unresolved at plan, so diff cannot see the path.
+    await expect(h.stack.deploy(body(0o750, 'v1.151.1'))).rejects.toThrow(
+      'would overwrite it in place',
+    );
+    // 🔴 MEASURED 2026-09-22 with diff answering `replace` here instead of `update`: the deploy
+    //   SUCCEEDED and the binary was gone — the new generation took the identical file as its own,
+    //   then Phase 2 deleted the old generation at the same path (binary-diff.ts).
+    expect(h.events).toEqual([`chmod 750 ${OLD}`]);
+    expect(h.fake.files.get(`${OLD}/vmalert`)?.bytes).toEqual(BINARY.vmalert);
+  });
+});

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

@@ -0,0 +1,48 @@
+/**
+ * The provider's plan-time refusals, through the engine-facing handlers (fake-provider.ts): each
+ * with zero requests and zero writes. (A version outside a catalog never reaches a handler: it
+ * fails in the stack program — catalog.test.ts, plan.test.ts.)
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import type { ReleaseBinaryProps } from './binary-form.ts';
+import { VMUTILS_DIR } from './fake-release.ts';
+import { call, harness, ids, must } from './fake-provider.ts';
+
+describe('plan-time refusals: zero requests, zero writes', () => {
+  test('the adoption probe refuses a malformed pin before touching the host', async () => {
+    const h = harness();
+    const next = { ...h.VMALERT, sha256: 'v1.151.0' };
+    const probe = h.run((p) => must(p.read)({ ...ids, olds: next as never, output: undefined }));
+    await expect(probe).rejects.toThrow('sha256 must be 64 lower-case hex digits');
+    expect(h.requests).toEqual([]);
+    expect(h.fake.calls).toEqual([]);
+  });
+
+  test('diff refuses a pin that is not a plain value, even while the directory is an Output', async () => {
+    const h = harness();
+    const output = await h.run((p) => h.reconcile(p, h.VMALERT));
+    h.requests.length = 0;
+    // ⛔ A pin computed during the deploy is a fetch by another name.
+    const pending = {
+      ...h.VMALERT,
+      directory: Effect.succeed(VMUTILS_DIR),
+      sha256: Effect.succeed(h.VMALERT.sha256),
+    };
+    const diff = h.run((p) =>
+      must(p.diff)({ ...ids, ...call, news: pending as never, olds: h.VMALERT as never, output }),
+    );
+    await expect(diff).rejects.toThrow('sha256 is required, as a plain string');
+    expect(h.requests).toEqual([]);
+  });
+
+  test('diff refuses a new pin at the same path', async () => {
+    const h = harness();
+    const output = await h.run((p) => h.reconcile(p, h.VMALERT));
+    const bumped: ReleaseBinaryProps = { ...h.VMALERT, sha256: 'e'.repeat(64) };
+    const diff = h.run((p) =>
+      must(p.diff)({ ...ids, ...call, news: bumped as never, olds: h.VMALERT as never, output }),
+    );
+    await expect(diff).rejects.toThrow('would overwrite it in place');
+  });
+});