@homeflare/alchemy 0.19.1 → 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/adopted-deploys.md

@@ -54,6 +54,9 @@ API token on the cluster, just as it does for `alchemy plan`.
 | `Pbs.Datastore`                | `config/datastore/{name}`                                       | read (PBS)  | own: GET, path/backend guards, PUT skipped on `matches`, settle GET — no write                       |
 | `Proxmox.SdnApply`             | 5 × `cluster/sdn/*?pending=1` + fabrics `?pending` / `?running` | read        | own: counts staged objects; zero returns at once — **no `PUT /cluster/sdn`**                         |
 | `Proxmox.CephPool` ⁴           | `nodes/{node}/ceph/pool/{name}/status?verbose=1`                | read        | own: GET, **PUT skipped on `matches` (was: always `PUT nodes/{node}/ceph/pool/{name}`)**, settle GET |
+| `Proxmox.CephDaemon` ⁶         | `nodes/{node}/ceph/{mon,mgr,mds}` (whole list, by `name`)       | read        | shared path, and no `updateForm`: GET, GET — no write                                                |
+| `Proxmox.CephFs` ⁶             | `nodes/{node}/ceph/fs` (whole list, by `name`)                  | read        | own: GET, present so returned untouched — no write                                                   |
+| `Proxmox.CephOsd` ⁶            | `nodes/{node}/ceph/osd` (the CRUSH tree)                        | read        | own: GET, host/class asserted; POSTs only with `dev` declared — no write                             |
 
 ¹ These object reads are gated on an allocate privilege, so the family reads with the provision
 lease (`readRole`, resource.ts). That is still a read.
