@homeflare/alchemy 0.47.0 → 0.48.0

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

@@ -0,0 +1,192 @@
+/**
+ * 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. 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.'
+    );
+  }
+}

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

@@ -0,0 +1,129 @@
+/**
+ * Round-2 findings, each THROUGH the real engine or providers with the fake `bao` and fake
+ * apiserver: (1) a workload moved between two PINNED literal uids plans a replace and never
+ * reconciles the old cluster's objects on the new one, and an Output uid is refused at declare
+ * time; (2) `Drift.repair` cannot launder a moved `Talos.ClusterIdentity`; (3) a silent apiserver
+ * fails closed with a typed timeout instead of hanging connect.
+ */
+import { expect, test } from 'bun:test';
+import { Manifest } from 'alchemy/Kubernetes/Manifest';
+import * as Output from 'alchemy/Output';
+import * as Duration from 'effect/Duration';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as ChildProcessSpawner from 'effect/process/ChildProcessSpawner';
+import { engineOver } from '../verify/fake-engine.ts';
+import { connectTalosOpenBao, talosOpenBaoConnection } from './cluster-adapter.ts';
+import { UIDS, config, failure, providerLayer, vault } from './cluster-adapter.fixtures.ts';
+import { readClusterUid } from './cluster-identity.ts';
+import { openTransport } from './cluster-transport.ts';
+import { fakeApiServer } from './fake-apiserver.ts';
+import { fakeSpawner } from './fake-process.ts';
+import { TalosClusterIdentity, TalosClusterIdentityProvider } from './talos-cluster-identity.ts';
+
+const namespace = (uid: string) =>
+  Manifest('ns', {
+    cluster: talosOpenBaoConnection(uid),
+    manifest: { apiVersion: 'v1', kind: 'Namespace', metadata: { name: 'ns-shared' } },
+  });
+const declare = (uid: string) =>
+  Effect.gen(function* () {
+    yield* namespace(uid);
+  });
+const spawner = Layer.succeed(ChildProcessSpawner.ChildProcessSpawner, fakeSpawner(vault));
+
+test('a workload moved between two pinned uids is a replace; the old objects are never deleted on the new cluster', async () => {
+  const api = fakeApiServer(UIDS);
+  try {
+    const engine = engineOver(providerLayer(config));
+    expect((await engine.deploy(declare('uid-c1')))['ns']).toBe('create');
+    api.seen.length = 0;
+    expect((await engine.deploy(declare('uid-c2')))['ns']).toBe('replace');
+    const onC1 = api.seen.filter((call) => call.includes('c1.cluster.invalid'));
+    const deletesOnC2 = api.seen.filter(
+      (call) => call.startsWith('DELETE ') && call.includes('c2.cluster.invalid'),
+    );
+    // The new cluster is created on; the replaced generation is cleaned up on the OLD one.
+    expect(api.seen.some((call) => call.startsWith('PATCH c2.cluster.invalid'))).toBe(true);
+    expect(onC1.some((call) => call.startsWith('DELETE '))).toBe(true);
+    expect(deletesOnC2).toEqual([]);
+  } finally {
+    api.restore();
+  }
+});
+
+test('an Output uid is refused when the connection is declared', () => {
+  const output = Output.literal('uid-c1') as unknown as string;
+  expect(() => talosOpenBaoConnection(output)).toThrow('literal string');
+});
+
+test('Drift.repair on a moved Talos.ClusterIdentity fails with TalosClusterMoved and keeps the saved uid', async () => {
+  const stack = Effect.gen(function* () {
+    yield* TalosClusterIdentity('c1', {
+      context: 'admin@c1',
+      target: { cluster: 'c1', mount: 'talos-c1' },
+    });
+  });
+  const engine = engineOver(Layer.mergeAll(TalosClusterIdentityProvider(), spawner));
+  const first = fakeApiServer({ 'c1.cluster.invalid': 'uid-c1' });
+  try {
+    await engine.deploy(stack);
+  } finally {
+    first.restore();
+  }
+  const moved = fakeApiServer({ 'c1.cluster.invalid': 'uid-c2' });
+  try {
+    const repaired = await engine.repair(stack).then(
+      (rows) => JSON.stringify(rows),
+      (error: unknown) => String(error),
+    );
+    expect(repaired).not.toContain('"repaired"');
+    expect(engine.stored()).toContain('uid-c1');
+    expect(engine.stored()).not.toContain('uid-c2');
+  } finally {
+    moved.restore();
+  }
+});
+
+test('a silent apiserver fails closed with TalosClusterIdentityTimeout', async () => {
+  const api = fakeApiServer(UIDS, ['c1.cluster.invalid']);
+  try {
+    const read = Effect.gen(function* () {
+      const transport = yield* openTransport(config.c1);
+      return yield* readClusterUid('c1', transport, Duration.millis(50));
+    });
+    const spawn = ChildProcessSpawner.ChildProcessSpawner;
+    const message = await failure(() =>
+      Effect.runPromise(Effect.provideService(read, spawn, fakeSpawner(vault))),
+    );
+    expect(message).toContain('TalosClusterIdentityTimeout');
+  } finally {
+    api.restore();
+  }
+});
+
+test(
+  'through connect, a silent apiserver fails with the identity timeout, not the outer deadline',
+  async () => {
+    // ⛔ The inner uid deadline (5 s) is shorter than the outer connect deadline (10 s), so a silent
+    //   apiserver must be reported as TalosClusterIdentityTimeout, never swallowed into
+    //   TalosOpenBaoConnectTimeout (red team, PR 355 — on a084e18 the inner deadline never fired).
+    const api = fakeApiServer(UIDS, ['c1.cluster.invalid']);
+    try {
+      const message = await failure(() =>
+        Effect.runPromise(
+          Effect.provideService(
+            connectTalosOpenBao(config, talosOpenBaoConnection('uid-c1')),
+            ChildProcessSpawner.ChildProcessSpawner,
+            fakeSpawner(vault),
+          ),
+        ),
+      );
+      expect(message).toContain('TalosClusterIdentityTimeout');
+      expect(message).not.toContain('TalosOpenBaoConnectTimeout');
+    } finally {
+      api.restore();
+    }
+  },
+  { timeout: 15000 },
+);

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

