@homeflare/alchemy 0.20.0 → 0.21.0

package/src/release/download.test.ts

@@ -0,0 +1,138 @@
+/**
+ * The download over a fake `HttpClient` — no network: status first, the body against the pinned
+ * size, bounded retries only where another attempt could help, and one download shared by the
+ * resources that need the same archive at the same time.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
+import * as HttpClientError from 'effect/unstable/http/HttpClientError';
+import * as HttpClientResponse from 'effect/unstable/http/HttpClientResponse';
+import { type FetchArchive, httpFetchArchive, sharingInFlight } from './download.ts';
+import { bytesOf } from './fake-release.ts';
+import { DownloadFailed } from './refused.ts';
+
+const URL_A = 'https://example.invalid/a.tar.gz';
+const FAST = { retries: 2, spacing: '1 millis', timeout: '5 seconds' } as const;
+
+/** A client that answers each request with the next scripted reply, recording every URL. */
+const scripted = (...replies: Array<{ status: number; body?: Uint8Array }>) => {
+  const urls: string[] = [];
+  const client = HttpClient.make((request, url) => {
+    urls.push(url.toString());
+    const reply = replies[Math.min(urls.length, replies.length) - 1] ?? { status: 599 };
+    const body = reply.body === undefined ? null : new Blob([reply.body.slice()]);
+    return Effect.succeed(
+      HttpClientResponse.fromWeb(request, new Response(body, { status: reply.status })),
+    );
+  });
+  return { fetch: httpFetchArchive(client, FAST), urls };
+};
+
+const failure = async (promise: Promise<unknown>): Promise<DownloadFailed> => {
+  try {
+    await promise;
+  } catch (cause) {
+    expect(cause).toBeInstanceOf(DownloadFailed);
+    return cause as DownloadFailed;
+  }
+  throw new Error('expected DownloadFailed');
+};
+
+describe('downloadPinned', () => {
+  test('200 with exactly the pinned size: the bytes', async () => {
+    const body = bytesOf('archive');
+    const { fetch, urls } = scripted({ body, status: 200 });
+    expect(await fetch(URL_A, body.length)).toEqual(body);
+    expect(urls).toEqual([URL_A]);
+  });
+
+  test('404 is final: one request, not retried', async () => {
+    const { fetch, urls } = scripted({ status: 404 });
+    const error = await failure(fetch(URL_A, 7));
+    expect(error.message).toContain('HTTP 404');
+    expect(error.retryable).toBe(false);
+    expect(urls.length).toBe(1);
+  });
+
+  test('a 5xx is retried, twice and no more', async () => {
+    const { fetch, urls } = scripted({ status: 503 });
+    expect((await failure(fetch(URL_A, 7))).message).toContain('HTTP 503');
+    expect(urls.length).toBe(3);
+  });
+
+  test('a 5xx then a good answer succeeds', async () => {
+    const body = bytesOf('archive');
+    const { fetch, urls } = scripted({ status: 502 }, { body, status: 200 });
+    expect(await fetch(URL_A, body.length)).toEqual(body);
+    expect(urls.length).toBe(2);
+  });
+
+  test('a body longer than the pin is cut off and refused, not retried', async () => {
+    const { fetch, urls } = scripted({ body: bytesOf('x'.repeat(100)), status: 200 });
+    expect((await failure(fetch(URL_A, 10))).message).toContain('runs past the pinned 10 bytes');
+    expect(urls.length).toBe(1);
+  });
+
+  test('a short body is refused (and retried, as a cut-off transfer)', async () => {
+    const { fetch, urls } = scripted({ body: bytesOf('abc'), status: 200 });
+    expect((await failure(fetch(URL_A, 10))).message).toContain('3 bytes, the pin says 10');
+    expect(urls.length).toBe(3);
+  });
+
+  test('a transport failure is a DownloadFailed with the reason, retried', async () => {
+    const urls: string[] = [];
+    const client = HttpClient.make((request, url) => {
+      urls.push(url.toString());
+      const reason = new HttpClientError.TransportError({
+        description: 'connection reset',
+        request,
+      });
+      return Effect.fail(new HttpClientError.HttpClientError({ reason }));
+    });
+    const error = await failure(httpFetchArchive(client, FAST)(URL_A, 7));
+    expect(error.message).toContain('connection reset');
+    expect(error.retryable).toBe(true);
+    expect(urls.length).toBe(3);
+  });
+
+  test('no answer in time is final', async () => {
+    const client = HttpClient.make(() => Effect.never);
+    const fetch = httpFetchArchive(client, { ...FAST, timeout: '20 millis' });
+    expect((await failure(fetch(URL_A, 7))).message).toContain('no complete response in time');
+  });
+});
+
+describe('sharingInFlight', () => {
+  test('two requests for one archive at once share one download; a later one downloads again', async () => {
+    let calls = 0;
+    let release: (bytes: Uint8Array) => void = () => undefined;
+    const slow: FetchArchive = () => {
+      calls += 1;
+      return new Promise((resolve) => {
+        release = resolve;
+      });
+    };
+    const fetch = sharingInFlight(slow);
+    const first = fetch(URL_A, 3);
+    const second = fetch(URL_A, 3);
+    release(bytesOf('abc'));
+    expect(await first).toBe(await second);
+    expect(calls).toBe(1);
+    const third = fetch(URL_A, 3);
+    release(bytesOf('abc'));
+    await third;
+    expect(calls).toBe(2);
+  });
+
+  test('a failed download is not cached', async () => {
+    let calls = 0;
+    const fetch = sharingInFlight(async () => {
+      calls += 1;
+      throw new DownloadFailed({ message: 'nope', retryable: false });
+    });
+    await expect(fetch(URL_A, 1)).rejects.toBeInstanceOf(DownloadFailed);
+    await expect(fetch(URL_A, 1)).rejects.toBeInstanceOf(DownloadFailed);
+    expect(calls).toBe(2);
+  });
+});

