@homeflare/alchemy 0.20.0 → 0.21.0

package/dist/release/victoria.d.ts

@@ -0,0 +1,36 @@
+/**
+ * VictoriaMetrics' release archives, pinned — the first data set for Release.Binary, and vendor
+ * facts only: every digest copied from the vendor's own checksum file for that archive and
+ * cross-checked against GitHub's asset digest ON THE RECORDED DATE. Nothing here names a host, a
+ * path, a user or an estate. victoria.test.ts holds every pin to the committed checksum files
+ * (fixtures/victoria/) — ⚠️ consistency, not provenance: it cannot re-read GitHub, so a fixture
+ * edited together with its pins passes, and review is the gate for that.
+ *
+ * ★ PINNED IN CODE, NOT FETCHED AT APPLY. The checksum file is published by the same account, on
+ *   the same release, over the same channel as the archive it describes — and these releases are
+ *   MUTABLE (`"immutable": false` on v1.151.0, v1.52.0 and v0.10.0, measured 2026-09-22; the
+ *   vendor's own release Makefile says to delete an asset in the UI to re-upload it). Whoever can
+ *   swap an archive can swap its checksum file in the same minute, and a provider that trusts
+ *   whatever checksum file it finds would install the new bytes and call them verified. A pin
+ *   committed here changes only through a reviewed kit release, so a swapped asset is a REFUSAL
+ *   that names the digest it expected. It also means an apply makes one request, not two, and a
+ *   plan knows exactly which bytes it will install without touching the network.
+ * ⚠️ TRUST ROOT. At apply, these pins alone: the transport (TLS, the redirect, the CDN) can fail
+ *   a download, never pass other bytes. The pins' own root is the GitHub release over TLS as read
+ *   on RECORDED (trust on first use), uploaded from a maintainer's personal account.
+ *   VictoriaMetrics publishes no signature, cosign bundle, SLSA provenance or GitHub artifact
+ *   attestation for these archives (measured 2026-09-22: no .sig/.asc/.pem/.bundle assets; the
+ *   attestations API answers 404 for all four digests, next to a positive control that answers
+ *   200). A checksum file proves the download is not corrupt — integrity — not who built it.
+ * ⛔ A NEW VERSION IS A NEW ENTRY, WALKED DOWN THE SAME WAY — docs/release-binary-catalogs.md.
+ *   Never `latest`, never sorted by publish date: VictoriaLogs v1.51.1 was published AFTER v1.52.0.
+ * ⛔ EXACT NAMES. `-enterprise`, `-cluster` and `-enterprise-cluster` archives sit beside each of
+ *   these with every prefix in common, so each asset name below is written out whole — never
+ *   composed from a package and a version, which is how a template drifts onto a sibling.
+ * ★ THE VENDOR'S `-prod` SUFFIX IS DROPPED ON PURPOSE: every member is `<binary>-prod`, and
+ *   installing it as `<binary>` keeps a job's argv[0], `ps` and `pgrep` names identical to the
+ *   builds it replaces. The map is written out per package, never derived.
+ */
+import type { ReleaseCatalog } from './catalog.ts';
+export declare const VICTORIA_RELEASES: ReleaseCatalog;
+//# sourceMappingURL=victoria.d.ts.map

package/dist/release/victoria.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"victoria.d.ts","sourceRoot":"","sources":["../../src/release/victoria.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAKnD,eAAO,MAAM,iBAAiB,EAAE,cAmH/B,CAAC"}

