@homeflare/alchemy 0.20.0 → 0.22.0

package/dist/release/refused.d.ts

@@ -0,0 +1,39 @@
+declare const BinaryRefused_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "BinaryRefused";
+} & Readonly<A>;
+/** The declaration itself: a version no catalog pins, a malformed pin, a bad path or mode. */
+export declare class BinaryRefused extends BinaryRefused_base<{
+    readonly message: string;
+}> {
+}
+declare const DownloadFailed_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "DownloadFailed";
+} & Readonly<A>;
+/** The download: a status that is not 200, a body that is not the pinned size, a dead transport. */
+export declare class DownloadFailed extends DownloadFailed_base<{
+    readonly message: string;
+    /** Worth another attempt: a transport failure or a 5xx, never a wrong size or a 404. */
+    readonly retryable: boolean;
+}> {
+}
+declare const ChecksumMismatch_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ChecksumMismatch";
+} & Readonly<A>;
+/** Bytes that do not hash to their pin — the archive, or a member extracted from it. */
+export declare class ChecksumMismatch extends ChecksumMismatch_base<{
+    readonly message: string;
+    readonly subject: string;
+    readonly expected: string;
+    readonly actual: string;
+}> {
+}
+declare const ArchiveRefused_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ArchiveRefused";
+} & Readonly<A>;
+/** An archive this reader will not trust: an unsafe or unexpected entry, a missing member. */
+export declare class ArchiveRefused extends ArchiveRefused_base<{
+    readonly message: string;
+}> {
+}
+export {};
+//# sourceMappingURL=refused.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"refused.d.ts","sourceRoot":"","sources":["../../src/release/refused.ts"],"names":[],"mappings":";;;AAgBA,8FAA8F;AAC9F,qBAAa,aAAc,SAAQ,mBAAkC;IACnE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;CAAG;;;;AAEL,oGAAoG;AACpG,qBAAa,cAAe,SAAQ,oBAAmC;IACrE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,wFAAwF;IACxF,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B,CAAC;CAAG;;;;AAEL,wFAAwF;AACxF,qBAAa,gBAAiB,SAAQ,sBAAqC;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;CAAG;;;;AAEL,8FAA8F;AAC9F,qBAAa,cAAe,SAAQ,oBAAmC;IACrE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;CAAG"}

package/dist/release/tar.d.ts

@@ -0,0 +1,14 @@
+/** Concatenate chunks into one buffer. */
+export declare const concatBytes: (parts: readonly Uint8Array[]) => Uint8Array;
+export type TarContents = {
+    /** The asked-for regular files, by exact name. An asked-for name that is absent is absent here. */
+    readonly members: ReadonlyMap<string, Uint8Array>;
+    /** Every entry name, in archive order — so a refusal can say what the archive did hold. */
+    readonly names: readonly string[];
+};
+/** A push parser: `push` each chunk of the unzipped stream, then `finish`. Either may throw. */
+export declare const tarReader: (wanted: ReadonlySet<string>) => {
+    finish: () => TarContents;
+    push: (chunk: Uint8Array) => void;
+};
+//# sourceMappingURL=tar.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tar.d.ts","sourceRoot":"","sources":["../../src/release/tar.ts"],"names":[],"mappings":"AAqFA,0CAA0C;AAC1C,eAAO,MAAM,WAAW,UAAW,SAAS,UAAU,EAAE,KAAG,UAQ1D,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,mGAAmG;IACnG,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAClD,2FAA2F;IAC3F,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC,CAAC;AAEF,gGAAgG;AAChG,eAAO,MAAM,SAAS,WAAY,WAAW,CAAC,MAAM,CAAC;kBAoFhC,WAAW;kBAlCT,UAAU,KAAG,IAAI;CAwCvC,CAAC"}

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/launchd-ports.md

