@homeflare/alchemy 0.21.0 → 0.22.0

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

@@ -1,7 +1,7 @@
 # Release binaries — the data sets, and adding one
 
 Status: active
-Verified: 2026-09-22
+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`),
@@ -9,7 +9,7 @@ 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
+## `VICTORIA_RELEASES`
 
 | package            | version | asset (darwin-arm64)                            | binaries (installed ← member)                                                                          |
 | ------------------ | ------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
@@ -36,6 +36,31 @@ change that re-pins both digest layers.
   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:
@@ -66,9 +91,9 @@ its data module's header with the date:
   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.
+  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
@@ -84,8 +109,8 @@ 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).
+`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

package/docs/release-binary-openbao.md

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

package/docs/release-binary.md

@@ -1,7 +1,7 @@
 # Release binaries — `@homeflare/alchemy/release`
 
 Status: active
-Verified: 2026-09-22
+Verified: 2026-09-23
 
 `Release.Binary` (`ReleaseBinary`) installs one binary out of a pinned release
 archive, verified twice: the archive against its pinned SHA-256 before anything
@@ -37,9 +37,20 @@ const vmalert = yield* ReleaseBinary('vmalert', {
   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'], … });
+yield* LaunchdJob('vmalert-job', { programArguments: [vmalert.path, '--httpListenAddr=127.0.0.1:8880'], … });
 ```
 
+⚠️ **Give every resource its own logical id, even across different types.**
+alchemy@2.0.0-beta.79's FQN is `namespace + id` alone (`FQN.ts`) — it does
+NOT fold in the resource type. `stack.resources[fqn]` (`Resource.ts`)
+returns the **first** registration for a repeated id whatever type it was:
+`ReleaseBinary('vmalert', …)` then `LaunchdJob('vmalert', …)` in the same
+namespace silently hands the job call back the _binary_ resource, and the
+job is never registered at all — no error, no second row in the plan, just a
+job that does not exist. Measured against the installed alchemy package,
+2026-09-23. Naming them `'vmalert'` and `'vmalert-job'` (as above) avoids it;
+so does any other pair of distinct ids.
+
 - **`catalogBinary()` runs in your stack program.** A version, package,
   platform or binary the data set does not pin throws `BinaryRefused` there,
   so `alchemy plan` fails before any resource is asked anything

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",

package/src/launchd/index.ts

@@ -21,6 +21,8 @@ export type { LocalRunnerOptions } from './local-runner.ts';
 export { localRunner } from './local-runner.ts';
 export type { PlistDict, PlistValue } from './plist.ts';
 export { PlistError, renderPlist } from './plist.ts';
+export type { PortClaim } from './port-claims.ts';
+export { PortRefused, claimPorts, portClaimProblems } from './port-claims.ts';
 export { launchdProviders } from './providers.ts';
 export type { ExecResult, FileStat, HostRunner, HostUser, WriteOptions } from './runner.ts';
 export { HostRunnerService, canActAsRoot, hostRunnerLayer } from './runner.ts';

package/src/launchd/port-claims.test.ts

@@ -0,0 +1,124 @@
+/**
+ * Port collisions, pure and through the engine. Every refusal here happens in the stack's own
+ * program (an ordinary `throw` before any resource is even declared), so plan.test.ts's proof for
+ * `catalogBinary()` — that the engine never runs a provider or touches a host once the body throws
+ * — is re-proved below for `claimPorts`, not assumed to carry over.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { fakeStack } from '../openbao/fake-stack.ts';
+import { fakeRunner } from './fake-runner.ts';
+import { LaunchdJob } from './job.ts';
+import { type PortClaim, PortRefused, claimPorts, portClaimProblems } from './port-claims.ts';
+import { launchdProviders } from './providers.ts';
+import type { HostRunner } from './runner.ts';
+
+describe('portClaimProblems', () => {
+  test.each([
+    [
+      'a port that is not an integer 1–65535 (too low)',
+      [{ owner: 'vector', port: 0 }],
+      'port must be an integer from 1 to 65535',
+    ],
+    [
+      'a port that is not an integer 1–65535 (too high)',
+      [{ owner: 'vector', port: 65536 }],
+      'port must be an integer from 1 to 65535',
+    ],
+    [
+      'a port that is not an integer 1–65535 (fractional)',
+      [{ owner: 'vector', port: 9094.5 }],
+      'port must be an integer from 1 to 65535',
+    ],
+    ['an empty owner', [{ owner: '', port: 9094 }], 'has an empty owner'],
+    [
+      'one owner claiming a port twice',
+      [
+        { owner: 'vector', port: 9094 },
+        { owner: 'vector', port: 9094, address: '127.0.0.1' },
+      ],
+      'vector claims port 9094 more than once',
+    ],
+    [
+      'two owners on one port, naming both owners and both addresses',
+      [
+        { owner: 'vector', port: 9094, address: '0.0.0.0' },
+        { owner: 'victoria-logs', port: 9094, address: '127.0.0.1' },
+      ],
+      'port 9094 is claimed by more than one owner: vector (0.0.0.0) and victoria-logs (127.0.0.1)',
+    ],
+  ] satisfies Array<[string, PortClaim[], string]>)('refuses %s', (_, claims, message) => {
+    expect(portClaimProblems(claims).join('; ')).toContain(message);
+    expect(() => claimPorts(claims)).toThrow(message);
+  });
+
+  test('distinct ports return no problems', () => {
+    const claims: PortClaim[] = [
+      { owner: 'vector', port: 9094 },
+      { owner: 'victoria-logs', port: 9428, address: '127.0.0.1' },
+    ];
+    expect(portClaimProblems(claims)).toEqual([]);
+    expect(() => claimPorts(claims)).not.toThrow();
+  });
+
+  // ★ MEASURED (docs/launchd-ports.md): on macOS both of these actually bind — SO_REUSEADDR plus
+  //   an address mismatch lets a wildcard and a specific address share one port at the OS level.
+  //   The check refuses it anyway: the key is the port NUMBER alone, like lib-ports.nix.
+  test('0.0.0.0:9094 against 127.0.0.1:9094 is refused, though the OS would let both bind', () => {
+    const problems = portClaimProblems([
+      { owner: 'vector', port: 9094, address: '0.0.0.0' },
+      { owner: 'victoria-logs', port: 9094, address: '127.0.0.1' },
+    ]);
+    expect(problems).toEqual([
+      'port 9094 is claimed by more than one owner: vector (0.0.0.0) and victoria-logs (127.0.0.1)',
+    ]);
+  });
+
+  test('claimPorts throws PortRefused carrying the house refusal sentence', () => {
+    let caught: unknown;
+    try {
+      claimPorts([
+        { owner: 'a', port: 9094 },
+        { owner: 'b', port: 9094 },
+      ]);
+    } catch (cause) {
+      caught = cause;
+    }
+    expect(caught).toBeInstanceOf(PortRefused);
+    expect((caught as Error).message).toMatch(/^Launchd ports: .* Nothing was declared\.$/);
+  });
+});
+
+describe('through the engine', () => {
+  test('a collision fails the plan before any provider or host call', async () => {
+    const fake = fakeRunner({ euid: 0 });
+    const events: string[] = [];
+    const runner: HostRunner = {
+      ...fake.runner,
+      exec: (argv) => {
+        events.push(`exec ${argv.join(' ')}`);
+        return fake.runner.exec(argv);
+      },
+      writeFileAtomic: (path, bytes, options) => {
+        events.push(`write ${path}`);
+        return fake.runner.writeFileAtomic(path, bytes, options);
+      },
+    };
+    const stack = fakeStack(launchdProviders(runner), {}, 'PortClaimsStack');
+    const body = Effect.gen(function* () {
+      claimPorts([
+        { owner: 'vector', port: 9094 },
+        { owner: 'victoria-logs', port: 9094 },
+      ]);
+      // Never reached: proves the collision is caught before this job — or any provider/host
+      // call it would make — runs at all.
+      yield* LaunchdJob('never-created', {
+        domain: 'system',
+        label: 'com.example.never-created',
+        programArguments: ['/usr/local/bin/never-created'],
+      });
+    });
+    await expect(stack.deploy(body)).rejects.toThrow('Nothing was declared');
+    expect(events).toEqual([]);
+  });
+});

package/src/launchd/port-claims.ts

@@ -0,0 +1,102 @@
+/**
+ * Port collision refusal for a stack's own launchd jobs — pure: no host, no network, and
+ * runtime-portable (no `Bun.*`, no `node:*`), so a future Linux consumer (systemd units, under
+ * `/linux`) can import it unchanged.
+ *
+ * ★ MIRRORS house/nix's REGISTRY, NOT A NEW RULE. `lib-ports.nix` (house @ 92cff7f) collides on
+ *   `lib.attrValues ports` alone — `dupes = lib.subtractLists (lib.unique vals) vals` — keying on
+ *   the PORT NUMBER by itself; address and protocol are never read. `portClaimProblems` below keys
+ *   the same way on purpose: it replaces that check for the jobs a kit stack declares, and a looser
+ *   or stricter rule would silently diverge from the registry it takes over from. What that trades
+ *   away — a wildcard bind beside a specific one on the same port both succeed, silently splitting
+ *   traffic — is measured in docs/launchd-ports.md, not assumed.
+ * ★ IN THE STACK PROGRAM, NOT A PROVIDER — same shape as `catalogBinary()` (../release/catalog.ts).
+ *   Two reasons, both structural to Alchemy 2.0.0-beta.79: Alchemy never diffs a first `create`
+ *   whose props still hold an unresolved `Output`, and every mini job's `programArguments` carries
+ *   a `HostFile` config digest as an `Output` — so a provider-side check would miss the very first
+ *   deploy of every job. And a provider never sees its sibling resources, so it could not compare
+ *   one job's port against another's even if props were resolved. A plain function called from the
+ *   stack's own `Effect.gen` body sees every claim the stack passes, before anything is applied.
+ * ⚠️ IT SEES ONLY WHAT THE STACK PASSES. A job the stack forgets to add to its claim list is
+ *   invisible to this check — there is no argv-parsing or host inspection here to catch that, and
+ *   adding one would be guessing at a job's own config shape. docs/launchd-ports.md says what this
+ *   cannot see, in full.
+ */
+import * as Data from 'effect/Data';
+
+/** One job's claim on one port. `address` is informational only — the key is `port` alone. */
+export interface PortClaim {
+  /** Whose claim this is, for the refusal message: a job id or label, never empty. */
+  readonly owner: string;
+  readonly port: number;
+  /** What the job binds, if the stack knows it. Omitted claims still collide by port number. */
+  readonly address?: string;
+}
+
+const describeAddress = (address: string | undefined): string => address ?? 'unspecified address';
+
+const describeOwner = (owner: string): string => (owner === '' ? '(empty owner)' : owner);
+
+/**
+ * Everything wrong with a set of claims; empty when none collide. ★ KEYS ON `port` ALONE, exactly
+ *   like `lib-ports.nix`'s `assertNoCollision` — see the file header for why.
+ */
+export const portClaimProblems = (claims: readonly PortClaim[]): string[] => {
+  const found: string[] = [];
+  const byPort = new Map<number, PortClaim[]>();
+  for (const claim of claims) {
+    if (!Number.isSafeInteger(claim.port) || claim.port < 1 || claim.port > 65535) {
+      found.push(
+        `${describeOwner(claim.owner)}: port must be an integer from 1 to 65535, got ${String(claim.port)}`,
+      );
+    }
+    if (claim.owner === '') {
+      found.push(`a claim on port ${String(claim.port)} has an empty owner`);
+    }
+    const list = byPort.get(claim.port) ?? [];
+    list.push(claim);
+    byPort.set(claim.port, list);
+  }
+  for (const [port, list] of byPort) {
+    if (list.length < 2) continue;
+    // One owner naming the same port more than once — flagged the first time it repeats.
+    const seen = new Set<string>();
+    for (const claim of list) {
+      if (claim.owner === '') continue; // already reported above
+      if (seen.has(claim.owner)) {
+        found.push(`${claim.owner} claims port ${String(port)} more than once`);
+      }
+      seen.add(claim.owner);
+    }
+    // Two different owners on the same port number — the collision the registry exists to catch.
+    const distinctOwners = [...new Set(list.map((claim) => claim.owner).filter((o) => o !== ''))];
+    if (distinctOwners.length > 1) {
+      const described = list
+        .map((claim) => `${describeOwner(claim.owner)} (${describeAddress(claim.address)})`)
+        .join(' and ');
+      found.push(`port ${String(port)} is claimed by more than one owner: ${described}`);
+    }
+  }
+  return found;
+};
+
+/** The declaration itself: a bad port, an empty owner, or two owners sharing one port number. */
+export class PortRefused extends Data.TaggedError('PortRefused')<{
+  readonly message: string;
+}> {}
+
+/**
+ * Refuse a colliding set of claims, or do nothing. ⛔ THROWS `PortRefused` — exactly like
+ *   `catalogBinary()`, this is a DEFECT in a stack program's `Effect.gen` body, not a typed failure
+ *   a caller can `Effect.catchTag` on: gap 10 of docs/release-binary-upstream.md applies here
+ *   unchanged (measured the same way, in port-claims.test.ts). The plan still fails before anything
+ *   is applied; the error itself is just not a typed channel yet.
+ */
+export const claimPorts = (claims: readonly PortClaim[]): void => {
+  const problems = portClaimProblems(claims);
+  if (problems.length > 0) {
+    throw new PortRefused({
+      message: `Launchd ports: ${problems.join('; ')}. Nothing was declared.`,
+    });
+  }
+};

package/src/launchd/providers.test.ts

@@ -212,11 +212,14 @@ describe('the barrel', () => {
       'LaunchdJob',
       'LaunchdJobProvider',
       'PlistError',
+      'PortRefused',
       'SudoRefusedError',
       'canActAsRoot',
+      'claimPorts',
       'hostRunnerLayer',
       'launchdProviders',
       'localRunner',
+      'portClaimProblems',
       'renderPlist',
       // ★ The opt-in elevating runner; makeSudoRunner and the allowlist internals stay off.
       'sudoRunner',