@homeflare/alchemy 0.20.0 → 0.21.0

package/src/release/fake-release.ts

@@ -0,0 +1,185 @@
+/**
+ * Synthetic release archives for the tests beside it: a tar writer, gzip, a catalog pinned to what
+ * they build, a counting transport, and a host with the versioned directories in place.
+ *
+ * ⛔ TEST-ONLY. No provider imports this file, it is not on the barrel, and nothing here reaches a
+ *   network or a real filesystem. The catalog is synthetic because a test cannot build bytes that
+ *   hash to the vendor's pins; victoria.test.ts holds the REAL data set to the vendor's own files.
+ * ★ THE ASSET NAMES AND URLS ARE THE REAL ONES, so a test that serves the `-enterprise` sibling
+ *   next to the plain archive proves the provider asks for exactly one of them.
+ */
+import { fakeRunner } from '../launchd/fake-runner.ts';
+import { sha256Hex } from '../launchd/job-form.ts';
+import { type ReleaseBinaryProps, releaseUrl } from './binary-form.ts';
+import { type PinnedArchive, type ReleaseCatalog, catalogBinary } from './catalog.ts';
+import type { FetchArchive } from './download.ts';
+import { DownloadFailed } from './refused.ts';
+import { VICTORIA_RELEASES } from './victoria.ts';
+
+export type TarEntry = {
+  readonly name: string;
+  readonly bytes?: Uint8Array;
+  /** The typeflag: '0' regular (default), '1' hard link, '2' symlink, '5' directory, 'L', 'x', … */
+  readonly type?: string;
+  readonly format?: 'gnu' | 'posix';
+  readonly prefix?: string;
+  /** Size field written as GNU base-256. */
+  readonly base256?: boolean;
+  readonly corruptChecksum?: boolean;
+};
+
+const put = (block: Uint8Array, at: number, text: string) =>
+  block.set(new TextEncoder().encode(text), at);
+const octal = (value: number, width: number) => `${value.toString(8).padStart(width - 1, '0')}\0`;
+
+export const tarHeader = (entry: TarEntry): Uint8Array => {
+  const block = new Uint8Array(512);
+  const size = entry.bytes?.length ?? 0;
+  put(block, 0, entry.name);
+  put(block, 100, octal(0o755, 8));
+  put(block, 108, octal(1000, 8));
+  put(block, 116, octal(1000, 8));
+  if (entry.base256 === true) block.set([0x80, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, size], 124);
+  else put(block, 124, octal(size, 12));
+  put(block, 136, octal(1_750_000_000, 12));
+  block.fill(0x20, 148, 156);
+  put(block, 156, entry.type ?? '0');
+  put(block, 257, entry.format === 'posix' ? 'ustar\u000000' : 'ustar  \u0000');
+  if (entry.prefix !== undefined) put(block, 345, entry.prefix);
+  const sum = block.reduce((total, byte) => total + byte, 0) + (entry.corruptChecksum ? 1 : 0);
+  put(block, 148, `${sum.toString(8).padStart(6, '0')}\0 `);
+  return block;
+};
+
+/** A tar: each header, its data padded to 512, then the two zero blocks. */
+export const tarOf = (entries: readonly TarEntry[], end = 1024): Uint8Array => {
+  const blocks: Uint8Array[] = [];
+  for (const entry of entries) {
+    blocks.push(tarHeader(entry));
+    const bytes = entry.bytes ?? new Uint8Array();
+    const padded = new Uint8Array(Math.ceil(bytes.length / 512) * 512);
+    padded.set(bytes);
+    blocks.push(padded);
+  }
+  blocks.push(new Uint8Array(end));
+  const out = new Uint8Array(blocks.reduce((total, block) => total + block.length, 0));
+  let at = 0;
+  for (const block of blocks) {
+    out.set(block, at);
+    at += block.length;
+  }
+  return out;
+};
+
+export const gzip = (bytes: Uint8Array): Uint8Array => Bun.gzipSync(bytes.slice());
+
+export const bytesOf = (text: string): Uint8Array => new TextEncoder().encode(text);
+
+/** Stand-ins for the vendor binaries: distinct bytes, so each digest is distinct. */
+export const BINARY = {
+  vmagent: bytesOf('#!fake vmagent 1.151.0\n'),
+  vmalert: bytesOf('#!fake vmalert 1.151.0\n'),
+  vmauth: bytesOf('#!fake vmauth 1.151.0\n'),
+  'victoria-traces': bytesOf('#!fake victoria-traces 0.10.0\n'),
+};
+
+const present = (archive: PinnedArchive | undefined): PinnedArchive => {
+  if (archive === undefined) throw new Error('the data set lost a pinned archive');
+  return archive;
+};
+const REAL = VICTORIA_RELEASES.packages;
+export const VMUTILS = present(REAL.vmutils?.versions['1.151.0']?.['darwin-arm64']);
+export const TRACES = present(REAL['victoria-traces']?.versions['0.10.0']?.['darwin-arm64']);
+export const urlOf = (archive: PinnedArchive): string =>
+  releaseUrl(archive.repo, archive.tag, archive.asset);
+export const VMUTILS_URL = urlOf(VMUTILS);
+export const TRACES_URL = urlOf(TRACES);
+export const ENTERPRISE_URL = VMUTILS_URL.replace('.tar.gz', '-enterprise.tar.gz');
+
+export const VMUTILS_ENTRIES: readonly TarEntry[] = [
+  { bytes: BINARY.vmagent, name: 'vmagent-prod' },
+  { bytes: BINARY.vmalert, name: 'vmalert-prod' },
+  { bytes: BINARY.vmauth, name: 'vmauth-prod' },
+];
+
+/** Pin an archive the way victoria.ts pins a vendor one, from the bytes themselves. */
+export const pinned = (
+  real: PinnedArchive,
+  archive: Uint8Array,
+  members: Readonly<Record<string, Uint8Array>>,
+): PinnedArchive => ({
+  ...real,
+  members: Object.fromEntries(Object.entries(members).map(([n, b]) => [n, sha256Hex(b)])),
+  sha256: sha256Hex(archive),
+  size: archive.length,
+});
+
+/** The real data set with vmutils 1.151.0 and victoria-traces 0.10.0 re-pinned to synthetic bytes. */
+export const syntheticRelease = (vmutilsEntries: readonly TarEntry[] = VMUTILS_ENTRIES) => {
+  const vmutils = gzip(tarOf(vmutilsEntries));
+  const traces = gzip(tarOf([{ bytes: BINARY['victoria-traces'], name: 'victoria-traces-prod' }]));
+  // ★ vmalert-prod is always pinned, as the vendor file lists it — so an archive built WITHOUT it
+  //   models "the checksum file names a member the archive does not hold".
+  const memberBytes = {
+    'vmalert-prod': BINARY.vmalert,
+    ...Object.fromEntries(vmutilsEntries.map((e) => [e.name, e.bytes ?? new Uint8Array()])),
+  };
+  const tracesPin = pinned(TRACES, traces, { 'victoria-traces-prod': BINARY['victoria-traces'] });
+  const catalog: ReleaseCatalog = {
+    ...VICTORIA_RELEASES,
+    packages: {
+      ...REAL,
+      'victoria-traces': {
+        binaries: { 'victoria-traces': 'victoria-traces-prod' },
+        versions: { '0.10.0': { 'darwin-arm64': tracesPin } },
+      },
+      vmutils: {
+        binaries: REAL.vmutils?.binaries ?? {},
+        versions: { '1.151.0': { 'darwin-arm64': pinned(VMUTILS, vmutils, memberBytes) } },
+      },
+    },
+  };
+  return { catalog, traces, vmutils };
+};
+
+/** A transport over a URL → bytes table that records every request, in order. */
+export const fakeTransport = (served: Readonly<Record<string, Uint8Array>>) => {
+  const requests: string[] = [];
+  const fetch: FetchArchive = async (url) => {
+    requests.push(url);
+    const bytes = served[url];
+    if (bytes === undefined)
+      throw new DownloadFailed({ message: `${url}: HTTP 404`, retryable: false });
+    return bytes;
+  };
+  return { fetch, requests };
+};
+
+export const ROOT = '/opt/example/bin';
+export const VMUTILS_DIR = `${ROOT}/vmutils-1.151.0`;
+export const TRACES_DIR = `${ROOT}/victoria-traces-0.10.0`;
+
+/** A host deploying as root, with the two versioned directories already declared. */
+export const releaseHost = () =>
+  fakeRunner({ dirs: { [ROOT]: 0, [TRACES_DIR]: 0, [VMUTILS_DIR]: 0 }, euid: 0 });
+
+export const VMALERT_REQUEST = {
+  binary: 'vmalert',
+  package: 'vmutils',
+  platform: 'darwin-arm64',
+  version: '1.151.0',
+} as const;
+
+/** vmalert's props out of `catalog` (the synthetic one, normally), in its versioned directory. */
+export const vmalertProps = (
+  catalog: ReleaseCatalog,
+  more: Partial<ReleaseBinaryProps> = {},
+): ReleaseBinaryProps => ({
+  ...catalogBinary(catalog, VMALERT_REQUEST),
+  directory: VMUTILS_DIR,
+  ...more,
+});
+
+/** Every path on the fake host, sorted — equal before and after means nothing was left behind. */
+export const pathsOn = (fake: ReturnType<typeof fakeRunner>): string[] =>
+  [...fake.files.keys()].sort();

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,41 @@
+/**
+ * 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,
+  IdentifiedBinary,
+  PinnedArchive,
+  PinnedBinary,
+  ReleaseCatalog,
+} from './catalog.ts';
+export { catalogBinary, catalogDirectory, catalogProblems, identifyBinary } from './catalog.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/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');
+  });
+});