@@ -0,0 +1,109 @@
+# Port collisions, before a job is declared — `claimPorts()`
+
+Status: active
+Verified: 2026-09-23
+
+`claimPorts(claims)` refuses two of a stack's own jobs sharing one port number, in the stack's own
+program, before `alchemy plan` asks a single provider anything. It is not a provider and it is not
+a `LaunchdJob` prop — it is a plain function a host stack calls itself, the same shape as
+[`catalogBinary()`](../src/release/catalog.ts) (see [release-binary-upstream.md](./release-binary-upstream.md)).
+
+```ts
+import { claimPorts } from '@homeflare/alchemy/launchd';
+
+claimPorts([
+  { owner: 'vmalert', port: 8880 },
+  { owner: 'vmalert-logs', port: 8881, address: '127.0.0.1' },
+]);
+// ...then declare the jobs themselves, as normal.
+```
+
+## Why the stack program, not a provider
+
+Two structural facts about Alchemy 2.0.0-beta.79 rule out a provider-side check:
+
+- **A provider never diffs a first `create` whose props still hold an unresolved `Output`.**
+  Every mini job's `programArguments` carries a `HostFile` config digest as an `Output`, so a
+  check living in `LaunchdJob`'s `diff` would be skipped on exactly the deploy that matters most —
+  the first one.
+- **A provider never sees its sibling resources.** Nothing in the `LaunchdJob` handlers can read
+  what port another declared job holds; the stack program is the only place that sees the whole
+  set at once.
+
+So `claimPorts` runs where the stack itself calls it, ordered however the stack likes (typically
+right before the jobs it describes), and fails the **plan** — nothing is fetched, written, or
+`launchctl`'d — if two claims collide.
+
+## Why it keys on the port number alone
+
+`house/nix/homeflare-config/hosts/macmini/modules/lib-ports.nix` (a different repo —
+`homeflare/homeflare`, read at `92cff7f`, 2026-09-23) is the check this replaces for a
+kit-declared job. Its `assertNoCollision` is:
+
+```nix
+dupes = lib.subtractLists (lib.unique vals) vals;  # vals = lib.attrValues ports
+```
+
+— every port **value** in the registry, address and protocol never read. `portClaimProblems`
+reproduces that rule rather than a looser one, because that is the strictness the registry already
+enforces across the whole estate, and a kit-side check that disagreed with it would be a second,
+inconsistent source of truth.
+
+### The measured bind table
+
+What that trades away is real: the OS itself is looser than the registry. Measured on the mini
+(Darwin 27.2.0) with `/usr/bin/python3` sockets, `SO_REUSEADDR` set on both sides, loopback high
+ports — first on 2026-09-23 at 47913–47917, **re-measured independently the same day** at
+47923–47927 with the same result:
+
+| first bind          | second bind | outcome                  |
+| ------------------- | ----------- | ------------------------ |
+| `127.0.0.1`         | `127.0.0.1` | **refused** — EADDRINUSE |
+| `0.0.0.0`           | `127.0.0.1` | both bind                |
+| `127.0.0.1`         | `0.0.0.0`   | both bind                |
+| `[::]` (`V6ONLY=0`) | `127.0.0.1` | both bind                |
+| `[::1]`             | `127.0.0.1` | both bind                |
+
+Only an **exact** address+port duplicate fails at bind time; a wildcard next to a specific address
+on the same port silently splits traffic between two listeners instead of refusing. `claimPorts`
+refuses that pairing anyway — the port number is the key, exactly like the registry — because
+"the OS allowed it" is not the same claim as "the estate meant two things to share a port."
+
+- **Every mini daemon this affects is Go**, and Go sets `SO_REUSEADDR` on **every** darwin
+  listener unconditionally: `setDefaultListenerSockopts` in `net/sockopt_bsd.go` (Go 1.26.5,
+  installed at `/opt/homebrew/Cellar/go/1.26.5`, `//go:build darwin || …`) —
+  `syscall.SetsockoptInt(s, syscall.SOL_SOCKET, syscall.SO_REUSEADDR, 1)`, no opt-out. The
+  Victoria family, Prometheus-family exporters and OpenBao are all Go, so the table above is their
+  actual behaviour, not a worst case.
+- **vector is Rust.** Whether it also sets `SO_REUSEADDR` by default is **unmeasured** — say so
+  rather than assume Go's default carries over.
+- **launchd itself has no port concept to collide on.** `man 5 launchd.plist`'s only socket-shaped
+  key is `Sockets` (launch-on-demand socket activation via `launch_activate_socket(3)`), and no
+  `LaunchdJobProps` today exposes it — a daemon binds its own port itself, launchd never mediates
+  it. So this check is squarely about daemons colliding with each other at bind time, not about
+  anything launchd enforces.
+
+## What it cannot see
+
+- **A job the stack does not pass.** `claimPorts` takes exactly the array a stack builds and
+  hands it; there is no argv-parsing, no config-file reading and no host inspection here to
+  recover a port a stack forgot to include. Leaving a job's claim out of the list is invisible to
+  this check, the same way a port left out of `lib-ports.nix` was invisible on 2026-09-02.
+- **A daemon still on Nix**, unless the migrating stack also passes that daemon's port as a claim
+  of its own (owner naming the Nix job, so the message is legible during a cutover). Until a job
+  moves off Nix, `lib-ports.nix` is still the thing keeping it collision-free; `claimPorts` only
+  starts covering a port once a kit stack declares the job that binds it.
+- **Two protocols of the same port number.** Keying on the port alone means a daemon on `tcp/9094`
+  and another on `udp/9094` would be refused as a collision, same as the Nix registry. No mini job
+  does that today (checked against the registry at `92cff7f`); if one needs to, the key widens
+  deliberately, in its own change — not silently here.
+
+## The error is a defect, not a typed channel
+
+`claimPorts` throws `PortRefused` (a `Data.TaggedError`), and like `catalogBinary()`, that throw
+inside a stack program's `Effect.gen` body is a **defect** — `Effect.catchTag('PortRefused', …)`
+never sees it, only `Effect.runPromiseExit` plus `Cause.hasDies`/`Cause.squash`. This is the exact
+gap [release-binary-upstream.md](./release-binary-upstream.md) names as gap 10 for
+`catalogBinary()`; it applies here unchanged because it is the same shape of function in the same
+kind of caller, not a new hole. `port-claims.test.ts` measures it the same way
+`error-channel.test.ts` measures `catalogBinary()`'s.

