@homeflare/alchemy 0.19.1 → 0.21.0

package/src/release/catalog.ts

@@ -0,0 +1,175 @@
+/**
+ * A vendor's pinned releases as DATA, and the one way to turn an entry into Release.Binary props —
+ * or into the reasons there is none. Pure: no network, no host.
+ *
+ * ★ THE DATA SITS BESIDE THE RESOURCE, NOT INSIDE IT. A catalog (victoria.ts is the first) is the
+ *   reviewed record of what one vendor published: exact asset names, sizes, both digest layers and
+ *   where each was copied from. The resource takes one pinned archive as props and never reads a
+ *   catalog, so adding a vendor is a data module with its own walk-down, never a resource change.
+ * ★ A VERSION THE CATALOG DOES NOT LIST IS A REFUSAL, NOT A DOWNLOAD ATTEMPT. `catalogBinary()` runs
+ *   in the stack's own program — which `alchemy plan` evaluates — so an unknown version, a
+ *   `-enterprise` spelling or a `v` prefix fails the plan before any resource is asked anything,
+ *   let alone fetches a byte.
+ * ⛔ ADD A VENDOR ONLY AFTER ITS OWN WALK-DOWN (docs/release-binary-catalogs.md): its checksum
+ *   format read byte-exact, and its binary's linkage measured (`otool -L`). Vendor binaries were
+ *   measured self-contained ONLY for the five Victoria ones; that is not a property of "Go".
+ */
+import type { ReleaseArchive, ReleaseBinaryProps } from './binary-form.ts';
+import { BinaryRefused } from './refused.ts';
+
+/** One release archive as a catalog records it: the pin, plus where every digest came from. */
+export interface PinnedArchive extends ReleaseArchive {
+  /** Archive member → its SHA-256. Every member the vendor's checksum file lists, not just ours. */
+  readonly members: Readonly<Record<string, string>>;
+  /** The checksum file the digests were copied from, its own SHA-256, and when. Never fetched. */
+  readonly checksums: { readonly url: string; readonly sha256: string; readonly recorded: string };
+}
+
+/** One package (one archive per version and platform) of a vendor. */
+export interface CatalogPackage {
+  /**
+   * Installed name → archive member, written out, never derived: a member the vendor adds is
+   * installable only once somebody names it here.
+   */
+  readonly binaries: Readonly<Record<string, string>>;
+  /** Version (as the catalog spells it) → platform (the vendor's spelling) → archive. */
+  readonly versions: Readonly<Record<string, Readonly<Record<string, PinnedArchive>>>>;
+}
+
+/** A vendor's pinned releases. */
+export interface ReleaseCatalog {
+  /** Who publishes these, for refusals: `'VictoriaMetrics'`. */
+  readonly vendor: string;
+  readonly packages: Readonly<Record<string, CatalogPackage>>;
+}
+
+/** Which binary a stack asks a catalog for. */
+export type CatalogRequest = {
+  readonly package: string;
+  readonly version: string;
+  readonly platform: string;
+  /** The installed name — `vmalert`, not the member `vmalert-prod`. */
+  readonly binary: string;
+};
+
+/** The pinned half of Release.Binary's props; the stack adds `directory`, `mode` and owner. */
+export type PinnedBinary = Pick<ReleaseBinaryProps, 'archive' | 'member' | 'sha256' | 'name'>;
+
+const quoted = (names: Iterable<string>): string => [...names].map((n) => `"${n}"`).join(', ');
+
+// ★ A plain boolean, not a type guard: on a `Record<string, …>` a guard narrows the miss to `never`.
+const has = (record: object, key: string): boolean => Object.hasOwn(record, key);
+
+/** Everything wrong with a request against a catalog; empty when it resolves. */
+export const catalogProblems = (catalog: ReleaseCatalog, request: CatalogRequest): string[] => {
+  const entry = has(catalog.packages, request.package)
+    ? catalog.packages[request.package]
+    : undefined;
+  if (entry === undefined) {
+    return [
+      `${catalog.vendor} package "${request.package}" is not in the catalog (${quoted(Object.keys(catalog.packages))})`,
+    ];
+  }
+  const found: string[] = [];
+  if (!has(entry.binaries, request.binary)) {
+    // ⚠️ The vendor spelling is the likeliest mistake: the member is `vmalert-prod`, the binary
+    //   this installs is `vmalert`.
+    const member = Object.values(entry.binaries).includes(request.binary);
+    const hint = member ? ' (that is the archive member; name the installed binary)' : '';
+    found.push(
+      `${request.package} has no binary "${request.binary}"${hint}; it has ${quoted(Object.keys(entry.binaries))}`,
+    );
+  }
+  const platforms = has(entry.versions, request.version)
+    ? entry.versions[request.version]
+    : undefined;
+  if (platforms === undefined) {
+    found.push(
+      `${request.package} ${request.version} is not in the catalog (it pins ${quoted(Object.keys(entry.versions))}); ` +
+        'a new version is a reviewed change that pins its digests, never a download of whatever is there',
+    );
+    return found;
+  }
+  const archive = has(platforms, request.platform) ? platforms[request.platform] : undefined;
+  if (archive === undefined) {
+    found.push(
+      `${request.package} ${request.version} is not pinned for platform "${request.platform}" (${quoted(Object.keys(platforms))})`,
+    );
+  } else if (found.length === 0) {
+    const member = entry.binaries[request.binary] ?? '';
+    if (!has(archive.members, member)) {
+      found.push(
+        `${request.package} ${request.version}'s checksum file lists no member "${member}"`,
+      );
+    }
+  }
+  return found;
+};
+
+/**
+ * The pinned props for one binary out of a catalog. ⛔ Throws BinaryRefused for anything the
+ * catalog does not pin — in a stack program, that fails the plan before anything is fetched.
+ */
+export const catalogBinary = (catalog: ReleaseCatalog, request: CatalogRequest): PinnedBinary => {
+  const problems = catalogProblems(catalog, request);
+  // ⚠️ Own keys only: `packages.constructor` is Object's, and would read as a package.
+  const own = <V>(record: Readonly<Record<string, V>> | undefined, key: string): V | undefined =>
+    record !== undefined && has(record, key) ? record[key] : undefined;
+  const entry = own(catalog.packages, request.package);
+  const archive = own(own(entry?.versions, request.version), request.platform);
+  const member = own(entry?.binaries, request.binary);
+  const sha256 = member === undefined ? undefined : own(archive?.members, member);
+  if (
+    problems.length > 0 ||
+    archive === undefined ||
+    member === undefined ||
+    sha256 === undefined
+  ) {
+    throw new BinaryRefused({
+      message: `Release.Binary ${request.binary}: ${problems.join('; ')}. Nothing was fetched.`,
+    });
+  }
+  const { asset, repo, sha256: archiveSha256, size, tag } = archive;
+  return {
+    archive: { asset, repo, sha256: archiveSha256, size, tag },
+    member,
+    name: request.binary,
+    sha256,
+  };
+};
+
+/** `<root>/<package>-<version>`: one directory per version, so an upgrade is a new path. */
+export const catalogDirectory = (
+  root: string,
+  request: Pick<CatalogRequest, 'package' | 'version'>,
+): string => `${root}/${request.package}-${request.version}`;
+
+/** What a catalog says an installed binary is, found by its SHA-256 alone. */
+export type IdentifiedBinary = CatalogRequest & { readonly vendor: string };
+
+/**
+ * Name an installed file by its digest — never by running it. ★ IDENTITY BY SHA-256: the running
+ *   Nix victoria-traces reports an empty version (`vm_app_version{version=""}` on /metrics, measured
+ *   2026-09-22 — its build sets no buildinfo), a stamped build prints `-version` to STDERR, not
+ *   stdout (lib/buildinfo, read, not run), and executing a binary to learn what it is runs the very
+ *   bytes whose provenance is the question. A digest needs a read, nothing more.
+ */
+export const identifyBinary = (
+  catalogs: readonly ReleaseCatalog[],
+  sha256: string,
+): IdentifiedBinary | undefined => {
+  for (const catalog of catalogs) {
+    for (const [pkg, entry] of Object.entries(catalog.packages)) {
+      for (const [version, platforms] of Object.entries(entry.versions)) {
+        for (const [platform, archive] of Object.entries(platforms)) {
+          for (const [binary, member] of Object.entries(entry.binaries)) {
+            if (archive.members[member] === sha256) {
+              return { binary, package: pkg, platform, vendor: catalog.vendor, version };
+            }
+          }
+        }
+      }
+    }
+  }
+  return undefined;
+};

