@homeflare/alchemy 0.47.1 → 0.48.1

package/docs/upstream-conformance-bun.md

@@ -4,7 +4,7 @@ Status: extracted from the [conformance ledger](./upstream-conformance.md); its
 measurements and open findings are preserved below.
 
 These are non-test files under `src/` that the standard (S42) says must be portable. "Exp"
-marks files exported from a subpath `index.ts`. `git grep` on `origin/main` finds 23 non-test
+marks files exported from a subpath `index.ts`. `git grep` on `origin/main` finds 24 non-test
 files under `src/` that call `Bun.*` or import `node:*`/`bun:*`. Six of them are outside
 S42's scope:
 
@@ -13,9 +13,21 @@ S42's scope:
 - `proxmox/provision-cli-fake.ts`, which is used only by tests;
 - `verify/args.ts`, which belongs to the CLI and so is tooling under S43.
 
-That leaves 17 files. The table lists them, plus `provision-cli-fake.ts`, which should move
-out of `src/`. The six out-of-scope files still ship in the tarball's `src/`, but no export
+That leaves 18 files. PR 355 brings the count on this branch to 29 by adding
+`talos/talosctl-binary.ts` and `talos/trust-boundary.ts` (both in scope below), making
+`talos/fake-process.ts` node-loading — on `origin/main` it imported only `effect/*`; here it
+imports `node:fs`, `node:path` and `node:url` — and adding `talos/fake-apiserver.ts`,
+`talos/node-connect.harness.ts` and the test seam `talos/trust-boundary.seam.ts`, three more
+Node-loaded loopback fakes that are test-side under S44 like the other fakes. With those three
+fakes and the seam, ten files on this branch are outside S42's scope, leaving 19 in scope. The
+table lists those 19, plus `provision-cli-fake.ts`, which should move out of `src/`. The
+out-of-scope files other than the seam still ship in the tarball's `src/`, but no export
 reaches them.
+⚠️ PR 355 red team re-measured 2026-10-06: `talos/credentials.ts` and
+`talos/talos-machine-config.ts` no longer call `Bun.*` or import `node:*`/`bun:*` (the temp-file
+mint moved to `talos/mint-temp-file.ts`, and `credentials.ts` reads through `resolveBao`), so
+they left the table and `talos/mint-temp-file.ts` took their row's place; `talos/credentials-write.ts`
+(always node-loaded, previously unlisted) is the +1 that had made the prose count one short.
 ⚠️ The first version of this table said 16 files and left out `launchd/job-form.ts`.
 ⚠️ Corrected 2026-09-22: 14 of the 17 break upstream's rule. `launchd/job-form.ts`,
 `proxmox/write-only.ts` and `proxmox/pbs-notification-target-wire.ts` use only synchronous
@@ -24,28 +36,46 @@ reaches them.
 among them `Fly/Secret.ts` and `Railway/Variable.ts`. They were listed under a blanket
 `node:*` ban that upstream does not have.
 