package/docs/launchd.md

@@ -165,6 +165,11 @@ Nix job is booted out first. Per job:
 - **Rolling back** is the same three steps reversed: destroy (or remove) the resource, restore the
   job in the Nix config, activate.
 
+## Port collisions
+
+`claimPorts()` refuses two of a stack's own jobs on one port, in the stack program, before any
+job is declared: [launchd-ports.md](./launchd-ports.md).
+
 ## The runner
 
 `HostRunner` (see `src/launchd/runner.ts`) is `exec(argv)` (never through a shell), `readFile`,

package/docs/release-binary-catalogs.md

@@ -0,0 +1,138 @@
+# Release binaries — the data sets, and adding one
+
+Status: active
+Verified: 2026-09-23
+
+`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`
+
+| 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.
+
+## `OPENBAO_RELEASES` — the first data set with a `computed` member
+
+| package   | version | asset (darwin_arm64)                | binaries (installed ← member)                               |
+| --------- | ------- | ----------------------------------- | ----------------------------------------------------------- |
+| `openbao` | 2.6.2   | `openbao_2.6.2_darwin_arm64.tar.gz` | `bao` ← `bao` (member digest: `computed`, ours — see below) |
+
+Walked down 2026-09-23, every command in
+[release-binary-openbao.md](./release-binary-openbao.md).
+
+- ★ **Platform key is `darwin_arm64`, underscore** — OpenBao's own asset
+  spelling, not Victoria's `darwin-arm64`. Each data set spells the platform
+  the way that vendor's asset names do; nothing here picks one estate-wide
+  convention (`openbao.ts`'s header has the rule and the one-line change if a
+  reviewer wants it unified).
+- ★ **The member digest is `computed`, not `members`.** `checksums.txt` lists
+  archives and every `.sbom.json`, never `bao` — the case this page used to
+  call out as "that field does not exist yet". It exists now: `catalogBinary`,
+  `catalogProblems` and `identifyBinary` all read `members` first, then
+  `computed`, and refuse a member pinned in both (`catalog.ts`).
+- ★ **GPG checked, Sigstore read but not verified.** `gpgv` against the key
+  published at openbao.org confirmed the signature over `checksums.txt`; the
+  key's own fingerprint matches OpenBao's install docs. `cosign` is not on
+  the mini, so the Sigstore bundle's workflow identity is recorded as
+  unverified, not as a passing check.
+
+## 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 says so under
+  `computed` rather than filing it beside the vendor's `members` lines
+  (`catalog.ts`; `OPENBAO_RELEASES` above is the 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 and vector. `bao` (OpenBao) is
+walked — see `OPENBAO_RELEASES` above.
+
+⚠️ 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.