package/src/release/download.ts

@@ -0,0 +1,110 @@
+/**
+ * One pinned release archive over Effect's `HttpClient`: status first, then the body read against
+ * the pinned size, into memory.
+ *
+ * ★ `HttpClient`, THE HOUSE TRANSPORT (openbao/bao-http.ts, decided 2026-09-14) and Alchemy's own:
+ *   a typed error channel, interruption, and a client a test swaps for a fake. releaseProviders()
+ *   provides `FetchHttpClient.layer` itself, so a host stack that has no HTTP layer yet (the Mac
+ *   stack's has none) cannot forget it. ⚠️ fetch follows GitHub's 302 to its asset CDN (measured
+ *   2026-09-22 with HEAD: a signed, expiring URL), so the status judged here is the CDN's.
+ * ★ THE PINNED SIZE BOUNDS MEMORY. A body that runs past it is cut off at that byte, so a
+ *   misbehaving server or a swapped asset cannot stream an unbounded file into the deploy.
+ * ★ NO API CALL. The browser-download URL needs no token and spends no API rate limit; the pins
+ *   say everything the release API would.
+ * ⚠️ IN MEMORY: vmutils is 123.6 MB. Nothing is staged on disk, so no failure leaves a file behind.
+ */
+import type * as Duration from 'effect/Duration';
+import * as Effect from 'effect/Effect';
+import * as Schedule from 'effect/Schedule';
+import * as Stream from 'effect/Stream';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
+import { DownloadFailed } from './refused.ts';
+
+/** The provider's view of a transport: an archive's bytes by URL, never longer than `size`. */
+export type FetchArchive = (url: string, size: number) => Promise<Uint8Array>;
+
+/** How patient a download is. ★ Parameters so a test never waits for real. */
+export type DownloadPolicy = {
+  /** @default '10 minutes' — 123.6 MB on a slow link, and still a bounded wait. */
+  readonly timeout?: Duration.Input;
+  /** Retries after the first attempt, transport failures and 5xx only. @default 2 */
+  readonly retries?: number;
+  /** @default '2 seconds' */
+  readonly spacing?: Duration.Input;
+};
+
+const failed = (message: string, retryable: boolean) => new DownloadFailed({ message, retryable });
+
+const attempt = (url: string, size: number) =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient;
+    const response = yield* client.get(url);
+    if (response.status !== 200) {
+      return yield* failed(`${url}: HTTP ${String(response.status)}`, response.status >= 500);
+    }
+    // ★ ONE BUFFER OF THE PINNED SIZE, filled in place: no chunk list and no concatenating copy,
+    //   so the archive costs its own size in memory and not twice it.
+    const archive = new Uint8Array(size);
+    let total = 0;
+    yield* Stream.runForEach(response.stream, (chunk) => {
+      if (total + chunk.length > size) {
+        return Effect.fail(failed(`${url}: runs past the pinned ${String(size)} bytes`, false));
+      }
+      archive.set(chunk, total);
+      total += chunk.length;
+      return Effect.void;
+    });
+    if (total !== size) {
+      return yield* failed(`${url}: ${String(total)} bytes, the pin says ${String(size)}`, true);
+    }
+    return archive;
+  }).pipe(
+    // ⛔ `.message` only: it carries the reason, method and URL, and nothing else goes to the log.
+    Effect.catchTag('HttpClientError', (cause) => Effect.fail(failed(cause.message, true))),
+  );
+
+/** The archive's bytes, exactly `size` of them, or DownloadFailed. */
+export const downloadPinned = (
+  url: string,
+  size: number,
+  policy: DownloadPolicy = {},
+): Effect.Effect<Uint8Array, DownloadFailed, HttpClient.HttpClient> =>
+  attempt(url, size).pipe(
+    Effect.timeoutOrElse({
+      duration: policy.timeout ?? '10 minutes',
+      orElse: () => Effect.fail(failed(`${url}: no complete response in time`, false)),
+    }),
+    Effect.retry({
+      schedule: Schedule.spaced(policy.spacing ?? '2 seconds'),
+      times: policy.retries ?? 2,
+      while: (error: DownloadFailed) => error.retryable,
+    }),
+  );
+
+/** A FetchArchive over one HttpClient. ⚠️ Rejects with the DownloadFailed itself. */
+export const httpFetchArchive =
+  (client: HttpClient.HttpClient, policy: DownloadPolicy = {}): FetchArchive =>
+  (url, size) =>
+    Effect.runPromise(
+      downloadPinned(url, size, policy).pipe(Effect.provideService(HttpClient.HttpClient, client)),
+    );
+
+/**
+ * ★ ONE DOWNLOAD PER ARCHIVE AT A TIME, NOT ONE PER BINARY. vmagent and vmalert are two resources
+ *   in one 123.6 MB archive, and Alchemy reconciles independent resources concurrently (its fan-out
+ *   is unbounded, Apply.ts), so two requests for one URL share the download already in flight.
+ *   The entry goes when it settles: a later request downloads again rather than pinning 123 MB in
+ *   memory for the rest of the deploy.
+ * ⚠️ The buffer is shared, so nothing downstream may write into it (archive.ts only reads).
+ */
+export const sharingInFlight = (fetch: FetchArchive): FetchArchive => {
+  const inFlight = new Map<string, Promise<Uint8Array>>();
+  return (url, size) => {
+    const key = `${String(size)} ${url}`;
+    const running = inFlight.get(key);
+    if (running !== undefined) return running;
+    const started = fetch(url, size).finally(() => inFlight.delete(key));
+    inFlight.set(key, started);
+    return started;
+  };
+};

