@homeflare/alchemy 0.20.0 → 0.21.0

package/src/release/binary.ts

@@ -0,0 +1,181 @@
+/**
+ * `Release.Binary` — one binary out of a pinned release archive, written onto a host and verified
+ * twice: the archive against its pinned SHA-256, then the binary against its own.
+ *
+ * - reconcile — validate every prop; download the archive by its exact URL; verify it; unpack ONLY
+ *   the declared member; verify that; write it atomically through the HostRunner; read it back. A
+ *   file already holding the pinned bytes is never downloaded again.
+ * - read — lstat plus the SHA-256 of the bytes; never runs the binary.
+ * - diff — the pins, the path, then mode and owner against the live file (binary-diff.ts).
+ * - replace — when the path moves (a new version is a new directory): create-before-delete.
+ * - delete — removes the file, never the directory.
+ *
+ * ★ VENDOR-NEUTRAL. The pinned archive arrives as props, usually from a data set beside this
+ *   (victoria.ts) through `catalogBinary()`; nothing here knows a vendor, a package or a version.
+ * ⛔ IT INSTALLS; IT NEVER STARTS. No launchctl, no systemctl, no restart: the job that runs the
+ *   binary is the stack's own `LaunchdJob`, which puts this resource's `path` in its argv so the
+ *   engine installs first and restarts the job when the path moves.
+ * ⚠️ NOTHING IS ADOPTED WITHOUT `--adopt`, AT PLAN OR AT APPLY: the probe reads a file already at
+ *   the path as `Unowned` — even one holding exactly the pinned bytes (docs/ownership.md) — and
+ *   where the probe never ran (a prop was an Output) reconcile refuses it the same way. With
+ *   `--adopt`, a file holding the pinned bytes is recognised by its digest and taken over without
+ *   a download. ⛔ A file with OTHER bytes is never adopted, `--adopt` or not: that would be an
+ *   overwrite in place that the plan prints as `adopted` (binary-claim.ts, both halves).
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
+import { lift } from '../launchd/host-effect.ts';
+import { HostRunnerService } from '../launchd/runner.ts';
+import { adoptsAtApply } from '../ownership/adopt.ts';
+import { noteUnfinished } from '../ownership/resume.ts';
+import { diffBinary } from './binary-diff.ts';
+import {
+  type ReleaseBinaryAttributes,
+  type ReleaseBinaryProps,
+  releaseBinaryPath,
+} from './binary-form.ts';
+import {
+  NOTHING,
+  deleteBinary,
+  reconcileBinary,
+  refreshBinary,
+  refuse,
+} from './binary-lifecycle.ts';
+import { readWithoutState } from './binary-read.ts';
+import { declaredPinProblems } from './declared-pins.ts';
+import { type DownloadPolicy, httpFetchArchive, sharingInFlight } from './download.ts';
+
+export type { ReleaseBinaryAttributes, ReleaseBinaryProps } from './binary-form.ts';
+
+export interface ReleaseBinary extends Resource<
+  'Release.Binary',
+  ReleaseBinaryProps,
+  ReleaseBinaryAttributes
+> {}
+
+/**
+ * One binary from a pinned release archive, installed onto a host and verified against digests
+ * the stack pins in code — the archive's, then the binary's own.
+ *
+ * ### Installing a binary
+ *
+ * The directory is declared first and passed by its `path`, which orders the two; the job that
+ * runs the binary references the binary's `path`, which orders the job after it.
+ *
+ * **Example:**
+ *
+ * ```ts
+ * const vmalertOf = { package: 'vmutils', version: '1.151.0', platform: 'darwin-arm64', binary: 'vmalert' };
+ * const dir = yield* HostDirectory('vmutils-1.151.0', {
+ *   path: catalogDirectory('/opt/example/bin', vmalertOf),
+ *   mode: 0o755,
+ * });
+ * const vmalert = yield* ReleaseBinary('vmalert', {
+ *   ...catalogBinary(VICTORIA_RELEASES, vmalertOf),
+ *   directory: dir.path,
+ * });
+ * // LaunchdJob(…, { programArguments: [vmalert.path, '--httpListenAddr=127.0.0.1:8880'] })
+ * ```
+ *
+ * @resource
+ */
+export const ReleaseBinary = Resource<ReleaseBinary>('Release.Binary');
+
+/** Test seams — NOT on the barrel. Every caller outside tests uses the defaults. */
+export type ReleaseBinaryInternals = { readonly download?: DownloadPolicy };
+
+export const makeReleaseBinaryProvider = (internals: ReleaseBinaryInternals = {}) =>
+  Provider.effect(
+    ReleaseBinary,
+    Effect.gen(function* () {
+      const runner = yield* HostRunnerService;
+      const client = yield* HttpClient.HttpClient;
+      const fetch = sharingInFlight(httpFetchArchive(client, internals.download));
+      /**
+       * ⛔ ONE PATH, ONE DECLARATION. MEASURED 2026-09-22 (binary-claims.test.ts, before this): two
+       *   resources installing one path in one deploy both planned `create`, shared one download,
+       *   and both recorded the file as theirs. Dropping either later — gating vmalert-logs off
+       *   along with its own ReleaseBinary, say — deleted the file the other still declared, and
+       *   that deploy reported the survivor `noop`. So a second resource claiming a path in the
+       *   same run is refused before it touches anything. Two jobs that run one binary share ONE
+       *   ReleaseBinary. ⚠️ Keyed by spelling: one file under two spellings is not caught here.
+       */
+      const claims = new Map<string, string>();
+      const claim = (fqn: string, props: ReleaseBinaryProps): void => {
+        const path = releaseBinaryPath(props);
+        const holder = claims.get(path);
+        if (holder !== undefined && holder !== fqn) {
+          throw refuse(
+            path,
+            `is already installed by ${holder} in this deploy; declare each binary path once, ` +
+              `and let every job that runs it share that one resource. ${NOTHING}`,
+          );
+        }
+        claims.set(path, fqn);
+      };
+      return ReleaseBinary.Provider.of({
+        list: () => Effect.succeed([]),
+
+        // ⛔ The probe (no `output`) validates every prop first, so a malformed pin fails the plan
+        //   here — before any host call, let alone a download. A recovery read never fails its
+        //   caller (binary-read.ts): its props are the failed deploy's.
+        read: ({ fqn, instanceId, olds, output }) =>
+          output === undefined
+            ? readWithoutState(runner, { fqn, instanceId, olds })
+            : lift(() => refreshBinary(runner, output)),
+
+        diff: ({ instanceId, news, olds, output }) =>
+          output === undefined
+            ? noteUnfinished(instanceId)
+            : lift(() => diffBinary(runner, news, olds, output)),
+
+        // ★ `--adopt` reaches the apply too: the probe never ran for a create with an Output prop.
+        // ⛔ So do the pins AS DECLARED: `news` is resolved by now, and a first deploy is never
+        //   diffed, so only the stack's own record can show a digest that was an Output.
+        reconcile: ({ fqn, instanceId, news, olds, output, session }) =>
+          Effect.gen(function* () {
+            const declared = yield* declaredPinProblems(fqn);
+            const adopt = yield* adoptsAtApply({ fqn, instanceId, output });
+            return yield* lift(async () => {
+              claim(fqn, news);
+              return reconcileBinary(runner, fetch, news, {
+                adopt,
+                declared,
+                note: (message) => Effect.runPromise(session.note(message)),
+                olds,
+                output,
+              });
+            });
+          }),
+
+        /**
+         * ⛔ NEVER REMOVE A FILE ANOTHER DECLARATION INSTALLED IN THIS DEPLOY. Alchemy runs every
+         *   delete (Apply.ts collectGarbage, Phase 2) only after every reconcile has succeeded, so a
+         *   claim by another name means the file is that resource's now, verified as its pin.
+         *   🔴 MEASURED 2026-09-22 (adopt-parity.test.ts): a rename under --adopt — the new name
+         *   claimed the file, the old name's orphan delete removed it, and the deploy succeeded
+         *   with the binary gone. ★ Left in place rather than removed: a stray file is a tidy-up, a
+         *   missing binary is an outage. ⚠️ Keyed by spelling, like the claims themselves.
+         * ★ A deleted resource gives its claim back, so a provider that outlives one deploy never
+         *   refuses the next resource declared at that path.
+         */
+        delete: ({ fqn, output, session }) =>
+          lift(async () => {
+            const holder = claims.get(output.path);
+            if (holder !== undefined && holder !== fqn) {
+              await Effect.runPromise(
+                session.note(`${output.path} was installed by ${holder} in this deploy; kept`),
+              );
+              return;
+            }
+            await deleteBinary(runner, output);
+            if (holder === fqn) claims.delete(output.path);
+          }),
+      });
+    }),
+  );
+
+/** The provider, as a stack uses it. It needs a HostRunnerService and an HttpClient. */
+export const ReleaseBinaryProvider = () => makeReleaseBinaryProvider();

