@homeflare/alchemy 0.21.0 → 0.23.0

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.23.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',

package/src/proxmox/api-token-adopt.test.ts

@@ -0,0 +1,138 @@
+/**
+ * `Proxmox.ApiToken` adopted, undeclared and drifted through Alchemy's own Plan and Apply, over a
+ * fake cluster — pinning the metadata-only shape decision 9 (2026-09-23) builds: adopt and manage
+ * `comment`/`expire`/`privsep`, never mint a token this resource cannot hand anybody the secret
+ * for (api-token.ts's header).
+ *
+ * ★ FOUR LIVE SHAPES: `metrics@pve!exporter` and `iac@pve!apply` are the no-comment / commented
+ *   shapes named in api-token.ts's own header; `svc@pve!lease1` and `svc@pve!lease2` are
+ *   PLACEHOLDERS (never an estate mint-user account — see the ⛔ on declaring under one in
+ *   api-token.ts's header) exercising a real non-zero `expire` offered as BOTH a JSON number and
+ *   a JSON string, which PVE does depending on path — `int()` (values.ts) must not care which.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { engineOver } from '../verify/fake-engine.ts';
+import { type ApiTokenProps, ProxmoxApiToken, ProxmoxApiTokenProvider } from './api-token.ts';
+import { shape } from './api-token-form.ts';
+import { FAKE_TARGET, type PveCall, fakePve, withoutBao } from './fake-pve.ts';
+import type {
+  AccessUsersUseridTokenTokenidPostParams,
+  AccessUsersUseridTokenTokenidPutParams,
+} from './generated/pve.ts';
+
+type Live = { comment?: string; expire: number | string; privsep: number };
+
+/** `access/users/{userid}/token/{tokenid}`, mutable so the PUT test can watch it change. */
+const tokens = new Map<string, Live>([
+  ['access/users/metrics@pve/token/exporter', { expire: 0, privsep: 0 }],
+  ['access/users/iac@pve/token/apply', { comment: 'automation', expire: 0, privsep: 0 }],
+  ['access/users/svc@pve/token/lease1', { expire: 1789327175, privsep: 0 }],
+  ['access/users/svc@pve/token/lease2', { comment: 'lease', expire: '1789327175', privsep: 0 }],
+]);
+
+const cluster = () =>
+  fakePve((call: PveCall) => {
+    if (call.method === 'GET') return tokens.get(call.path);
+    if (call.method === 'PUT') {
+      const live = tokens.get(call.path);
+      if (live !== undefined) tokens.set(call.path, { ...live, ...call.form });
+      return call.form;
+    }
+    return undefined;
+  });
+
+/** The declared props matching a live fixture exactly — `expire` always as a `number` prop. */
+const propsFor = (
+  userid: string,
+  tokenid: string,
+  over: { comment?: string; privsep?: boolean },
+): ApiTokenProps => ({
+  expire: Number(tokens.get(`access/users/${userid}/token/${tokenid}`)?.expire ?? 0),
+  privsep: over.privsep ?? false,
+  target: FAKE_TARGET,
+  tokenid,
+  userid,
+  ...(over.comment === undefined ? {} : { comment: over.comment }),
+});
+
+const token = (userid: string, tokenid: string, over: { comment?: string; privsep?: boolean }) =>
+  ProxmoxApiToken(`${userid.replace('@', '-')}-${tokenid}`, propsFor(userid, tokenid, over));
+
+const engineFor = (fake: ReturnType<typeof cluster>) =>
+  engineOver(ProxmoxApiTokenProvider().pipe(Layer.provideMerge(fake.layer)));
+
+const declared = () =>
+  Effect.all([
+    token('metrics@pve', 'exporter', {}),
+    token('iac@pve', 'apply', { comment: 'automation' }),
+    token('svc@pve', 'lease1', {}),
+    token('svc@pve', 'lease2', { comment: 'lease' }),
+  ]);
+
+describe('adopting a metadata-only ApiToken declaration', () => {
+  test('no comment, commented, and a real expire as both a number and a string: noop, adopted, no writes', async () => {
+    const fake = cluster();
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      const report = await engine.verify(declared());
+      expect(report.rows).toHaveLength(4);
+      for (const row of report.rows) {
+        expect(row).toMatchObject({ changed: [], diff: 'noop', ok: true, planned: 'adopted' });
+      }
+      const planned = await engine.deploy(declared());
+      expect(new Set(Object.values(planned))).toEqual(new Set(['adopted']));
+      expect(Object.keys(planned)).toHaveLength(4);
+    });
+    expect(fake.writes()).toEqual([]);
+  });
+
+  test('undeclaring all four sends no DELETE (retain is the default)', async () => {
+    const fake = cluster();
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      await engine.deploy(declared());
+      expect(await engine.deploy(Effect.void)).toEqual({});
+    });
+    expect(fake.writes()).toEqual([]);
+  });
+
+  test('an absent token: the deploy refuses with the mint-elsewhere message, and writes nothing', async () => {
+    const fake = cluster();
+    const gone = () =>
+      ProxmoxApiToken('gone', {
+        expire: 0,
+        privsep: false,
+        target: FAKE_TARGET,
+        tokenid: 'missing',
+        userid: 'nope@pve',
+      });
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      await expect(engine.deploy(gone())).rejects.toBeDefined();
+    });
+    expect(fake.writes()).toEqual([]);
+  });
+
+  test('a privsep flip: verify shows changed, and the deploy sends exactly one PUT of comment/expire/privsep', async () => {
+    const fake = cluster();
+    const flipped = () => token('iac@pve', 'apply', { comment: 'automation', privsep: true });
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      const report = await engine.verify(flipped());
+      expect(report.rows[0]).toMatchObject({ changed: ['privsep'], diff: 'update', ok: false });
+      expect(await engine.deploy(flipped())).toEqual({ 'iac-pve-apply': 'adopted' });
+    });
+    const put = fake.calls.find((call) => call.method === 'PUT');
+    expect(fake.writes()).toEqual(['PUT access/users/iac@pve/token/apply']);
+    expect(put?.pairs.map(([name]) => name)).toEqual(['comment', 'expire', 'privsep']);
+  });
+
+  test('the form keys typecheck against both generated PVE params, with no cast', () => {
+    const props = propsFor('iac@pve', 'apply', { comment: 'automation' });
+    const post: AccessUsersUseridTokenTokenidPostParams = shape(props);
+    const put: AccessUsersUseridTokenTokenidPutParams = shape(props);
+    expect(post).toEqual(put);
+  });
+});