@@ -73,6 +76,13 @@ compares a seal kept in the previous state ([pbs-notifications.md](./pbs-notific
 adopted target has no seal, so its secret values are presence-only and adoption writes nothing.
 Pinned by `src/proxmox/pbs-notification-target-state.test.ts`.
 
+⁶ Exported from the barrel 2026-09-22. None has a PUT, and CephDaemon and CephFs compare nothing,
+so a present object is `noop` and can never plan a replace. All three retain on destroy: removing
+the declaration plans `orphaned` and sends no DELETE. `Proxmox.CephFlag` stays Provider-only (a
+declared flag reasserts a maintenance toggle on every deploy). Pinned by
+`src/proxmox/ceph-adopt.test.ts`, whose mutation check (retain flipped to destroy) shows nine
+DELETEs, one per mon, mgr and mds.
+
 ## Before the fix: `Proxmox.CephPool`
 
 `reconcile` read the pool and, whenever it existed, PUT the declared `size`, `min_size`,
@@ -90,6 +100,9 @@ list shows six such tasks (2026-09-13 and 2026-09-20), one per declared pool per
 - `src/proxmox/adopt-noop.test.ts` does the same for each reconcile shape: the shared path
   (`Proxmox.Pool`), the wrapper (`Proxmox.Acl`), and the two hand-written ones (`Pbs.Datastore`,
   `Proxmox.SdnApply`). A drifted Pool row proves the harness sees a write when there is one.
+- `src/proxmox/ceph-adopt.test.ts` adopts a reference cluster's nine daemons, one CephFS and six
+  OSDs (GETs only), undeclares all sixteen (no DELETE), and refuses an OSD on the wrong host
+  without a write.
 - `src/verify/verify.test.ts` pins Alchemy's own behaviour: `adopted` for a match and for a
   drift, and a reconcile for both. If an Alchemy upgrade changes that, the test fails and this
   page needs re-reading.

package/docs/linux-host.md

@@ -107,6 +107,9 @@ one declared line
 - ⛔ **Ambiguity is a refusal.** Two BEGIN markers, an END before its BEGIN, or
   a BEGIN with no END each name the line rather than guess.
 - **Delete removes only the block**, leaving the rest byte-identical.
+- ⛔ **The region's name and comment token are its identity.** Changing either
+  moves the block: the new one is written and verified, then the old one goes.
+  Switching between whole-file and region mode at one path is refused.
 - ⚠️ A file with no final newline gains exactly one when the block is appended.
   That is the only byte added outside the block, and it is not taken back.
 
@@ -164,7 +167,8 @@ unit reads converged — the same limit the Mac side records.
   before that swap is promised. A file byte-identical to this render is the
   declaration's own leftover, not someone else's unit. A rename the plan could
   not see (a name still an Output) gets the same checks at apply, before the
-  old unit is stopped.
+  old unit is stopped; one whose `content` is still an Output gets the checks
+  that need only the name — deletable, writable, not masked — in the plan.
 
 ### The directive set is systemd's, not the kit's
 

package/docs/provider-standard.md

@@ -0,0 +1,138 @@
+# The provider standard
+
+Status: in force. Verified 2026-09-22 against `alchemy@2.0.0-beta.79` (tag
+`v2.0.0-beta.79`, commit `473c3959`) and the distilled commit that tag pins (`c2a78002`).
+
+This page is the kit-side statement of the house standard for a custom Alchemy provider.
+The full rule set is the `alchemy-provider-standard` skill in the estate's workflow plugin.
+It has 46 numbered rules (S1–S46) and 14 house differences (H1–H14), and every rule cites
+`alchemy-run/alchemy` as `<path>@v2.0.0-beta.79#<section>`. This page keeps the rule numbers
+so that a review comment can name the rule a change breaks. How each family measures up is
+in [upstream-conformance.md](./upstream-conformance.md).
+
+★ **Why this package holds itself to upstream's bar.** Everything in `@homeflare/alchemy`
+should be good enough to contribute to Alchemy. So the kit builds only what upstream lacks,
+and builds it the way upstream would. A house re-implementation of something Alchemy
+already ships is a finding, even when it works.
+
+## Three questions before any code
+
+1. **Does upstream ship the resource?** Look under `packages/alchemy/src/<Cloud>/` at the
+   pinned tag. If it does, use it. `github/` does exactly this: it composes
+   `GitHub.Repository` and `GitHub.Ruleset`. `website.ts` does it too, over
+   `Website.Astro` and `Website.Vite`. A missing prop means an upstream PR, never a fork
+   (S1).
+2. **Does `@distilled.cloud/<vendor>` exist?** If it does, every call goes through it,
+   with its typed error unions and Credentials layer. A second SDK or a hand-rolled client
+   is a finding. On 2026-09-22 npm had distilled packages for Forgejo, GitHub, Kubernetes
+   and Docker, among others, and none for Proxmox, OpenBao, Caddy, Talos, NetBox or UniFi
+   (S23).
+3. **Does Alchemy ship the helper?** Hashing (`alchemy/Util/sha256`), polling
+   (`alchemy/Util/poll`), atomic writes (`alchemy/Util/AtomicFile`), equality
+   (`deepEqual` in `alchemy/Diff`), names (`alchemy/PhysicalName`), tags (`alchemy/Tags`),
+   ownership (`alchemy/AdoptPolicy`), credentials (`alchemy/Auth`) and the test harness
+   (`alchemy/Test/Bun`) all exist. Use them.
+
+## The contract, in brief
+
+- **Shape (S2, S3).** Declare the interface as
+  `Resource<"Vendor.Service.Type", Props, Attrs, never, Providers>`, and the constructor as
+  `const X = Resource<X>(…)`. The type string starts with the vendor's own name. The
+  contract and its provider share a file, and helpers go in sibling files that `index.ts`
+  does not export.
+- **Props (S5).** Props are plain types, never `Input<T>`, and every field has JSDoc.
+- **Diff (S6).** `diff` narrows with `isResolved`. It returns `undefined` for an ordinary
+  update and `replace` only for identity changes.
+- **Read (S7, S8).** `read` works with `output: undefined`. It answers `undefined`, plain
+  attributes or `Unowned(attrs)`. This package answers `Unowned` for any live object this
+  stack cannot prove it made (H1; [ownership.md](./ownership.md)).
+- **Reconcile (S9, S10).** `reconcile` is one flow: observe, ensure, sync, return. It
+  never trusts `output` as proof, and it makes zero writes when nothing drifted.
+- **Delete (S11, S14).** `delete` is idempotent and bounded. A family whose deletion
+  breaks its consumers defaults to `retain`, and still implements `delete` in full.
+- **List (S12).** `list` enumerates every object of the type in its scope, or returns `[]`
+  with the reason written down. A family whose objects carry ownership marks filters to
+  owned ones, as upstream's third-party providers do; the core contract does not ask for it. `nuke` is declared wherever nuke must never reach the object.
+- **Scope (S15).** The account, zone and region are resolved inside each operation. They
+  are never props.
+
+## Code, errors, credentials
+
+- **Effect only (S19).** Provider code, helpers and tests use `FileSystem`, `Path`,
+  `HttpClient` and `ChildProcessSpawner`. They never use `async`/`await`, a raw `Promise`,
+  `node:fs`, `node:fs/promises`, `node:os`, `node:path` or bare `fetch`. A synchronous,
+  CPU-only Node call (`node:crypto` `createHash`, `Buffer`) goes inside `Effect.sync`, which
+  is upstream's own example. When a promise cannot be avoided, use `Effect.tryPromise`,
+  never `Effect.promise`.
+- **No defects (S20).** Lifecycle operations contain no `Effect.orDie` and no
+  `Effect.die`. A refusal is a typed error.
+- **Typed errors (S21, S22).** Handle errors with `Effect.catchTag` over the SDK's union.
+  Where the kit generates its own client from a vendor schema, the status-to-tag mapping
+  lives in that client, once, and never in a resource.
+- **Credentials (S24).** Credentials come from an `alchemy/Auth` provider and a lazy
+  Credentials service. Short-lived credentials are minted per call, never reused, and never
+  taken as props.
+- **Secrets (S25).** A secret value is never a prop or an attribute. Alchemy persists
+  `Redacted` values in plaintext, and only one state store encrypts them.
+- **Bounded waits (S26).** A retry stops after at most 8 to 10 attempts and under about a
+  minute. A poll never runs past about 90 seconds.
+
+## The Bun line for this package (S42–S45)
+
+★ This package is Bun to author and runtime-neutral to consume. It builds with
+`bun build --target node`, and consumers run `dist/` on Node.
+
+- **`src/**` provider code** (resources, providers, clients, and helpers a provider calls)
+  never calls `Bun.*` and never imports `bun:*` or the `node:*` modules S19 names. A Node
+  consumer calling an exported helper that uses `Bun.YAML` fails with
+  `ReferenceError: Bun is not defined` at the call site. `node:crypto`, `node:http` and
+  `node:child_process` all load on Node. Where they break the standard, they break the
+  Effect-only rule, not the runtime.
+- **Tests, fakes, scripts and codegen** are Bun-native. That means `bun:test` (never
+  `node:test`, never vitest), `Bun.serve` fakes on loopback, `Bun.YAML`, `Bun.file()`,
+  `Bun.Glob` and `Bun.CryptoHasher`. Upstream runs its scripts and its test runner on Bun
+  too.
+- **A module that truly needs Bun** is named for Bun, sits behind its own subpath, or
+  guards on `typeof globalThis.Bun`. The package root never reaches it.
+
+The files currently on the wrong side of the line are listed in
+[upstream-conformance.md](./upstream-conformance.md#the-bun-line).
+
+## Versions (S37–S41)
+
+- **One aligned set.** `effect`, `@distilled.cloud/*` and `@effect/platform-*` are pinned
+  exactly to what the pinned `alchemy` release was built and tested against. They move only
+  in the same PR as the `alchemy` bump.
+- **Every family records the vendor version it was walked against, in code.**
+  - For a generated client, the record is the schema manifest entry and the generated
+    header. `codegen/manifest.json` holds the product, version, sha256, fetch date and
+    source role for PVE, PBS, UniFi and NetBox.
+  - For a distilled-backed family, it is the chain: `alchemy` version, distilled package
+    version, distilled commit, spec-mirror commit and date, and Smithy service version.
+  - For a CLI or OS-service family, it is the binary or OS version, the command that
+    reports it, and the date, in that family's docs page.
+- **And in its changeset.** A provider change names the vendor version it was walked
+  against. A pin move names every link, old and new.
+
+| family              | vendor version walked against          | recorded in                       |
+| ------------------- | -------------------------------------- | --------------------------------- |
+| `proxmox` (PVE)     | pve-manager 9.2.11                     | `codegen/manifest.json` + headers |
+| `proxmox` (PBS)     | proxmox-backup-server 4.2.6-1          | `codegen/manifest.json` + headers |
+| `netbox`            | NetBox 4.7.0 OpenAPI                   | `codegen/manifest.json` + headers |
+| `cloudflare`        | distilled 1.0.0-rc.12 (API v4)         | `package.json` pins only          |
+| `openbao`           | OpenBao 2.6.2                          | source comments only ⚠️           |
+| `caddy`             | Caddy 2.11.4                           | source comments only ⚠️           |
+| `forgejo`           | Forgejo 16.0.3                         | source comments only ⚠️           |
+| `talos`             | Talos v1.13 docs (never measured live) | source comments only ⚠️           |
+| `launchd` / `linux` | macOS 27 / systemd 257                 | source comments only ⚠️           |
+
+⚠️ These rows record a version only in prose, so no test catches a drift. `schemas/manifest.json`
+also repeats the PVE, PBS and UniFi entries, which means there are two manifests for one
+fact.
+
+## Where this package differs from upstream on purpose
+
+Each difference is written down with its reason. H1 is strict `Unowned`. H2 is the
+apply-time ownership re-check in `ownership/`. H4 is `retain` by default. H5 is `adopt(true)`
+on each resource. H6 is `hf-adopt-verify`. [upstream-conformance.md](./upstream-conformance.md)
+marks each one justified or a gap. Anything not listed there is a gap by definition.

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`).