@homeflare/alchemy 0.19.1 → 0.21.0

package/docs/release-binary-upstream.md

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

package/docs/release-binary.md

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

package/docs/upstream-conformance.md

@@ -0,0 +1,164 @@
+# Upstream conformance, family by family
+
+Status: open ledger. Verified 2026-09-22 by reading `origin/main` `925454b` against
+[provider-standard.md](./provider-standard.md) (`alchemy@2.0.0-beta.79`). Nothing in any
+family was changed by this audit. Each row names the rule it breaks and the upstream
+replacement or fix. A row is crossed off in the PR that fixes it, with that PR's evidence.
+A decision marked **maintainer** is not an agent's to make.
+
+## Ranked findings
+
+Findings are ranked by what they can break: runtime safety first, then contributability,
+then tidiness.
+
+1. **`cloudflare/R2BucketLock` diverges on four rules.**
+   - `readLock` ends in `Effect.orDie` (S20).
+   - `reconcileLock` and `deleteLock` use `Effect.promise` (S19).
+   - `reconcileLock` skips the PUT whenever `output.rules` equals the declaration, without
+     reading the live lock (S10). So neither `--force` nor `drift --repair` can restore
+     lock rules that were removed out of band. ⚠️ Reasoned from the source, not measured
+     live.
+   - `accountId` is a prop (S15).
+
+   It is built on a second Cloudflare SDK, `cloudflare@4.5.0` (S23). Upstream
+   `Cloudflare.R2.Bucket` has lifecycle and CORS rules but no lock, so this is a real gap.
+   **Fix:** move to `@distilled.cloud/cloudflare/r2` `getBucketLock`/`putBucketLock`,
+   observe before the PUT, and resolve the account from `CloudflareEnvironment`. Then drop
+   the `cloudflare` peer. That makes it contributable as `lockRules` on `R2.Bucket`, or as
+   `Cloudflare.R2.BucketLock`. **Decision:** maintainer, on the upstream shape.
+
+2. **`forgejo/*` duplicates an upstream building block.** `client.ts` is a hand-rolled
+   Effect `HttpClient` client with a status-carrying `ForgejoError`, while
+   `@distilled.cloud/forgejo@1.0.0-rc.12` exists. That package's Smithy service version is
+   16.0.3, the version this family measured (S21, S23). Credentials come from
+   `FORGEJO_TOKEN` at call time instead of an Auth provider (S24). `read` never answers
+   `Unowned` (H1). **Replacement:** the distilled SDK plus an `alchemy/Auth` provider.
+   Untyped errors become distilled patches. **Decision:** maintainer, because it changes
+   the error surface.
+3. **`cloudflare/MeshNode` duplicates `Cloudflare.Tunnel.WarpConnector`.** The divergence is
+   deliberate and documented in [mesh-node.md](./mesh-node.md): upstream persists the
+   connector token in state as a `Redacted` attribute, and it cannot create an HA node. The
+   type string `Cloudflare.MeshNode` sits inside upstream's own namespace (H14).
+   **Options:** contribute `ha` upstream and raise the token-in-state concern, then switch;
+   or keep the house resource as a recorded divergence. **Decision:** maintainer.
+4. **Unguarded `Bun.*`, and the `node:*` modules upstream names, in shipped provider code**
+   (S42). This is listed in [the Bun line](#the-bun-line). The exported `Bun.*` paths crash
+   under Node, which is the runtime this package promises its consumers. The `node:*` paths
+   load on Node but break the Effect-only rule.
+5. **`launchd`, `linux` and `caddy` have promise-based seams (H3).** `HostRunner` and
+   `CaddyAdmin` are plain `async` interfaces, with `node:child_process`, `node:fs/promises`
+   and `node:http` behind them, and failures are untyped `Error` (S19, S21). The stated
+   reason is that a consumer implements plain async functions. Upstream meets the same need
+   by letting a caller provide `FileSystem`, `ChildProcessSpawner` or `CommandExecutor`
+   layers, and `alchemy/Util/AtomicFile.writeFileAtomic` covers the temp-and-rename write.
+   ⚠️ Only in part. `local-runner.ts` creates its temp file with `O_EXCL`, mode 0600 and
+   `chown` before `chmod`, and it refuses a planted symlink. `writeFileAtomic` writes with
+   default flags and mode, `chmod`s afterwards, and never `chown`s.
+   **Decision:** maintainer. These families are also host-specific, so "house-only" is a
+   valid answer.
+6. **`openbao/*` has no upstream equivalent, and it conforms on the contract** (Effect
+   `HttpClient`, strict `Unowned`, retain). It diverges in three ways:
+   - 30 `Effect.die` sites in non-test source, several of them on `diff` and
+     `reconcile` paths (S20);
+   - 42 test files on `node:test` (S43);
+   - `Bao.*` type strings, where the vendor name is `OpenBao` (H14).
+
+   No distilled SDK exists. OpenBao serves an OpenAPI document, so a generated SDK in
+   distilled's shape is the S23 path. **Decision:** maintainer, on whether the kit authors
+   a distilled package.
+
+7. **`proxmox/*` is the model for S38.** Its types and constraints are generated from the
+   vendor schema, and a manifest records the version and sha256. It diverges in four ways:
+   - the generic factory's `read` returns plain attributes, so every family except `Lxc`
+     adopts silently, against the house's own H1;
+   - 27 `Effect.die` sites in non-test source (S20);
+   - 7 test files on `node:test`;
+   - `Pbs.*` type strings (H14).
+8. **`talos/*`.** Its `talosctl` calls go through `ChildProcessSpawner`, as upstream's Docker
+   provider does, which conforms. Its file handling uses `Bun.file`, `Bun.write`,
+   `Bun.YAML` and `node:fs` (S42), and it uses `Effect.promise` in 3 files (S19). The
+   kubeconfig it writes is meant to be consumed through upstream's
+   `Kubernetes.KubeConfig({ path })`.
+9. **`netbox/*` conforms mostly.** Its constraints are generated from NetBox 4.7.0's
+   OpenAPI, and it uses Effect `HttpClient`. Adopting first is documented as deliberate.
+   It diverges in its credentials: `NETBOX_TOKEN` is read at call time (S24).
+10. **Every family repeats `list: () => Effect.succeed([])`**, 30 times, and only
+    `R2BucketLock` and `MeshNode` declare `nuke`. The constructor already defaults `list`
+    (S12). **Fix:** write the reason where it differs, and declare `nuke: { skip: true }`
+    where nuke must never reach the object.
+11. **Resource JSDoc is not in upstream's generator format.** Zero files use `@resource`,
+    `**Example:**` or `### Section` (S31, H10). **Decision:** maintainer, because it moves
+    the house's glyph rationale into `//` comments.
+12. **Tests never use `alchemy/Test/Bun`.** Every lifecycle is proven against loopback
+    fakes (S28, H12). Live suites need a place to run, and that is a maintainer decision.
+
+## Conforms
+
+- **`github/declareRepoPolicy`** composes upstream `GitHub.Repository` and
+  `GitHub.Ruleset`. Its one hazard is upstream's own: `Ruleset.read` returns `undefined`
+  without prior output, so a first deploy creates a duplicate
+  ([repo-policy.md](./repo-policy.md)). The fix belongs upstream: read by name and answer
+  `Unowned`.
+- **`cloudflare/website.ts`** sets house defaults over upstream `Website.Astro` and
+  `Website.Vite`.
+- **`ownership/*`** is built only on `AdoptPolicy`, `Stack`, `State` and `Artifacts`. Its
+  apply-time re-check (H2) exists because beta.79 skips the adoption probe while props hold
+  an Output. That fix also belongs in the engine upstream.
+- **`verify/*`** (`hf-adopt-verify`) runs Alchemy's own planner. It exists because beta.79
+  labels every cold adoption as an update (H6).
+
+## The Bun line
+
+These are non-test files under `src/` that the standard (S42) says must be portable. "Exp"
+marks files exported from a subpath `index.ts`. `git grep` on `origin/main` finds 23 non-test
+files under `src/` that call `Bun.*` or import `node:*`/`bun:*`. Six of them are outside
+S42's scope:
+
+- four loopback fakes (`caddy/fake-caddy.ts`, `openbao/fake-bao.ts`, `proxmox/fake-pve.ts`,
+  `proxmox/fake-pve-lxc.ts`), which are test-side under S44;
+- `proxmox/provision-cli-fake.ts`, which is used only by tests;
+- `verify/args.ts`, which belongs to the CLI and so is tooling under S43.
+
+That leaves 17 files. The table lists them, plus `provision-cli-fake.ts`, which should move
+out of `src/`. The six out-of-scope files still ship in the tarball's `src/`, but no export
+reaches them.
+⚠️ The first version of this table said 16 files and left out `launchd/job-form.ts`.
+⚠️ Corrected 2026-09-22: 14 of the 17 break upstream's rule. `launchd/job-form.ts`,
+`proxmox/write-only.ts` and `proxmox/pbs-notification-target-wire.ts` use only synchronous
+`node:crypto` or `Buffer`. Upstream allows those inside `Effect.sync`
+(`AGENTS.md@v2.0.0-beta.79#Workflow`), and 40 upstream `src/` files import `node:crypto`,
+among them `Fly/Secret.ts` and `Railway/Variable.ts`. They were listed under a blanket
+`node:*` ban that upstream does not have.
+
+| file                                                       | API                                          | exp | portable replacement                         |
+| ---------------------------------------------------------- | -------------------------------------------- | --- | -------------------------------------------- |
+| `openbao/cloudflare-roles-config.ts`                       | `Bun.YAML`                                   | yes | parse on the tooling side; pass data in      |
+| `openbao/digest.ts` (14 importers)                         | `Bun.CryptoHasher`                           | —   | `Crypto.digest` + hex; keep `canonical()` ⚠️ |
+| `openbao/cloudflare-parity-snapshot.ts`                    | `Bun.file`, `Bun.Glob`                       | —   | `FileSystem` + `Path`                        |
+| `openbao/approle-login-form.ts`                            | `Bun.file`                                   | —   | `FileSystem.readFileString`                  |
+| `openbao/approle-login-result.ts`                          | `Bun.inspect`                                | —   | a plain formatter                            |
+| `openbao/forgejo-bootstrap.ts`                             | `Bun.spawn`                                  | —   | unreferenced; `ChildProcessSpawner` or drop  |
+| `talos/credentials.ts`                                     | `Bun.write/file/env/randomUUIDv7`, `node:fs` | —   | `FileSystem.makeTempFileScoped`              |
+| `talos/kubeconfig.ts`                                      | `Bun.file`                                   | yes | `FileSystem`                                 |
+| `talos/talos-machine-config.ts`                            | `Bun.file`                                   | yes | `FileSystem`                                 |
+| `talos/values.ts`                                          | `Bun.YAML`, `node:crypto`                    | —   | tooling-side parse; hash may stay            |
+| `launchd/local-runner.ts`                                  | `node:child_process`, `node:fs/promises`     | yes | H3 above                                     |
+| `launchd/sudo-stage.ts`                                    | `node:fs/promises`, `node:os`, `node:path`   | —   | `FileSystem`, `Path`                         |
+| `launchd/job-form.ts`                                      | `node:crypto` (`createHash`)                 | —   | allowed in `Effect.sync`                     |
+| `linux/ssh-runner.ts`                                      | `node:child_process`, `node:crypto`          | yes | H3 above                                     |
+| `caddy/local-admin.ts`                                     | `node:http` (unix socket)                    | yes | H3 above                                     |
+| `proxmox/write-only.ts`, `pbs-notification-target-wire.ts` | `node:crypto`, `node:buffer`                 | —   | allowed in `Effect.sync` ⚠️                  |
+| `proxmox/provision-cli-fake.ts`                            | `Bun.spawn`, `node:fs`                       | —   | test-only; move out of `src/`                |
+
+The ⚠️ rows:
+
+- `openbao/digest.ts`: every `Bao.*` family persists this digest in state, so a swap must
+  hash the same bytes (`canonical()`, lowercase hex), or every row plans an update.
+  `Crypto.digest` from `effect/Crypto` is in every stack's services and fails with a typed
+  error; `alchemy/Util/sha256` wraps WebCrypto in `Effect.promise`.
+- `proxmox/write-only.ts`: a salted scrypt seal with `timingSafeEqual`. No Alchemy helper
+  replaces it. A plain `sha256` would make a write-only secret cheap to brute-force from
+  state, and it would change the persisted seal format.
+
+Test runners: 51 files import `node:test`/`node:assert` (openbao 42, proxmox 7, forgejo 1,
+talos 1), and 126 import `bun:test`. S43 says `bun:test`.

package/package.json

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

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

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