@homeflare/alchemy 0.19.1 → 0.21.0

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

package/src/release/providers.test.ts

@@ -0,0 +1,174 @@
+/**
+ * The Alchemy wiring: the provider built as a Layer over a fake host and a fake `HttpClient`, its
+ * handlers called the way the engine calls them — plus the barrel, the subpath's public API.
+ *
+ * ★ `read` with no prior state is the adoption probe. A binary already at the path comes back
+ *   `Unowned`, recognised by its digest; after `--adopt` the forced update finds it matching and
+ *   neither downloads nor writes. The plan-time refusals: provider-refusals.test.ts.
+ */
+import { describe, expect, test } from 'bun:test';
+import { Unowned, stripUnowned } from 'alchemy/AdoptPolicy';
+import * as Effect from 'effect/Effect';
+import { ReleaseBinary } from './binary.ts';
+import {
+  BINARY,
+  VMUTILS_DIR,
+  VMUTILS_URL,
+  pathsOn,
+  releaseHost,
+  syntheticRelease,
+  vmalertProps,
+} from './fake-release.ts';
+import { PATH, call, harness, ids, must } from './fake-provider.ts';
+import * as barrel from './index.ts';
+import { releaseProviders } from './providers.ts';
+
+describe('the lifecycle through the engine-facing handlers', () => {
+  test('reconcile installs, noting progress; diff is then a noop, a mode change an update', async () => {
+    const h = harness();
+    const [output, same, mode] = await h.run((p) =>
+      Effect.gen(function* () {
+        const output = yield* h.reconcile(p, h.VMALERT);
+        const diff = must(p.diff);
+        const base = { ...ids, ...call, olds: h.VMALERT as never, output };
+        return [
+          output,
+          yield* diff({ ...base, news: h.VMALERT as never }),
+          yield* diff({ ...base, news: { ...h.VMALERT, mode: 0o555 } as never }),
+        ] as const;
+      }),
+    );
+    expect(output.sha256).toBe(new Bun.CryptoHasher('sha256').update(BINARY.vmalert).digest('hex'));
+    expect([same, mode]).toEqual([{ action: 'noop' }, { action: 'update' }]);
+    expect(h.notes.some((n) => n.startsWith('downloading '))).toBe(true);
+  });
+
+  test('while the directory is an Output: other bytes are a replace, the same bytes an update', async () => {
+    const h = harness();
+    const diffs = await h.run((p) =>
+      Effect.gen(function* () {
+        const output = yield* h.reconcile(p, h.VMALERT);
+        const base = { ...ids, ...call, olds: h.VMALERT as never, output };
+        const pending = { ...h.VMALERT, directory: Effect.succeed(`${VMUTILS_DIR}-next`) };
+        const archive = { ...h.VMALERT.archive, tag: 'v1.152.0' };
+        const diff = (news: object) => must(p.diff)({ ...base, news: news as never });
+        return [
+          yield* diff({ ...pending, archive, sha256: 'e'.repeat(64) }),
+          yield* diff({ ...pending, archive }),
+          yield* diff(pending),
+        ];
+      }),
+    );
+    // ★ Never `replace` for the same bytes: onto an unmoved path, the new generation would accept
+    //   the old file as its own and Phase 2 would then delete it (binary-diff.ts).
+    expect(diffs).toEqual([{ action: 'replace' }, { action: 'update' }, undefined]);
+  });
+
+  test('that update, if the path did not move after all, is refused at apply', async () => {
+    const h = harness();
+    const output = await h.run((p) => h.reconcile(p, h.VMALERT));
+    h.requests.length = 0;
+    const repinned = { ...h.VMALERT, archive: { ...h.VMALERT.archive, tag: 'v1.152.0' } };
+    const applying = h.run((p) => h.reconcile(p, repinned, output, h.VMALERT));
+    await expect(applying).rejects.toThrow('would overwrite it in place');
+    expect(h.requests).toEqual([]);
+    expect(h.fake.files.get(PATH)?.bytes).toEqual(BINARY.vmalert);
+  });
+
+  test('a binary someone already placed: Unowned by digest, then adopted with no download', async () => {
+    const h = harness();
+    h.fake.files.set(PATH, { bytes: BINARY.vmalert, gid: 0, kind: 'file', mode: 0o755, uid: 0 });
+    const before = pathsOn(h.fake);
+    const [probe, adopted] = await h.run((p) =>
+      Effect.gen(function* () {
+        const probe = yield* must(p.read)({ ...ids, olds: h.VMALERT as never, output: undefined });
+        if (probe === undefined) throw new Error('nothing found');
+        // What the engine does after `--adopt`: strip the brand, then force an update.
+        const adopted = yield* h.reconcile(p, h.VMALERT, stripUnowned(probe));
+        return [probe, adopted] as const;
+      }),
+    );
+    expect(Unowned.is(probe)).toBe(true);
+    // ★ Recognised by its digest alone: the probe's sha256 IS the pin; nothing was executed.
+    expect(probe.sha256).toBe(h.VMALERT.sha256);
+    expect(adopted).toMatchObject({
+      member: 'vmalert-prod',
+      path: PATH,
+      sha256: h.VMALERT.sha256,
+      url: VMUTILS_URL,
+    });
+    expect(h.requests).toEqual([]);
+    expect(h.fake.calls.filter((c) => c[0] === 'write')).toEqual([]);
+    expect(pathsOn(h.fake)).toEqual(before);
+  });
+
+  test('vmagent and vmalert at once: ONE download of the shared archive', async () => {
+    const h = harness();
+    const vmagent = {
+      ...h.VMALERT,
+      member: 'vmagent-prod',
+      name: 'vmagent',
+      sha256: new Bun.CryptoHasher('sha256').update(BINARY.vmagent).digest('hex'),
+    };
+    await h.run((p) =>
+      Effect.all([h.reconcile(p, h.VMALERT), h.reconcile(p, vmagent)], {
+        concurrency: 'unbounded',
+      }),
+    );
+    expect(h.requests).toEqual([VMUTILS_URL]);
+    expect(pathsOn(h.fake)).toEqual([`${VMUTILS_DIR}/vmagent`, PATH]);
+  });
+
+  test('delete removes the binary and never the directory', async () => {
+    const h = harness();
+    await h.run((p) =>
+      Effect.gen(function* () {
+        const output = yield* h.reconcile(p, h.VMALERT);
+        yield* p.delete({
+          ...ids,
+          bindings: [] as never,
+          olds: h.VMALERT as never,
+          output,
+          session: undefined as never,
+        });
+      }),
+    );
+    expect(h.fake.files.has(PATH)).toBe(false);
+    expect(h.fake.dirs.has(VMUTILS_DIR)).toBe(true);
+  });
+});
+
+describe('the subpath', () => {
+  test('releaseProviders builds with its own HTTP client, and a probe of nothing is nothing', async () => {
+    const fake = releaseHost();
+    const VMALERT = vmalertProps(syntheticRelease().catalog);
+    const found = await Effect.runPromise(
+      Effect.gen(function* () {
+        const p = yield* ReleaseBinary.Provider;
+        return yield* must(p.read)({ ...ids, olds: VMALERT as never, output: undefined });
+      }).pipe(Effect.provide(releaseProviders(fake.runner))),
+    );
+    expect(found).toBeUndefined();
+  });
+
+  test('the barrel is exactly the public API', () => {
+    expect(Object.keys(barrel).sort()).toEqual([
+      'ArchiveRefused',
+      'BinaryRefused',
+      'ChecksumMismatch',
+      'DownloadFailed',
+      'HostRunnerService',
+      'ReleaseBinary',
+      'ReleaseBinaryProvider',
+      'VICTORIA_RELEASES',
+      'catalogBinary',
+      'catalogDirectory',
+      'catalogProblems',
+      'hostRunnerLayer',
+      'identifyBinary',
+      'releaseBinaryPath',
+      'releaseProviders',
+      'releaseUrl',
+    ]);
+  });
+});