package/dist/{proxmox → secrets}/write-only.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write-only.d.ts","sourceRoot":"","sources":["../../src/proxmox/write-only.ts"],"names":[],"mappings":"AA2BA,+FAA+F;AAC/F,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,+FAA+F;AAC/F,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAEvE;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,SACf,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,QAClC,WAAW,KACf;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CAS1F,CAAC;AAqBF;;;;;;GAMG;AACH,eAAO,MAAM,IAAI,WAAY,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,SAAS,MAAM,KAAG,MAI9E,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,WAAW,WAAY,MAAM,UAAU,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,KAAG,OAStF,CAAC"}
+{"version":3,"file":"write-only.d.ts","sourceRoot":"","sources":["../../src/secrets/write-only.ts"],"names":[],"mappings":"AAiCA,+FAA+F;AAC/F,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,+FAA+F;AAC/F,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAEvE;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,SACf,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,QAClC,WAAW,KACf;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CAS1F,CAAC;AAqBF;;;;;;GAMG;AACH,eAAO,MAAM,IAAI,WAAY,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,SAAS,MAAM,KAAG,MAI9E,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,WAAW,WAAY,MAAM,UAAU,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,KAAG,OAStF,CAAC"}

package/docs/release-binary-catalogs.md

@@ -0,0 +1,113 @@
+# Release binaries — the data sets, and adding one
+
+Status: active
+Verified: 2026-09-22
+
+`Release.Binary` takes one pinned archive as props and knows no vendor. What
+each vendor published lives in a **data set** beside it (`src/release/<vendor>.ts`),
+typed `ReleaseCatalog`, and `catalogBinary(dataSet, request)` turns one entry
+into props. This page is what is in the data sets, and the rule for adding to
+them. The guide is [release-binary.md](./release-binary.md).
+
+## `VICTORIA_RELEASES` — the only data set today
+
+| package            | version | asset (darwin-arm64)                            | binaries (installed ← member)                                                                          |
+| ------------------ | ------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `victoria-metrics` | 1.151.0 | `victoria-metrics-darwin-arm64-v1.151.0.tar.gz` | `victoria-metrics` ← `victoria-metrics-prod`                                                           |
+| `victoria-logs`    | 1.52.0  | `victoria-logs-darwin-arm64-v1.52.0.tar.gz`     | `victoria-logs` ← `victoria-logs-prod`                                                                 |
+| `victoria-traces`  | 0.10.0  | `victoria-traces-darwin-arm64-v0.10.0.tar.gz`   | `victoria-traces` ← `victoria-traces-prod`                                                             |
+| `vmutils`          | 1.151.0 | `vmutils-darwin-arm64-v1.151.0.tar.gz`          | `vmagent`, `vmalert`, `vmalert-tool`, `vmauth`, `vmbackup`, `vmctl`, `vmrestore`, each ← `<name>-prod` |
+
+These are the versions the Mac host runs today, pinned for parity first. An
+upgrade (VictoriaMetrics 1.152.0, VictoriaTraces 0.11.1 exist) is its own
+change that re-pins both digest layers.
+
+- ⛔ **The single-node `victoria-metrics` archive**, not `-cluster`, which holds
+  vminsert, vmselect and vmstorage instead.
+- ★ **The `-prod` suffix is dropped on purpose.** The installed names keep a
+  job's argv[0], `ps` and `pgrep` names identical to the builds they replace.
+  The map is written out per package, never derived.
+- **vmalert-logs is not a binary.** It is `vmalert` run with
+  `--rule.defaultRuleType=vlogs`: one `ReleaseBinary`, two jobs.
+- **A consumer's path.** `catalogDirectory(root, request)` plus the name gives
+  `<root>/<package>-<version>/<binary>`, e.g.
+  `<root>/vmutils-1.151.0/vmalert`. That is the layout homeflare-mini's
+  `binaryPath()` already renders, so its argv and goldens need no path change.
+  A stack that keeps its own digest slots (the mini's `PINS`) can compare them
+  with `catalogBinary(...).sha256` in its own tests: two witnesses, one source.
+
+## Adding a version of a vendor already here
+
+Walk it down from the vendor, never from memory:
+
+1. `gh api repos/<owner>/<repo>/releases/tags/<tag>`: the exact asset names,
+   sizes and `digest`s, and `immutable`.
+2. Fetch the checksum file. Its SHA-256 must equal GitHub's digest of it, and
+   its archive line must equal the archive's digest.
+3. Stream the archive through `tar -tvzf -`, saving nothing: root-level
+   regular files with the expected member names, nothing else.
+4. Add the entry with `recorded` set to that day. Commit the checksum file
+   under `src/release/fixtures/<vendor>/` and add the asset names to the
+   listing there. `<vendor>.test.ts` then holds the pins to it.
+5. Re-check attestations with a positive control, so a 404 means something:
+   `gh api repos/<owner>/<repo>/attestations/sha256:<digest>` next to a repo
+   known to publish them (`cli/cli` answered 2 on 2026-09-22).
+
+⛔ Never `latest`, and never sort by publish date. VictoriaLogs v1.51.1 was
+published after v1.52.0, and VictoriaMetrics interleaves LTS lines.
+
+## Adding a vendor
+
+⛔ **Only after that vendor's own walk-down measures two things**, recorded in
+its data module's header with the date:
+
+- **Its checksum format, byte-exact.** `checksums.ts` parses one measured shape,
+  `sha256sum` text mode listing the archive and every member. Most vendors the
+  estate census found (landscape PR 88) list **archives only**: Prometheus's
+  `sha256sums.txt`, vector's `-SHA256SUMS`, pyroscope's and OpenBao's
+  `checksums.txt`. For those the member digest is not a vendor fact. It is
+  computed from a verified archive, and the data set must say so rather than
+  file it beside the vendor's lines. That field does not exist yet; it arrives
+  with its first consumer.
+- **Its binary's linkage** (`otool -L` on the extracted member, or `ldd`).
+  Vendor binaries were measured self-contained **only for the five Victoria
+  ones** (system libraries and `/usr/lib/libresolv.9.dylib` only). That is not
+  a property of "a Go binary". The Nix vector links jemalloc, librdkafka,
+  oniguruma and libiconv from `/nix/store`, and whether the vendor tarball
+  bundles them is unknown until someone inspects the extracted member.
+
+Also carried over from the Victoria walk-down, and checked again per vendor:
+exact asset names against near-identical siblings; the tar layout; the
+`immutable` flag; signatures and attestations with a positive control; and
+where `-version` prints, if anything ever runs it (Victoria's goes to stderr).
+
+The queue, from the census, each **not yet walked for this resource**:
+alertmanager, blackbox_exporter, node_exporter and postgres_exporter
+(Prometheus `sha256sums.txt`), unpoller (detached `.sig`; 5.2.7 renames
+`darwin_arm64` to `darwin_all`), pyroscope, vector, and `bao` (OpenBao, with
+GPG and Sigstore to check).
+
+⚠️ REASONED NOT MEASURED: the Prometheus-family archives wrap their files in a
+directory, and `tar.ts` refuses a directory entry (and any PAX header) for the
+whole archive. Walking those down includes a reader change, not only a data
+set ([release-binary-upstream.md](./release-binary-upstream.md), gap 11).
+
+## What this resource is not for
+
+- **A whole tree.** Grafana needs its homepath and plugins, and an interpreter
+  like python-build-standalone needs its `lib/`. That is a **tree mode**:
+  unpack an archive into a directory. It is a separate, later capability with
+  its own walk-down, not a flag bent onto `Release.Binary`. Grafana's darwin
+  builds also come from grafana.com's downloads API, not a GitHub release. (The
+  house's stdlib-only Python jobs are tracked for a Bun/TS rewrite instead of a
+  vendored interpreter, decided 2026-09-23.)
+- **Another source kind.** Only GitHub release downloads, whose URL is
+  `https://github.com/<repo>/releases/download/<tag>/<asset>`. A second kind
+  (grafana.com JSON, Codeberg) arrives with its first consumer.
+- **Another archive format.** Only `.tar.gz`/`.tgz`. A `.zip` or a bare
+  binary is refused at plan rather than downloaded and then not unpacked.
+- **Builds from source.** Postgres, pgBackRest and Valkey ship no darwin
+  binary. Caddy with its plugins and cloudflare-exporter are to be built by the
+  public `taslabs-net/homeflare-builds` repo, which publishes GitHub releases
+  with a `SHA256SUMS` file (decided 2026-09-23). Each then becomes an ordinary
+  data set, after its own walk-down like any vendor's.

package/docs/release-binary-measured.md

@@ -0,0 +1,163 @@
+# Release binaries — measured, and the limits
+
+Status: active
+Verified: 2026-09-22
+
+What [release-binary.md](./release-binary.md) rests on, how each fact was read,
+and what is still reasoned rather than measured. Every vendor fact here is
+VictoriaMetrics': the only data set so far. Host class: the Mac mini the stack is for
+(macOS 27.2, arm64), bun 1.4.0. No binary was executed for any of this.
+
+## The vendor side (read-only, `gh api` and `curl`)
+
+| archive (darwin-arm64)        | bytes       | members (all regular, root-level)    |
+| ----------------------------- | ----------- | ------------------------------------ |
+| `victoria-metrics-…-v1.151.0` | 12,739,105  | `victoria-metrics-prod`              |
+| `victoria-logs-…-v1.52.0`     | 10,943,697  | `victoria-logs-prod`                 |
+| `victoria-traces-…-v0.10.0`   | 11,126,077  | `victoria-traces-prod`               |
+| `vmutils-…-v1.151.0`          | 123,584,800 | seven `-prod` tools, 264 MB unpacked |
+
+- **Asset names are exact**, and `-cluster`, `-enterprise`,
+  `-enterprise-cluster` (and `vlutils`) archives sit beside them with every
+  prefix in common — twelve siblings in the darwin-arm64 listing alone. The
+  listing is committed as `src/release/fixtures/victoria/darwin-arm64-assets.txt`.
+- **Each checksum file hashes both layers**: line 1 the archive, then one line
+  per `-prod` member, in `sha256sum` text mode (`<hex>  <name>`, LF, trailing
+  newline). For all four, GitHub's asset `digest` equals line 1, and GitHub's
+  digest of the checksum file equals the SHA-256 of the committed fixture.
+- **Re-read the same day by the supply-chain review** (`gh api …/releases/tags/<tag>`):
+  all four archives' and checksum files' sizes and `digest`s still equal the pins
+  and the recorded checksum-file digests. Nothing had been swapped since recording.
+- **Releases are mutable** (`"immutable": false`), uploaded from maintainers'
+  personal accounts. **No signatures or attestations** exist for the archives:
+  no `.sig`/`.asc`/`.pem`/`.bundle` assets, and the attestations API answers 404
+  for all four digests next to a positive control (`cli/cli`) that answers 200.
+- **Tar format**: `tar -tvzf -` on each streamed archive (nothing saved) shows
+  only root-level regular files with short names — no directories, links, PAX
+  or GNU long-name headers. Owners differ by release (`builder`, `valyala`,
+  `ubuntu`), which is why the archive's mode and owner are never used.
+
+## The provider against the real archives
+
+The provider, as `Victoria.Binary` through `victoriaProviders(localRunner())`,
+installed all five binaries the stack needs into a scratch directory (never
+`/opt`), 2026-09-22. ⚠️ **That was the code before it was generalised into
+`Release.Binary`, and the generalised resource has NOT been re-run against the
+real archives** (a download needs the operator's go-ahead). What carried over
+unchanged: `download.ts`, `tar.ts`, the two checks in `archive.ts` and the write
+through `file-converge.ts`. What changed: where the pins come from (props,
+filled by `catalogBinary()`) and the URL, now composed from repo, tag and asset
+and held equal to the old whole URLs by `victoria.test.ts`.
+
+- **Every digest verified**, both layers, and every installed file's SHA-256 is
+  its pin. One run took 1.7–5.9 s on the mini's link.
+- **One download for vmagent + vmalert** installed concurrently: `fetch` was
+  called once for the shared vmutils archive (counted by wrapping `fetch`).
+- **`codesign -v` is valid** on all five as written: the vendor binaries are
+  ad-hoc, linker-signed (`flags=0x20002`, no TeamIdentifier) and the write is
+  byte-identical, so the embedded signature survives. The running Nix builds are
+  the same signature class, and launchd runs them.
+- **No `com.apple.quarantine`**, only `com.apple.provenance` — the same as the
+  running Nix binaries.
+- **No `/nix/store` library** (`otool -L`, all five): `libSystem`,
+  `/usr/lib/libresolv.9.dylib`, CoreFoundation, Security. ⚠️ `libresolv.9.dylib`
+  is not on disk; it is in the dyld shared cache — a preflight that checks the
+  file exists would refuse a working binary.
+- **Memory (peak RSS, bun 1.4.0)**: victoria-traces alone ~200 MB; vmalert
+  alone ~520 MB; vmagent + vmalert together ~590–720 MB; all five together
+  ~750–930 MB. 🔴 Before the gzip input was fed in slices, vmalert alone peaked
+  at 1,116 MB: the whole archive inflated in one step and 264 MB of output queued
+  ahead of the reader (archive.ts). Before the download filled one pinned-size
+  buffer, the chunk list plus its concatenated copy held the archive twice.
+- **Under node** (v26.7.0), the bundled extractor reads a gzipped tar the same
+  way (`DecompressionStream` is the web standard in both runtimes).
+
+## Through Alchemy's own engine (fakes, not a host)
+
+`src/release/plan.test.ts` runs alchemy@2.0.0-beta.79's Plan and Apply over
+in-memory state, with `HostDirectory` declared in front of the binary, a fake
+host that models `mkdir`/`rmdir`, and a fake HTTP server:
+
+- **A first deploy** runs `mkdir`, one `GET`, one write, in that order: the
+  `directory: dir.path` Output orders them.
+- **A version bump** (`HostDirectory('vmutils-<version>')`, `ReleaseBinary('vmalert')`)
+  plans `replace` / `create` / `delete` and runs: mkdir new, GET new, write new,
+  **then** remove old, **then** rmdir old. That was reasoned from `Apply.ts`
+  before; it is measured now, on the engine, not on a host.
+- **A version outside the data set** fails in the stack program: zero requests,
+  zero host calls.
+- **A new pin in the same directory** fails at plan: the directory already
+  exists, so its path is resolved when `diff` runs.
+- 🔴 **The same bytes re-pinned while the directory is being updated** (its
+  path unresolved at plan): with `diff` answering `replace`, the deploy
+  SUCCEEDED and the binary was gone. The new generation accepted the identical
+  file as its own, and Phase 2 deleted the old generation at the same path.
+  `diff` now answers `update` there, and reconcile's in-place guard refuses it
+  with the binary kept (`plan.test.ts` pins the refusal).
+
+## The install path on a real filesystem (red team, 2026-09-22)
+
+Measured on macOS 27.2 in temp directories only: no live host, no sudo.
+
+- 🔴 **One file under two spellings was lost, silently** (fixed;
+  `binary-alias.test.ts`). Respelling the directory through a symlinked parent,
+  or by case alone on case-insensitive APFS, planned a `replace`: the new
+  generation took the identical file as its resumed install, then Phase 2
+  deleted the old generation's path, which was the same file. The deploy
+  succeeded with no binary on disk. Now `diff` compares device and inode
+  (`launchd/file-identity.ts`) and answers `update`, and a move never removes
+  an old path that is the file it just verified.
+- 🔴 **An execute-only mode (`0o111`) was written and then unreadable** (fixed).
+  The read-back threw EACCES, the file stayed with no state, and every later
+  probe threw the same. Now the mode must be owner-readable, and a read-back
+  that throws rolls the create back like one that mismatches.
+- 🔴 **Two resources at one path both owned it** (fixed; `binary-claims.test.ts`).
+  `vmalert` and `vmalert-logs` declared at one path both created it; the deploy
+  that dropped `vmalert-logs` deleted the file `vmalert` still declared, and
+  reported `vmalert` as `noop`. A second claim on a path in one run is refused.
+- ⚠️ **`/usr/bin/install -S` chmods after the rename.** An lstat poller racing a
+  300 MB install saw the new inode at the path as `0600`, then `0755` 0.2–0.4 ms
+  later, six runs out of six. Never torn and never wider than declared. localRunner
+  sets the mode before its rename. Closing the window under `sudoRunner` changes
+  the sudo allowlist, so it has not been done.
+- ⚠️ **`install` copies extended attributes**, `com.apple.quarantine` included.
+  Files this process writes through `node:fs` carried only
+  `com.apple.provenance`, so no staged file is quarantined today.
+- ★ **Tar-slip cannot reach the disk by construction.** The installed path is
+  `<directory>/<name>`, with `name` one `[A-Za-z0-9._-]` segment; an archive
+  entry's name only selects bytes and never becomes a path.
+
+## Reasoned, not measured
+
+- ⚠️ **REASONED NOT MEASURED: a quarantined binary would not start under
+  launchd.** Adoption (`--adopt`) and the resume rule accept a file by digest,
+  mode and owner, and never read xattrs. A binary that was downloaded by a
+  browser and placed by hand would be adopted with its quarantine. Remove it
+  (`xattr -d com.apple.quarantine`) before adopting.
+
+- ⚠️ **REASONED NOT MEASURED: a vendor binary runs under launchd from the
+  installed path.** Strongly suggested — same signature class as the running
+  Nix builds, valid signature, no quarantine — but nothing was executed.
+- ⚠️ **REASONED NOT MEASURED: `sudoRunner` installs under the real
+  `/opt/<estate>/obs`.** Exercised only over the kit's fake sudo host
+  (`binary-sudo.test.ts`: one staged file, one `install -S -m 0755 -o 0 -g 0`,
+  the staged file removed on success and on failure).
+- ⚠️ **`HostDirectory` under `sudoRunner` does not work today** (measured with
+  the kit's fakes during the walk-down): `mkdir` is not on the sudo allowlist,
+  and `checkWrite` refuses a directory. A stack that deploys as itself cannot
+  create `<root>/<package>-<version>` through sudo yet; deploy as root, or
+  pre-create the directory. Fixing it is a sudo-seam change with its own review.
+- ⚠️ **REASONED NOT MEASURED: `HostDirectory`'s argv (`mkdir -m`, `chmod`,
+  `chown`, `rmdir`) behaves the same on macOS** — its header says so.
+- ⚠️ **REASONED NOT MEASURED: the process-memory panels.** The vendor darwin
+  builds are `CGO_ENABLED=0` (their Makefile), and VictoriaMetrics' metrics
+  library reads darwin RSS only with cgo — the reason the house Nix module
+  builds with cgo. Expect `process_resident_memory_bytes` to go missing after
+  the swap until someone decides what replaces it. A consumer decision, not
+  this provider's.
+- ⚠️ **The platform is not checked against the host.** A `darwin-arm64` pin on
+  a Linux host installs a binary that will not start; the job's first launch is
+  where that shows. The platform is the data set's key, not a prop.
+- ⚠️ **A stamped vendor build prints `-version` to stderr**, not stdout
+  (`lib/buildinfo`, read). Identity here is the SHA-256 alone; if a check ever
+  runs `-version`, read stderr, and say which build (Nix or vendor) it was.

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.