package/src/release/error-channel.test.ts

@@ -0,0 +1,69 @@
+/**
+ * What a caller can actually catch from Release.Binary — MEASURED, so docs/release-binary-upstream.md
+ * cannot claim more than is true. (The upstream-lens review of 2026-09-22 found it claiming
+ * "callers can `catchTag`"; neither path below allows it.)
+ *
+ * ⚠️ catalogBinary() THROWS. In a stack program (`Effect.gen`) its BinaryRefused is therefore a
+ *   DEFECT, not a typed failure: `Effect.catchTag('BinaryRefused')` never sees it. The plan still
+ *   fails before anything is fetched — the house guarantee holds — but the error is not typed.
+ * ⚠️ THE PROVIDER'S CHANNEL IS `Error`. Every lifecycle call goes through the house `lift()`
+ *   (launchd/host-effect.ts), which keeps the tagged instance at runtime but types the channel as
+ *   plain `Error`, so no caller can name a tag without a cast — which upstream's AGENTS.md forbids.
+ * ★ WHEN EITHER BECOMES TYPED, THIS FILE FAILS FIRST: the defect assertions flip, or the
+ *   `@ts-expect-error` below becomes unused and `tsc` refuses it. Update the upstream page with it.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Cause from 'effect/Cause';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import { lift } from '../launchd/host-effect.ts';
+import { catalogBinary } from './catalog.ts';
+import { BinaryRefused, ChecksumMismatch } from './refused.ts';
+import { VICTORIA_RELEASES } from './victoria.ts';
+
+const UNPINNED = {
+  binary: 'vmalert',
+  package: 'vmutils',
+  platform: 'darwin-arm64',
+  version: '1.152.0',
+};
+
+describe('the stack program: catalogBinary', () => {
+  test('a refusal fails the program as a defect carrying BinaryRefused, not a typed failure', async () => {
+    // The shape of a stack program: it yields its resources, and calls catalogBinary() plainly.
+    const program = Effect.gen(function* () {
+      yield* Effect.void;
+      return catalogBinary(VICTORIA_RELEASES, UNPINNED);
+    });
+    const exit = await Effect.runPromiseExit(program);
+    expect(Exit.isFailure(exit)).toBe(true);
+    if (!Exit.isFailure(exit)) return;
+    expect(Cause.hasFails(exit.cause)).toBe(false);
+    expect(Cause.hasDies(exit.cause)).toBe(true);
+    expect(Cause.squash(exit.cause)).toBeInstanceOf(BinaryRefused);
+  });
+});
+
+describe('the provider: lift()', () => {
+  const mismatch = new ChecksumMismatch({
+    actual: '0'.repeat(64),
+    expected: '1'.repeat(64),
+    message: 'Release.Binary /x/y: hashes wrong. Nothing was written.',
+    subject: 'member "y"',
+  });
+
+  test('the tagged instance survives at runtime, as a failure', async () => {
+    const exit = await Effect.runPromiseExit(lift(() => Promise.reject(mismatch)));
+    expect(Exit.isFailure(exit)).toBe(true);
+    if (!Exit.isFailure(exit)) return;
+    expect(Cause.hasFails(exit.cause)).toBe(true);
+    expect(Cause.squash(exit.cause)).toBe(mismatch);
+  });
+
+  test('but the channel is typed `Error`, so a tag cannot be named without a cast', () => {
+    const lifted = lift(() => Promise.reject(mismatch));
+    // @ts-expect-error — lift() erases the tag union to `Error`; see the file header.
+    const caught = Effect.catchTag(lifted, 'ChecksumMismatch', () => Effect.succeed('caught'));
+    expect(Effect.isEffect(caught)).toBe(true);
+  });
+});

package/src/release/fake-deploy.ts

@@ -0,0 +1,87 @@
+/**
+ * Release.Binary and HostDirectory deployed through Alchemy's OWN Plan and Apply
+ * (openbao/fake-stack.ts, in-memory state), over a fake host (linux/fake-linux-host.ts) and a fake
+ * server holding the synthetic vmutils archive at its real URL. `events` is every host change and
+ * request, in order; `serving = false` answers every request 404.
+ *
+ * ⛔ TEST-ONLY, like fake-release.ts: no provider imports it and it is not on the barrel.
+ */
+import { renamedFrom } from 'alchemy/Rename';
+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 { 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 type { ReleaseBinaryProps } from './binary-form.ts';
+import { ReleaseBinary, makeReleaseBinaryProvider } from './binary.ts';
+import { catalogBinary } from './catalog.ts';
+import { VMALERT_REQUEST, VMUTILS_URL, bytesOf, syntheticRelease } from './fake-release.ts';
+
+export const ROOT = '/opt/example/bin';
+export const DIR = `${ROOT}/vmutils-1.151.0`;
+export const PATH = `${DIR}/vmalert`;
+export const THEIRS = bytesOf('#!someone else built this vmalert\n');
+
+/** One fake host (with DIR already there when `dirExists`), one fake server, one stack. */
+export const deployHarness = (dirExists: boolean) => {
+  const release = syntheticRelease();
+  const pins = catalogBinary(release.catalog, VMALERT_REQUEST);
+  const fake = fakeLinuxHost({
+    dirs: dirExists ? { [DIR]: 0, [ROOT]: 0 } : { [ROOT]: 0 },
+    euid: 0,
+  });
+  const events: string[] = [];
+  const server = { serving: true };
+  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 found = server.serving && url.toString() === VMUTILS_URL;
+    const body = found ? new Blob([release.vmutils.slice()]) : null;
+    return Effect.succeed(
+      HttpClientResponse.fromWeb(request, new Response(body, { status: found ? 200 : 404 })),
+    );
+  });
+  const providers = Layer.mergeAll(makeReleaseBinaryProvider(), HostDirectoryProvider()).pipe(
+    Layer.provide(
+      Layer.mergeAll(hostRunnerLayer(runner), Layer.succeed(HttpClient.HttpClient, client)),
+    ),
+  );
+  const place = (bytes: Uint8Array, mode = 0o755, kind: 'file' | 'symlink' = 'file') =>
+    fake.files.set(PATH, { bytes, gid: 0, kind, mode, uid: 0 });
+  /** The binary declared with the directory as a literal, so Alchemy probes it. */
+  const literal = ReleaseBinary('vmalert', { ...pins, directory: DIR });
+  /** The documented shape: the directory is HostDirectory's `path`, an Output at a first plan. */
+  const wired = (
+    id = 'vmalert',
+    dirMode = 0o755,
+    formerId?: string,
+    more: Partial<ReleaseBinaryProps> = {},
+  ) =>
+    Effect.gen(function* () {
+      const dir = yield* HostDirectory('dir', { mode: dirMode, path: DIR });
+      const binary = ReleaseBinary(id, { ...pins, ...more, directory: dir.path });
+      yield* formerId === undefined ? binary : binary.pipe(renamedFrom(formerId));
+    });
+  /** The directory alone: the binary's declaration removed. */
+  const dirOnly = HostDirectory('dir', { mode: 0o755, path: DIR });
+  const stack = fakeStack(providers, {}, 'ReleaseStack');
+  return { dirOnly, events, fake, literal, place, server, stack, wired };
+};