package/src/release/providers.ts

@@ -0,0 +1,24 @@
+/**
+ * The release-binary provider with ONE HostRunner and its own HTTP client, as a single layer for a
+ * host stack:
+ *
+ *     const runner = localRunner();
+ *     Layer.mergeAll(launchdProviders(runner), releaseProviders(runner), …the stack's others)
+ *
+ * ★ PASS THE SAME RUNNER THE JOBS USE, so the binary and the daemon that runs it are written by one
+ *   identity on one host — a stack cannot install as one user and bootstrap as another by accident.
+ * ⛔ THERE IS NO DEFAULT RUNNER. A binary is written wherever the runner reaches; a silent default to
+ *   "this machine" would install a Mac's daemons onto whichever laptop ran the deploy (the same
+ *   reasoning as linuxProviders()).
+ * ★ `FetchHttpClient.layer` IS PROVIDED HERE, not left to the stack: the Mac host stack this exists
+ *   for provides no HTTP layer, and a missing one fails only at the first install.
+ */
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import { type HostRunner, hostRunnerLayer } from '../launchd/runner.ts';
+import { ReleaseBinaryProvider } from './binary.ts';
+
+export const releaseProviders = (runner: HostRunner) =>
+  ReleaseBinaryProvider().pipe(
+    Layer.provide(Layer.mergeAll(hostRunnerLayer(runner), FetchHttpClient.layer)),
+  );

