@homeflare/alchemy 0.20.0 → 0.21.0

package/src/launchd/runner.ts

@@ -33,10 +33,23 @@ export type FileStat = {
   readonly uid: number;
   readonly gid: number;
   readonly size: number;
+  /**
+   * The entry's identity, device and inode, when the runner can say. ★ Two spellings of ONE file
+   *   (`/tmp/x` and `/private/tmp/x`; `Bin` and `bin` on case-insensitive APFS) differ as strings
+   *   and match here, and a move must not delete its old path when that path IS the new file
+   *   (file-identity.ts). Optional: a runner that leaves them out gets a check after the fact.
+   */
+  readonly dev?: number;
+  readonly ino?: number;
 };
 
 export type WriteOptions = {
-  /** Permission bits for the final file, applied BEFORE it becomes visible at `path`. */
+  /**
+   * Permission bits for the final file. localRunner applies them BEFORE the file is visible at
+   * `path`. ⚠️ sudoRunner's `install -S` does NOT: MEASURED 2026-09-22 on macOS 27.2 (an lstat
+   *   poller racing /usr/bin/install), the new inode appears at `path` as 0600 and is chmodded
+   *   0.2–0.4 ms later. Never torn, never wider than declared, but briefly not executable.
+   */
   readonly mode: number;
   /** Numeric owner; omitted means whoever the runner writes as. */
   readonly uid?: number;
@@ -69,7 +82,9 @@ export interface HostRunner {
   stat(path: string): Promise<FileStat | undefined>;
   /**
    * Write `bytes` so that `path` holds either the old file or the new one, never a torn mix:
-   * a temporary file in the same directory, mode and owner set on it, then rename(2) over `path`.
+   * a temporary file in the same directory, mode and owner set on it, then rename(2) over `path`
+   * (sudoRunner: the mode just after the rename, measured — see WriteOptions.mode; the owner too,
+   * ⚠️ REASONED NOT MEASURED, since measuring it needs root).
    * ⚠️ The parent directory must exist; creating it would invent an owner and mode nobody declared.
    */
   writeFileAtomic(path: string, bytes: Uint8Array, options: WriteOptions): Promise<void>;

package/src/launchd/sudo-runner.ts

@@ -21,6 +21,17 @@
  * ★ `install -S`: install(1) on macOS 27.2 (read 2026-09-21) always writes a temp file in the
  *   target directory and renames it, so the file is never torn, and -S adds the fsync that
  *   localRunner's `handle.sync()` does.
+ * ⚠️ BUT IT CHMODS AFTER THE RENAME. MEASURED 2026-09-22 (an lstat poller racing
+ *   `/usr/bin/install -S -m 0755`, 300 MB, six runs, target absent and present): the new inode
+ *   is visible at the path as 0600, then 0755 0.2–0.4 ms later. Only ever narrower than declared.
+ *   ⚠️ REASONED NOT MEASURED: a launchd start inside that window gets EACCES and retries after its
+ *   throttle, and an install killed inside it leaves a root-owned 0600 file the operator cannot
+ *   read back. Closing it needs a second privileged step (install to a temp name, then rename),
+ *   which is a change to this allowlist and wants its own red team.
+ * ⚠️ AND IT COPIES XATTRS, com.apple.quarantine included (MEASURED 2026-09-22: a quarantined
+ *   source installed as a quarantined target). The staged file is written by this process, and
+ *   node:fs writes here carried only com.apple.provenance (measured the same day) — so nothing
+ *   is quarantined today, but a quarantined staging file would be installed quarantined.
  * ⚠️ REASONED, NOT MEASURED: sudo's failure text (sudo-said.ts has the strings and their sources).
  * ⛔ EVERY CHECK BEFORE SUDO ALSO RUNS AT PLAN TIME (`checkWrite`, 2026-09-21): the mode, the
  *   directories from the prefix down, the read-back. Reads only, as the operator — never sudo.

package/src/linux/sudo-listing.ts

@@ -0,0 +1,122 @@
+/**
+ * ONE READ OF `ls -ldn --` FOR A WHOLE LIST OF PATHS, parsed into the same FileStat the seam uses
+ * plus the one thing `stat` cannot say on Linux: whether the path carries a POSIX ACL.
+ *
+ * ★ WHY `ls` AND NOT `stat`, AND WHY ONE CALL. The Mac guard lstats every directory from `/` down
+ *   with a local syscall each; over ssh each of those is a TCP connection with no multiplexing
+ *   (ssh-runner.ts), so a five-deep chain would be five handshakes per check and per plan. `ls -ldn`
+ *   takes every path as an operand and answers in one connection, and its mode column carries the
+ *   ACL flag the chain check needs anyway.
+ * ★ MEASURED 2026-09-22, read-only over ssh, on two host classes — an unprivileged LXC container
+ *   and a Proxmox VE node, both Debian 13 / coreutils 9.7, LANG=C, ssh user uid 1001 and 1000:
+ *     $ ls -ldn / /etc /etc/systemd /etc/systemd/system /usr /usr/lib /usr/lib/systemd …
+ *       drwxr-xr-x 18 0 0 4096 Sep 22 10:12 /etc          (all ten root:root 0755, no flag)
+ *     $ ls -ld /var/log/journal
+ *       drwxr-sr-x+ 3 root systemd-journal …              (the `+` IS the POSIX ACL flag here)
+ *     $ ls -lden …  →  ls: invalid option -- 'e'          (the Mac's spelling does not exist)
+ *     $ command -v getfacl  →  absent on both Debian classes (present on the NixOS class)
+ *   ⛔ SO THE ACL SIGNAL IS THE `+` FLAG, NOT `getfacl`: the tool that would enumerate the entries
+ *     is not installed on the hosts this runner is for, and a guard that shells out to a missing
+ *     program and fails closed would refuse every write on them. `ls` is coreutils, always there.
+ *   ⚠️ THE PRICE, STATED: we learn THAT a directory has an ACL, never WHAT it grants, so any ACL on
+ *     the chain is a refusal — including a read-only one the Mac guard would allow. Fail closed and
+ *     say so; the remedy is a prefix without one.
+ * ⚠️ `.` in that column is an SELinux context, not an ACL, and is not a grant. `@` is macOS's.
+ * ⛔ FAIL CLOSED ON ANYTHING WE DO NOT UNDERSTAND. A line that does not parse, a path that no line
+ *   named, two lines for one path, or a non-zero exit is an error — never "nothing is there".
+ */
+import type { FileStat, HostRunner } from '../launchd/runner.ts';
+import { SudoRefusedError } from '../launchd/sudo-allowlist.ts';
+
+/** What one `ls -ldn` line says: the lstat fields, plus whether the path carries an ACL. */
+export type Listed = FileStat & { readonly acl: boolean };
+
+const KINDS = new Map<string, FileStat['kind']>([
+  ['-', 'file'],
+  ['d', 'directory'],
+  ['l', 'symlink'],
+]);
+
+/**
+ * `rwxr-x---` → 0o750, with the three special bits `ls` hides in the execute columns:
+ * `s`/`S` = setuid (user) or setgid (group), `t`/`T` = sticky; the capital is the bit without
+ * execute. ⚠️ Anything else in a column is a shape we do not know, and returns undefined.
+ */
+export const permBits = (perms: string): number | undefined => {
+  if (perms.length !== 9) return undefined;
+  let mode = 0;
+  for (const index of [0, 1, 2]) {
+    const at = index * 3;
+    const shift = 6 - at;
+    const [read, write, exec] = [perms[at], perms[at + 1], perms[at + 2]];
+    if ((read !== 'r' && read !== '-') || (write !== 'w' && write !== '-')) return undefined;
+    if (read === 'r') mode |= 0o4 << shift;
+    if (write === 'w') mode |= 0o2 << shift;
+    const [set, unset] = index === 2 ? ['t', 'T'] : ['s', 'S'];
+    if (exec === 'x' || exec === set) mode |= 0o1 << shift;
+    else if (exec !== '-' && exec !== unset) return undefined;
+    if (exec === set || exec === unset) mode |= 0o4000 >> index;
+  }
+  return mode;
+};
+
+/** `drwxr-xr-x+ 4 0 0 4096 Sep 22 10:12 /etc/systemd` — the tail holds the date and the name. */
+const LINE = /^([-dlbcps])(\S{9})([+.@]?)\s+\d+\s+(\d+)\s+(\d+)\s+(\d+)\s+(.*)$/;
+
+/**
+ * Match each line to the path that asked for it, by NAME rather than by position.
+ * ⚠️ `ls` SORTS ITS OPERANDS, so the answers do not come back in the order they were asked; and a
+ *   symlink's line ends `<path> -> <target>`, so it is not a suffix match either. The longest
+ *   candidate wins, so a path that is a tail of another cannot steal its line.
+ */
+const nameOf = (tail: string, paths: readonly string[]): string | undefined =>
+  [...paths]
+    .sort((left, right) => right.length - left.length)
+    .find((path) => tail.endsWith(` ${path}`) || tail.includes(` ${path} -> `));
+
+/** Every requested path's entry, or `undefined` when the listing is not exactly that. */
+export const parseListing = (
+  stdout: string,
+  paths: readonly string[],
+): Map<string, Listed> | undefined => {
+  const entries = new Map<string, Listed>();
+  for (const line of stdout.split('\n').filter((text) => text.trim() !== '')) {
+    const match = LINE.exec(line);
+    if (match === null) return undefined;
+    const [, type, perms, flag, uid, gid, size, tail] = match;
+    const mode = permBits(perms ?? '');
+    const path = nameOf(tail ?? '', paths);
+    if (mode === undefined || path === undefined || entries.has(path)) return undefined;
+    entries.set(path, {
+      acl: flag === '+',
+      gid: Number(gid),
+      kind: KINDS.get(type ?? '') ?? 'other',
+      mode,
+      size: Number(size),
+      uid: Number(uid),
+    });
+  }
+  return entries.size === paths.length ? entries : undefined;
+};
+
+/**
+ * Read every path in one call, as the deploying user — no sudo, the same read at plan time and
+ * before the write. ⛔ Anything but a complete, understood listing is a SudoRefusedError: a chain
+ *   we could not read is a chain we cannot say is root's alone.
+ */
+export const readListing = async (
+  base: HostRunner,
+  ls: string,
+  what: string,
+  paths: readonly string[],
+): Promise<Map<string, Listed>> => {
+  const result = await base.exec([ls, '-ldn', '--', ...paths]);
+  const entries = result.exitCode === 0 ? parseListing(result.stdout, paths) : undefined;
+  if (entries === undefined) {
+    throw new SudoRefusedError(
+      `sudoRunner ${what}: could not read ${paths.join(', ')} (${ls} -ldn exit ` +
+        `${String(result.exitCode)}: ${result.stderr.trim().slice(0, 200)}). Nothing ran as root.`,
+    );
+  }
+  return entries;
+};

package/src/proxmox/credential-literals.ts

@@ -23,7 +23,7 @@
  *   it from the template. docs/pbs-notifications.md says the same to the reader.
  * ⛔ A REFUSAL NAMES THE FIELD, NEVER THE VALUE — the message lands in a terminal and a CI log.
  */
-import type { FromEnv } from './write-only.ts';
+import type { FromEnv } from '../secrets/write-only.ts';
 
 /** `{{ secrets.x }}`, `{{secrets.x}}`, `{{ url-encode secrets.x }}` — a reference, not a value. */
 const READS_SECRET = /\{\{[^}]*\bsecrets\./;

package/src/proxmox/generated/pbs/nodes-node.ts

@@ -241,4 +241,4 @@ export type NodesNodeDisksZfsPostParams = {
 export type NodesNodeDisksZfsPostReturn = string;
 
 /** GET /nodes/{node}/disks/zfs/{name} — `data` payload after client unwrap. */
-export type NodesNodeDisksZfsNameGetReturn = {};
+export type NodesNodeDisksZfsNameGetReturn = Record<string, unknown>;

package/src/proxmox/generated/pbs.ts

@@ -13,6 +13,13 @@
  * ⚠️ 151 request parameters are typed `\`${number}\`` because the vendor calls them
  *   integer or number. They were `string` before, which accepted 'banana'. A caller holding a
  *   number writes \`${n}\` — `String(n)` is a plain `string` and will not typecheck, deliberately.
+ *
+ * ⛔ 135 OF THESE NAMES ARE ALSO EXPORTED BY `pve.ts`, MEANING SOMETHING ELSE. Both
+ *   products document a `/nodes/{node}` subtree, so a name like `NodesNodeCertificatesGetReturn`
+ *   exists on each side — here an array of objects, there `null`. Nothing stops a pve call
+ *   importing the pbs spelling: it compiles, and the type is simply wrong about the payload.
+ *   Import from the barrel that names your product. tests/schema-types.test.ts pins this count, so
+ *   a vendor upgrade that adds a collision fails there rather than at runtime.
  */
 export * from './pbs/access.ts';
 export * from './pbs/access-users.ts';

package/src/proxmox/generated/pve.ts

@@ -13,6 +13,13 @@
  * ⚠️ 480 request parameters are typed `\`${number}\`` because the vendor calls them
  *   integer or number. They were `string` before, which accepted 'banana'. A caller holding a
  *   number writes \`${n}\` — `String(n)` is a plain `string` and will not typecheck, deliberately.
+ *
+ * ⛔ 135 OF THESE NAMES ARE ALSO EXPORTED BY `pbs.ts`, MEANING SOMETHING ELSE. Both
+ *   products document a `/nodes/{node}` subtree, so a name like `NodesNodeCertificatesGetReturn`
+ *   exists on each side — here an array of objects, there `null`. Nothing stops a pbs call
+ *   importing the pve spelling: it compiles, and the type is simply wrong about the payload.
+ *   Import from the barrel that names your product. tests/schema-types.test.ts pins this count, so
+ *   a vendor upgrade that adds a collision fails there rather than at runtime.
  */
 export * from './pve/access.ts';
 export * from './pve/access-roles.ts';

package/src/proxmox/index.ts

@@ -104,5 +104,5 @@ export { ProxmoxSdnVnet, ProxmoxSdnVnetProvider } from './sdn-vnet.ts';
 export { ProxmoxSdnZone, ProxmoxSdnZoneProvider } from './sdn-zone.ts';
 export { ProxmoxStorage, ProxmoxStorageProvider } from './storage.ts';
 export { ProxmoxUser, ProxmoxUserProvider } from './user.ts';
-export { type FromEnv } from './write-only.ts';
+export { type FromEnv } from '../secrets/write-only.ts';
 export { ProxmoxZfsPoolProvider } from './zfs-pool.ts';

package/src/proxmox/pbs-notification-target-form.ts

@@ -25,7 +25,7 @@ import type {
   PbsNotificationTargetProps,
 } from './pbs-notification-target.ts';
 import { base64, headerDigest, names, wireItem } from './pbs-notification-target-wire.ts';
-import { type Environment, type FromEnv, resolveAll, sealMatches } from './write-only.ts';
+import { type Environment, type FromEnv, resolveAll, sealMatches } from '../secrets/write-only.ts';
 
 type Props = PbsNotificationTargetProps;
 type Field = keyof Props;

package/src/proxmox/pbs-notification-target-lifecycle.ts

@@ -32,7 +32,7 @@ import {
   targetForm,
 } from './pbs-notification-target-form.ts';
 import { targetAttributes } from './pbs-notification-target-wire.ts';
-import { seal } from './write-only.ts';
+import { seal } from '../secrets/write-only.ts';
 
 type Props = PbsNotificationTargetProps;
 type Attributes = PbsNotificationTargetAttributes;

package/src/proxmox/pbs-notification-target-wire.ts

@@ -23,7 +23,7 @@ import type {
   PbsNotificationTargetProps,
 } from './pbs-notification-target.ts';
 import { bool, text } from './values.ts';
-import { seal } from './write-only.ts';
+import { seal } from '../secrets/write-only.ts';
 
 export const base64 = (value: string): string => Buffer.from(value, 'utf8').toString('base64');
 

package/src/proxmox/pbs-notification-target.ts

@@ -31,7 +31,7 @@ import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
 import { handlers } from './pbs-notification-target-lifecycle.ts';
 import type { PveRequirements, WithPbsTarget } from './resource.ts';
-import type { FromEnv } from './write-only.ts';
+import type { FromEnv } from '../secrets/write-only.ts';
 
 export type PbsNotificationTargetType = 'sendmail' | 'smtp' | 'webhook';
 

package/src/release/adopt-parity.test.ts

@@ -0,0 +1,106 @@
+/**
+ * Adoption through Alchemy's OWN Plan and Apply (openbao/fake-stack.ts): a file already at the path,
+ * and a stack holding no state for it. What binary-claim.ts decides, measured end to end — the plan
+ * and the apply must give the same answer, and `adopted` must never stand for other bytes.
+ *
+ * 🔴 EVERY REFUSAL BELOW WAS A SILENT WRITE OR LOSS BEFORE 2026-09-22 (adversarial review of PR 138,
+ *   lens: adoption and plan parity), each measured with this harness against the code before the
+ *   fix: other bytes under `--adopt` planned `adopted` (resolved) or `create` (directory an Output)
+ *   and were downloaded over in place; a symlink planned `adopted` and was refused only at apply;
+ *   a renamed declaration claimed the identical file at apply and its old name's delete removed it.
+ */
+import { describe, expect, test } from 'bun:test';
+import { BINARY } from './fake-release.ts';
+import { DIR, PATH, THEIRS, deployHarness as harness } from './fake-deploy.ts';
+
+describe('a file already at the path, with no state', () => {
+  test('OTHER bytes under --adopt, probed: the plan refuses; nothing fetched, their file kept', async () => {
+    const h = harness(true);
+    h.place(THEIRS);
+    await expect(h.stack.deploy(h.literal, { adopt: true })).rejects.toThrow(
+      '--adopt takes over only the pinned binary',
+    );
+    expect(h.events).toEqual([]);
+    expect(h.fake.files.get(PATH)?.bytes).toEqual(THEIRS);
+  });
+
+  test('OTHER bytes under --adopt, the directory an Output: refused at apply, before the download', async () => {
+    const h = harness(true);
+    h.place(THEIRS);
+    await expect(h.stack.deploy(h.wired(), { adopt: true })).rejects.toThrow(
+      '--adopt takes over only the pinned binary',
+    );
+    expect(h.events.filter((e) => e.startsWith('GET ') || e.startsWith('write '))).toEqual([]);
+    expect(h.fake.files.get(PATH)?.bytes).toEqual(THEIRS);
+  });
+
+  test('a symlink under --adopt: refused by the PLAN, not first by the apply', async () => {
+    const h = harness(true);
+    h.place(new Uint8Array(), 0o755, 'symlink');
+    // ★ The plan-side wording; the apply's own would be "is a symlink".
+    await expect(h.stack.deploy(h.literal, { adopt: true })).rejects.toThrow(
+      'something that is not a regular file',
+    );
+    expect(h.events).toEqual([]);
+  });
+
+  test('the pinned bytes with a wrong mode, under --adopt: adopted, re-written from disk, never fetched', async () => {
+    const h = harness(true);
+    h.place(BINARY.vmalert, 0o775);
+    expect(await h.stack.deploy(h.literal, { adopt: true })).toEqual({ vmalert: 'adopted' });
+    expect(h.events).toEqual([`write ${PATH}`]);
+    expect(h.fake.files.get(PATH)?.mode).toBe(0o755);
+  });
+
+  test('the pinned bytes, the directory an Output, under --adopt: kept, never fetched', async () => {
+    const h = harness(true);
+    h.place(BINARY.vmalert);
+    const planned = await h.stack.deploy(h.wired(), { adopt: true });
+    expect(planned).toEqual({ dir: 'adopted', vmalert: 'create' });
+    expect(h.events).toEqual([]);
+    expect(h.fake.files.get(PATH)?.bytes).toEqual(BINARY.vmalert);
+  });
+
+  test('a renamed declaration while its directory changes: refused at apply, the binary kept', async () => {
+    const h = harness(false);
+    await h.stack.deploy(h.wired('vmalert'));
+    h.events.length = 0;
+    // The directory's mode change leaves `dir.path` an Output at plan, so nothing probes the path.
+    await expect(h.stack.deploy(h.wired('vmalert-rules', 0o750))).rejects.toThrow(
+      'it holds the pinned binary, but this stack holds no state for it',
+    );
+    // 🔴 Before: planned {dir: update, vmalert-rules: create, vmalert: delete}; the new name took
+    //   the identical file as its own, the old name's delete removed it, and the deploy succeeded.
+    expect(h.events).not.toContain(`remove ${PATH}`);
+    expect(h.fake.files.get(PATH)?.bytes).toEqual(BINARY.vmalert);
+  });
+
+  test('the same rename declared with renamedFrom (the remedy the refusal names): the binary kept', async () => {
+    const h = harness(false);
+    await h.stack.deploy(h.wired('vmalert'));
+    h.events.length = 0;
+    const planned = await h.stack.deploy(h.wired('vmalert-rules', 0o750, 'vmalert'));
+    expect(planned).toEqual({ dir: 'update', 'vmalert-rules': 'update' });
+    expect(h.events).toEqual([`chmod 750 ${DIR}`]);
+    expect(h.fake.files.get(PATH)?.bytes).toEqual(BINARY.vmalert);
+  });
+
+  test('the same rename under --adopt: the new name takes the file, the old name leaves it', async () => {
+    const h = harness(false);
+    await h.stack.deploy(h.wired('vmalert'));
+    h.events.length = 0;
+    const planned = await h.stack.deploy(h.wired('vmalert-rules', 0o750), { adopt: true });
+    expect(planned).toEqual({ dir: 'update', vmalert: 'delete', 'vmalert-rules': 'create' });
+    // 🔴 Before 2026-09-22 (release gate): the old name's orphan delete ran `remove ${PATH}` after
+    //   the new name had claimed it, and the deploy succeeded with the binary gone.
+    expect(h.events).toEqual([`chmod 750 ${DIR}`]);
+    expect(h.fake.files.get(PATH)?.bytes).toEqual(BINARY.vmalert);
+    // The new name owns it now: the next deploy of the same declaration changes nothing.
+    h.events.length = 0;
+    expect(await h.stack.deploy(h.wired('vmalert-rules', 0o750))).toEqual({
+      dir: 'noop',
+      'vmalert-rules': 'noop',
+    });
+    expect(h.events).toEqual([]);
+  });
+});

package/src/release/apply-pins.test.ts

@@ -0,0 +1,128 @@
+/**
+ * ⛔ A PIN IS NEVER COMPUTED DURING THE DEPLOY — on a FIRST deploy too. Release.Binary through
+ * Alchemy's own Plan and Apply (openbao/fake-stack.ts), with a pin wired from another resource's
+ * Output: the shape of "fetch the checksum file at apply and trust what it says".
+ *
+ * 🔴 MEASURED 2026-09-22 (supply-chain review of PR 138): before the apply-time check, the engine
+ *   never diffed this create and skipped its probe (an Output in `news`), so reconcile saw only the
+ *   RESOLVED digests. The release asset and its checksum file were both swapped (the releases are
+ *   mutable, victoria.ts), the Output carried the swapped digests, and the deploy installed the
+ *   swapped bytes and reported them verified. binary-diff.ts refused the same declaration only
+ *   from the SECOND plan on — after the wrong binary was already on the host.
+ */
+import { describe, expect, test } from 'bun:test';
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+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 { ReleaseBinary, makeReleaseBinaryProvider } from './binary.ts';
+import { catalogBinary } from './catalog.ts';
+import {
+  VMALERT_REQUEST,
+  VMUTILS_URL,
+  bytesOf,
+  gzip,
+  syntheticRelease,
+  tarOf,
+} from './fake-release.ts';
+
+const ROOT = '/opt/example/bin';
+const DIR = `${ROOT}/vmutils-1.151.0`;
+const EVIL = bytesOf('#!swapped vmalert\n');
+const SWAPPED = gzip(tarOf([{ bytes: EVIL, name: 'vmalert-prod' }]));
+
+/** What a stack might write to "stay current": digests read from the release at apply. */
+type Sums = { readonly archive: string; readonly member: string; readonly size: number };
+interface FetchedSums extends Resource<'Test.FetchedSums', { url: string }, Sums> {}
+const FetchedSums = Resource<FetchedSums>('Test.FetchedSums');
+/** ★ It answers with the SWAPPED asset's digests — what the swapped checksum file would say. */
+const FetchedSumsProvider = () =>
+  Provider.effect(
+    FetchedSums,
+    Effect.succeed(
+      FetchedSums.Provider.of({
+        delete: () => Effect.void,
+        list: () => Effect.succeed([]),
+        reconcile: () =>
+          Effect.succeed({
+            archive: sha256Hex(SWAPPED),
+            member: sha256Hex(EVIL),
+            size: SWAPPED.length,
+          }),
+      }),
+    ),
+  );
+
+const harness = () => {
+  const pins = catalogBinary(syntheticRelease().catalog, VMALERT_REQUEST);
+  const fake = fakeLinuxHost({ dirs: { [ROOT]: 0 }, euid: 0 });
+  const events: string[] = [];
+  const runner: HostRunner = {
+    ...fake.runner,
+    writeFileAtomic: (path, bytes, options) => {
+      events.push(`write ${path}`);
+      return fake.runner.writeFileAtomic(path, bytes, options);
+    },
+  };
+  // ★ The attacker's release: the swapped archive at the REAL asset URL.
+  const client = HttpClient.make((request, url) => {
+    events.push(`GET ${url.toString()}`);
+    const body = url.toString() === VMUTILS_URL ? new Blob([SWAPPED.slice()]) : null;
+    return Effect.succeed(
+      HttpClientResponse.fromWeb(request, new Response(body, { status: body ? 200 : 404 })),
+    );
+  });
+  const providers = Layer.mergeAll(
+    makeReleaseBinaryProvider({ download: { retries: 0 } }),
+    HostDirectoryProvider(),
+    FetchedSumsProvider(),
+  ).pipe(
+    Layer.provide(
+      Layer.mergeAll(hostRunnerLayer(runner), Layer.succeed(HttpClient.HttpClient, client)),
+    ),
+  );
+  return { events, fake, pins, stack: fakeStack(providers, {}, 'ApplyPinStack') };
+};
+
+type Wiring = 'every digest and the size' | 'the member digest' | 'the archive digest and size';
+
+describe('a pin wired from an Output, on a first deploy', () => {
+  test.each<[Wiring, string]>([
+    ['every digest and the size', 'archive.sha256 is required, as a plain string'],
+    ['the member digest', 'sha256 is required, as a plain string'],
+    ['the archive digest and size', 'archive.size must be'],
+  ])('%s: refused at apply, nothing fetched, nothing written', async (wiring, refusal) => {
+    const h = harness();
+    const body = Effect.gen(function* () {
+      const dir = yield* HostDirectory('vmutils-1.151.0', { mode: 0o755, path: DIR });
+      const sums = yield* FetchedSums('sums', { url: `${VMUTILS_URL}_checksums.txt` });
+      const archive =
+        wiring === 'the member digest'
+          ? h.pins.archive
+          : { ...h.pins.archive, sha256: sums.archive, size: sums.size };
+      const sha256 = wiring === 'the archive digest and size' ? h.pins.sha256 : sums.member;
+      yield* ReleaseBinary('vmalert', { ...h.pins, archive, directory: dir.path, sha256 });
+    });
+    await expect(h.stack.deploy(body)).rejects.toThrow(refusal);
+    expect(h.events).toEqual([]);
+    expect(h.fake.files.has(`${DIR}/vmalert`)).toBe(false);
+  });
+
+  test('control: the same swap against plain pins is refused by the download it makes', async () => {
+    const h = harness();
+    const body = Effect.gen(function* () {
+      const dir = yield* HostDirectory('vmutils-1.151.0', { mode: 0o755, path: DIR });
+      yield* ReleaseBinary('vmalert', { ...h.pins, directory: dir.path });
+    });
+    await expect(h.stack.deploy(body)).rejects.toThrow('the pin says');
+    expect(h.events).toEqual([`GET ${VMUTILS_URL}`]);
+    expect(h.fake.files.has(`${DIR}/vmalert`)).toBe(false);
+  });
+});

package/src/release/archive.ts

@@ -0,0 +1,94 @@
+/**
+ * A pinned archive, verified, to the one member a declaration names, verified — the order the
+ * checks run in is the point of the file.
+ *
+ *   1. the archive's SHA-256 against its pin — BEFORE a single byte is unpacked;
+ *   2. gunzip and tar-read as one stream, keeping only the declared member (tar.ts refuses anything
+ *      unsafe in the archive, asked-for or not);
+ *   3. that member's SHA-256 against its own pin.
+ *
+ * ★ BOTH LAYERS, BECAUSE THE VENDOR HASHES BOTH. Each checksum file lists the archive AND every
+ *   binary inside it (measured 2026-09-22, all four). The archive check says the download is the
+ *   published file; the member check says the bytes about to be written are the published binary —
+ *   and it is the only check that still holds if the tar reader were ever wrong about a boundary.
+ * ★ DecompressionStream, THE WEB STANDARD: node and bun both ship it, so dist behaves the same
+ *   under either runtime — no zlib binding, no dependency.
+ * ⛔ IN MEMORY ONLY. Nothing here touches a disk, so no failure below can leave a staged download
+ *   behind; the bytes reach a host only through HostRunner.writeFileAtomic (file-converge.ts).
+ */
+import { sha256Hex } from '../launchd/job-form.ts';
+import type { PinnedDownload } from './binary-form.ts';
+import { ArchiveRefused, ChecksumMismatch } from './refused.ts';
+import { type TarContents, tarReader } from './tar.ts';
+
+/** How much gzip is handed to the inflater at a time. */
+const SLICE = 1 << 20;
+
+/** Gunzip and read a tar, keeping only `wanted`. Throws ArchiveRefused. */
+export const extractMembers = async (
+  gzipped: Uint8Array,
+  wanted: ReadonlySet<string>,
+): Promise<TarContents> => {
+  const tar = tarReader(wanted);
+  // ⚠️ FED IN SLICES, ON DEMAND. Enqueued whole, the 123.6 MB vmutils archive is inflated in one
+  //   transform step and all 264 MB of output queue up before the first read: MEASURED 2026-09-22,
+  //   a peak RSS of 1116 MB for vmalert alone under bun 1.4.0. `pull` hands over the next slice only
+  //   when the stream asks, so backpressure bounds what is inflated ahead of the tar reader.
+  let offset = 0;
+  const source = new ReadableStream<Uint8Array>({
+    pull(controller) {
+      if (offset >= gzipped.length) {
+        controller.close();
+        return;
+      }
+      controller.enqueue(gzipped.slice(offset, offset + SLICE));
+      offset += SLICE;
+    },
+  });
+  const unzipped = source.pipeThrough(new DecompressionStream('gzip')).getReader();
+  try {
+    for (;;) {
+      const { done, value } = await unzipped.read();
+      if (done) break;
+      tar.push(value);
+    }
+  } catch (cause) {
+    await unzipped.cancel().catch(() => undefined);
+    if (cause instanceof ArchiveRefused) throw cause;
+    throw new ArchiveRefused({ message: `not a gzip stream (${String(cause)})` });
+  }
+  return tar.finish();
+};
+
+const mismatch = (subject: string, expected: string, actual: string): ChecksumMismatch =>
+  new ChecksumMismatch({
+    actual,
+    expected,
+    message: `${subject} hashes to ${actual}, not the pinned ${expected}`,
+    subject,
+  });
+
+/**
+ * The declared member's bytes out of a downloaded archive, both layers checked.
+ * ⚠️ `archive` may be shared with another resource's extraction (download.ts sharingInFlight):
+ *   this only reads it.
+ */
+export const verifiedMember = async (
+  archive: Uint8Array,
+  release: PinnedDownload,
+): Promise<Uint8Array> => {
+  const archiveSha = sha256Hex(archive);
+  if (archiveSha !== release.sha256) throw mismatch(release.url, release.sha256, archiveSha);
+  const { members, names } = await extractMembers(archive, new Set([release.member]));
+  const bytes = members.get(release.member);
+  if (bytes === undefined) {
+    throw new ArchiveRefused({
+      message: `${release.url} has no member named exactly "${release.member}" (it has ${names.map((n) => `"${n}"`).join(', ') || 'none'})`,
+    });
+  }
+  const memberSha = sha256Hex(bytes);
+  if (memberSha !== release.memberSha256) {
+    throw mismatch(`member "${release.member}"`, release.memberSha256, memberSha);
+  }
+  return bytes;
+};