-| file                                                       | API                                          | exp | portable replacement                         |
-| ---------------------------------------------------------- | -------------------------------------------- | --- | -------------------------------------------- |
-| `openbao/cloudflare-roles-config.ts`                       | `Bun.YAML`                                   | yes | parse on the tooling side; pass data in      |
-| `openbao/digest.ts` (14 importers)                         | `Bun.CryptoHasher`                           | —   | `Crypto.digest` + hex; keep `canonical()` ⚠️ |
-| `openbao/cloudflare-parity-snapshot.ts`                    | `Bun.file`, `Bun.Glob`                       | —   | `FileSystem` + `Path`                        |
-| `openbao/approle-login-form.ts`                            | `Bun.file`                                   | —   | `FileSystem.readFileString`                  |
-| `openbao/approle-login-result.ts`                          | `Bun.inspect`                                | —   | a plain formatter                            |
-| `openbao/forgejo-bootstrap.ts`                             | `Bun.spawn`                                  | —   | unreferenced; `ChildProcessSpawner` or drop  |
-| `talos/credentials.ts`                                     | `Bun.write/file/env/randomUUIDv7`, `node:fs` | —   | `FileSystem.makeTempFileScoped`              |
-| `talos/kubeconfig.ts`                                      | `Bun.file`                                   | yes | `FileSystem`                                 |
-| `talos/talos-machine-config.ts`                            | `Bun.file`                                   | yes | `FileSystem`                                 |
-| `talos/values.ts`                                          | `Bun.YAML`, `node:crypto`                    | —   | tooling-side parse; hash may stay            |
-| `launchd/local-runner.ts`                                  | `node:child_process`, `node:fs/promises`     | yes | H3 above                                     |
-| `launchd/sudo-stage.ts`                                    | `node:fs/promises`, `node:os`, `node:path`   | —   | `FileSystem`, `Path`                         |
-| `launchd/job-form.ts`                                      | `node:crypto` (`createHash`)                 | —   | allowed in `Effect.sync`                     |
-| `linux/ssh-runner.ts`                                      | `node:child_process`, `node:crypto`          | yes | H3 above                                     |
-| `caddy/caddy-http-client.ts`                               | `node:http`, `node:stream` (unix socket)     | yes | inherent — an Effect `HttpClient`, not H3 ⚠️ |
-| `proxmox/write-only.ts`, `pbs-notification-target-wire.ts` | `node:crypto`, `node:buffer`                 | —   | allowed in `Effect.sync` ⚠️                  |
-| `proxmox/provision-cli-fake.ts`                            | `Bun.spawn`, `node:fs`                       | —   | test-only; move out of `src/`                |
+| file                                                       | API                                                       | exp | portable replacement                         |
+| ---------------------------------------------------------- | --------------------------------------------------------- | --- | -------------------------------------------- |
+| `openbao/cloudflare-roles-config.ts`                       | `Bun.YAML`                                                | yes | parse on the tooling side; pass data in      |
+| `openbao/digest.ts` (14 importers)                         | `Bun.CryptoHasher`                                        | —   | `Crypto.digest` + hex; keep `canonical()` ⚠️ |
+| `openbao/cloudflare-parity-snapshot.ts`                    | `Bun.file`, `Bun.Glob`                                    | —   | `FileSystem` + `Path`                        |
+| `openbao/approle-login-form.ts`                            | `Bun.file`                                                | —   | `FileSystem.readFileString`                  |
+| `openbao/approle-login-result.ts`                          | `Bun.inspect`                                             | —   | a plain formatter                            |
+| `openbao/forgejo-bootstrap.ts`                             | `Bun.spawn`                                               | —   | unreferenced; `ChildProcessSpawner` or drop  |
+| `talos/credentials-write.ts`                               | `node:fs/promises`, `node:crypto`, `node:os`, `node:path` | —   | `FileSystem.makeTempFileScoped`              |
+| `talos/mint-temp-file.ts`                                  | `node:fs`, `node:crypto`, `node:os`, `node:path`          | —   | `FileSystem.makeTempFileScoped`              |
+| `talos/kubeconfig.ts`                                      | `Bun.file`, `node:fs`                                     | yes | `FileSystem`                                 |
+| `talos/values.ts`                                          | `node:crypto`                                             | —   | allowed in `Effect.sync`                     |
+| `talos/talosctl-binary.ts`                                 | `node:fs`, `node:path` (binary vetting) ⚠️                | —   | recorded difference, below                   |
+| `talos/trust-boundary.ts`                                  | `node:fs` (`realpathSync`, test seam)                     | —   | recorded difference, below                   |
+| `launchd/local-runner.ts`                                  | `node:child_process`, `node:fs/promises`                  | yes | H3 above                                     |
+| `launchd/sudo-stage.ts`                                    | `node:fs/promises`, `node:os`, `node:path`                | —   | `FileSystem`, `Path`                         |
+| `launchd/job-form.ts`                                      | `node:crypto` (`createHash`)                              | —   | allowed in `Effect.sync`                     |
+| `linux/ssh-runner.ts`                                      | `node:child_process`, `node:crypto`                       | yes | H3 above                                     |
+| `caddy/caddy-http-client.ts`                               | `node:http`, `node:stream` (unix socket)                  | yes | inherent — an Effect `HttpClient`, not H3 ⚠️ |
+| `proxmox/write-only.ts`, `pbs-notification-target-wire.ts` | `node:crypto`, `node:buffer`                              | —   | allowed in `Effect.sync` ⚠️                  |
+| `proxmox/provision-cli-fake.ts`                            | `Bun.spawn`, `node:fs`                                    | —   | test-only; move out of `src/`                |
 
 The ⚠️ rows:
 