package/src/release/recovery-read.test.ts

@@ -0,0 +1,44 @@
+/**
+ * A FAILED FIRST INSTALL MUST NOT BRICK THE STAGE (binary-read.ts), through Alchemy's own Plan and
+ * Apply. With `directory: dir.path`, the documented shape, Apply commits the `creating` row while
+ * the directory is still an Output, so the row carries no `directory`; the next plan's recovery
+ * read — and, once the declaration is gone, Apply's orphan delete — is asked with that row.
+ *
+ * 🔴 MEASURED 2026-09-22 against the code before binary-read.ts, every case below: the next deploy
+ *   died with `TypeError: undefined is not an object (evaluating 'path.startsWith')`, the fixed
+ *   declaration included, and removing the declaration failed with `DestroyError`.
+ */
+import { describe, expect, test } from 'bun:test';
+import { BINARY, VMUTILS_URL } from './fake-release.ts';
+import { DIR, PATH, deployHarness } from './fake-deploy.ts';
+
+describe('after a failed first install', () => {
+  test('a download that failed: the next deploy installs, then is a noop', async () => {
+    const h = deployHarness(false);
+    h.server.serving = false;
+    await expect(h.stack.deploy(h.wired())).rejects.toThrow('HTTP 404');
+    h.server.serving = true;
+    h.events.length = 0;
+    expect(await h.stack.deploy(h.wired())).toEqual({ dir: 'noop', vmalert: 'create' });
+    expect(h.events).toEqual([`GET ${VMUTILS_URL}`, `write ${PATH}`]);
+    expect(h.fake.files.get(PATH)?.bytes).toEqual(BINARY.vmalert);
+    expect(await h.stack.deploy(h.wired())).toEqual({ dir: 'noop', vmalert: 'noop' });
+  });
+
+  test('a declaration refused at apply (a group-writable mode), then fixed: it installs', async () => {
+    const h = deployHarness(false);
+    await expect(
+      h.stack.deploy(h.wired('vmalert', 0o755, undefined, { mode: 0o775 })),
+    ).rejects.toThrow('mode must not be group- or world-writable');
+    expect(await h.stack.deploy(h.wired())).toEqual({ dir: 'noop', vmalert: 'create' });
+    expect(h.fake.files.get(PATH)?.mode).toBe(0o755);
+  });
+
+  test('the failed declaration removed instead: its row is dropped, the directory kept', async () => {
+    const h = deployHarness(false);
+    h.server.serving = false;
+    await expect(h.stack.deploy(h.wired())).rejects.toThrow('HTTP 404');
+    expect(await h.stack.deploy(h.dirOnly)).toEqual({ dir: 'noop', vmalert: 'delete' });
+    expect(h.fake.dirs.has(DIR)).toBe(true);
+  });
+});

package/src/release/refused.ts

@@ -0,0 +1,40 @@
+/**
+ * Release.Binary's failures as tagged errors — each carrying the house refusal sentence
+ * (`Release.Binary <path>: …`) as its `message`.
+ *
+ * ★ TAGGED BECAUSE ALCHEMY UPSTREAM REQUIRES IT (its AGENTS.md at v2.0.0-beta.79: Data.TaggedError,
+ *   `catchTag`, never a cast on `_tag`), so the classes need no rewrite on the way there. The
+ *   MESSAGE stays the kit's wording, so a deploy log reads the same as every other house family's.
+ * ⚠️ TAGGED IS NOT YET TYPED END TO END — measured in error-channel.test.ts. catalogBinary() throws,
+ *   so in a stack program its BinaryRefused is a DEFECT that `catchTag` never sees; and the provider
+ *   runs every lifecycle call through the house `lift()`, which keeps the instance at runtime but
+ *   types the channel as `Error`. No caller can name one of these tags today without a cast.
+ * ★ THE TAGS NAME NO VENDOR. Downloading a pinned archive, refusing an unsafe one and comparing
+ *   digests are the same for every catalog (docs/release-binary-upstream.md).
+ */
+import * as Data from 'effect/Data';
+
+/** The declaration itself: a version no catalog pins, a malformed pin, a bad path or mode. */
+export class BinaryRefused extends Data.TaggedError('BinaryRefused')<{
+  readonly message: string;
+}> {}
+
+/** The download: a status that is not 200, a body that is not the pinned size, a dead transport. */
+export class DownloadFailed extends Data.TaggedError('DownloadFailed')<{
+  readonly message: string;
+  /** Worth another attempt: a transport failure or a 5xx, never a wrong size or a 404. */
+  readonly retryable: boolean;
+}> {}
+
+/** Bytes that do not hash to their pin — the archive, or a member extracted from it. */
+export class ChecksumMismatch extends Data.TaggedError('ChecksumMismatch')<{
+  readonly message: string;
+  readonly subject: string;
+  readonly expected: string;
+  readonly actual: string;
+}> {}
+
+/** An archive this reader will not trust: an unsafe or unexpected entry, a missing member. */
+export class ArchiveRefused extends Data.TaggedError('ArchiveRefused')<{
+  readonly message: string;
+}> {}

