@homeflare/alchemy 0.20.0 → 0.21.0

package/src/release/binary-alias.test.ts

@@ -0,0 +1,109 @@
+/**
+ * ONE FILE UNDER TWO SPELLINGS (launchd/file-identity.ts), on a REAL filesystem: localRunner in a
+ * fresh temp directory, through Alchemy's own Plan and Apply where the engine's order matters.
+ * Nothing outside `mkdtemp` is touched, and the release is synthetic (fake-release.ts).
+ *
+ * 🔴 EACH TEST BELOW FAILED BEFORE THE FIX (measured 2026-09-22): the respelled deploy planned a
+ *   `replace`, reported success, and left no binary on disk; the next deploy put it back.
+ */
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdir, mkdtemp, rm, stat, symlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { type HostRunner } from '../launchd/runner.ts';
+import { localRunner } from '../launchd/local-runner.ts';
+import { reconcileBinary } from './binary-lifecycle.ts';
+import { VMALERT_TEXT, realEngine } from './fake-engine.ts';
+import { VMUTILS_URL, fakeTransport, syntheticRelease, vmalertProps } from './fake-release.ts';
+
+let tmp = '';
+beforeEach(async () => {
+  tmp = await mkdtemp(join(tmpdir(), 'hf-alias-'));
+  await mkdir(join(tmp, 'real', 'vmutils-1.151.0'), { recursive: true });
+  await symlink(join(tmp, 'real'), join(tmp, 'link'));
+});
+afterEach(async () => {
+  await rm(tmp, { force: true, recursive: true });
+});
+
+const REAL = () => join(tmp, 'real', 'vmutils-1.151.0');
+const LINKED = () => join(tmp, 'link', 'vmutils-1.151.0');
+/** The installed binary's text, or undefined when the deploy lost it. */
+const onDisk = () =>
+  Bun.file(join(REAL(), 'vmalert'))
+    .text()
+    .catch(() => undefined);
+const engine = () => {
+  const e = realEngine();
+  return { deploy: (directory: string) => e.deploy({ vmalert: directory }), gets: e.gets };
+};
+
+/** Whether this temp directory's volume folds case (APFS's default on macOS; not ext4). */
+const foldsCase = async (): Promise<boolean> =>
+  stat(join(tmp, 'REAL')).then(
+    () => true,
+    () => false,
+  );
+
+describe('a respelled directory is an update that keeps the file, never a replace', () => {
+  test('through a symlinked parent, via the engine', async () => {
+    const e = engine();
+    expect(await e.deploy(REAL())).toEqual({ vmalert: 'create' });
+    expect(await e.deploy(LINKED())).toEqual({ vmalert: 'update' });
+    expect(await onDisk()).toBe(VMALERT_TEXT);
+    expect(await e.deploy(LINKED())).toEqual({ vmalert: 'noop' });
+    expect(e.gets).toEqual([VMUTILS_URL]);
+  });
+
+  test('by case alone, on a volume that folds case', async () => {
+    if (!(await foldsCase())) return;
+    const e = engine();
+    await e.deploy(REAL());
+    expect(await e.deploy(join(tmp, 'real', 'VMUTILS-1.151.0'))).toEqual({ vmalert: 'update' });
+    expect(await onDisk()).toBe(VMALERT_TEXT);
+  });
+
+  test('an update across the respelling (the path unresolved at plan) keeps the file', async () => {
+    const { catalog, vmutils } = syntheticRelease();
+    const fetch = fakeTransport({ [VMUTILS_URL]: vmutils }).fetch;
+    const olds = vmalertProps(catalog, { directory: REAL() });
+    const output = await reconcileBinary(localRunner(), fetch, olds);
+    const news = vmalertProps(catalog, { directory: LINKED() });
+    const after = await reconcileBinary(localRunner(), fetch, news, { olds, output });
+    expect(after.path).toBe(join(LINKED(), 'vmalert'));
+    expect(await onDisk()).toBe(VMALERT_TEXT);
+  });
+
+  test('⛔ other bytes at the respelled path are still refused, never written in place', async () => {
+    const { catalog, vmutils } = syntheticRelease();
+    const transport = fakeTransport({ [VMUTILS_URL]: vmutils });
+    const olds = vmalertProps(catalog, { directory: REAL() });
+    const output = await reconcileBinary(localRunner(), transport.fetch, olds);
+    const news = vmalertProps(catalog, { directory: LINKED(), sha256: 'e'.repeat(64) });
+    await expect(
+      reconcileBinary(localRunner(), transport.fetch, news, { olds, output }),
+    ).rejects.toThrow('already exists and is not this resource');
+    expect(await onDisk()).toBe(VMALERT_TEXT);
+  });
+
+  test('⚠️ a runner that reports no identity: the loss fails the deploy instead of passing', async () => {
+    const real = localRunner();
+    const blind: HostRunner = {
+      ...real,
+      stat: async (path) => {
+        const found = await real.stat(path);
+        if (found === undefined) return undefined;
+        const { dev: _dev, ino: _ino, ...rest } = found;
+        return rest;
+      },
+    };
+    const { catalog, vmutils } = syntheticRelease();
+    const fetch = fakeTransport({ [VMUTILS_URL]: vmutils }).fetch;
+    const olds = vmalertProps(catalog, { directory: REAL() });
+    const output = await reconcileBinary(blind, fetch, olds);
+    const news = vmalertProps(catalog, { directory: LINKED() });
+    await expect(reconcileBinary(blind, fetch, news, { olds, output })).rejects.toThrow(
+      'they are one file under two spellings',
+    );
+  });
+});