+- `talos/talosctl-binary.ts` (added 2026-10-06, hunt round 5; extracted from `talosctl.ts` in
+  round 6, where it also walks every ancestor directory): the binary vetting needs `lstat` and a
+  synchronous PATH walk. `effect/FileSystem` has `stat` (follows symlinks) and `readLink`
+  but no `lstat`, so "not a symlink" cannot be asked of it without a second probe, and the
+  Service would become a requirement of every `talosctl` caller and test (the offline fakes
+  provide only a `ChildProcessSpawner`). The published `dist/` also runs on Node, where
+  `Bun.which` is absent. The calls are synchronous, read-only, inside `Effect.try`; no
+  write, no async. Revisit when `FileSystem` gains `lstat`.
+
+- `talos/trust-boundary.ts` (added 2026-10-06 by PR 355): the same `node:fs` rationale as
+  `talos/talosctl-binary.ts`, which imports it. Its query resolves the directory with
+  `realpathSync` so the boundary compare is canonical; the call is synchronous, read-only and
+  made inside `Effect.try`. The register function lives in `talos/trust-boundary.seam.ts`
+  (test-side, excluded from the tarball), so the shipped module offers no way to stop the walk
+  early. Revisit together with `talosctl-binary.ts` when `FileSystem` gains `lstat`.
+
 - `openbao/digest.ts`: every `Bao.*` family persists this digest in state, so a swap must
   hash the same bytes (`canonical()`, lowercase hex), or every row plans an update.
   `Crypto.digest` from `effect/Crypto` is in every stack's services and fails with a typed
@@ -63,5 +93,12 @@ The ⚠️ rows:
   more-portable replacement to point to; the file already conforms to S19 (no async/await,
   no raw `Promise` — `Effect.callback`/`Effect.tryPromise` throughout).
 
-Test runners: 51 files import `node:test`/`node:assert` (openbao 42, proxmox 7, forgejo 1,
-talos 1), and 126 import `bun:test`. S43 says `bun:test`.
+Test runners: 63 files import `node:test`/`node:assert` (openbao 41, proxmox 10, forgejo 1,
+talos 11), and 395 import `bun:test`. S43 says `bun:test`.
+
+Measured 2026-10-06 from this worktree with:
+`grep -rl --include='*.ts' -e 'node:test' -e 'node:assert' src/ | wc -l` (per directory, the same
+grep scoped to `src/<area>`), and `grep -rl --include='*.ts' -e 'bun:test' src/ | wc -l`.
+
+Re-measured 2026-10-06 (PR 355 red team) — the in-scope table rows above:
+`grep -rlE --include='*.ts' "from ['\"](node|bun):|Bun\\.[A-Za-z]" src/talos/ | grep -v '\\.test\\.ts' | grep -vE 'fake-|harness|\\\\.seam\\\\.'`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.47.1",
+  "version": "0.48.1",
   "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",
@@ -18,6 +18,9 @@
     "dist",
     "docs",
     "src",
+    "!src/**/fixtures",
+    "!src/**/trust-boundary.seam.ts",
+    "!dist/**/trust-boundary.seam.*",
     "README.md",
     "LICENSE"
   ],