package/src/release/fake-engine.ts

@@ -0,0 +1,50 @@
+/**
+ * Release.Binary through Alchemy's own Plan and Apply (openbao/fake-stack.ts) over the REAL
+ * localRunner, for tests that need what a fake host cannot model: two spellings of one file, and
+ * the engine's order across resources. The HTTP server is a fake serving the synthetic vmutils.
+ *
+ * ⛔ TEST-ONLY, like fake-release.ts: no provider imports it and it is not on the barrel. Every
+ *   directory a test passes must be under its own `mkdtemp`; nothing here chooses a path.
+ */
+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 { localRunner } from '../launchd/local-runner.ts';
+import { hostRunnerLayer } from '../launchd/runner.ts';
+import { fakeStack } from '../openbao/fake-stack.ts';
+import { ReleaseBinary, makeReleaseBinaryProvider } from './binary.ts';
+import { catalogBinary } from './catalog.ts';
+import { BINARY, VMALERT_REQUEST, VMUTILS_URL, syntheticRelease } from './fake-release.ts';
+
+/** vmalert's bytes as text, to compare with what a test reads off the disk. */
+export const VMALERT_TEXT = new TextDecoder().decode(BINARY.vmalert);
+
+/** One stack over localRunner; `deploy` takes logical id → directory; `gets` counts downloads. */
+export const realEngine = () => {
+  const { catalog, vmutils } = syntheticRelease();
+  const gets: string[] = [];
+  const client = HttpClient.make((request, url) => {
+    gets.push(url.toString());
+    const body = url.toString() === VMUTILS_URL ? new Blob([vmutils.slice()]) : null;
+    return Effect.succeed(
+      HttpClientResponse.fromWeb(request, new Response(body, { status: body ? 200 : 404 })),
+    );
+  });
+  const providers = makeReleaseBinaryProvider().pipe(
+    Layer.provide(
+      Layer.mergeAll(hostRunnerLayer(localRunner()), Layer.succeed(HttpClient.HttpClient, client)),
+    ),
+  );
+  const stack = fakeStack(providers, {}, 'RealEngineStack');
+  const pins = catalogBinary(catalog, VMALERT_REQUEST);
+  const deploy = (binaries: Readonly<Record<string, string>>) =>
+    stack.deploy(
+      Effect.gen(function* () {
+        for (const [id, directory] of Object.entries(binaries)) {
+          yield* ReleaseBinary(id, { ...pins, directory });
+        }
+      }),
+    );
+  return { deploy, gets };
+};