package/src/release/catalog.test.ts

@@ -0,0 +1,96 @@
+/**
+ * A catalog request → pinned props, or a refusal — pure, over the REAL Victoria data set. Every
+ * refusal here happens in the stack's own program, so it fails the plan before any resource runs
+ * (plan.test.ts proves that through the engine).
+ */
+import { describe, expect, test } from 'bun:test';
+import { binaryProblems } from './binary-form.ts';
+import { catalogBinary, catalogDirectory, catalogProblems, identifyBinary } from './catalog.ts';
+import { BinaryRefused } from './refused.ts';
+import { VICTORIA_RELEASES } from './victoria.ts';
+
+const VMALERT = {
+  binary: 'vmalert',
+  package: 'vmutils',
+  platform: 'darwin-arm64',
+  version: '1.151.0',
+};
+
+describe('refusing what the catalog does not pin', () => {
+  test.each([
+    [
+      'a version the catalog does not pin',
+      { version: '1.152.0' },
+      'vmutils 1.152.0 is not in the catalog',
+    ],
+    ['the tag spelling', { version: 'v1.151.0' }, 'is not in the catalog'],
+    ['an enterprise version', { version: '1.151.0-enterprise' }, 'is not in the catalog'],
+    [
+      'a cluster package',
+      { package: 'victoria-metrics-cluster' },
+      'package "victoria-metrics-cluster"',
+    ],
+    ['the vendor member name', { binary: 'vmalert-prod' }, 'that is the archive member'],
+    ['a binary vmutils does not ship', { binary: 'vminsert' }, 'has no binary "vminsert"'],
+    ['another platform', { platform: 'linux-amd64' }, 'not pinned for platform "linux-amd64"'],
+    ['an inherited key', { package: 'constructor' }, 'package "constructor"'],
+  ])('refuses %s', (_, change, message) => {
+    const request = { ...VMALERT, ...change };
+    expect(catalogProblems(VICTORIA_RELEASES, request).join('; ')).toContain(message);
+    expect(() => catalogBinary(VICTORIA_RELEASES, request)).toThrow(message);
+  });
+
+  test('the refusal is typed, names the binary, and says nothing was fetched', () => {
+    let caught: unknown;
+    try {
+      catalogBinary(VICTORIA_RELEASES, { ...VMALERT, version: '1.152.0' });
+    } catch (cause) {
+      caught = cause;
+    }
+    expect(caught).toBeInstanceOf(BinaryRefused);
+    expect((caught as Error).message).toMatch(
+      /^Release\.Binary vmalert: .* Nothing was fetched\.$/,
+    );
+  });
+});
+
+describe('what a pinned request becomes', () => {
+  test('props that validate once the stack adds a directory', () => {
+    const pinned = catalogBinary(VICTORIA_RELEASES, VMALERT);
+    const directory = catalogDirectory('/opt/example/bin', VMALERT);
+    expect(directory).toBe('/opt/example/bin/vmutils-1.151.0');
+    expect(binaryProblems({ ...pinned, directory })).toEqual([]);
+  });
+
+  test('every binary of every pinned archive resolves to valid props', () => {
+    for (const [pkg, entry] of Object.entries(VICTORIA_RELEASES.packages)) {
+      for (const [version, platforms] of Object.entries(entry.versions)) {
+        for (const platform of Object.keys(platforms)) {
+          for (const binary of Object.keys(entry.binaries)) {
+            const request = { binary, package: pkg, platform, version };
+            const props = { ...catalogBinary(VICTORIA_RELEASES, request), directory: '/x/y' };
+            expect(binaryProblems(props)).toEqual([]);
+          }
+        }
+      }
+    }
+  });
+});
+
+describe('identifying an installed file', () => {
+  test('by its digest alone', () => {
+    const pin = '4759ec89a466129b9eefc22244a111e1f489739340747805fd93b58fd0f7b2dd';
+    expect(identifyBinary([VICTORIA_RELEASES], pin)).toEqual({
+      binary: 'victoria-traces',
+      package: 'victoria-traces',
+      platform: 'darwin-arm64',
+      vendor: 'VictoriaMetrics',
+      version: '0.10.0',
+    });
+  });
+
+  test("an archive's digest is not a binary's: identity is by the member's own line", () => {
+    const archive = 'cbe83f1d409cbb85fbf1c890c4a9b7fd34c1d74acec4dce2e0ebe46fcb260e38';
+    expect(identifyBinary([VICTORIA_RELEASES], archive)).toBeUndefined();
+  });
+});

package/src/release/catalog.ts

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

package/src/release/checksums.test.ts

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

package/src/release/checksums.ts

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

package/src/release/declared-pins.ts

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