package/src/release/checksums.test.ts

@@ -0,0 +1,35 @@
+/**
+ * The checksum-file parser, held to the one format it was measured on (`sha256sum` text mode,
+ * 2026-09-22): anything else is a vendor change to read before a pin moves, so it throws.
+ */
+import { describe, expect, test } from 'bun:test';
+import { parseChecksums } from './checksums.ts';
+
+const line = `${'a'.repeat(64)}  vmagent-prod`;
+
+describe('parseChecksums is strict', () => {
+  test('the measured shape: name → digest, in file order', () => {
+    const text = `${'b'.repeat(64)}  vmutils.tar.gz\n${line}\n`;
+    expect([...parseChecksums(text).entries()]).toEqual([
+      ['vmutils.tar.gz', 'b'.repeat(64)],
+      ['vmagent-prod', 'a'.repeat(64)],
+    ]);
+  });
+
+  test.each([
+    ['CRLF endings', `${line}\r\n`],
+    ['a binary-mode marker', `${'a'.repeat(64)} *vmagent-prod\n`],
+    ['upper-case hex', `${'A'.repeat(64)}  vmagent-prod\n`],
+    ['a blank line', `${line}\n\n`],
+    ['no trailing newline', line],
+    ['a name listed twice', `${line}\n${line}\n`],
+    ['a path in a name', `${'a'.repeat(64)}  bin/vmagent-prod\n`],
+    ['an empty file', '\n'],
+    ['a tab for the two spaces', `${'a'.repeat(64)}\tvmagent-prod\n`],
+    ['one space', `${'a'.repeat(64)} vmagent-prod\n`],
+    ['a trailing space (a name that merely starts with another)', `${line} \n`],
+    ['a no-break space in the name', `${line}\u00a0-enterprise\n`],
+  ])('refuses %s', (_, text) => {
+    expect(() => parseChecksums(text)).toThrow();
+  });
+});