package/src/release/fake-install.ts

@@ -0,0 +1,59 @@
+/**
+ * The install lifecycle's test bench: a fake host, a synthetic release served at the REAL URLs next
+ * to an `-enterprise` decoy, and `refused()`, which asserts a refusal left the host exactly as it
+ * was and wrote nothing.
+ *
+ * ⛔ TEST-ONLY, like fake-release.ts: no provider imports it and it is not on the barrel.
+ */
+import { expect } from 'bun:test';
+import type { ReleaseBinaryProps } from './binary-form.ts';
+import { reconcileBinary } from './binary-lifecycle.ts';
+import {
+  ENTERPRISE_URL,
+  TRACES_URL,
+  VMUTILS_DIR,
+  VMUTILS_ENTRIES,
+  VMUTILS_URL,
+  bytesOf,
+  fakeTransport,
+  gzip,
+  pathsOn,
+  releaseHost,
+  syntheticRelease,
+  tarOf,
+  vmalertProps,
+} from './fake-release.ts';
+
+export const PATH = `${VMUTILS_DIR}/vmalert`;
+export const writes = (fake: ReturnType<typeof releaseHost>) =>
+  fake.calls.filter((c) => c[0] === 'write');
+
+/** A host, a synthetic release served at the real URLs (plus an enterprise decoy), and a runner. */
+export const setup = (entries = VMUTILS_ENTRIES) => {
+  const { catalog, traces, vmutils } = syntheticRelease(entries);
+  const decoy = gzip(tarOf([{ bytes: bytesOf('#!enterprise\n'), name: 'vmalert-prod' }]));
+  const transport = fakeTransport({
+    [ENTERPRISE_URL]: decoy,
+    [TRACES_URL]: traces,
+    [VMUTILS_URL]: vmutils,
+  });
+  const fake = releaseHost();
+  const props = (more: Partial<ReleaseBinaryProps> = {}) => vmalertProps(catalog, more);
+  const install = (declared = props(), options = {}) =>
+    reconcileBinary(fake.runner, transport.fetch, declared, options);
+  return { fake, install, props, transport };
+};
+
+/** Run a refusal; return it, having checked the host is exactly as it was and nothing was written. */
+export const refused = async (s: ReturnType<typeof setup>, run: () => Promise<unknown>) => {
+  const before = pathsOn(s.fake);
+  const error = await run().then(
+    () => {
+      throw new Error('expected a refusal');
+    },
+    (cause: unknown) => cause,
+  );
+  expect(pathsOn(s.fake)).toEqual(before);
+  expect(writes(s.fake)).toEqual([]);
+  return error as Error;
+};