package/src/proxmox/api-token-form.ts

@@ -16,6 +16,10 @@ import type { ApiTokenAttributes, ApiTokenProps } from './api-token.ts';
  *   that costs a forever-diff: the schema gives `expire` the default "same as user", and the code
  *   never implements it. api-token.ts records what that means.
  */
+import type {
+  AccessUsersUseridTokenTokenidPostParams,
+  AccessUsersUseridTokenTokenidPutParams,
+} from './generated/pve.ts';
 import type { PveSpec } from './resource.ts';
 import { bool, int, text } from './values.ts';
 
@@ -56,10 +60,23 @@ export const fullTokenid = (props: ApiTokenProps) => `${props.userid}!${props.to
  *   required prop precisely so that it is never undeclared, so there is nothing for it to do and
  *   its `string | undefined` return would have to be asserted away to fit `Record<string,string>`.
  *   An assertion here would be a claim about the prop that the type already makes properly.
+ *
+ * ★ TYPED AGAINST THE GENERATED PUT AND POST PARAMS, NOT `Record<string, string>`, since
+ *   2026-09-23 — the `notification-matcher-form.ts` pattern: `Pick` rather than the whole type,
+ *   because neither `AccessUsersUseridTokenTokenidPutParams` nor …`PostParams` (generated/pve.ts)
+ *   carries `userid`/`tokenid` (they are path segments — see the ⛔ above) and Put alone also
+ *   carries `delete`/`regenerate`, which this family never sends. A schema drift on any of the
+ *   three fields this function DOES send fails `tsc` here rather than surfacing as a 400 on a live
+ *   cluster; api-token.test.ts pins the assignment both ways (Put and Post) without a cast.
+ *   `expire` is written as a template literal, not `String(...)`, because the generated type is
+ *   `` `${number}` ``, not `string` — `String(n)` widens to plain `string` and would not typecheck.
  */
-export const shape = (props: ApiTokenProps): Record<string, string> => ({
+export const shape = (
+  props: ApiTokenProps,
+): Pick<AccessUsersUseridTokenTokenidPutParams, 'comment' | 'expire' | 'privsep'> &
+  Pick<AccessUsersUseridTokenTokenidPostParams, 'comment' | 'expire' | 'privsep'> => ({
   comment: props.comment ?? '',
-  expire: String(props.expire),
+  expire: `${props.expire}`,
   privsep: props.privsep ? '1' : '0',
 });
 

package/src/proxmox/api-token.ts

@@ -20,9 +20,14 @@
  *     whole of a token's policy, and declaring them is real work: it is how `expire` stops being
  *     whatever somebody typed in 2024. Mint NEW tokens where the secret can be caught — OpenBao's
  *     `proxmox-c1` mount, or a human at `pveum user token add`.
- *   ⚠️ THE CREATE PATH IS LEFT REACHABLE RATHER THAN STUBBED. A create that silently did nothing
- *     would be the same lie as the stubbed delete resource.ts's ★ refuses; the honest arrangement
- *     is a create that works and a header that says what it produces.
+ *   ⛔ ★ CORRECTED 2026-09-23 — THIS PARAGRAPH PREVIOUSLY SAID "THE CREATE PATH IS LEFT REACHABLE
+ *     RATHER THAN STUBBED… the honest arrangement is a create that works". THAT CONTRADICTED THE
+ *     `reconcile` BELOW, WHICH REFUSES: `handlers.reconcile` calls `Effect.die` by name when `read`
+ *     answers absent, before any POST — metadata-only per decision 9 (2026-09-23), exported on the
+ *     barrel as an adopt-and-manage-only Resource. A create that silently did nothing WOULD be the
+ *     lie resource.ts's ★ describes for a stubbed delete; refusing loudly, by name, with the two
+ *     ways to get a usable token, is the honest arrangement instead — see the ★ further down and
+ *     api-token-adopt.test.ts's absent-token row, which pins the refusal and zero writes.
  *
  * ⛔ THERE IS NO `regenerate` PROP, AND IT IS NOT AN OVERSIGHT. PVE's own description: "All users
  *   of the previous secret will lose access after this operation." A prop for it would revoke a