package/src/release/checksums.ts

@@ -0,0 +1,43 @@
+/**
+ * A vendor checksum file in `sha256sum` text mode, parsed strictly — the shape every pin in
+ * victoria.ts was copied from.
+ *
+ * ★ WHY PARSE A FILE THE PROVIDER NEVER FETCHES. The pins are the ground truth at apply; this is
+ *   the ground truth when a pin is WRITTEN. victoria.test.ts feeds it the exact bytes of all four
+ *   recorded files (fixtures/victoria/, each matching GitHub's digest of that asset AS READ on the
+ *   recorded date — no test re-reads it) and requires the catalog to equal what it reads, so a pin
+ *   typed by hand, a line missed, or a member added by the vendor is a failing test rather than a
+ *   trusted typo.
+ * ⛔ STRICT, BECAUSE THE FORMAT IS KNOWN. Measured 2026-09-22 on all four files: `sha256sum` text
+ *   mode — `<64 lowercase hex><two spaces><name>` per line, LF endings, a trailing newline, the
+ *   archive on line 1 and one `-prod` member per line after it. Anything else (a `*` binary-mode
+ *   marker, CRLF, upper-case hex, a blank line, a repeated name) is a refusal: a file that no longer
+ *   has this shape is a vendor change to read before any pin moves, not something to guess past.
+ * ⚠️ ONE FORMAT, MEASURED FOR ONE VENDOR. Other vendors list archives only (Prometheus, vector,
+ *   pyroscope, OpenBao — the estate census, 2026-09-22) or publish digests in JSON (grafana.com). A
+ *   catalog for one of them reads ITS format byte-exact first; nothing here is assumed to fit it.
+ */
+
+const LINE = /^([0-9a-f]{64}) {2}([^\s/]+)$/;
+
+/** Name → SHA-256, in file order. Throws, naming the line, on anything but the measured shape. */
+export const parseChecksums = (text: string): ReadonlyMap<string, string> => {
+  if (!text.endsWith('\n')) throw new Error('checksum file: no trailing newline');
+  const lines = text.slice(0, -1).split('\n');
+  const digests = new Map<string, string>();
+  for (const [index, line] of lines.entries()) {
+    const match = LINE.exec(line);
+    if (match === null) {
+      throw new Error(
+        `checksum file line ${String(index + 1)}: not "<sha256>  <name>": ${JSON.stringify(line)}`,
+      );
+    }
+    const [, digest = '', name = ''] = match;
+    if (digests.has(name)) {
+      throw new Error(`checksum file line ${String(index + 1)}: "${name}" is listed twice`);
+    }
+    digests.set(name, digest);
+  }
+  if (digests.size === 0) throw new Error('checksum file: no lines');
+  return digests;
+};