@@ -139,7 +142,8 @@
     "@distilled.cloud/paperless-ngx": "npm:@homeflare/distilled-paperless-ngx@0.3.1",
     "@distilled.cloud/proxmox": "npm:@homeflare/distilled-proxmox@0.3.5",
     "@distilled.cloud/proxmox-backup": "npm:@homeflare/distilled-proxmox-backup@0.3.2",
-    "@distilled.cloud/unifi-network": "npm:@homeflare/distilled-unifi-network@0.4.1"
+    "@distilled.cloud/unifi-network": "npm:@homeflare/distilled-unifi-network@0.4.1",
+    "yaml": "2.9.1"
   },
   "peerDependencies": {
     "@distilled.cloud/argocd": "1.0.0-rc.13",

package/src/talos/bao-env.ts

@@ -0,0 +1,16 @@
+/**
+ * ⛔ THE CHILD GETS A MINIMAL ENV, NOT `process.env`: `PATH` to find `bao`, the vault address and
+ *   token, and the optional namespace / CA. `undefined` when BAO_ADDR or BAO_TOKEN is missing —
+ *   `bao` would then read a cached `~/.vault-token` login and act as whoever last logged in.
+ */
+export const baoEnv = (): Record<string, string> | undefined => {
+  const addr = process.env['BAO_ADDR'];
+  const token = process.env['BAO_TOKEN'];
+  if (addr === undefined || addr === '' || token === undefined || token === '') return undefined;
+  const env: Record<string, string> = { BAO_ADDR: addr, BAO_TOKEN: token };
+  for (const name of ['PATH', 'BAO_NAMESPACE', 'BAO_CACERT']) {
+    const value = process.env[name];
+    if (value !== undefined && value !== '') env[name] = value;
+  }
+  return env;
+};

package/src/talos/bao-vetting.test.ts

@@ -0,0 +1,97 @@
+/**
+ * `bao` vetting (PR 355 red team, round 1): `bao` fetches the cluster credentials, so it must be
+ * resolved and vetted exactly like `talosctl` before any environment reaches it. A fake `bao` in a
+ * group/world-writable PATH folder (umask 002, the round-10 incident) must be refused, never
+ * launched. Fails on a084e18, where `readKvValue`/`writeKvValue` spawned a bare `bao` from PATH
+ * with no vetting.
+ */
+import { chmodSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as ChildProcessSpawner from 'effect/process/ChildProcessSpawner';
+import { readKvValue } from './credentials.ts';
+import { writeKvValue } from './credentials-write.ts';
+import { type FakeCall, fakeSpawner } from './fake-process.ts';
+
+/**
+ * Run `effect` with a fake `bao` planted in a 775 PATH folder prepended to the real PATH, capture
+ * every spawn the fake spawner saw, and restore PATH when done. Returns the failure text.
+ */
+const withFakeBaoIn775 = async (
+  effect: Effect.Effect<unknown, Error, ChildProcessSpawner.ChildProcessSpawner>,
+): Promise<{ failure: string; calls: FakeCall[]; options: unknown[] }> => {
+  const dir = mkdtempSync(join(tmpdir(), 'hf-bao-vet-'));
+  const open = join(dir, 'open');
+  mkdirSync(open);
+  writeFileSync(join(open, 'bao'), '#!/bin/sh\n', { mode: 0o755 });
+  chmodSync(join(open, 'bao'), 0o755);
+  chmodSync(open, 0o775); // group-writable, like a umask-002 checkout
+  const savedPath = process.env['PATH'];
+  process.env['PATH'] = `${realpathSync(open)}:${savedPath ?? ''}`;
+  const calls: FakeCall[] = [];
+  const options: unknown[] = [];
+  try {
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        Effect.provideService(
+          effect,
+          ChildProcessSpawner.ChildProcessSpawner,
+          ChildProcessSpawner.make((cmd) => {
+            if (cmd._tag === 'StandardCommand') options.push(cmd.options);
+            return fakeSpawner(() => ({}), calls).spawn(cmd);
+          }),
+        ),
+      ),
+    ).then((e) => String(e));
+    return { failure, calls, options };
+  } finally {
+    if (savedPath === undefined) delete process.env['PATH'];
+    else process.env['PATH'] = savedPath;
+    rmSync(dir, { force: true, recursive: true });
+  }
+};
+
+test('a fake bao in a group/world-writable PATH folder is refused before any env reaches it', async () => {
+  const { failure, calls } = await withFakeBaoIn775(
+    readKvValue('talos-c1', 'kubeconfig', ['kubeconfig', 'config']),
+  );
+  expect(failure).toContain('writable directory');
+  // ⛔ The refusal happens before the spawn, so the fake `bao` never ran and never saw an env.
+  expect(calls).toEqual([]);
+});
+
+test('writeKvValue vets bao the same way and passes a minimal env with extendEnv off', async () => {
+  const { failure, calls } = await withFakeBaoIn775(
+    writeKvValue('talos-c1', 'kubeconfig', 'kubeconfig', 'secret-body'),
+  );
+  expect(failure).toContain('writable directory');
+  expect(calls).toEqual([]);
+});
+
+test('a vetted bao gets baoEnv with extendEnv off and forceKillAfter set', async () => {
+  // Uses the committed stub `bao` (fake-process.ts), which passes vetting, and observes the spawn.
+  const options: Array<{
+    env?: Record<string, string | undefined> | undefined;
+    extendEnv?: boolean | undefined;
+    forceKillAfter?: unknown;
+  }> = [];
+  const outcome = await Effect.runPromise(
+    Effect.provideService(
+      writeKvValue('talos-c1', 'kubeconfig', 'kubeconfig', 'secret-body'),
+      ChildProcessSpawner.ChildProcessSpawner,
+      ChildProcessSpawner.make((cmd) => {
+        if (cmd._tag === 'StandardCommand') options.push(cmd.options);
+        return fakeSpawner(() => ({}), []).spawn(cmd);
+      }),
+    ),
+  );
+  expect(outcome).toBeUndefined();
+  expect(options.length).toBe(1);
+  const opts = options[0];
+  expect(opts?.extendEnv).toBe(false);
+  expect(opts?.forceKillAfter).toBeDefined();
+  expect(Object.keys(opts?.env ?? {})).toContain('BAO_ADDR');
+  expect(Object.keys(opts?.env ?? {})).toContain('BAO_TOKEN');
+});