package/src/release/binary-claim.ts

@@ -0,0 +1,80 @@
+/**
+ * What a Release.Binary may take over at a path it holds no state for: ONLY the pinned binary, and
+ * only under `--adopt`. Asked the same way at plan (binary-diff.ts) and at apply
+ * (binary-lifecycle.ts), so a plan never says `adopted` or `create` for a file the apply would then
+ * overwrite or silently claim.
+ *
+ * ⛔ OTHER BYTES ARE NEVER ADOPTED, `--adopt` OR NOT. 🔴 MEASURED 2026-09-22 (adopt-parity.test.ts,
+ *   through Alchemy's own Plan and Apply): under `--adopt`, a file with other bytes at the path
+ *   planned as `adopted` — beta.79 forces an `adopted` update after every takeover and prints it for
+ *   drift too — and the apply downloaded the archive and overwrote that file in place. With the
+ *   directory an Output (the probe skipped) the same file planned as `create`, and was overwritten.
+ *   ★ Refused rather than converged, which is what Host.File does with a file it adopts: a binary's
+ *   content is named entirely by its pin, so "adopting" other bytes is replacing them under
+ *   whatever runs them, with no rollback but a re-download — the very overwrite binary-form.ts
+ *   inPlaceRefusal refuses for a re-pin. The pinned bytes with another mode or owner ARE adopted;
+ *   the apply re-writes the bytes already on disk.
+ * ⛔ THE PINNED BYTES WITH NO STATE ARE NOT OURS WITHOUT `--adopt` — AT APPLY AS AT PLAN. The probe
+ *   already says `Unowned` for them (docs/ownership.md: identical is not ours). file-converge.ts
+ *   accepts them at apply as the resume of an interrupted install, and that gap is where the probe
+ *   never runs: every first deploy that passes `directory: dir.path`. 🔴 MEASURED 2026-09-22: a
+ *   declaration renamed (a new logical id, the same path) in a deploy that also changed its
+ *   HostDirectory's mode claimed the identical file at apply without `--adopt`; the orphan delete of
+ *   the old name then removed it, and the deploy reported success with the binary gone. With the
+ *   directory unchanged, the probe refused that same rename.
+ *   ⚠️ THE COST: an install interrupted between its write and its commit while a prop was an
+ *   Output now resumes only with `--adopt` — as the same install with every prop resolved already
+ *   did (its recovery read is `Unowned`), and as ownership.md says a create or replace interrupted
+ *   while a prop was an Output does. A retained old version is not re-claimed by a rollback either.
+ *   ★ `renamedFrom()` IS THE REMEDY FOR A RENAME: `.pipe(renamedFrom('old-id'))` migrates the row
+ *   and keeps the file (adopt-parity.test.ts). 🔴 MEASURED 2026-09-22: the same rename under
+ *   `--adopt` claimed the file, the old name's delete then removed it, and the deploy succeeded
+ *   with the binary gone. binary.ts's delete now leaves a path another declaration installed in
+ *   the same deploy, so that is kept too — as an adoption, not as the old row. ⚠️ That guard sees
+ *   only this deploy's claims, by spelling; nothing here sees another row's claim in state.
+ * ★ HOW DIFF TELLS A TAKEOVER FROM ITS OWN ROW. Every row this resource commits records the digest
+ *   reconcile READ BACK, which it checked equal to the pin — so `output.sha256 === olds.sha256` for
+ *   every row of its own, and an update never changes the digest (a new digest is a new path, a
+ *   `replace`). The engine hands diff anything else only after a read of a path it holds no state
+ *   for: the adoption probe (`olds` = the declaration) or the recovery read of an interrupted
+ *   create (`olds` = its row). A non-file reads with digest '' (file-converge.ts).
+ */
+import { type FileTarget, readFileAttributes } from '../launchd/file-converge.ts';
+import type { HostRunner } from '../launchd/runner.ts';
+
+const TAKEN = 'already exists and is not this resource';
+
+const otherBytes = (found: string, pinned: string): string =>
+  `${found === '' ? 'something that is not a regular file' : `a file hashing to ${found}`} is ` +
+  `there, not the pinned binary (${pinned}). --adopt takes over only the pinned binary: taking ` +
+  'over other bytes would overwrite them in place. Remove it (or move it aside) and deploy again';
+
+/** Plan side: why diff must refuse `found` — a digest read at a path with no state — or undefined. */
+export const adoptionProblem = (found: string, pinned: string): string | undefined =>
+  found === pinned ? undefined : `${TAKEN}: ${otherBytes(found, pinned)}`;
+
+/**
+ * Apply side, for a reconcile with no `output` — a create, a replace's new generation, or the
+ * resume of either: why it must not write, or undefined. `adopt` is adoptsAtApply's answer (never
+ * true for a fresh replace). A symlink or directory is left to convergeFile, which refuses it by
+ * kind.
+ */
+export const claimProblem = async (
+  runner: HostRunner,
+  want: FileTarget,
+  adopt: boolean,
+): Promise<string | undefined> => {
+  const stat = await runner.stat(want.path);
+  if (stat?.kind !== 'file') return undefined;
+  const found = (await readFileAttributes(runner, want.path))?.sha256 ?? '';
+  if (found !== want.sha256) return adoptionProblem(found, want.sha256);
+  if (adopt) return undefined;
+  return (
+    `${TAKEN}: it holds the pinned binary, but this stack holds no state for it and the plan ` +
+    'could not ask first (a prop was still an Output, or a replace landed on it). ' +
+    'Identical is not ours: once claimed, a later delete removes it from whoever put it there. ' +
+    'Deploy with --adopt to take it over (a create, or an interrupted install of this one), or ' +
+    'remove it. If another declaration in this stack owned it under another name, declare the ' +
+    'rename with renamedFrom() instead'
+  );
+};