package/src/release/declared-pins.ts

@@ -0,0 +1,39 @@
+/**
+ * The pins as the STACK PROGRAM declared them — before the engine resolved a single Output — checked
+ * at apply. The half of "a pin is never computed during the deploy" that a FIRST deploy needs.
+ *
+ * ⛔ WHY APPLY HAS TO ASK THE STACK, NOT `news`. By the time `reconcile` runs, the engine has
+ *   resolved every Output in `news`, so a digest wired from another resource (a checksum file read
+ *   at apply, a lookup, a computed value) arrives as a well-formed plain string, indistinguishable
+ *   from a reviewed pin. And on a first deploy nothing else looked: Alchemy never diffs a create,
+ *   and skips the adoption probe while `news` holds an Output (beta.79 Plan.ts). 🔴 MEASURED
+ *   2026-09-22 (apply-pins.test.ts): a swapped archive plus the swapped digests, wired in as an
+ *   Output, installed the swapped bytes and the deploy reported success. binary-diff.ts refused the
+ *   same declaration only from the SECOND plan on, after the wrong binary was on the host.
+ * ★ `Stack.resources[fqn].Props` IS WHAT THE PROGRAM PASSED, Outputs and all: Alchemy's
+ *   `Resource` records it at registration (beta.79 Resource.ts, `Props: props`), and the same Stack
+ *   reaches the apply (ownership/adopt.ts reads `Adopt` from the same record for the same reason).
+ *   pinProblems then sees the Output itself — a function-typed proxy, an Effect or a Config — and
+ *   refuses it as "not a plain string".
+ * ⚠️ NO STACK, NO ANSWER. A handler called outside the engine (the fake-provider.ts harness) has no
+ *   Stack service and no registration to read, so this says nothing there; the engine always has
+ *   one. apply-pins.test.ts runs the real Plan and Apply, so an Alchemy upgrade that stops
+ *   recording `Props` there makes the swapped bytes install again, and fails that test by name.
+ */
+import { Stack } from 'alchemy/Stack';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+import { pinProblems } from './binary-form.ts';
+
+/** Everything wrong with the pins of the resource at `fqn` as its stack program declared them. */
+export const declaredPinProblems = (fqn: string): Effect.Effect<string[]> =>
+  Effect.gen(function* () {
+    const stack = yield* Effect.serviceOption(Stack);
+    if (Option.isNone(stack)) return [];
+    const declared: unknown = stack.value.resources[fqn]?.Props;
+    if (typeof declared !== 'object' && typeof declared !== 'function') return [];
+    if (declared === null) return [];
+    return pinProblems(declared as Parameters<typeof pinProblems>[0]).map(
+      (problem) => `as declared in the stack program, ${problem}`,
+    );
+  });

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