package/src/release/tar.test.ts

@@ -0,0 +1,142 @@
+/**
+ * The tar reader against archives built here, byte by byte: it hands back only what was asked for,
+ * by exact name, and refuses the WHOLE archive for any entry that could make a name lie — whether
+ * or not that entry was the one asked for.
+ */
+import { describe, expect, test } from 'bun:test';
+import { extractMembers } from './archive.ts';
+import { type TarEntry, bytesOf, gzip, tarHeader, tarOf } from './fake-release.ts';
+import { ArchiveRefused } from './refused.ts';
+import { tarReader } from './tar.ts';
+
+const binary = { bytes: bytesOf('#!binary\n'), name: 'vmalert-prod' } as const;
+const read = (tar: Uint8Array, wanted = ['vmalert-prod'], chunk = tar.length) => {
+  const reader = tarReader(new Set(wanted));
+  for (let at = 0; at < tar.length; at += chunk) reader.push(tar.subarray(at, at + chunk));
+  return reader.finish();
+};
+const refusal = (run: () => unknown): string => {
+  try {
+    run();
+  } catch (cause) {
+    expect(cause).toBeInstanceOf(ArchiveRefused);
+    return (cause as ArchiveRefused).message;
+  }
+  throw new Error('expected a refusal');
+};
+
+describe('reading', () => {
+  test('only the asked-for member comes back; every name is listed', () => {
+    const tar = tarOf([{ bytes: bytesOf('x'.repeat(700)), name: 'vmagent-prod' }, binary]);
+    const { members, names } = read(tar);
+    expect([...members.keys()]).toEqual(['vmalert-prod']);
+    expect(new TextDecoder().decode(members.get('vmalert-prod'))).toBe('#!binary\n');
+    expect(names).toEqual(['vmagent-prod', 'vmalert-prod']);
+  });
+
+  test('one byte at a time reads the same as all at once', () => {
+    const tar = tarOf([{ bytes: bytesOf('y'.repeat(1025)), name: 'vmagent-prod' }, binary]);
+    expect(read(tar, ['vmagent-prod', 'vmalert-prod'], 1).members).toEqual(
+      read(tar, ['vmagent-prod', 'vmalert-prod']).members,
+    );
+  });
+
+  test('matching is exact: no ./, no prefix, no suffix', () => {
+    const tar = tarOf([
+      { ...binary, name: './vmalert-prod' },
+      { ...binary, name: 'vmalert-prod-x' },
+    ]);
+    expect(read(tar).members.size).toBe(0);
+  });
+
+  test('a POSIX prefix is part of the name', () => {
+    const tar = tarOf([{ ...binary, format: 'posix', prefix: 'bin' }]);
+    expect(read(tar, ['bin/vmalert-prod']).members.size).toBe(1);
+    expect(read(tar).members.size).toBe(0);
+  });
+
+  test('an empty member and trailing zero padding are fine', () => {
+    const tar = tarOf([{ name: 'empty' }, binary], 10_240);
+    expect(read(tar, ['empty']).members.get('empty')?.length).toBe(0);
+  });
+
+  test('extractMembers gunzips as it reads', async () => {
+    const { members } = await extractMembers(gzip(tarOf([binary])), new Set(['vmalert-prod']));
+    expect(members.get('vmalert-prod')).toEqual(binary.bytes);
+  });
+});
+
+describe('tar-slip and every other entry that could lie is refused, asked for or not', () => {
+  const beside = (entry: TarEntry) => tarOf([binary, entry]);
+  test.each([
+    ['an absolute name', { name: '/etc/passwd' }, 'is absolute'],
+    ['a .. segment', { name: '../vmalert-prod' }, 'climbs out'],
+    ['a .. deeper in', { name: 'bin/../../x' }, 'climbs out'],
+    ['a symlink', { name: 'link', type: '2' }, 'a symlink'],
+    ['a hard link', { name: 'hard', type: '1' }, 'a hard link'],
+    ['a directory', { name: 'bin/', type: '5' }, 'a directory'],
+    ['a FIFO', { name: 'fifo', type: '6' }, 'a FIFO'],
+    ['a GNU long name', { name: '././@LongLink', type: 'L' }, 'GNU long-name'],
+    ['a PAX header', { name: 'PaxHeader', type: 'x' }, 'PAX extended'],
+    ['an unknown type', { name: 'odd', type: 'Z' }, 'unknown type'],
+    ['a repeated name', binary, 'appears twice'],
+    ['a failed header checksum', { corruptChecksum: true, name: 'x' }, 'fails its checksum'],
+    ['a base-256 size', { base256: true, bytes: bytesOf('z'), name: 'big' }, 'base-256'],
+    ['a character device', { name: 'tty', type: '3' }, 'a character device'],
+    ['a block device', { name: 'disk', type: '4' }, 'a block device'],
+    ['a contiguous file', { name: 'contig', type: '7' }, 'a contiguous file'],
+    ['a GNU long link', { name: '././@LongLink', type: 'K' }, 'GNU long-link'],
+    ['a PAX global header', { name: 'pax_global_header', type: 'g' }, 'PAX global'],
+    ['an empty name', { bytes: bytesOf('z'), name: '' }, 'empty name'],
+  ] as const)('%s', (_, entry, message) => {
+    expect(refusal(() => read(beside(entry)))).toContain(message);
+  });
+
+  test('a name that is not UTF-8 is refused, not decoded loosely into another name', () => {
+    const tar = tarOf([binary, { bytes: bytesOf('z'), name: 'x' }]);
+    const at = 1024; // the second header: one header block and one data block in
+    tar[at] = 0xff;
+    tar.fill(0x20, at + 148, at + 156);
+    const sum = tar.subarray(at, at + 512).reduce((total, byte) => total + byte, 0);
+    tar.set(bytesOf(`${sum.toString(8).padStart(6, '0')}\0 `), at + 148);
+    expect(refusal(() => read(tar))).toContain('not UTF-8');
+  });
+
+  test('a symlink under the asked-for name is refused, not followed', () => {
+    expect(refusal(() => read(tarOf([{ name: 'vmalert-prod', type: '2' }])))).toContain('symlink');
+  });
+
+  test('a header that is neither ustar nor GNU (v7 tar) is refused', () => {
+    const tar = tarOf([binary]);
+    tar.fill(0, 257, 265);
+    const header = tarHeader(binary);
+    header.fill(0, 257, 265);
+    header.fill(0x20, 148, 156);
+    const sum = header.reduce((total, byte) => total + byte, 0);
+    header.set(new TextEncoder().encode(`${sum.toString(8).padStart(6, '0')}\0 `), 148);
+    tar.set(header, 0);
+    expect(refusal(() => read(tar))).toContain('neither ustar nor GNU');
+  });
+
+  test('a truncated archive — no end marker — is refused', () => {
+    const tar = tarOf([binary]);
+    expect(refusal(() => read(tar.subarray(0, tar.length - 1024)))).toContain('stops before');
+  });
+
+  test('a lone zero block between entries is refused', () => {
+    const one = tarOf([binary], 512);
+    const two = tarOf([{ ...binary, name: 'other' }]);
+    const spliced = new Uint8Array([...one, ...two]);
+    expect(refusal(() => read(spliced))).toContain('zero block');
+  });
+
+  test('data after the end marker is refused', () => {
+    const tar = new Uint8Array([...tarOf([binary]), 1]);
+    expect(refusal(() => read(tar))).toContain('follows the end-of-archive');
+  });
+
+  test('bytes that are not gzip are refused as an archive, not thrown raw', async () => {
+    const promise = extractMembers(bytesOf('not gzip at all'), new Set(['x']));
+    await expect(promise).rejects.toBeInstanceOf(ArchiveRefused);
+  });
+});