package/src/release/binary-claims.test.ts

@@ -0,0 +1,47 @@
+/**
+ * ONE PATH, ONE DECLARATION (binary.ts `claim`), through Alchemy's own Plan and Apply over the real
+ * localRunner in a fresh temp directory (fake-engine.ts).
+ *
+ * 🔴 MEASURED 2026-09-22 BEFORE THE FIX: `vmalert` and `vmalert-logs` declared at one path both
+ *   planned `create` and both succeeded; the next deploy, without `vmalert-logs`, planned
+ *   `vmalert: noop, vmalert-logs: delete` — and the file `vmalert` still declared was gone.
+ */
+import { afterEach, beforeEach, expect, test } from 'bun:test';
+import { mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { VMALERT_TEXT, realEngine } from './fake-engine.ts';
+import { VMUTILS_URL } from './fake-release.ts';
+
+let dir = '';
+beforeEach(async () => {
+  dir = join(await mkdtemp(join(tmpdir(), 'hf-claims-')), 'vmutils-1.151.0');
+  await mkdir(dir);
+});
+afterEach(async () => {
+  await rm(join(dir, '..'), { force: true, recursive: true });
+});
+
+const onDisk = () =>
+  Bun.file(join(dir, 'vmalert'))
+    .text()
+    .catch(() => undefined);
+
+test('⛔ a second resource at the same path is refused in the deploy that declares it', async () => {
+  const e = realEngine();
+  await expect(e.deploy({ vmalert: dir, 'vmalert-logs': dir })).rejects.toThrow(
+    'is already installed by',
+  );
+  // One of the two installed it; the other touched nothing.
+  expect(await onDisk()).toBe(VMALERT_TEXT);
+  expect(e.gets).toEqual([VMUTILS_URL]);
+});
+
+test('declared once, the survivor keeps its file when the stack is corrected', async () => {
+  const e = realEngine();
+  await e.deploy({ vmalert: dir, 'vmalert-logs': dir }).catch(() => undefined);
+  // ★ MEASURED: the first declared won the claim. The refused one left only the engine's
+  //   unfinished-create row, whose delete touches no file — so the survivor keeps its binary.
+  expect(await e.deploy({ vmalert: dir })).toEqual({ vmalert: 'noop', 'vmalert-logs': 'delete' });
+  expect(await onDisk()).toBe(VMALERT_TEXT);
+});

package/src/release/binary-diff.ts

@@ -0,0 +1,73 @@
+/**
+ * Release.Binary's plan-time answer: refuse what the plan can already see is wrong, `replace` when
+ * the binary's identity moves, and otherwise compare the live file with the declaration.
+ *
+ * ⛔ THE PINS MUST BE PLAIN VALUES, AND ARE CHECKED EVEN WHILE `directory` IS AN OUTPUT. A pin that
+ *   is an Output would be computed during the deploy — a fetch by another name — so a malformed or
+ *   non-literal pin fails the plan here, before a byte is fetched, whatever else is unresolved.
+ *   ⚠️ A CREATE IS NEVER DIFFED: the engine plans a first deploy without calling diff, and skips
+ *   the adoption probe while any prop is an Output. A pin wired from another resource's Output on
+ *   a FIRST deploy therefore reaches no plan-time check; reconcile refuses it before any host call
+ *   or request, from the props as the stack program declared them (declared-pins.ts). 🔴 Until
+ *   2026-09-22 it was checked there for shape only, and a swapped archive with swapped digests
+ *   installed (apply-pins.test.ts).
+ * ⛔ A NEW PIN IS A NEW PATH (binary-form.ts inPlaceRefusal). When the path is resolved and
+ *   unchanged, a changed pin is refused here; when it is resolved and new, it is a `replace`.
+ * ⚠️ WHILE THE DIRECTORY IS STILL AN OUTPUT the path is unknown, and the answer depends on whether
+ *   the BYTES move, because the path may turn out not to have:
+ *   - other bytes (or another name) → `replace`. If the path did not move after all, the new
+ *     generation's create finds the old file, which does not hold its bytes, and refuses
+ *     (file-converge.ts never overwrites what a generation does not own).
+ *   - the same bytes from another archive (a re-pin, a repack) → `update`, NEVER `replace`. 🔴 A
+ *     replace onto the same path would accept the old file as its own (same bytes, same mode) and
+ *     then Phase 2 would delete the OLD generation — at that same path, taking the new one's file
+ *     with it. An update reaches reconcile with `olds`, whose in-place guard refuses the same path,
+ *     and whose move (file-converge.ts) writes the new path before removing the old.
+ *   ★ Not the engine's default either way: a changed prop is an update by default, which is
+ *   exactly the in-place overwrite this resource refuses.
+ * ★ Create-before-delete: two versions can sit in two directories at once, so nothing forces
+ *   `deleteFirst`; the old file goes only once the new one is written and verified.
+ * ⚠️ HOUSE, NOT UPSTREAM: this reads the live file at plan time and can answer `noop`. Upstream's
+ *   guidance is a diff that rarely does either (docs/release-binary-upstream.md).
+ */
+import { type Diff, isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import { diffTarget } from '../launchd/file-converge.ts';
+import { resolvedString } from '../launchd/host-effect.ts';
+import type { HostRunner } from '../launchd/runner.ts';
+import { adoptionProblem } from './binary-claim.ts';
+import {
+  type ReleaseBinaryAttributes,
+  type ReleaseBinaryProps,
+  inPlaceRefusal,
+  pinProblems,
+  pinsMoved,
+} from './binary-form.ts';
+import { NOTHING, desiredBinary, refuse } from './binary-lifecycle.ts';
+
+export const diffBinary = async (
+  runner: HostRunner,
+  news: Input<ReleaseBinaryProps>,
+  olds: ReleaseBinaryProps,
+  output: ReleaseBinaryAttributes,
+): Promise<Diff | undefined> => {
+  const problems = pinProblems((news ?? {}) as Parameters<typeof pinProblems>[0]);
+  if (problems.length > 0) throw refuse(output.path, `${problems.join('; ')}. ${NOTHING}`);
+  // ⛔ A TAKEOVER IS ONLY EVER OF THE PINNED BINARY (binary-claim.ts): `output` here is a read of a
+  //   path with no state, so the plan refuses what it would otherwise print as `adopted`.
+  const takeover = adoptionProblem(output.sha256, olds.sha256);
+  if (takeover !== undefined) throw refuse(output.path, `${takeover}. ${NOTHING}`);
+  // ★ pinProblems passed, so every pin — and `name` — is a plain value; only these are read below.
+  const pins = news as Pick<ReleaseBinaryProps, 'archive' | 'member' | 'sha256' | 'name'>;
+  const directory = resolvedString(news, 'directory');
+  const path = directory === undefined ? undefined : `${directory}/${pins.name}`;
+  const pinned = pinsMoved(olds, pins);
+  if (pinned && path === output.path) {
+    throw refuse(output.path, `${inPlaceRefusal(olds, pins)}. ${NOTHING}`);
+  }
+  // Resolved: a new path is a replace, other bytes or a mode or owner drift an update (diffTarget).
+  if (isResolved(news)) return diffTarget(runner, (await desiredBinary(runner, news)).want, output);
+  if (path !== undefined) return path === output.path ? undefined : { action: 'replace' };
+  if (pins.name !== olds.name || pins.sha256 !== olds.sha256) return { action: 'replace' };
+  return pinned ? { action: 'update' } : undefined;
+};

package/src/release/binary-form.ts

@@ -0,0 +1,229 @@
+/**
+ * Release.Binary's props, attributes and validation — the pure half of the provider.
+ *
+ * ★ THE PINNED ARCHIVE IS A PROP, NOT A LOOKUP. Repository, tag, exact asset name, size, the
+ *   archive's SHA-256, the member and the member's SHA-256 all arrive as props — usually spread from
+ *   a vendor data set (victoria.ts) by `catalogBinary()`. So the resource knows no vendor at all: a
+ *   second vendor is a second data module, never a change here, and the resource is the shape
+ *   Alchemy could accept (docs/release-binary-upstream.md).
+ * ⛔ NOTHING ESTATE-SPECIFIC IS A CONSTANT HERE. The install directory, owner, group and mode are
+ *   the consuming stack's props. A stack that keeps binaries under `/opt/<estate>/obs/bin` says so
+ *   in its own code.
+ * ⛔ EVERY PIN IS REQUIRED, AND WELL-FORMED OR REFUSED. There is no "latest", no optional digest and
+ *   no fallback to a checksum file fetched at apply — see victoria.ts for why a pin beats a fetch.
+ */
+import type { HostFileAttributes } from '../launchd/host-file-form.ts';
+import { identityProblems, pathProblems } from '../launchd/host-file-form.ts';
+
+/** One release archive, pinned: where it is published, and the bytes it must be. */
+export interface ReleaseArchive {
+  /** The GitHub repository that publishes it, `owner/name`: `'VictoriaMetrics/VictoriaMetrics'`. */
+  readonly repo: string;
+  /** The release tag, exactly as published: `'v1.151.0'`. */
+  readonly tag: string;
+  /**
+   * The asset's file name, whole: `'vmutils-darwin-arm64-v1.151.0.tar.gz'`. ⛔ Never a prefix or a
+   * pattern — `-enterprise` and `-cluster` siblings share every prefix with it.
+   */
+  readonly asset: string;
+  /** Bytes, per the release API. A download that runs past this is cut off and refused. */
+  readonly size: number;
+  /** The archive's SHA-256, lower-case hex, as the vendor's checksum file lists it. */
+  readonly sha256: string;
+}
+
+export interface ReleaseBinaryProps {
+  /** The pinned archive the binary comes out of. `catalogBinary()` fills it from a data set. */
+  archive: ReleaseArchive;
+  /** The archive member to extract, by its exact name: `'vmalert-prod'`. Nothing else is unpacked. */
+  member: string;
+  /** The member's own SHA-256 — what the installed file must hash to. */
+  sha256: string;
+  /**
+   * The installed file name: `'vmalert'`. ★ Separate from `member` on purpose — VictoriaMetrics
+   * names every member `<binary>-prod`, and a job's argv[0] should not carry that.
+   */
+  name: string;
+  /**
+   * The directory the binary is written into. ⛔ It must already exist — declare it with
+   * `HostDirectory` and pass that resource's `path`, which also orders it first. ★ Give each
+   * version its own directory (`catalogDirectory()`): an upgrade is then a new path — a
+   * create-before-delete replace, never an overwrite under a running daemon — and a rollback is a
+   * path. A new pin at the SAME path is refused (binary-diff.ts).
+   */
+  directory: string;
+  /**
+   * Permission bits. ⛔ Owner-readable and -executable, never group- or world-writable, never
+   * setuid, setgid or sticky — a writable binary is whoever-can-write's code, run as whoever runs
+   * the daemon. Its directory must not be group- or world-writable either (binary-lifecycle.ts).
+   * @default 0o755
+   */
+  mode?: number;
+  /** User name or numeric uid. Omitted: whoever the runner writes as. */
+  owner?: string | number;
+  /** Group name or numeric gid. Omitted: the directory's default group. */
+  group?: string | number;
+}
+
+export interface ReleaseBinaryAttributes extends HostFileAttributes {
+  /** The archive the bytes came from, whole. */
+  url: string;
+  /** The archive member installed, by its exact name: `vmalert-prod`. */
+  member: string;
+}
+
+/** Everything a download and its two checks need: one archive, one member, both digests. */
+export type PinnedDownload = {
+  readonly url: string;
+  readonly size: number;
+  /** The archive's pinned SHA-256. */
+  readonly sha256: string;
+  /** The archive member to extract, by exact name. */
+  readonly member: string;
+  /** The member's pinned SHA-256. */
+  readonly memberSha256: string;
+};
+
+export const DEFAULT_BINARY_MODE = 0o755;
+
+/**
+ * The release-asset URL. ★ GITHUB'S DOWNLOAD PATH, NOT THE API: it needs no token and spends no rate
+ *   limit (it redirects to a signed CDN URL — measured 2026-09-22 with HEAD). Every consumer the
+ *   estate census found publishes on GitHub except Grafana (grafana.com), which is not a
+ *   single-binary consumer anyway (docs/release-binary-catalogs.md). A second source kind arrives
+ *   with its first consumer, not before.
+ */
+export const releaseUrl = (repo: string, tag: string, asset: string): string =>
+  `https://github.com/${repo}/releases/download/${tag}/${asset}`;
+
+/** Where a declaration puts its binary: `<directory>/<name>`. */
+export const releaseBinaryPath = (props: {
+  readonly directory: string;
+  readonly name: string;
+}): string => `${props.directory}/${props.name}`;
+
+/** The download a declaration means. ⚠️ Validate first (binaryProblems): this trusts its input. */
+export const pinnedDownload = (props: ReleaseBinaryProps): PinnedDownload => ({
+  member: props.member,
+  memberSha256: props.sha256,
+  sha256: props.archive.sha256,
+  size: props.archive.size,
+  url: releaseUrl(props.archive.repo, props.archive.tag, props.archive.asset),
+});
+
+export const modeProblems = (mode: number): string[] => {
+  if (!Number.isSafeInteger(mode) || mode < 0 || mode > 0o7777) return ['mode must be 0–0o7777'];
+  const found: string[] = [];
+  if ((mode & 0o7000) !== 0) found.push('mode must not set setuid, setgid or sticky');
+  if ((mode & 0o022) !== 0) found.push('mode must not be group- or world-writable');
+  if ((mode & 0o100) === 0) found.push('mode must let the owner execute it');
+  // ⛔ AND READ IT: every plan re-hashes the binary, and a write is read back. MEASURED 2026-09-22,
+  //   an execute-only 0111 written by a non-root operator failed its read-back with EACCES.
+  if ((mode & 0o400) === 0) found.push('mode must let the owner read it (it is re-hashed)');
+  return found;
+};
+
+const HEX64 = /^[0-9a-f]{64}$/;
+export const MAX_ARCHIVE = 1 << 30;
+// ⛔ Strict on purpose: each is written into a URL or a path. GitHub's own owner and name alphabet.
+const REPO = /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?\/[A-Za-z0-9._-]+$/;
+const SEGMENT = /^[A-Za-z0-9._-]+$/;
+// ★ ONLY WHAT THE READER HANDLES: a gzipped tar. A `.zip` or a bare binary is a new capability
+//   with its own walk-down, not a name this should accept and then fail to unpack.
+const TARBALL = /\.(tar\.gz|tgz)$/;
+
+/** A single path segment that cannot climb, hide or name the directory itself. */
+const segmentProblem = (what: string, value: string): string | undefined =>
+  !SEGMENT.test(value) || value === '.' || value === '..'
+    ? `${what} must be one path segment of letters, digits, '.', '_' or '-': ${JSON.stringify(value)}`
+    : undefined;
+
+/** Everything wrong with the pins alone — plain strings in any declaration, resolved or not. */
+export const pinProblems = (props: {
+  readonly archive?: Partial<ReleaseArchive>;
+  readonly member?: unknown;
+  readonly sha256?: unknown;
+  readonly name?: unknown;
+}): string[] => {
+  const archive = props.archive ?? {};
+  const found: string[] = [];
+  const text = (what: string, value: unknown): string | undefined => {
+    if (typeof value === 'string') return value;
+    found.push(`${what} is required, as a plain string`);
+    return undefined;
+  };
+  const repo = text('archive.repo', archive.repo);
+  // ⚠️ `owner/..` passes the alphabet, and a URL parser normalises it away: the request would go
+  //   to `github.com/releases/…`, somewhere nobody pinned. Refused by name.
+  const repoName = repo?.slice(repo.indexOf('/') + 1);
+  if (repo !== undefined && (!REPO.test(repo) || repoName === '.' || repoName === '..'))
+    found.push(`archive.repo must be "owner/name": ${JSON.stringify(repo)}`);
+  for (const [what, value] of [
+    ['archive.tag', archive.tag],
+    ['name', props.name],
+  ] as const) {
+    const given = text(what, value);
+    const problem = given === undefined ? undefined : segmentProblem(what, given);
+    if (problem !== undefined) found.push(problem);
+  }
+  const asset = text('archive.asset', archive.asset);
+  if (asset !== undefined) {
+    const problem = segmentProblem('archive.asset', asset);
+    if (problem !== undefined) found.push(problem);
+    else if (!TARBALL.test(asset))
+      found.push(`archive.asset must be a .tar.gz or .tgz: "${asset}"`);
+  }
+  // ⛔ THE SIZE IS ALLOCATED UP FRONT (download.ts fills one buffer of exactly this many bytes), so
+  //   a typo'd size is a memory bomb in the deploying process. vmutils, the largest archive pinned,
+  //   is 123.6 MB; a gibibyte is a ceiling nothing single-binary should reach.
+  const size = archive.size;
+  if (typeof size !== 'number' || !Number.isSafeInteger(size) || size <= 0 || size > MAX_ARCHIVE) {
+    found.push(`archive.size must be the asset's byte count, 1 to ${String(MAX_ARCHIVE)}`);
+  }
+  for (const [what, value] of [
+    ['archive.sha256', archive.sha256],
+    ['sha256', props.sha256],
+  ] as const) {
+    const given = text(what, value);
+    if (given !== undefined && !HEX64.test(given))
+      found.push(`${what} must be 64 lower-case hex digits`);
+  }
+  const member = text('member', props.member);
+  // ⛔ The tar reader refuses these entries anyway; asking for one is a mistake to name at plan.
+  if (
+    member !== undefined &&
+    (member === '' || member.startsWith('/') || member.split('/').includes('..'))
+  ) {
+    found.push(`member must be a relative name inside the archive: ${JSON.stringify(member)}`);
+  }
+  return found;
+};
+
+const ARCHIVE_KEYS = ['repo', 'tag', 'asset', 'size', 'sha256'] as const;
+
+type Pins = Pick<ReleaseBinaryProps, 'archive' | 'member' | 'sha256'>;
+
+/** Whether two declarations pin different bytes: another archive, member or member digest. */
+export const pinsMoved = (olds: Pins, news: Pins): boolean =>
+  olds.member !== news.member ||
+  olds.sha256 !== news.sha256 ||
+  ARCHIVE_KEYS.some((key) => olds.archive[key] !== news.archive[key]);
+
+/**
+ * ⛔ A NEW PIN IS A NEW PATH. The same path with other bytes would overwrite a binary under the
+ *   daemon running it, and leave no rollback but a re-download — so it is refused, at plan when the
+ *   path is resolved (binary-diff.ts) and at apply otherwise (binary-lifecycle.ts).
+ */
+export const inPlaceRefusal = (olds: Pins, news: Pins): string =>
+  `a new pin (${news.archive.tag} ${news.member} ${news.sha256}) at the path of the installed ` +
+  `one (${olds.archive.tag} ${olds.member} ${olds.sha256}) would overwrite it in place; give each ` +
+  'version its own directory (catalogDirectory), so an upgrade is a new path';
+
+/** Everything wrong with a declaration, before any host or network is asked anything. */
+export const binaryProblems = (props: ReleaseBinaryProps): string[] => [
+  ...pinProblems(props),
+  ...pathProblems(props.directory).map((problem) => `directory: ${problem}`),
+  ...modeProblems(props.mode ?? DEFAULT_BINARY_MODE),
+  ...identityProblems('owner', props.owner),
+  ...identityProblems('group', props.group),
+];

package/src/release/binary-lifecycle.test.ts

@@ -0,0 +1,90 @@
+/**
+ * The install lifecycle over a fake host (launchd/fake-runner.ts) and a fake transport — no network,
+ * no real filesystem: what an install writes, what a matching host costs (nothing), and read and
+ * delete. Every refusal: binary-refusals.test.ts.
+ */
+import { describe, expect, test } from 'bun:test';
+import { sha256Hex } from '../launchd/job-form.ts';
+import { deleteBinary, readBinary } from './binary-lifecycle.ts';
+import { PATH, setup, writes } from './fake-install.ts';
+import { BINARY, ENTERPRISE_URL, VMUTILS_URL, bytesOf, pathsOn } from './fake-release.ts';
+
+describe('installing', () => {
+  test('the declared member, from the plain archive only, verified, at <directory>/<name>', async () => {
+    const s = setup();
+    const notes: string[] = [];
+    const attrs = await s.install(s.props(), { note: async (m: string) => void notes.push(m) });
+    // ⛔ The enterprise sibling was served too, under its real name; it was never asked for.
+    expect(s.transport.requests).toEqual([VMUTILS_URL]);
+    expect(s.transport.requests).not.toContain(ENTERPRISE_URL);
+    expect(s.fake.files.get(PATH)?.bytes).toEqual(BINARY.vmalert);
+    expect(attrs).toMatchObject({
+      member: 'vmalert-prod',
+      mode: 0o755,
+      path: PATH,
+      url: VMUTILS_URL,
+    });
+    expect(attrs.sha256).toBe(sha256Hex(BINARY.vmalert));
+    expect(notes[0]).toContain('downloading');
+  });
+
+  test('⛔ an undeclared member is never written: vmagent-prod and vmauth-prod stay in the archive', async () => {
+    const s = setup();
+    await s.install();
+    expect(pathsOn(s.fake)).toEqual([PATH]);
+    expect(writes(s.fake).map((c) => c[1])).toEqual([PATH]);
+  });
+
+  test('already installed and matching: no download, no write', async () => {
+    const s = setup();
+    const output = await s.install();
+    s.transport.requests.length = 0;
+    s.fake.calls.length = 0;
+    await s.install(s.props(), { olds: s.props(), output });
+    expect([s.transport.requests, writes(s.fake)]).toEqual([[], []]);
+  });
+
+  test('the right bytes with the wrong mode: re-written from disk, not downloaded', async () => {
+    const s = setup();
+    const output = await s.install();
+    s.transport.requests.length = 0;
+    const fixed = await s.install(s.props({ mode: 0o555 }), { olds: s.props(), output });
+    expect(fixed.mode).toBe(0o555);
+    expect(s.transport.requests).toEqual([]);
+  });
+
+  // ⚠️ Only under --adopt (binary-claim.ts); without it, binary-refusals.test.ts refuses the same file.
+  test('unprobed, the pinned bytes at the path, under --adopt: kept, not fetched', async () => {
+    const s = setup();
+    s.fake.files.set(PATH, { bytes: BINARY.vmalert, gid: 0, kind: 'file', mode: 0o755, uid: 0 });
+    expect((await s.install(s.props(), { adopt: true })).sha256).toBe(sha256Hex(BINARY.vmalert));
+    expect([s.transport.requests, writes(s.fake)]).toEqual([[], []]);
+  });
+
+  test('a new version is a new path: written, then the old one removed', async () => {
+    const s = setup();
+    const old = { ...(await s.install()), path: '/opt/example/bin/vmutils-1.150.0/vmalert' };
+    s.fake.files.set(old.path, {
+      bytes: bytesOf('old'),
+      gid: 0,
+      kind: 'file',
+      mode: 0o755,
+      uid: 0,
+    });
+    await s.install(s.props(), { output: old });
+    expect(s.fake.files.has(old.path)).toBe(false);
+    expect(s.fake.files.has(PATH)).toBe(true);
+  });
+});
+
+describe('read and delete', () => {
+  test('read reports the file at the path by its digest; delete removes it, twice', async () => {
+    const s = setup();
+    expect(await readBinary(s.fake.runner, s.props())).toBeUndefined();
+    const output = await s.install();
+    expect((await readBinary(s.fake.runner, s.props()))?.sha256).toBe(output.sha256);
+    await deleteBinary(s.fake.runner, output);
+    await deleteBinary(s.fake.runner, output);
+    expect(s.fake.files.has(PATH)).toBe(false);
+  });
+});