@homeflare/alchemy 0.20.0 → 0.22.0

package/docs/release-binary-openbao.md

@@ -0,0 +1,151 @@
+# Release binaries — the OpenBao walk-down
+
+Status: active
+Verified: 2026-09-23
+
+`OPENBAO_RELEASES` (`src/release/openbao.ts`) is the second data set, and the
+first whose checksum file never lists its own binary. Every command below was
+run 2026-09-23 against `openbao/openbao` v2.6.2, from this worktree, network
+reads only — nothing executed the vendor binary.
+
+## The release itself
+
+```
+gh api repos/openbao/openbao/releases/tags/v2.6.2
+```
+
+`published_at` 2026-08-18T16:21:00Z, `immutable: false`, 251 assets.
+`openbao_2.6.2_darwin_arm64.tar.gz`: 76,833,570 bytes,
+`digest: sha256:4e495376174accc0e014d31e9901f518a974f966850c839f626347eaac05fd52`.
+
+## checksums.txt
+
+```
+curl -sL -o checksums.txt \
+  https://github.com/openbao/openbao/releases/download/v2.6.2/checksums.txt
+shasum -a 256 checksums.txt
+```
+
+8,683 bytes, `sha256 3d4a19fdc54a86fd94ce59ea91316dbf4304180bb27ae818e78e85c7f2164645`
+— equal to GitHub's own `digest` for the asset. 83 lines, every one matching
+`^[0-9a-f]{64}  [^\s/]+$` (`checksums.ts`'s parser), LF endings, a trailing
+newline, no name repeated. Line 20 is the darwin_arm64 archive and equals the
+release API's digest. **41 of the 83 lines are `.sbom.json`; the rest are
+archives, `.deb` or `.rpm` — never `bao` itself**: `grep -n '  bao$'
+checksums.txt` finds nothing. That is why the member digest is `computed`,
+never `members` (checksums.ts's header explains the shape generally; this is
+OpenBao's instance of it).
+
+## The signature over checksums.txt
+
+```
+curl -sL -o checksums.txt.gpgsig \
+  https://github.com/openbao/openbao/releases/download/v2.6.2/checksums.txt.gpgsig
+curl -sL -o openbao-gpg-pub-20240618.asc \
+  https://openbao.org/assets/openbao-gpg-pub-20240618.asc
+gpg --dearmor -o openbao-pub.gpg openbao-gpg-pub-20240618.asc
+gpgv --keyring ./openbao-pub.gpg checksums.txt.gpgsig checksums.txt
+```
+
+```
+gpgv: Signature made Tue Aug 18 11:57:25 2026 EDT
+gpgv:                using RSA key E617DCD4065C2AFC0B2CF7A7BA8BC08C0F691F94
+gpgv: Good signature from "OpenBao <openbao@lists.lfedge.org>"
+```
+
+`gpg --show-keys --with-fingerprint` on the same file: primary
+`66D1 5FDD 8728 7219 C8E1 5478 D200 CD70 2853 E6D0`, signing subkey
+`E617 DCD4 065C 2AFC 0B2C F7A7 BA8B C08C 0F69 1F94` — both match OpenBao's own
+`install.mdx` at this tag. `checksums.txt.gpgsig` is 566 bytes, sha256
+`40f294d642a2b4e9adac766ca6b8b2633e15b3dbfdf63969dedbf46d94df53e8`; the key
+file is 6,896 bytes, sha256
+`1862a196422947124282e026ea4e09d6f7c5d383b628d90c17906936e6e5a8e0`.
+
+⚠️ **Trust on first use, across two channels one project runs**: the release
+asset (GitHub) and the key (openbao.org) are both OpenBao's own
+infrastructure. A verified signature says the two agree, not that a third
+party attests to either. `cosign` is not installed on the mini (`which
+cosign` — not found), so the Sigstore bundle alongside `checksums.txt` was
+read, not verified: its certificate names
+`https://github.com/openbao/openbao/.github/workflows/release.yml@refs/heads/release/2.6.x`,
+issuer `https://token.actions.githubusercontent.com` — recorded in
+`openbao.ts` as an **unverified** identity. "GPG or Sigstore" is met by the
+GPG half.
+
+Attestations, for completeness: `gh api
+repos/openbao/openbao/attestations/sha256:4e49…` → 404. Positive control
+(`gh api repos/cli/cli/attestations/sha256:<its macOS_arm64 digest>`) → 200,
+2 attestations, same day. A 404 here means "none published", not "the API is
+down".
+
+## The archive: download, hash, unpack
+
+```
+curl -sL -o openbao_2.6.2_darwin_arm64.tar.gz \
+  https://github.com/openbao/openbao/releases/download/v2.6.2/openbao_2.6.2_darwin_arm64.tar.gz
+shasum -a 256 openbao_2.6.2_darwin_arm64.tar.gz
+tar -tvzf openbao_2.6.2_darwin_arm64.tar.gz
+```
+
+76,833,570 bytes, sha256
+`4e495376174accc0e014d31e9901f518a974f966850c839f626347eaac05fd52` — equal to
+the pin. `tar -tvzf` (full stream, nothing saved beyond the archive itself):
+four root-level regular files, `ustar`, no PAX header, no directory entry —
+
+```
+-rw-r--r--  0 runner runner    131858 CHANGELOG.md
+-rw-r--r--  0 runner runner     15958 LICENSE
+-rw-r--r--  0 runner runner      7136 README.md
+-rwxr-xr-x  0 root   root   193769394 bao
+```
+
+The kit's own `extractMembers` (`archive.ts`) read the same stream without
+refusing it and returned the same four names, in the same order — the
+previous partial-range read (`release-binary-catalogs.md`'s queue note) is
+superseded by this full-stream one, so **no tar-reader change is needed for
+this vendor**.
+
+## The member digest — computed, not the vendor's
+
+```
+tar -xzOf openbao_2.6.2_darwin_arm64.tar.gz bao | shasum -a 256
+```
+
+`d476d17e81a35e6d70dd7e86a8ab2a3664313525118f1f1cfe0130e7a2b95f3a` — and the
+kit's `extractMembers` over the same bytes produced the identical digest. Two
+independent readers agree, which is what `computed` in `openbao.ts` records,
+dated, next to a header explaining it is not a vendor fact.
+
+## The extracted binary, never run
+
+```
+tar -xzf openbao_2.6.2_darwin_arm64.tar.gz bao
+chmod -x bao   # never made executable in this worktree
+otool -L bao
+codesign -dv --verbose=2 bao
+xattr -l bao
+```
+
+`otool -L`: `libSystem.B.dylib`, `libresolv.9.dylib`, CoreFoundation,
+Security — all system frameworks, none from `/nix/store` — the same class as
+Victoria's five. `codesign`: `flags=0x20002(adhoc,linker-signed)`, no
+TeamIdentifier — a stock Go/macOS ad-hoc signature, same as the Victoria
+binaries. `xattr -l`: `com.apple.provenance` only, no quarantine. Build
+provenance (`goreleaser.other.yaml` at v2.6.2, read, not re-measured here):
+`CGO_ENABLED=0`, tag `ui` — the same build class the darwin release ships for
+every OpenBao platform.
+
+Both scratch copies (`bao`, the `.tar.gz`) were deleted after these commands;
+nothing was executed and nothing was written outside the scratch directory.
+
+## What this does NOT establish
+
+- **Sigstore identity is read, not cryptographically checked** — `cosign` was
+  not run. Treat the workflow identity above as a claim, not a verification.
+- **The agent never ran `bao`.** Whether it starts under launchd, and whether
+  its approle auto-auth / template / exec behaviour matches the Nix build
+  the vault server runs today, is unmeasured — expected to be unaffected
+  (nothing here suggests otherwise), but nobody has watched it happen.
+- **No adoption or install-path measurement.** This PR adds only the catalog
+  entry, its tests and this record — no `ReleaseBinary` declaration, no
+  consuming stack change.

package/docs/release-binary-refusals.md

@@ -0,0 +1,57 @@
+# Release binaries — every refusal
+
+Status: active
+Verified: 2026-09-22
+
+Everything `Release.Binary` refuses, by where it is refused. The guide is
+[release-binary.md](./release-binary.md). ★ One page per subject: the guide says
+what a declaration does, this says what stops it, and a new refusal lands here.
+
+In the stack program (`catalogBinary`): a package, version, platform or
+binary the data set does not pin, including `v1.151.0`, `1.151.0-enterprise`,
+`victoria-metrics-cluster`, `vmalert-prod` and inherited keys like
+`constructor`.
+
+At plan (the probe and `diff`), before anything is touched: a pin that is
+missing or not a plain value (an Output pin would be a fetch; a first deploy
+is never diffed, so reconcile refuses it there, before any host call, from the
+props as declared); a repo that is not `owner/name`, or whose name is `.` or
+`..`; a tag, asset or name that is not one safe path segment; an asset that is
+not a `.tar.gz` or `.tgz` (a glob is not a name); a size that is not an
+integer from 1 byte to 1 GiB (it is allocated up front); a digest that is not
+64 lower-case hex; a member that is absolute or climbs. Also a relative or
+unnormalised directory; a mode that is setuid, setgid, sticky, group- or
+world-writable, or not owner-readable and owner-executable; an owner or group
+that is not a valid name or id; a new pin at the same path.
+
+⚠️ **Not on a first deploy with `directory: dir.path`.** Alchemy neither
+probes nor diffs a create whose props hold an Output, so there every check
+above runs at apply, after `HostDirectory` has made the directory (measured: a
+group-writable mode planned `create`, then the apply ran `mkdir` and refused).
+Nothing is written to the binary's path. A failed first install never bricks
+the next plan: the recovery read of its row answers "nothing recovered"
+(`binary-read.ts`).
+
+At plan, only under `--adopt` (the probe then hands `diff` what it read): a
+file at the path that is not the pinned binary, or not a regular file.
+
+At apply, before the download: a second resource installing the same path in
+one deploy (two jobs that run one binary share one `ReleaseBinary`; measured,
+two owners meant dropping either deleted the other's file); a missing
+directory, one that is a symlink, or one that group or other may write; a
+symlink or directory at the path; a file the resource does not own (without
+`--adopt`, even the pinned bytes; with it, anything but the pinned bytes); a
+chown without root.
+
+From the vendor: a status other than 200; a body past or short of the pinned
+size; an archive whose SHA-256 is not the pin; an archive entry that is
+absolute, has a `..` segment, is a hard link, symlink, directory, device, FIFO
+or contiguous file, is a GNU long-name or PAX header, is named twice, fails its
+header checksum, uses base-256, is neither ustar nor GNU, a lone zero block,
+data after the end, a truncated archive; the declared member missing; the
+member's SHA-256 not its pin. Every one of these ends `Nothing was written.`
+
+After the write: a file that does not read back as declared (a create is
+removed). Errors are tagged (`BinaryRefused`, `DownloadFailed`,
+`ChecksumMismatch`, `ArchiveRefused`) and carry the house refusal sentence.
+⚠️ Tagged, not typed: no caller can `catchTag` one yet (`error-channel.test.ts`).

package/docs/release-binary-upstream.md

@@ -0,0 +1,163 @@
+# Release binaries — what upstream would need
+
+Status: active
+Verified: 2026-09-22 (against `alchemy-run/alchemy` at `v2.0.0-beta.79`, read-only:
+AGENTS.md and `scripts/generate-api-reference.ts`, plus the installed
+`src/Command/Exec.ts`, `src/GitHub/Release.ts`, `src/GitHub/BaseUrl.ts`,
+`src/Util/AtomicFile.ts`, `src/Hetzner/Ssh.ts` and `src/Hetzner/Providers.ts`)
+
+`Release.Binary` is built so it **could** be contributed to Alchemy. This page
+is the honest gap list: what already fits, and what a pull request to
+`alchemy-run/alchemy` would have to change first. Nothing here is a promise
+that upstream wants it.
+
+## Already shaped for it
+
+- **Generic before its first release.** It began as `Victoria.Binary` with the
+  catalog inside the resource. It was generalised before any state row carried
+  that type name, because a rename after release would be a state migration.
+  The pinned archive (repo, tag, exact asset name, size, archive digest,
+  member, member digest, installed name) is props. Vendor data sets sit beside
+  it as plain modules. Alchemy could ship the resource without shipping anyone's
+  pins.
+- **Named the upstream way.** The type is `Release.Binary` (`Namespace.Kind`).
+  Under upstream's layout it would be `src/Release/Binary.ts`, imported as
+  `import * as Release from "alchemy/Release"`, used as `Release.Binary`. The
+  house exports the prefixed `ReleaseBinary`, as it does `HostFile` and
+  `LaunchdJob`. Upstream's `GitHub.Release` already means _publishing_ a
+  release, so the GitHub namespace would be the confusing home.
+- **The lifecycle is beta.79's**: `read`, `diff`, `reconcile`, `delete`,
+  `list` returning `[]`. No `create`/`update`. `reconcile` is one flow —
+  observe the path, ensure the bytes, sync mode and owner, read back — not a
+  create body and an update body. ⚠️ It does branch on `output` and `olds` for
+  **ownership**: only a create may take over a file under `--adopt`
+  (`file-converge.ts`), and the in-place guard compares `olds`' pins (gap 3).
+- **Props are plain types**, never `Input<T>`, and every prop has JSDoc, with
+  `@default` where one applies. ⚠️ Not every attribute: `path`, `mode`, `uid`,
+  `gid` and `size` come from `HostFileAttributes` with no JSDoc, so the
+  generator would print them bare.
+- **The resource JSDoc is the generator's shape**: `### Installing a binary`,
+  `**Example:**` with fenced TypeScript, and `@resource` last. (An untitled
+  example is titled "Example" by the generator.) ⚠️ The example needs
+  `HostDirectory`, `LaunchdJob` and `VICTORIA_RELEASES`, which upstream lacks.
+- **Errors are tagged** (`Data.TaggedError`: `BinaryRefused`, `DownloadFailed`,
+  `ChecksumMismatch`, `ArchiveRefused`), and nothing casts on `_tag`.
+  ⚠️ **They are not typed end to end, so no caller can `catchTag` one**
+  (measured, `error-channel.test.ts`). `catalogBinary()` throws, which in a
+  stack program is a defect that `catchTag` never sees. The provider's `lift()`
+  keeps the instance at runtime but types the channel as `Error` (gap 10).
+- **HTTP is Effect's `HttpClient`**, and `reconcile` reports progress through
+  `session.note`. A provider layer that brings `FetchHttpClient.layer` itself
+  has upstream precedent (`Hetzner/Providers.ts`).
+- **The props carry nothing estate-specific.** Paths, owners and modes are the
+  stack's. ⚠️ The wiring does carry the estate's name: the host service is
+  keyed `homeflare/launchd/HostRunner`, and the ownership notes are
+  `Artifacts` keys `homeflare/ownership/*` (gaps 1 and 2).
+
+## What would have to change
+
+1. **The host seam.** Every host touch goes through the kit's promise-based
+   `HostRunner`, a Context service under `launchd/`. Upstream would expect an
+   Effect service with a neutral key. ⚠️ `Util/AtomicFile.ts` is not that
+   service as it stands: it writes a **string** (`writeFileString`) and a mode,
+   never bytes, a uid or a gid. `FileSystem` reaches only the deploying
+   machine. Upstream's one remote-host seam is `Hetzner.Ssh` (Effect `exec` and
+   `scp`). A contribution needs a host service with a local implementation over
+   `FileSystem` and a remote one in that shape. The house seam is one file wide
+   on purpose, so the swap is local.
+2. **Ownership semantics.** The house refuses to adopt without `--adopt`:
+   `read` returns `Unowned` even for a byte-identical file, and `reconcile`
+   resolves adoption at apply through `ownership/adopt.ts`. That reads
+   `Stack.resources[fqn].Adopt`, which upstream marks `@internal`, and state
+   rows. Upstream's default for a resource without ownership metadata is
+   **plain attributes, which means silent adoption**. A contribution would drop
+   `adoptsAtApply` / `noteUnfinished`, ask the engine to hand `adopt` to
+   `reconcile`, and settle whether a file on disk is ever adopted silently.
+   Worth keeping in any form: a file whose digest is not the pin is never
+   adopted, because adopting it is overwriting it (`binary-claim.ts`).
+   ⚠️ `declared-pins.ts` reads the same `@internal` record (`.Props`) to refuse
+   a pin that was an Output on a first deploy. Upstream applies `Input<T>` to
+   every prop automatically, so "this prop must be a literal" is an engine
+   feature to propose (the declared props handed to `reconcile`, or a
+   literal-only marker), not something a provider can reach for.
+3. **`diff` does live I/O and returns `noop`.** Upstream's guidance is that a
+   diff should almost never return `noop`. Live I/O has precedent, though:
+   `Command.Exec`'s diff hashes a directory and answers `noop` on a match, the
+   same shape as this one. Two rules are worth keeping in any form: a new pin
+   or path → `replace`, even while `directory` is an Output; and a new pin at
+   the same path is refused. The apply-time half of that refusal reads `olds`,
+   which upstream's reconciler doctrine calls "at most a hint". Restated as
+   observation it reads: the recorded path's live file is not these bytes.
+4. **Layout and exports.** Upstream co-locates contract and provider in
+   `src/{Cloud}/{Service}/{Resource}.ts`, re-exports with `export *`, and
+   registers providers in a `Providers.ts` collection that `alchemy unsafe nuke`
+   enumerates. The house splits files under a 250-line cap, curates its barrel,
+   and exports `releaseProviders(runner)` with no collection.
+5. **Where the data sets live.** Upstream ships no estate's pins. The resource,
+   `catalogBinary()` and the tar reader would go upstream; `victoria.ts` and its
+   fixtures would stay in the kit, or become a documented example.
+6. **Tests.** The house tests run on fakes (`bun:test`, no network, no host),
+   plus Alchemy's real Plan and Apply over in-memory state (`plan.test.ts`).
+   Upstream tests run `pnpm test` against the real target, start and end with
+   `stack.destroy()`, and verify out of band. For a host resource the honest
+   equivalent is a real temporary directory and a real download. That was done
+   once, by hand, before the generalisation (release-binary-measured.md), and
+   CI here deliberately never does it.
+7. **Toolchain and style.** pnpm, the alchemy-test runner, `tsc -b`, double
+   quotes; generated docs via `pnpm docs:gen`, never hand-edited.
+8. **The pull request itself.** A conventional-commit title; no `#` or `##`
+   headings in the body (the smallest is `###`), the summary first with no
+   heading, no test plan, and code over prose.
+9. **The directory must already exist.** `reconcile` refuses a missing one, and
+   the kit's `HostDirectory` (linux subpath) is what creates it. Upstream has no
+   such resource, so a contribution brings one, or a prop that creates the
+   directory with a declared mode and owner.
+10. **A typed error channel.** `catalogBinary()` would return an `Effect` that
+    fails with `BinaryRefused`, and the provider would fail with the tag union
+    instead of `lift()`'s `Error`. `error-channel.test.ts` fails the moment
+    either changes, so this page moves with it.
+11. **The tar reader accepts one measured layout.** Measured 2026-09-22 against
+    `extractMembers`: macOS's default `tar czf` (bsdtar 3.5.3) writes a PAX `x`
+    header before every entry (a sub-second `mtime` and the
+    `com.apple.provenance` xattr), so even a one-file archive is refused whole.
+    `--no-mac-metadata` still writes them; `--format ustar` passes. A wrapping
+    directory entry is refused whole. Go's `archive/tar` writing root-level
+    files passes. The house accepts this on purpose: the Victoria archives are
+    flat, and homeflare-builds writes plain ustar. ⚠️ REASONED NOT MEASURED:
+    the Prometheus family's archives (`alertmanager-0.34.1.darwin-arm64.tar.gz`)
+    wrap their files in a directory, so the queue in
+    release-binary-catalogs.md needs a reader change, not only a data set.
+    Generic replacement: skip directory entries, and links that are not the
+    declared member, because nothing is ever written from an entry name; read
+    PAX records and refuse only a `path`, `linkpath` or `size` record. The
+    member digest still guards the bytes.
+12. **One source, one tag alphabet, other prop names.** `releaseUrl` fixes
+    `https://github.com`. Upstream's GitHub family also reaches GitHub
+    Enterprise (`normalizeGitHubBaseUrl`, `GitHub/BaseUrl.ts`). A tag must be
+    one `[A-Za-z0-9._-]` segment, so kustomize's `kustomize/v5.8.1` (measured:
+    GitHub's own download URL carries the raw `/`) and a changesets-style
+    `pkg@1.2.3` are refused at plan. Generic: validate git's ref-name rules,
+    segment by segment. Upstream's GitHub props split `owner` and `repository`
+    and call a tag `tagName`; this takes `repo: "owner/name"` and `tag`.
+13. **No platform check.** `platform` is a catalog key, not a prop, and nothing
+    compares the archive's platform with the host. On a Linux runner, a stack
+    that asks for `darwin-arm64` gets a Mach-O written, read back and reported
+    installed; its unit then fails with "exec format error". Generic: a
+    `platform` prop, checked against the host (`uname -sm` through the host
+    service) or against the member's executable header.
+
+## What should NOT change on the way
+
+- ⛔ **Pins in code, never a checksum file fetched at apply.** Mutable releases
+  make a fetched checksum file a claim by the same party whose bytes it vouches
+  for. A pin that is an Output is refused for the same reason.
+- ⛔ **Two layers.** Verify the archive before unpacking and the member before
+  writing. The member check is what still holds if a reader is ever wrong about
+  a boundary.
+- ⛔ **Exact names.** An asset and a member are matched whole, never by a
+  prefix, a glob or "contains darwin-arm64", because the enterprise and cluster
+  siblings share every prefix.
+- ⛔ **Refuse the whole archive** for any unsafe entry, extract only what was
+  declared, and stage nothing on disk before the one atomic write. ⚠️ Gap 11 is
+  where upstream is likeliest to push back: which entries count as unsafe when
+  nothing is written from an entry name.

package/docs/release-binary.md

@@ -0,0 +1,165 @@
+# Release binaries — `@homeflare/alchemy/release`
+
+Status: active
+Verified: 2026-09-23
+
+`Release.Binary` (`ReleaseBinary`) installs one binary out of a pinned release
+archive, verified twice: the archive against its pinned SHA-256 before anything
+is unpacked, then the binary against its own before it is written. The pinned
+archive is **props**. Each vendor's pinned versions are **data** kept beside
+the resource, and `VICTORIA_RELEASES` is the first data set. It exists to
+replace the Nix-built Victoria binaries on the Mac host: all five Nix builds
+link a `/nix/store` `libresolv`, and the vendor builds link none.
+
+⛔ **It installs; it never starts.** No `launchctl`, no `systemctl`, no restart.
+The daemon is the stack's own `LaunchdJob` (or systemd unit), and it puts the
+binary's `path` in its argv.
+
+## Declaring one
+
+```ts
+import { HostDirectory, linuxProviders } from '@homeflare/alchemy/linux';
+import { LaunchdJob, launchdProviders, localRunner } from '@homeflare/alchemy/launchd';
+import {
+  ReleaseBinary, VICTORIA_RELEASES, catalogBinary, catalogDirectory, releaseProviders,
+} from '@homeflare/alchemy/release';
+
+const runner = localRunner();
+// providers: Layer.mergeAll(launchdProviders(runner), linuxProviders(runner), releaseProviders(runner))
+
+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), // …/vmutils-1.151.0
+  mode: 0o755, owner: 0, group: 0,
+});
+const vmalert = yield* ReleaseBinary('vmalert', {
+  ...catalogBinary(VICTORIA_RELEASES, vmalertOf), // archive, member, sha256, name
+  directory: dir.path, // ★ an Output: the engine creates the directory first
+  owner: 0, group: 0, mode: 0o555,
+});
+yield* LaunchdJob('vmalert-job', { programArguments: [vmalert.path, '--httpListenAddr=127.0.0.1:8880'], … });
+```
+
+⚠️ **Give every resource its own logical id, even across different types.**
+alchemy@2.0.0-beta.79's FQN is `namespace + id` alone (`FQN.ts`) — it does
+NOT fold in the resource type. `stack.resources[fqn]` (`Resource.ts`)
+returns the **first** registration for a repeated id whatever type it was:
+`ReleaseBinary('vmalert', …)` then `LaunchdJob('vmalert', …)` in the same
+namespace silently hands the job call back the _binary_ resource, and the
+job is never registered at all — no error, no second row in the plan, just a
+job that does not exist. Measured against the installed alchemy package,
+2026-09-23. Naming them `'vmalert'` and `'vmalert-job'` (as above) avoids it;
+so does any other pair of distinct ids.
+
+- **`catalogBinary()` runs in your stack program.** A version, package,
+  platform or binary the data set does not pin throws `BinaryRefused` there,
+  so `alchemy plan` fails before any resource is asked anything
+  (`plan.test.ts`: zero requests, zero host calls).
+- **The directory is yours, one per version.** It must exist.
+  `catalogDirectory(root, …)` names it `<root>/<package>-<version>`. A version
+  bump is then a new path. Measured through the engine (`plan.test.ts`):
+  mkdir new, download, write new, remove old, rmdir old, in that order.
+- ⛔ **A new pin at the same path is refused**, at plan when the path is
+  resolved and at apply otherwise, rather than overwriting a binary under the
+  daemon that runs it. 🔴 While the directory is still an Output, a re-pin of
+  the same bytes is planned as an `update`, never a `replace`: measured through
+  the engine, a `replace` onto an unmoved path took the identical file as the
+  new generation's, then deleted it with the old one, and reported success.
+- **The job references `vmalert.path`**, not a string it built. That Output
+  orders the job after the binary. A version bump moves the path, so the plist
+  changes and the job restarts on the new binary before the old one is deleted.
+- **Declare each path once.** vmalert-logs is vmalert with other flags: one
+  `ReleaseBinary`, referenced by both jobs.
+- **One logical id per binary, one per versioned directory.** `plan.test.ts`
+  declares `ReleaseBinary('vmalert')` and `HostDirectory('vmutils-<version>')`:
+  a bump plans the binary as a `replace`, the new directory as a `create` and
+  the old one as a `delete`, and the engine removes the old binary before its
+  directory.
+- **Nothing estate-specific is in the kit.** Root, owner, group and mode are
+  your props. The data sets hold vendor facts only.
+- **One runner for all of it.** Pass the same `HostRunner` to
+  `releaseProviders()` as to the jobs. There is no default: a binary goes
+  wherever the runner reaches. It provides its own `FetchHttpClient.layer`.
+- **Your own pins work too.** The props are plain data, so a stack may write
+  them itself. ⛔ They must be plain values in the stack program: a pin wired
+  from another resource's Output (a checksum file read at apply) is refused,
+  on a first deploy too (`apply-pins.test.ts`). ⚠️ A stack program that
+  fetches the file itself and passes plain strings cannot be told apart from
+  a reviewed pin; `catalogBinary()` over a reviewed data set is the path
+  that keeps them reviewed.
+
+## What reconcile does, in order
+
+1. **Validate every prop**, before any host or network call. Every pin must be a
+   plain, well-formed value, as the stack program DECLARED it: by now an Output
+   has resolved to a plausible string (`declared-pins.ts`).
+2. **Check the directory exists**, is not a symlink, and is not writable by
+   group or other (they could rename a file over the binary), before any download.
+3. **Observe the path.** A symlink or directory there is refused. A file this
+   resource does not own is refused without `--adopt`, even one holding the
+   pinned bytes: at plan the probe calls it `Unowned`, and at apply, when a
+   prop was an Output and the probe never ran, reconcile refuses it the same
+   way (`binary-claim.ts`). ⛔ A file with other bytes is refused under
+   `--adopt` too, at plan and at apply: adopting it would overwrite it in
+   place, and the plan would print that as `adopted`. Under `--adopt`, the
+   pinned bytes are kept: no download, and a write only to fix mode or owner.
+   ⚠️ A rename is not an adoption: declare it with `renamedFrom()`. Under
+   `--adopt` the new name takes the file, and the old name's delete leaves a
+   path another declaration installed in the same deploy (`adopt-parity.test.ts`).
+4. **Download** `https://github.com/<repo>/releases/download/<tag>/<asset>`,
+   into memory, never past the pinned size. Two binaries from one archive at
+   once share one download.
+5. **Verify the archive** against its pinned SHA-256, before unpacking a byte.
+6. **Unpack only the declared member**, streaming. The tar reader refuses the
+   whole archive for any unsafe entry, declared or not.
+7. **Verify the member** against its own pinned SHA-256.
+8. **Write** through `HostRunner.writeFileAtomic`, the one writer every file
+   resource uses: a temp file in the same directory, mode and owner set, then
+   rename. Under `sudoRunner`, one staged `install -S`, ⚠️ which sets the mode
+   just after its rename (measured: `0600` for under half a millisecond).
+9. **Read back** and compare. A create that does not read back, or whose
+   read-back fails, is removed.
+
+A binary with the right bytes but the wrong mode or owner is re-written from
+the bytes already on disk, re-hashed, without a download.
+
+⛔ A directory respelled to the same place (a symlinked parent, or case on
+APFS) is an `update` that keeps the file, never a `replace`: the replace's
+Phase 2 would delete the old path, which is the file (`launchd/file-identity.ts`).
+
+## Trust: why the digests are pinned in code
+
+★ **Pinned, not fetched at apply.** A checksum file comes from the same
+account, release and channel as the archive, and every release checked so far
+is mutable (`"immutable": false`). Whoever can swap an archive can swap its
+checksum file, and a provider that trusts what it fetches would call the swap
+verified. A pin moves only through a reviewed change, so a swapped asset is a
+refusal. And a plan knows exactly which bytes it will install without the
+network. Each data-set entry records the checksum file's URL, its own SHA-256
+and the date the pins were copied.
+
+⚠️ **The trust root.** At apply it is the pins alone: TLS, GitHub's redirect,
+its CDN or a proxy can make a download fail, never make other bytes pass. The
+pins rest on one read of the GitHub release over TLS on the `recorded` date
+(trust on first use), checked against GitHub's own asset `digest`, then on
+review of that commit and the kit release the stack's lockfile resolves.
+VictoriaMetrics publishes no signature, cosign bundle, SLSA provenance or
+GitHub attestation for these archives: a checksum proves integrity, not
+authorship.
+
+★ **What CI proves without a network** (`victoria.test.ts`) is consistency,
+not provenance: each committed checksum file in `src/release/fixtures/victoria/`
+hashes to the digest the data set records for it; the strict parser reads
+them; the data set equals what it reads; every asset is in the committed
+listing, and none is an `-enterprise`, `-cluster` or `vlutils` sibling.
+⚠️ That those recorded digests are GitHub's was measured once, not by CI. A
+change that edits a fixture and its pins together passes; review is the gate.
+
+## Refusals
+
+Every refusal, by where it is refused (the stack program, the plan, the apply,
+the vendor's bytes, the read-back): [release-binary-refusals.md](./release-binary-refusals.md).
+
+Data sets and adding a vendor: [release-binary-catalogs.md](./release-binary-catalogs.md).
+Measurements and limits: [release-binary-measured.md](./release-binary-measured.md).
+What alchemy-run/alchemy would need: [release-binary-upstream.md](./release-binary-upstream.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",
@@ -64,6 +64,10 @@
       "types": "./dist/linux/index.d.ts",
       "default": "./dist/linux/index.js"
     },
+    "./release": {
+      "types": "./dist/release/index.d.ts",
+      "default": "./dist/release/index.js"
+    },
     "./caddy": {
       "types": "./dist/caddy/index.d.ts",
       "default": "./dist/caddy/index.js"

package/src/caddy/access-forward-auth.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from 'bun:test';
+import { accessForwardAuth, verifierProblems } from './access-forward-auth.ts';
+
+describe('accessForwardAuth', () => {
+  test('emits a forward_auth block with the identity headers copied', () => {
+    const block = accessForwardAuth({
+      verifier: '127.0.0.1:9101',
+      body: ['reverse_proxy 127.0.0.1:6080'],
+    });
+
+    expect(block).toBe(
+      [
+        '\treverse_proxy 127.0.0.1:6080',
+        '\tforward_auth 127.0.0.1:9101 {',
+        '\t\turi /access/verify',
+        '\t\tcopy_headers {',
+        '\t\t\tX-Access-Email',
+        '\t\t\tX-Access-Sub',
+        '\t\t}',
+        '\t}',
+      ].join('\n'),
+    );
+  });
+
+  test('copies exactly the headers the verifier sets, by default', () => {
+    // ⛔ A header the verifier emits but Caddy does not copy never reaches the upstream;
+    //    a header Caddy copies but the verifier never sets is the SPOOFING case — the
+    //    client's own value survives. These two lists must agree, which is why the default
+    //    is not configurable-by-accident.
+    const block = accessForwardAuth({ verifier: '127.0.0.1:9101' });
+    expect(block).toContain('X-Access-Email');
+    expect(block).toContain('X-Access-Sub');
+  });
+
+  test('refuses a verifier on a routable address', () => {
+    // 🔴 A verifier reachable from off-box can be answered around, and the upstream with it.
+    expect(() => accessForwardAuth({ verifier: '10.20.10.250:9101' })).toThrow(/loopback/);
+    expect(() => accessForwardAuth({ verifier: '0.0.0.0:9101' })).toThrow(/loopback/);
+  });
+
+  test('accepts loopback in its usual spellings, and a unix socket', () => {
+    for (const verifier of ['127.0.0.1:9101', 'localhost:9101', '[::1]:9101', 'unix//run/v.sock']) {
+      expect(verifierProblems(verifier)).toEqual([]);
+    }
+  });
+
+  test('a custom uri and header names flow through', () => {
+    const block = accessForwardAuth({
+      verifier: 'unix//run/access.sock',
+      uri: '/verify/vnc',
+      copyHeaders: ['Remote-Email'],
+    });
+
+    expect(block).toContain('forward_auth unix//run/access.sock {');
+    expect(block).toContain('uri /verify/vnc');
+    expect(block).toContain('Remote-Email');
+    expect(block).not.toContain('X-Access-Sub');
+  });
+
+  test('refuses an empty verifier rather than emitting a block that adapts to nothing', () => {
+    expect(() => accessForwardAuth({ verifier: '   ' })).toThrow(/empty/);
+  });
+});