package/src/release/fake-provider.ts

@@ -0,0 +1,68 @@
+/**
+ * One Release.Binary provider over one fake host and one fake HTTP server, for the handler tests
+ * beside it: `requests` counts every URL asked, `notes` every `session.note`.
+ *
+ * ⛔ TEST-ONLY, like fake-release.ts: no provider imports it and it is not on the barrel.
+ */
+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 { hostRunnerLayer } from '../launchd/runner.ts';
+import { ReleaseBinary, makeReleaseBinaryProvider } from './binary.ts';
+import {
+  VMUTILS_DIR,
+  VMUTILS_URL,
+  releaseHost,
+  syntheticRelease,
+  vmalertProps,
+} from './fake-release.ts';
+
+export const ids = { fqn: 'stack/vmalert', id: 'vmalert', instanceId: 'i-1' };
+export const call = { bindings: [] as never, newBindings: [] as never, oldBindings: [] as never };
+export const PATH = `${VMUTILS_DIR}/vmalert`;
+
+export type Service = Effect.Success<typeof ReleaseBinary.Provider>;
+
+/** One provider over one fake host and one fake HTTP server; `requests` counts every URL asked. */
+export const harness = () => {
+  const release = syntheticRelease();
+  const VMALERT = vmalertProps(release.catalog);
+  const fake = releaseHost();
+  const requests: string[] = [];
+  const notes: string[] = [];
+  const client = HttpClient.make((request, url) => {
+    requests.push(url.toString());
+    const body = url.toString() === VMUTILS_URL ? new Blob([release.vmutils.slice()]) : null;
+    return Effect.succeed(
+      HttpClientResponse.fromWeb(request, new Response(body, { status: body ? 200 : 404 })),
+    );
+  });
+  const layer = makeReleaseBinaryProvider().pipe(
+    Layer.provide(
+      Layer.mergeAll(hostRunnerLayer(fake.runner), Layer.succeed(HttpClient.HttpClient, client)),
+    ),
+  );
+  const session = { note: (m: string) => Effect.sync(() => void notes.push(m)) } as never;
+  const run = <A>(use: (p: Service) => Effect.Effect<A, unknown>) =>
+    Effect.runPromise(
+      Effect.gen(function* () {
+        return yield* use(yield* ReleaseBinary.Provider);
+      }).pipe(Effect.provide(layer)) as Effect.Effect<A>,
+    );
+  const reconcile = (p: Service, news: object, output?: unknown, olds?: object) =>
+    p.reconcile({
+      ...ids,
+      ...call,
+      news: news as never,
+      olds: olds as never,
+      output: output as never,
+      session,
+    });
+  return { VMALERT, fake, notes, reconcile, release, requests, run };
+};
+
+export const must = <F>(fn: F | undefined): F => {
+  if (fn === undefined) throw new Error('provider has no such handler');
+  return fn;
+};