@@ -0,0 +1,165 @@
+/**
+ * `Kubernetes.Manifest` and `Kubernetes.HelmChart` THROUGH the registered `talos-openbao` adapter,
+ * with a fake `bao` and a fake apiserver (`fake-apiserver.ts` — no socket, no vault, no cluster).
+ * Proves the per-cluster config (each connection reaches its own endpoint, an unconfigured uid
+ * is refused, a retired cluster's delete is a no-op) and the IDENTITY RULE (cluster-adapter.ts):
+ * a saved row whose uid-pinned entry was repointed at another physical cluster is refused with NO
+ * write sent to either (one read-only GET proves the mismatch), while a matching uid still works and a missing uid fails closed.
+ * The alias-rename and engine-level cases live in cluster-adapter-rename.test.ts.
+ */
+import { expect, test } from 'bun:test';
+import type { Manifest } from 'alchemy/Kubernetes/Manifest';
+import type * as Provider from 'alchemy/Provider';
+import { talosOpenBaoConnection } from './cluster-adapter.ts';
+import {
+  UIDS,
+  config,
+  failure,
+  helmApi,
+  helmRow,
+  manifestApi,
+  manifestRow,
+  session,
+} from './cluster-adapter.fixtures.ts';
+import { fakeApiServer } from './fake-apiserver.ts';
+
+test('two clusters in one stack each reach their own endpoint, uid-checked first', async () => {
+  const api = fakeApiServer(UIDS);
+  try {
+    const reconcile = (cluster: string, uid: string) => (s: Provider.ProviderService<Manifest>) =>
+      s.reconcile({
+        news: {
+          cluster: talosOpenBaoConnection(uid),
+          manifest: { apiVersion: 'v1', kind: 'Namespace', metadata: { name: `ns-${cluster}` } },
+        },
+        output: undefined,
+        session,
+      } as never);
+    const out1 = (await manifestApi(reconcile('c1', 'uid-c1'))) as { connection: unknown };
+    await manifestApi(reconcile('c2', 'uid-c2'));
+    expect(api.seen).toEqual([
+      'GET c1.cluster.invalid/api/v1/namespaces/kube-system',
+      'PATCH c1.cluster.invalid/api/v1/namespaces/ns-c1',
+      'GET c2.cluster.invalid/api/v1/namespaces/kube-system',
+      'PATCH c2.cluster.invalid/api/v1/namespaces/ns-c2',
+    ]);
+    expect(JSON.stringify(out1.connection)).toBe(
+      '{"auth":{"kind":"talos-openbao","uid":"uid-c1"}}',
+    );
+  } finally {
+    api.restore();
+  }
+});
+
+test('a connection naming an unconfigured uid is refused before any request', async () => {
+  const api = fakeApiServer(UIDS);
+  try {
+    const message = await failure(() =>
+      manifestApi((s) => s.delete({ output: manifestRow({ uid: 'uid-c9' }) } as never)),
+    );
+    expect(message).toContain('no entry pinned to cluster uid uid-c9');
+    expect(api.seen).toEqual([]);
+  } finally {
+    api.restore();
+  }
+});
+
+test('delete on a retired cluster is a no-op, on a live one it reaches that cluster only', async () => {
+  const api = fakeApiServer(UIDS);
+  try {
+    await manifestApi((s) => s.delete({ output: manifestRow({ uid: 'uid-gone' }) } as never));
+    expect(api.seen).toEqual([]);
+    await manifestApi((s) =>
+      s.delete({ output: manifestRow({ uid: 'uid-c2' }, 'ns-c2') } as never),
+    );
+    expect(api.seen).toEqual([
+      'GET c2.cluster.invalid/api/v1/namespaces/kube-system',
+      'DELETE c2.cluster.invalid/api/v1/namespaces/ns-c2',
+    ]);
+  } finally {
+    api.restore();
+  }
+});
+
+// ★ THE CODEX SCENARIO: create with c1's config, then repoint the entry pinned to uid-c1 at c2's
+//   vault key and delete the saved output. Before the identity rule that sent DELETE to c2.
+const repointed = { ...config, c1: { ...config.c2, uid: 'uid-c1' } };
+
+test('a saved c1 row is refused when its entry now points at c2: no write reaches either', async () => {
+  const api = fakeApiServer(UIDS);
+  try {
+    const row = manifestRow({ uid: 'uid-c1' });
+    const message = await failure(() =>
+      manifestApi((s) => s.delete({ output: row } as never), repointed),
+    );
+    expect(message).toContain('TalosClusterIdentityMismatch');
+    expect(message).toContain('uid-c2');
+    expect(api.seen).toEqual(['GET c2.cluster.invalid/api/v1/namespaces/kube-system']);
+  } finally {
+    api.restore();
+  }
+});
+
+test('the same repoint refuses a Manifest read and a HelmChart cleanup: no write reaches either', async () => {
+  const api = fakeApiServer(UIDS);
+  try {
+    const read = await failure(() =>
+      manifestApi(
+        (s) => s.read?.({ output: manifestRow({ uid: 'uid-c1' }) } as never) as never,
+        repointed,
+      ),
+    );
+    expect(read).toContain('TalosClusterIdentityMismatch');
+    const cleanup = await failure(() =>
+      helmApi((s) => s.delete({ output: helmRow({ uid: 'uid-c1' }) } as never), repointed),
+    );
+    expect(cleanup).toContain('TalosClusterIdentityMismatch');
+    expect(api.seen.filter((call) => !call.startsWith('GET '))).toEqual([]);
+    expect(api.seen.every((call) => call.startsWith('GET c2.'))).toBe(true);
+  } finally {
+    api.restore();
+  }
+});
+
+test('a matching uid still deletes on the right cluster (Manifest and HelmChart)', async () => {
+  const api = fakeApiServer(UIDS);
+  try {
+    await manifestApi((s) => s.delete({ output: manifestRow({ uid: 'uid-c1' }) } as never));
+    await helmApi((s) => s.delete({ output: helmRow({ uid: 'uid-c1' }) } as never));
+    expect(api.seen.filter((call) => call.startsWith('DELETE '))).toEqual([
+      'DELETE c1.cluster.invalid/api/v1/namespaces/ns-c1',
+      'DELETE c1.cluster.invalid/api/v1/namespaces/ns-c1',
+    ]);
+  } finally {
+    api.restore();
+  }
+});
+
+test('a saved auth block with no uid fails closed with no request', async () => {
+  const api = fakeApiServer(UIDS);
+  try {
+    const message = await failure(() =>
+      manifestApi((s) => s.delete({ output: manifestRow({}) } as never)),
+    );
+    expect(message).toContain('TalosClusterIdentityMissing');
+    expect(api.seen).toEqual([]);
+  } finally {
+    api.restore();
+  }
+});
+
+test('a legacy row with auth.cluster is refused with no request and a remedy', async () => {
+  const api = fakeApiServer(UIDS);
+  try {
+    const message = await failure(() =>
+      manifestApi((s) =>
+        s.delete({ output: manifestRow({ cluster: 'c1', uid: 'uid-c1' }) } as never),
+      ),
+    );
+    expect(message).toContain('TalosOpenBaoLegacyAuth');
+    expect(message).toContain('edit the saved state');
+    expect(api.seen).toEqual([]);
+  } finally {
+    api.restore();
+  }
+});

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

