@homeflare/alchemy 0.20.0 → 0.22.0

package/src/launchd/local-runner.ts

@@ -130,7 +130,9 @@ export const localRunner = (options: LocalRunnerOptions = {}): HostRunner => {
       try {
         const stats = await lstat(path);
         return {
+          dev: stats.dev,
           gid: stats.gid,
+          ino: stats.ino,
           kind: kindOf(stats),
           mode: stats.mode & 0o7777,
           size: stats.size,

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/launchd/runner.ts

@@ -33,10 +33,23 @@ export type FileStat = {
   readonly uid: number;
   readonly gid: number;
   readonly size: number;
+  /**
+   * The entry's identity, device and inode, when the runner can say. ★ Two spellings of ONE file
+   *   (`/tmp/x` and `/private/tmp/x`; `Bin` and `bin` on case-insensitive APFS) differ as strings
+   *   and match here, and a move must not delete its old path when that path IS the new file
+   *   (file-identity.ts). Optional: a runner that leaves them out gets a check after the fact.
+   */
+  readonly dev?: number;
+  readonly ino?: number;
 };
 
 export type WriteOptions = {
-  /** Permission bits for the final file, applied BEFORE it becomes visible at `path`. */
+  /**
+   * Permission bits for the final file. localRunner applies them BEFORE the file is visible at
+   * `path`. ⚠️ sudoRunner's `install -S` does NOT: MEASURED 2026-09-22 on macOS 27.2 (an lstat
+   *   poller racing /usr/bin/install), the new inode appears at `path` as 0600 and is chmodded
+   *   0.2–0.4 ms later. Never torn, never wider than declared, but briefly not executable.
+   */
   readonly mode: number;
   /** Numeric owner; omitted means whoever the runner writes as. */
   readonly uid?: number;
@@ -69,7 +82,9 @@ export interface HostRunner {
   stat(path: string): Promise<FileStat | undefined>;
   /**
    * Write `bytes` so that `path` holds either the old file or the new one, never a torn mix:
-   * a temporary file in the same directory, mode and owner set on it, then rename(2) over `path`.
+   * a temporary file in the same directory, mode and owner set on it, then rename(2) over `path`
+   * (sudoRunner: the mode just after the rename, measured — see WriteOptions.mode; the owner too,
+   * ⚠️ REASONED NOT MEASURED, since measuring it needs root).
    * ⚠️ The parent directory must exist; creating it would invent an owner and mode nobody declared.
    */
   writeFileAtomic(path: string, bytes: Uint8Array, options: WriteOptions): Promise<void>;

package/src/launchd/sudo-runner.ts

@@ -21,6 +21,17 @@
  * ★ `install -S`: install(1) on macOS 27.2 (read 2026-09-21) always writes a temp file in the
  *   target directory and renames it, so the file is never torn, and -S adds the fsync that
  *   localRunner's `handle.sync()` does.
+ * ⚠️ BUT IT CHMODS AFTER THE RENAME. MEASURED 2026-09-22 (an lstat poller racing
+ *   `/usr/bin/install -S -m 0755`, 300 MB, six runs, target absent and present): the new inode
+ *   is visible at the path as 0600, then 0755 0.2–0.4 ms later. Only ever narrower than declared.
+ *   ⚠️ REASONED NOT MEASURED: a launchd start inside that window gets EACCES and retries after its
+ *   throttle, and an install killed inside it leaves a root-owned 0600 file the operator cannot
+ *   read back. Closing it needs a second privileged step (install to a temp name, then rename),
+ *   which is a change to this allowlist and wants its own red team.
+ * ⚠️ AND IT COPIES XATTRS, com.apple.quarantine included (MEASURED 2026-09-22: a quarantined
+ *   source installed as a quarantined target). The staged file is written by this process, and
+ *   node:fs writes here carried only com.apple.provenance (measured the same day) — so nothing
+ *   is quarantined today, but a quarantined staging file would be installed quarantined.
  * ⚠️ REASONED, NOT MEASURED: sudo's failure text (sudo-said.ts has the strings and their sources).
  * ⛔ EVERY CHECK BEFORE SUDO ALSO RUNS AT PLAN TIME (`checkWrite`, 2026-09-21): the mode, the
  *   directories from the prefix down, the read-back. Reads only, as the operator — never sudo.

package/src/linux/sudo-listing.ts

@@ -0,0 +1,122 @@
+/**
+ * ONE READ OF `ls -ldn --` FOR A WHOLE LIST OF PATHS, parsed into the same FileStat the seam uses
+ * plus the one thing `stat` cannot say on Linux: whether the path carries a POSIX ACL.
+ *
+ * ★ WHY `ls` AND NOT `stat`, AND WHY ONE CALL. The Mac guard lstats every directory from `/` down
+ *   with a local syscall each; over ssh each of those is a TCP connection with no multiplexing
+ *   (ssh-runner.ts), so a five-deep chain would be five handshakes per check and per plan. `ls -ldn`
+ *   takes every path as an operand and answers in one connection, and its mode column carries the
+ *   ACL flag the chain check needs anyway.
+ * ★ MEASURED 2026-09-22, read-only over ssh, on two host classes — an unprivileged LXC container
+ *   and a Proxmox VE node, both Debian 13 / coreutils 9.7, LANG=C, ssh user uid 1001 and 1000:
+ *     $ ls -ldn / /etc /etc/systemd /etc/systemd/system /usr /usr/lib /usr/lib/systemd …
+ *       drwxr-xr-x 18 0 0 4096 Sep 22 10:12 /etc          (all ten root:root 0755, no flag)
+ *     $ ls -ld /var/log/journal
+ *       drwxr-sr-x+ 3 root systemd-journal …              (the `+` IS the POSIX ACL flag here)
+ *     $ ls -lden …  →  ls: invalid option -- 'e'          (the Mac's spelling does not exist)
+ *     $ command -v getfacl  →  absent on both Debian classes (present on the NixOS class)
+ *   ⛔ SO THE ACL SIGNAL IS THE `+` FLAG, NOT `getfacl`: the tool that would enumerate the entries
+ *     is not installed on the hosts this runner is for, and a guard that shells out to a missing
+ *     program and fails closed would refuse every write on them. `ls` is coreutils, always there.
+ *   ⚠️ THE PRICE, STATED: we learn THAT a directory has an ACL, never WHAT it grants, so any ACL on
+ *     the chain is a refusal — including a read-only one the Mac guard would allow. Fail closed and
+ *     say so; the remedy is a prefix without one.
+ * ⚠️ `.` in that column is an SELinux context, not an ACL, and is not a grant. `@` is macOS's.
+ * ⛔ FAIL CLOSED ON ANYTHING WE DO NOT UNDERSTAND. A line that does not parse, a path that no line
+ *   named, two lines for one path, or a non-zero exit is an error — never "nothing is there".
+ */
+import type { FileStat, HostRunner } from '../launchd/runner.ts';
+import { SudoRefusedError } from '../launchd/sudo-allowlist.ts';
+
+/** What one `ls -ldn` line says: the lstat fields, plus whether the path carries an ACL. */
+export type Listed = FileStat & { readonly acl: boolean };
+
+const KINDS = new Map<string, FileStat['kind']>([
+  ['-', 'file'],
+  ['d', 'directory'],
+  ['l', 'symlink'],
+]);
+
+/**
+ * `rwxr-x---` → 0o750, with the three special bits `ls` hides in the execute columns:
+ * `s`/`S` = setuid (user) or setgid (group), `t`/`T` = sticky; the capital is the bit without
+ * execute. ⚠️ Anything else in a column is a shape we do not know, and returns undefined.
+ */
+export const permBits = (perms: string): number | undefined => {
+  if (perms.length !== 9) return undefined;
+  let mode = 0;
+  for (const index of [0, 1, 2]) {
+    const at = index * 3;
+    const shift = 6 - at;
+    const [read, write, exec] = [perms[at], perms[at + 1], perms[at + 2]];
+    if ((read !== 'r' && read !== '-') || (write !== 'w' && write !== '-')) return undefined;
+    if (read === 'r') mode |= 0o4 << shift;
+    if (write === 'w') mode |= 0o2 << shift;
+    const [set, unset] = index === 2 ? ['t', 'T'] : ['s', 'S'];
+    if (exec === 'x' || exec === set) mode |= 0o1 << shift;
+    else if (exec !== '-' && exec !== unset) return undefined;
+    if (exec === set || exec === unset) mode |= 0o4000 >> index;
+  }
+  return mode;
+};
+
+/** `drwxr-xr-x+ 4 0 0 4096 Sep 22 10:12 /etc/systemd` — the tail holds the date and the name. */
+const LINE = /^([-dlbcps])(\S{9})([+.@]?)\s+\d+\s+(\d+)\s+(\d+)\s+(\d+)\s+(.*)$/;
+
+/**
+ * Match each line to the path that asked for it, by NAME rather than by position.
+ * ⚠️ `ls` SORTS ITS OPERANDS, so the answers do not come back in the order they were asked; and a
+ *   symlink's line ends `<path> -> <target>`, so it is not a suffix match either. The longest
+ *   candidate wins, so a path that is a tail of another cannot steal its line.
+ */
+const nameOf = (tail: string, paths: readonly string[]): string | undefined =>
+  [...paths]
+    .sort((left, right) => right.length - left.length)
+    .find((path) => tail.endsWith(` ${path}`) || tail.includes(` ${path} -> `));
+
+/** Every requested path's entry, or `undefined` when the listing is not exactly that. */
+export const parseListing = (
+  stdout: string,
+  paths: readonly string[],
+): Map<string, Listed> | undefined => {
+  const entries = new Map<string, Listed>();
+  for (const line of stdout.split('\n').filter((text) => text.trim() !== '')) {
+    const match = LINE.exec(line);
+    if (match === null) return undefined;
+    const [, type, perms, flag, uid, gid, size, tail] = match;
+    const mode = permBits(perms ?? '');
+    const path = nameOf(tail ?? '', paths);
+    if (mode === undefined || path === undefined || entries.has(path)) return undefined;
+    entries.set(path, {
+      acl: flag === '+',
+      gid: Number(gid),
+      kind: KINDS.get(type ?? '') ?? 'other',
+      mode,
+      size: Number(size),
+      uid: Number(uid),
+    });
+  }
+  return entries.size === paths.length ? entries : undefined;
+};
+
+/**
+ * Read every path in one call, as the deploying user — no sudo, the same read at plan time and
+ * before the write. ⛔ Anything but a complete, understood listing is a SudoRefusedError: a chain
+ *   we could not read is a chain we cannot say is root's alone.
+ */
+export const readListing = async (
+  base: HostRunner,
+  ls: string,
+  what: string,
+  paths: readonly string[],
+): Promise<Map<string, Listed>> => {
+  const result = await base.exec([ls, '-ldn', '--', ...paths]);
+  const entries = result.exitCode === 0 ? parseListing(result.stdout, paths) : undefined;
+  if (entries === undefined) {
+    throw new SudoRefusedError(
+      `sudoRunner ${what}: could not read ${paths.join(', ')} (${ls} -ldn exit ` +
+        `${String(result.exitCode)}: ${result.stderr.trim().slice(0, 200)}). Nothing ran as root.`,
+    );
+  }
+  return entries;
+};

package/src/proxmox/credential-literals.ts

@@ -23,7 +23,7 @@
  *   it from the template. docs/pbs-notifications.md says the same to the reader.
  * ⛔ A REFUSAL NAMES THE FIELD, NEVER THE VALUE — the message lands in a terminal and a CI log.
  */
-import type { FromEnv } from './write-only.ts';
+import type { FromEnv } from '../secrets/write-only.ts';
 
 /** `{{ secrets.x }}`, `{{secrets.x}}`, `{{ url-encode secrets.x }}` — a reference, not a value. */
 const READS_SECRET = /\{\{[^}]*\bsecrets\./;

package/src/proxmox/generated/pbs/nodes-node.ts

@@ -241,4 +241,4 @@ export type NodesNodeDisksZfsPostParams = {
 export type NodesNodeDisksZfsPostReturn = string;
 
 /** GET /nodes/{node}/disks/zfs/{name} — `data` payload after client unwrap. */
-export type NodesNodeDisksZfsNameGetReturn = {};
+export type NodesNodeDisksZfsNameGetReturn = Record<string, unknown>;

package/src/proxmox/generated/pbs.ts

@@ -13,6 +13,13 @@
  * ⚠️ 151 request parameters are typed `\`${number}\`` because the vendor calls them
  *   integer or number. They were `string` before, which accepted 'banana'. A caller holding a
  *   number writes \`${n}\` — `String(n)` is a plain `string` and will not typecheck, deliberately.
+ *
+ * ⛔ 135 OF THESE NAMES ARE ALSO EXPORTED BY `pve.ts`, MEANING SOMETHING ELSE. Both
+ *   products document a `/nodes/{node}` subtree, so a name like `NodesNodeCertificatesGetReturn`
+ *   exists on each side — here an array of objects, there `null`. Nothing stops a pve call
+ *   importing the pbs spelling: it compiles, and the type is simply wrong about the payload.
+ *   Import from the barrel that names your product. tests/schema-types.test.ts pins this count, so
+ *   a vendor upgrade that adds a collision fails there rather than at runtime.
  */
 export * from './pbs/access.ts';
 export * from './pbs/access-users.ts';

package/src/proxmox/generated/pve.ts

@@ -13,6 +13,13 @@
  * ⚠️ 480 request parameters are typed `\`${number}\`` because the vendor calls them
  *   integer or number. They were `string` before, which accepted 'banana'. A caller holding a
  *   number writes \`${n}\` — `String(n)` is a plain `string` and will not typecheck, deliberately.
+ *
+ * ⛔ 135 OF THESE NAMES ARE ALSO EXPORTED BY `pbs.ts`, MEANING SOMETHING ELSE. Both
+ *   products document a `/nodes/{node}` subtree, so a name like `NodesNodeCertificatesGetReturn`
+ *   exists on each side — here an array of objects, there `null`. Nothing stops a pbs call
+ *   importing the pve spelling: it compiles, and the type is simply wrong about the payload.
+ *   Import from the barrel that names your product. tests/schema-types.test.ts pins this count, so
+ *   a vendor upgrade that adds a collision fails there rather than at runtime.
  */
 export * from './pve/access.ts';
 export * from './pve/access-roles.ts';

package/src/proxmox/index.ts

@@ -104,5 +104,5 @@ export { ProxmoxSdnVnet, ProxmoxSdnVnetProvider } from './sdn-vnet.ts';
 export { ProxmoxSdnZone, ProxmoxSdnZoneProvider } from './sdn-zone.ts';
 export { ProxmoxStorage, ProxmoxStorageProvider } from './storage.ts';
 export { ProxmoxUser, ProxmoxUserProvider } from './user.ts';
-export { type FromEnv } from './write-only.ts';
+export { type FromEnv } from '../secrets/write-only.ts';
 export { ProxmoxZfsPoolProvider } from './zfs-pool.ts';

package/src/proxmox/pbs-notification-target-form.ts

@@ -25,7 +25,7 @@ import type {
   PbsNotificationTargetProps,
 } from './pbs-notification-target.ts';
 import { base64, headerDigest, names, wireItem } from './pbs-notification-target-wire.ts';
-import { type Environment, type FromEnv, resolveAll, sealMatches } from './write-only.ts';
+import { type Environment, type FromEnv, resolveAll, sealMatches } from '../secrets/write-only.ts';
 
 type Props = PbsNotificationTargetProps;
 type Field = keyof Props;

package/src/proxmox/pbs-notification-target-lifecycle.ts

@@ -32,7 +32,7 @@ import {
   targetForm,
 } from './pbs-notification-target-form.ts';
 import { targetAttributes } from './pbs-notification-target-wire.ts';
-import { seal } from './write-only.ts';
+import { seal } from '../secrets/write-only.ts';
 
 type Props = PbsNotificationTargetProps;
 type Attributes = PbsNotificationTargetAttributes;

package/src/proxmox/pbs-notification-target-wire.ts

@@ -23,7 +23,7 @@ import type {
   PbsNotificationTargetProps,
 } from './pbs-notification-target.ts';
 import { bool, text } from './values.ts';
-import { seal } from './write-only.ts';
+import { seal } from '../secrets/write-only.ts';
 
 export const base64 = (value: string): string => Buffer.from(value, 'utf8').toString('base64');
 

package/src/proxmox/pbs-notification-target.ts

@@ -31,7 +31,7 @@ import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
 import { handlers } from './pbs-notification-target-lifecycle.ts';
 import type { PveRequirements, WithPbsTarget } from './resource.ts';
-import type { FromEnv } from './write-only.ts';
+import type { FromEnv } from '../secrets/write-only.ts';
 
 export type PbsNotificationTargetType = 'sendmail' | 'smtp' | 'webhook';
 

package/src/release/adopt-parity.test.ts

@@ -0,0 +1,106 @@
+/**
+ * Adoption through Alchemy's OWN Plan and Apply (openbao/fake-stack.ts): a file already at the path,
+ * and a stack holding no state for it. What binary-claim.ts decides, measured end to end — the plan
+ * and the apply must give the same answer, and `adopted` must never stand for other bytes.
+ *
+ * 🔴 EVERY REFUSAL BELOW WAS A SILENT WRITE OR LOSS BEFORE 2026-09-22 (adversarial review of PR 138,
+ *   lens: adoption and plan parity), each measured with this harness against the code before the
+ *   fix: other bytes under `--adopt` planned `adopted` (resolved) or `create` (directory an Output)
+ *   and were downloaded over in place; a symlink planned `adopted` and was refused only at apply;
+ *   a renamed declaration claimed the identical file at apply and its old name's delete removed it.
+ */
+import { describe, expect, test } from 'bun:test';
+import { BINARY } from './fake-release.ts';
+import { DIR, PATH, THEIRS, deployHarness as harness } from './fake-deploy.ts';
+
+describe('a file already at the path, with no state', () => {
+  test('OTHER bytes under --adopt, probed: the plan refuses; nothing fetched, their file kept', async () => {
+    const h = harness(true);
+    h.place(THEIRS);
+    await expect(h.stack.deploy(h.literal, { adopt: true })).rejects.toThrow(
+      '--adopt takes over only the pinned binary',
+    );
+    expect(h.events).toEqual([]);
+    expect(h.fake.files.get(PATH)?.bytes).toEqual(THEIRS);
+  });
+
+  test('OTHER bytes under --adopt, the directory an Output: refused at apply, before the download', async () => {
+    const h = harness(true);
+    h.place(THEIRS);
+    await expect(h.stack.deploy(h.wired(), { adopt: true })).rejects.toThrow(
+      '--adopt takes over only the pinned binary',
+    );
+    expect(h.events.filter((e) => e.startsWith('GET ') || e.startsWith('write '))).toEqual([]);
+    expect(h.fake.files.get(PATH)?.bytes).toEqual(THEIRS);
+  });
+
+  test('a symlink under --adopt: refused by the PLAN, not first by the apply', async () => {
+    const h = harness(true);
+    h.place(new Uint8Array(), 0o755, 'symlink');
+    // ★ The plan-side wording; the apply's own would be "is a symlink".
+    await expect(h.stack.deploy(h.literal, { adopt: true })).rejects.toThrow(
+      'something that is not a regular file',
+    );
+    expect(h.events).toEqual([]);
+  });
+
+  test('the pinned bytes with a wrong mode, under --adopt: adopted, re-written from disk, never fetched', async () => {
+    const h = harness(true);
+    h.place(BINARY.vmalert, 0o775);
+    expect(await h.stack.deploy(h.literal, { adopt: true })).toEqual({ vmalert: 'adopted' });
+    expect(h.events).toEqual([`write ${PATH}`]);
+    expect(h.fake.files.get(PATH)?.mode).toBe(0o755);
+  });
+
+  test('the pinned bytes, the directory an Output, under --adopt: kept, never fetched', async () => {
+    const h = harness(true);
+    h.place(BINARY.vmalert);
+    const planned = await h.stack.deploy(h.wired(), { adopt: true });
+    expect(planned).toEqual({ dir: 'adopted', vmalert: 'create' });
+    expect(h.events).toEqual([]);
+    expect(h.fake.files.get(PATH)?.bytes).toEqual(BINARY.vmalert);
+  });
+
+  test('a renamed declaration while its directory changes: refused at apply, the binary kept', async () => {
+    const h = harness(false);
+    await h.stack.deploy(h.wired('vmalert'));
+    h.events.length = 0;
+    // The directory's mode change leaves `dir.path` an Output at plan, so nothing probes the path.
+    await expect(h.stack.deploy(h.wired('vmalert-rules', 0o750))).rejects.toThrow(
+      'it holds the pinned binary, but this stack holds no state for it',
+    );
+    // 🔴 Before: planned {dir: update, vmalert-rules: create, vmalert: delete}; the new name took
+    //   the identical file as its own, the old name's delete removed it, and the deploy succeeded.
+    expect(h.events).not.toContain(`remove ${PATH}`);
+    expect(h.fake.files.get(PATH)?.bytes).toEqual(BINARY.vmalert);
+  });
+
+  test('the same rename declared with renamedFrom (the remedy the refusal names): the binary kept', async () => {
+    const h = harness(false);
+    await h.stack.deploy(h.wired('vmalert'));
+    h.events.length = 0;
+    const planned = await h.stack.deploy(h.wired('vmalert-rules', 0o750, 'vmalert'));
+    expect(planned).toEqual({ dir: 'update', 'vmalert-rules': 'update' });
+    expect(h.events).toEqual([`chmod 750 ${DIR}`]);
+    expect(h.fake.files.get(PATH)?.bytes).toEqual(BINARY.vmalert);
+  });
+
+  test('the same rename under --adopt: the new name takes the file, the old name leaves it', async () => {
+    const h = harness(false);
+    await h.stack.deploy(h.wired('vmalert'));
+    h.events.length = 0;
+    const planned = await h.stack.deploy(h.wired('vmalert-rules', 0o750), { adopt: true });
+    expect(planned).toEqual({ dir: 'update', vmalert: 'delete', 'vmalert-rules': 'create' });
+    // 🔴 Before 2026-09-22 (release gate): the old name's orphan delete ran `remove ${PATH}` after
+    //   the new name had claimed it, and the deploy succeeded with the binary gone.
+    expect(h.events).toEqual([`chmod 750 ${DIR}`]);
+    expect(h.fake.files.get(PATH)?.bytes).toEqual(BINARY.vmalert);
+    // The new name owns it now: the next deploy of the same declaration changes nothing.
+    h.events.length = 0;
+    expect(await h.stack.deploy(h.wired('vmalert-rules', 0o750))).toEqual({
+      dir: 'noop',
+      'vmalert-rules': 'noop',
+    });
+    expect(h.events).toEqual([]);
+  });
+});