package/src/talos/cluster-adapter-deadline.test.ts

@@ -0,0 +1,110 @@
+/**
+ * One deadline over the whole `talos-openbao` connect path, with a REAL child process: a `bao`
+ * that never exits, forks a sleeper, or ignores SIGTERM must fail connect with
+ * `TalosOpenBaoConnectTimeout` and must not outlive it. The fake `bao` is a throwaway executable
+ * in `os.tmpdir()`, removed on every exit path; PATH is the only process-global touched and is
+ * restored.
+ */
+import { chmodSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { expect, test } from 'bun:test';
+import * as NodeServices from '@effect/platform-node/NodeServices';
+import * as Duration from 'effect/Duration';
+import * as Effect from 'effect/Effect';
+import { connectTalosOpenBao, talosOpenBaoConnection } from './cluster-adapter.ts';
+import './fake-process.ts';
+
+const alive = (pid: number) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const settle = async (pid: number) => {
+  for (let i = 0; i < 40 && alive(pid); i++) await Bun.sleep(100);
+  return alive(pid);
+};
+
+const config = { c1: { context: 'admin@c1', key: 'kubeconfig', mount: 'talos-c1', uid: 'uid-c1' } };
+const BOUND = Duration.millis(1500);
+// `__DIR__` is declared at the top of each script (the child gets a minimal env, no process.env).
+const recordPid = `require('node:fs').writeFileSync(__DIR__ + '/pid', String(process.pid));\n`;
+const hang = 'setInterval(() => {}, 1000);\n';
+// The sleeper is a node child of `bao`: only a group kill reaches it.
+const forkSleeper = [
+  'const sleeper = "require(\'node:fs\').writeFileSync(" + JSON.stringify(__DIR__ + "/grandchild")',
+  '  + ", String(process.pid)); setInterval(() => {}, 1000)";',
+  "require('node:child_process').spawn(process.execPath, ['-e', sleeper], { stdio: 'ignore' });",
+  '',
+].join('\n');
+
+/**
+ * Run the production connect path against a throwaway `bao` script on PATH, with only the bound
+ * shortened. `pids` reads a pid file the script wrote, while the directory still exists.
+ */
+const connectAgainst = async (
+  script: string,
+  assert: (run: {
+    failure: { _tag: string };
+    elapsed: number;
+    pid: (name: string) => number;
+  }) => Promise<void>,
+) => {
+  const dir = mkdtempSync(join(tmpdir(), 'hf-deadline-'));
+  const saved = { path: process.env['PATH'] };
+  try {
+    const header = `#!${process.execPath}\nconst __DIR__ = ${JSON.stringify(dir)};\n`;
+    writeFileSync(join(dir, 'bao'), `${header}${script}`);
+    chmodSync(join(dir, 'bao'), 0o700);
+    process.env['PATH'] = `${dir}:${saved.path ?? ''}`;
+    const started = Date.now();
+    const failure = await Effect.runPromise(
+      connectTalosOpenBao(config, talosOpenBaoConnection('uid-c1'), BOUND).pipe(
+        Effect.flip,
+        Effect.provide(NodeServices.layer),
+      ),
+    );
+    await assert({
+      elapsed: Date.now() - started,
+      failure: failure as { _tag: string },
+      pid: (name) => Number(readFileSync(join(dir, name), 'utf8')),
+    });
+  } finally {
+    if (saved.path === undefined) delete process.env['PATH'];
+    else process.env['PATH'] = saved.path;
+    rmSync(dir, { force: true, recursive: true });
+  }
+};
+
+test('a bao that never exits fails connect with the typed timeout and the child is killed', async () => {
+  await connectAgainst(`${recordPid}${hang}`, async (run) => {
+    expect(run.failure._tag).toBe('TalosOpenBaoConnectTimeout');
+    expect(run.pid('pid')).toBeGreaterThan(0);
+    expect(await settle(run.pid('pid'))).toBe(false);
+  });
+});
+
+test('a bao that forks a sleeper leaves no grandchild alive after the timeout', async () => {
+  // ⛔ Killing only the leader (the old `detached: false`) leaves the sleeper running.
+  await connectAgainst(`${recordPid}${forkSleeper}${hang}`, async (run) => {
+    expect(run.failure._tag).toBe('TalosOpenBaoConnectTimeout');
+    await Bun.sleep(300);
+    const grandchild = run.pid('grandchild');
+    expect(grandchild).toBeGreaterThan(0);
+    expect(await settle(grandchild)).toBe(false);
+    expect(await settle(run.pid('pid'))).toBe(false);
+  });
+});
+
+test('a bao that ignores SIGTERM still fails connect within the deadline plus ~2 s', async () => {
+  // ⛔ Without `forceKillAfter` the finalizer waits on a leader that never exits.
+  await connectAgainst(`${recordPid}process.on('SIGTERM', () => {});\n${hang}`, async (run) => {
+    expect(run.failure._tag).toBe('TalosOpenBaoConnectTimeout');
+    expect(run.elapsed).toBeLessThan(1500 + 2500);
+    expect(await settle(run.pid('pid'))).toBe(false);
+  });
+});

package/src/talos/cluster-adapter-errors.ts

@@ -0,0 +1,193 @@
+/**
+ * Typed failures of the `talos-openbao` adapter — split out of cluster-adapter.ts to keep each
+ * class's own header out of that file's 250-line budget. No message names document bytes.
+ */
+import * as Data from 'effect/Data';
+
+/** The connection's uid matches no adapter entry. Uids are public. */
+export class TalosOpenBaoUnknownCluster extends Data.TaggedError('TalosOpenBaoUnknownCluster')<{
+  readonly uid: string;
+  readonly known: readonly string[];
+}> {
+  override get message(): string {
+    return (
+      `talos-openbao adapter has no entry pinned to cluster uid ${this.uid} ` +
+      `(configured uids: ${this.known.join(', ') || 'none'}). Refused rather than reading ` +
+      "another cluster's kubeconfig. If the cluster was retired, keep its entry with " +
+      '`retired: true` and its uid until its rows are destroyed.'
+    );
+  }
+}
+
+/** Two adapter entries pin the same uid, so which vault key to read is ambiguous. */
+export class TalosOpenBaoAmbiguousUid extends Data.TaggedError('TalosOpenBaoAmbiguousUid')<{
+  readonly uid: string;
+  readonly aliases: readonly string[];
+}> {
+  override get message(): string {
+    return (
+      `talos-openbao adapter entries ${this.aliases.join(', ')} are all pinned to uid ` +
+      `${this.uid}. Refused instead of picking one: a uid names exactly one entry.`
+    );
+  }
+}
+
+/** The saved auth block still carries the alias an earlier build of this branch persisted. */
+export class TalosOpenBaoLegacyAuth extends Data.TaggedError('TalosOpenBaoLegacyAuth')<{
+  readonly _?: never;
+}> {
+  override get message(): string {
+    return (
+      'talos-openbao connection carries a legacy `cluster` alias in its auth block. Refused ' +
+      'before any vault read or request, with no silent migration (old and new auth differ, so ' +
+      'upstream would PATCH then DELETE the same object). Remedy: edit the saved state ONCE so ' +
+      "each such row's `connection.auth` is `{ kind: 'talos-openbao', uid }` (drop `cluster`), " +
+      'then redeploy.'
+    );
+  }
+}
+
+/** `Talos.ClusterIdentity` read a different uid than the one it published. Never an update. */
+export class TalosClusterMoved extends Data.TaggedError('TalosClusterMoved')<{
+  readonly cluster: string;
+  readonly saved: string;
+  readonly live: string;
+}> {
+  override get message(): string {
+    return (
+      `Talos.ClusterIdentity '${this.cluster}' published uid ${this.saved} but the vault key now ` +
+      `answers as ${this.live}. Refused, not updated: an update cannot become a replace for the ` +
+      'workloads downstream, so the new cluster would be force-applied and the old one orphaned. ' +
+      'A move is explicit: declare a NEW Talos.ClusterIdentity for the new cluster and leave this ' +
+      'one pointing at the old cluster until its workloads are destroyed.'
+    );
+  }
+}
+
+/** `bao kv get` reported the key unwritten. The message names `mount/key` and no document bytes. */
+export class TalosVaultKeyMissing extends Data.TaggedError('TalosVaultKeyMissing')<{
+  readonly mount: string;
+  readonly key: string;
+}> {
+  override get message(): string {
+    return (
+      `${this.mount}/${this.key}: OpenBao has no value at this key. Talos.Kubeconfig writes it ` +
+      'once at bring-up. Connect refused instead of reading a kubeconfig from disk.'
+    );
+  }
+}
+
+/** Vault bytes exist but are not a kubeconfig for the pinned context. The document is not echoed. */
+export class TalosKubeconfigUnreadable extends Data.TaggedError('TalosKubeconfigUnreadable')<{
+  readonly mount: string;
+  readonly key: string;
+  readonly context: string;
+}> {
+  override get message(): string {
+    return (
+      `${this.mount}/${this.key}: OpenBao kubeconfig does not parse for context ${this.context}. ` +
+      'The document stayed in the vault. Connect wrote nothing to disk and nothing to state.'
+    );
+  }
+}
+
+/** The layer was asked to connect a different auth kind. */
+export class TalosOpenBaoAuthKind extends Data.TaggedError('TalosOpenBaoAuthKind')<{
+  readonly kind: string;
+}> {
+  override get message(): string {
+    return (
+      `talos-openbao adapter received auth kind '${this.kind}'. This adapter only connects ` +
+      '`talos-openbao`.'
+    );
+  }
+}
+
+/** The saved auth block carries no `uid`, so nothing says WHICH physical cluster it meant. */
+export class TalosClusterIdentityMissing extends Data.TaggedError('TalosClusterIdentityMissing')<{
+  readonly _?: never;
+}> {
+  override get message(): string {
+    return (
+      'talos-openbao connection carries no uid, so it cannot say which physical cluster it ' +
+      'targets. Refused before any vault read or request: pin the uid ' +
+      'printed by `Talos.ClusterIdentity` as a literal in `TalosOpenBaoAdapter` and build ' +
+      'workloads from `talosOpenBaoConnection(<that literal>)`.'
+    );
+  }
+}
+
+/** The cluster that answered is not the one the saved auth block named. Uids are public. */
+export class TalosClusterIdentityMismatch extends Data.TaggedError('TalosClusterIdentityMismatch')<{
+  readonly cluster: string;
+  readonly expected: string;
+  readonly got: string;
+}> {
+  override get message(): string {
+    return (
+      `talos-openbao cluster '${this.cluster}' answered as kube-system uid ${this.got}, but the ` +
+      `saved connection expects ${this.expected}. Refused before any apply or delete: the name ` +
+      'now resolves to a different physical cluster. If the original cluster is gone for good, ' +
+      'remove its rows from state deliberately.'
+    );
+  }
+}
+
+/** `GET /api/v1/namespaces/kube-system` answered without a usable `metadata.uid`. */
+export class TalosClusterIdentityUnreadable extends Data.TaggedError(
+  'TalosClusterIdentityUnreadable',
+)<{
+  readonly cluster: string;
+}> {
+  override get message(): string {
+    return (
+      `talos-openbao cluster '${this.cluster}': kube-system has no readable metadata.uid. ` +
+      'Refused rather than assuming the cluster is the expected one.'
+    );
+  }
+}
+
+/** The kube-system GET got no answer in time: a silent apiserver must not hang connect or plan. */
+export class TalosClusterIdentityTimeout extends Data.TaggedError('TalosClusterIdentityTimeout')<{
+  readonly cluster: string;
+  readonly seconds: number;
+}> {
+  override get message(): string {
+    return (
+      `talos-openbao cluster '${this.cluster}': no answer to the kube-system uid read within ` +
+      `${this.seconds}s (the identity read's own deadline, inside the 10 s connect deadline). ` +
+      'Refused (failed closed) rather than waiting on a silent apiserver.'
+    );
+  }
+}
+
+/**
+ * The whole connect path (vault read, parse, kube-system uid read) did not finish in time. One
+ * deadline covers `bao` and the apiserver together: a hung `bao` or a silent apiserver must not
+ * hang connect or a plan. The `bao` child is killed when the deadline interrupts the read.
+ */
+export class TalosOpenBaoConnectTimeout extends Data.TaggedError('TalosOpenBaoConnectTimeout')<{
+  readonly cluster: string;
+  readonly seconds: number;
+}> {
+  override get message(): string {
+    return (
+      `talos-openbao cluster '${this.cluster}': vault read and identity check did not finish ` +
+      `within ${this.seconds}s. Refused (failed closed); the bao child was killed.`
+    );
+  }
+}
+
+/** A connection was built from a uid that is not a plain string known at plan time. */
+export class TalosUidNotLiteral extends Data.TaggedError('TalosUidNotLiteral')<{
+  readonly _?: never;
+}> {
+  override get message(): string {
+    return (
+      'talos-openbao connection uid must be a literal string taken from the adapter config, not ' +
+      'an Output (for example a Talos.ClusterIdentity attribute). An unresolved uid hides a ' +
+      "cluster change from the plan: upstream would plan an UPDATE and reconcile the old cluster's " +
+      'objects on the new one. Pin the uid in `TalosOpenBaoAdapter` and take it from there.'
+    );
+  }
+}