@@ -0,0 +1,102 @@
+/**
+ * `talos-openbao` connect refusals that must happen BEFORE any vault read: a legacy `auth.cluster`
+ * row, no uid, a uid no entry is pinned to, and two entries pinned to one uid. Fake `bao` only; the
+ * `calls` list proves the vault was never spawned.
+ */
+import type { Connection } from 'alchemy/Kubernetes/Connection';
+import { expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as ChildProcessSpawner from 'effect/process/ChildProcessSpawner';
+import { connectTalosOpenBao, talosOpenBaoConnection } from './cluster-adapter.ts';
+import { type FakeCall, fakeSpawner } from './fake-process.ts';
+
+const config = {
+  c1: { context: 'admin@hf-c1', key: 'kubeconfig', mount: 'talos-c1', uid: 'uid-c1' },
+};
+const connection = talosOpenBaoConnection('uid-c1');
+
+const run = <A, E>(
+  effect: Effect.Effect<A, E, ChildProcessSpawner.ChildProcessSpawner>,
+  calls: FakeCall[] = [],
+) =>
+  Effect.runPromise(
+    Effect.provideService(
+      effect,
+      ChildProcessSpawner.ChildProcessSpawner,
+      fakeSpawner(() => ({ stdout: '{}' }), calls),
+    ),
+  );
+
+const refusedWith = (
+  effect: Effect.Effect<unknown, unknown, ChildProcessSpawner.ChildProcessSpawner>,
+  calls: FakeCall[],
+) =>
+  run(
+    effect.pipe(
+      Effect.catch((error) =>
+        Effect.succeed(error instanceof Error && '_tag' in error ? String(error._tag) : 'untagged'),
+      ),
+    ),
+    calls,
+  );
+
+test('a legacy auth.cluster row is refused with no vault read and a remedy', async () => {
+  const calls: FakeCall[] = [];
+  const legacy = { auth: { kind: 'talos-openbao', cluster: 'c1', uid: 'uid-c1' } } as Connection;
+  expect(await refusedWith(connectTalosOpenBao(config, legacy), calls)).toBe(
+    'TalosOpenBaoLegacyAuth',
+  );
+  expect(calls).toEqual([]);
+  const message = await run(
+    connectTalosOpenBao(config, legacy).pipe(
+      Effect.catchTag('TalosOpenBaoLegacyAuth', (error) => Effect.succeed(error.message)),
+    ),
+  );
+  expect(message).toContain('edit the saved state');
+});
+
+test('the missing-uid remedy says to pin a literal, not wire ClusterIdentity (fails on 19502c6)', async () => {
+  const noUid = { auth: { kind: 'talos-openbao' } } as Connection;
+  const message = await run(
+    connectTalosOpenBao(config, noUid).pipe(
+      Effect.catchTag('TalosClusterIdentityMissing', (error) => Effect.succeed(error.message)),
+    ),
+  );
+  expect(message).toContain('pin the uid');
+  expect(message).not.toContain('its `connection`');
+});
+
+test('a connection with no auth block is refused as a typed failure, not a raw TypeError', async () => {
+  const calls: FakeCall[] = [];
+  const noAuth = { endpoint: 'https://example.invalid' } as Connection;
+  expect(await refusedWith(connectTalosOpenBao(config, noAuth), calls)).toBe(
+    'TalosClusterIdentityMissing',
+  );
+  expect(calls).toEqual([]);
+});
+
+test('a connection that is itself undefined or null is refused as a typed failure (fails on a7668f7: the whole-connection destructure threw)', async () => {
+  const calls: FakeCall[] = [];
+  for (const absent of [undefined, null]) {
+    expect(
+      await refusedWith(connectTalosOpenBao(config, absent as unknown as Connection), calls),
+    ).toBe('TalosClusterIdentityMissing');
+  }
+  expect(calls).toEqual([]);
+});
+
+test('no uid, an unknown uid and an ambiguous pin are refused before any vault read', async () => {
+  const calls: FakeCall[] = [];
+  const noUid = { auth: { kind: 'talos-openbao' } } as Connection;
+  expect(await refusedWith(connectTalosOpenBao(config, noUid), calls)).toBe(
+    'TalosClusterIdentityMissing',
+  );
+  expect(
+    await refusedWith(connectTalosOpenBao(config, talosOpenBaoConnection('uid-x')), calls),
+  ).toBe('TalosOpenBaoUnknownCluster');
+  const twice = { ...config, c1b: { ...config.c1 } };
+  expect(await refusedWith(connectTalosOpenBao(twice, connection), calls)).toBe(
+    'TalosOpenBaoAmbiguousUid',
+  );
+  expect(calls).toEqual([]);
+});

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

@@ -0,0 +1,87 @@
+/**
+ * Renaming adapter configuration must be a no-op for upstream workloads, THROUGH the real
+ * `ManifestProvider` and `HelmChartProvider` with the fake apiserver. Upstream hashes only the auth
+ * block (`internal/workload.ts:91-96` `connectionIdentity`) and replaces on a difference, and a
+ * replace PATCHes then DELETEs the same-named object. The auth block is `{ kind, uid }`, so an
+ * alias, vault key, mount or context rename must change nothing it hashes.
+ *
+ * ⚠️ The engine-level plan (Plan.ts) is not driven here: it needs a state store, a stack and the
+ *   full alchemy runtime. What decides replace-versus-update is the provider `diff` result, which
+ *   is asserted directly; the engine only maps `undefined` to update and `replace` to a recreate.
+ */
+import { expect, test } from 'bun:test';
+import type { Manifest } from 'alchemy/Kubernetes/Manifest';
+import type * as Provider from 'alchemy/Provider';
+import { talosOpenBaoConnection } from './cluster-adapter.ts';
+import { UIDS, manifestApi, session } from './cluster-adapter.fixtures.ts';
+import { fakeApiServer } from './fake-apiserver.ts';
+
+const props = (uid: string) => ({
+  cluster: talosOpenBaoConnection(uid),
+  manifest: { apiVersion: 'v1', kind: 'Namespace', metadata: { name: 'ns-c1' } },
+});
+const only = (calls: readonly string[], method: string) =>
+  calls.filter((call) => call.startsWith(`${method} `));
+
+/** Same physical cluster (uid-c1) under a new alias: context, key and mount stay as they were. */
+const renamed = {
+  moved: { context: 'admin@c1', key: 'kubeconfig', mount: 'talos-c1', uid: 'uid-c1' },
+};
+
+test('an alias rename plans no replace and sends no DELETE; update and delete reach c1 only', async () => {
+  const api = fakeApiServer(UIDS);
+  try {
+    const out = (await manifestApi((s: Provider.ProviderService<Manifest>) =>
+      s.reconcile({ news: props('uid-c1'), olds: undefined, output: undefined, session } as never),
+    )) as { connection: unknown };
+    api.seen.length = 0;
+
+    const diff = await manifestApi(
+      (s) =>
+        s.diff?.({
+          news: props('uid-c1'),
+          olds: props('uid-c1'),
+          output: out,
+        } as never) as never,
+      renamed,
+    );
+    expect(diff).toBeUndefined();
+    expect(api.seen).toEqual([]);
+
+    await manifestApi(
+      (s) =>
+        s.reconcile({
+          news: props('uid-c1'),
+          olds: props('uid-c1'),
+          output: out,
+          session,
+        } as never),
+      renamed,
+    );
+    await manifestApi((s) => s.delete({ output: out } as never), renamed);
+    expect(only(api.seen, 'DELETE')).toEqual(['DELETE c1.cluster.invalid/api/v1/namespaces/ns-c1']);
+    expect(api.seen.filter((call) => !call.includes('c1.cluster.invalid'))).toEqual([]);
+    expect(only(api.seen, 'PATCH')).toHaveLength(1);
+    expect(JSON.stringify(out.connection)).toBe('{"auth":{"kind":"talos-openbao","uid":"uid-c1"}}');
+  } finally {
+    api.restore();
+  }
+});
+
+test('a real move (a different uid) is a replace, never an in-place update', async () => {
+  const api = fakeApiServer(UIDS);
+  try {
+    const diff = await manifestApi(
+      (s) =>
+        s.diff?.({
+          news: props('uid-c2'),
+          olds: props('uid-c1'),
+          output: undefined,
+        } as never) as never,
+    );
+    expect(diff).toEqual({ action: 'replace' });
+    expect(api.seen).toEqual([]);
+  } finally {
+    api.restore();
+  }
+});