@homeflare/alchemy 0.20.0 → 0.22.0

package/src/release/providers.test.ts

@@ -0,0 +1,175 @@
+/**
+ * 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',
+      'OPENBAO_RELEASES',
+      '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);
+  });
+});

package/src/release/tar.ts

@@ -0,0 +1,195 @@
+/**
+ * A tar reader with one job: hand back the NAMED regular files of a vendor archive, and refuse the
+ * whole archive if any entry could make a name mean something other than what it says.
+ *
+ * ★ IN PROCESS, NOT `tar` ON THE HOST. An exec'd tar writes through its own path — past the
+ *   HostRunner seam, past sudoRunner's allowlist, and past the member digest check, which has to
+ *   see the bytes BEFORE they exist on any disk. Nothing this file reads is ever written by it.
+ * ★ STREAMING. It is fed the gunzip output chunk by chunk; an entry nobody asked for is counted
+ *   past, never held. vmutils unpacks to 264 MB across seven binaries (measured 2026-09-22) and a
+ *   stack wants two, so the unpacked archive never exists whole in memory.
+ * ⛔ REFUSED, WHOLE ARCHIVE, whichever entry it is and whether or not it was asked for:
+ *   an absolute name; a `..` segment; a hard link, symlink, directory, device, FIFO or contiguous
+ *   file (only a regular file is accepted); a name given twice; a header whose checksum fails; a
+ *   size in GNU base-256; a header that is neither ustar nor GNU; a lone zero block between entries;
+ *   non-zero bytes after the end marker; an archive that stops before it.
+ * ★ GNU LONG NAMES ('L', 'K') AND PAX HEADERS ('x', 'g') ARE REFUSED, NOT INTERPRETED. Each renames
+ *   the entry after it: a reader that honours them must get them exactly right to match exactly,
+ *   and one that skips them matches under the wrong name. The four pinned archives use neither
+ *   (measured 2026-09-22 with `tar -tvzf` on each: every entry a root-level regular file with a
+ *   short name), so refusing costs nothing today, and a vendor format change becomes a refusal that
+ *   says what changed instead of a silent mis-read.
+ */
+import { ArchiveRefused } from './refused.ts';
+
+const BLOCK = 512;
+
+const KINDS: Readonly<Record<string, string>> = {
+  '1': 'a hard link',
+  '2': 'a symlink',
+  '3': 'a character device',
+  '4': 'a block device',
+  '5': 'a directory',
+  '6': 'a FIFO',
+  '7': 'a contiguous file',
+  K: 'a GNU long-link header',
+  L: 'a GNU long-name header',
+  g: 'a PAX global header',
+  x: 'a PAX extended header',
+};
+
+const refuse = (message: string): ArchiveRefused => new ArchiveRefused({ message });
+const strict = new TextDecoder('utf-8', { fatal: true });
+const ascii = new TextDecoder('latin1');
+
+/** One NUL-terminated header field. */
+const field = (block: Uint8Array, start: number, length: number): Uint8Array => {
+  const slice = block.subarray(start, start + length);
+  const end = slice.indexOf(0);
+  return end === -1 ? slice : slice.subarray(0, end);
+};
+
+const text = (block: Uint8Array, start: number, length: number): string => {
+  try {
+    return strict.decode(field(block, start, length));
+  } catch {
+    throw refuse('an entry name is not UTF-8');
+  }
+};
+
+const octal = (block: Uint8Array, start: number, length: number, what: string): number => {
+  const raw = block.subarray(start, start + length);
+  if (((raw[0] ?? 0) & 0x80) !== 0) throw refuse(`${what} is base-256 encoded`);
+  const digits = ascii
+    .decode(raw)
+    .replace(/[\0 ]+$/, '')
+    .replace(/^ +/, '');
+  if (!/^[0-7]+$/.test(digits)) throw refuse(`${what} is not octal: ${JSON.stringify(digits)}`);
+  return Number.parseInt(digits, 8);
+};
+
+const checksumHolds = (block: Uint8Array): boolean => {
+  let sum = 0;
+  // The checksum field itself counts as eight spaces (POSIX ustar).
+  for (let at = 0; at < BLOCK; at += 1) sum += at >= 148 && at < 156 ? 0x20 : (block[at] ?? 0);
+  return sum === octal(block, 148, 8, 'a header checksum');
+};
+
+/** Why an entry name is unsafe to trust, or undefined. */
+const nameProblem = (name: string): string | undefined => {
+  if (name === '') return 'has an empty name';
+  if (name.startsWith('/')) return 'is absolute';
+  if (name.split('/').includes('..')) return 'climbs out of the archive with ".."';
+  return undefined;
+};
+
+/** Concatenate chunks into one buffer. */
+export const concatBytes = (parts: readonly Uint8Array[]): Uint8Array => {
+  const out = new Uint8Array(parts.reduce((total, part) => total + part.length, 0));
+  let at = 0;
+  for (const part of parts) {
+    out.set(part, at);
+    at += part.length;
+  }
+  return out;
+};
+
+export type TarContents = {
+  /** The asked-for regular files, by exact name. An asked-for name that is absent is absent here. */
+  readonly members: ReadonlyMap<string, Uint8Array>;
+  /** Every entry name, in archive order — so a refusal can say what the archive did hold. */
+  readonly names: readonly string[];
+};
+
+/** A push parser: `push` each chunk of the unzipped stream, then `finish`. Either may throw. */
+export const tarReader = (wanted: ReadonlySet<string>) => {
+  const header = new Uint8Array(BLOCK);
+  const members = new Map<string, Uint8Array>();
+  const names: string[] = [];
+  const seen = new Set<string>();
+  let phase: 'header' | 'data' | 'pad' | 'end' = 'header';
+  let filled = 0;
+  let remaining = 0;
+  let padding = 0;
+  let zeros = 0;
+  let name = '';
+  let parts: Uint8Array[] | undefined;
+
+  const endEntry = () => {
+    if (parts !== undefined) members.set(name, concatBytes(parts));
+    parts = undefined;
+    phase = padding > 0 ? 'pad' : 'header';
+  };
+
+  const startEntry = () => {
+    if (header.every((byte) => byte === 0)) {
+      zeros += 1;
+      if (zeros === 2) phase = 'end';
+      return;
+    }
+    if (zeros > 0) throw refuse('a zero block sits between entries (truncated or spliced)');
+    if (!checksumHolds(header)) throw refuse('an entry header fails its checksum');
+    const magic = ascii.decode(header.subarray(257, 265));
+    const posix = magic === 'ustar\u000000';
+    if (!posix && magic !== 'ustar  \u0000')
+      throw refuse('an entry header is neither ustar nor GNU');
+    const prefix = posix ? text(header, 345, 155) : '';
+    name = prefix === '' ? text(header, 0, 100) : `${prefix}/${text(header, 0, 100)}`;
+    const problem = nameProblem(name);
+    if (problem !== undefined) throw refuse(`entry ${JSON.stringify(name)} ${problem}`);
+    const type = String.fromCharCode(header[156] ?? 0);
+    if (type !== '0' && type !== '\0') {
+      const kind = KINDS[type] ?? `of unknown type ${JSON.stringify(type)}`;
+      throw refuse(`entry "${name}" is ${kind}; only regular files are accepted`);
+    }
+    if (seen.has(name)) throw refuse(`entry "${name}" appears twice`);
+    seen.add(name);
+    names.push(name);
+    remaining = octal(header, 124, 12, `entry "${name}"'s size`);
+    padding = (BLOCK - (remaining % BLOCK)) % BLOCK;
+    parts = wanted.has(name) ? [] : undefined;
+    phase = 'data';
+    if (remaining === 0) endEntry();
+  };
+
+  const push = (chunk: Uint8Array): void => {
+    let at = 0;
+    while (at < chunk.length) {
+      if (phase === 'end') {
+        if (chunk.subarray(at).some((byte) => byte !== 0)) {
+          throw refuse('data follows the end-of-archive marker');
+        }
+        return;
+      }
+      if (phase === 'header') {
+        const take = Math.min(BLOCK - filled, chunk.length - at);
+        header.set(chunk.subarray(at, at + take), filled);
+        filled += take;
+        at += take;
+        if (filled === BLOCK) {
+          filled = 0;
+          startEntry();
+        }
+      } else if (phase === 'data') {
+        const take = Math.min(remaining, chunk.length - at);
+        // ⚠️ slice, not subarray: a chunk's buffer may be reused by the stream after this returns.
+        parts?.push(chunk.slice(at, at + take));
+        remaining -= take;
+        at += take;
+        if (remaining === 0) endEntry();
+      } else {
+        const take = Math.min(padding, chunk.length - at);
+        padding -= take;
+        at += take;
+        if (padding === 0) phase = 'header';
+      }
+    }
+  };
+
+  const finish = (): TarContents => {
+    if (phase !== 'end') throw refuse('the archive stops before its end-of-archive marker');
+    return { members, names };
+  };
+
+  return { finish, push };
+};