@homeflare/alchemy 0.39.0 → 0.41.0

package/src/talos/kubeconfig.test.ts

@@ -0,0 +1,256 @@
+/**
+ * `Talos.Kubeconfig` landing in OpenBao, written once at bring-up (K-talos-first-boot). Fully
+ * offline: fake-process.ts fakes `bao`/`talosctl`; the fake `talosctl kubeconfig` handler writes a
+ * fixture file to the temp path it was given, standing in for what the real binary would do.
+ *
+ * ⚠️ FIXTURES ONLY — see values.test.ts's own header for why the base64 fields are built from
+ *   plain words at run time rather than written out literally.
+ */
+import assert from 'node:assert/strict';
+import { existsSync, writeFileSync } from 'node:fs';
+import { describe, it } from 'node:test';
+import * as Effect from 'effect/Effect';
+import * as ChildProcessSpawner from 'effect/unstable/process/ChildProcessSpawner';
+import { type FakeCall, fakeSpawner } from './fake-process.ts';
+import {
+  type KubeconfigAttributes,
+  type KubeconfigProps,
+  diffKubeconfig as diff,
+  readKubeconfig as read,
+  reconcileKubeconfig as reconcile,
+} from './kubeconfig.ts';
+
+const b64 = (words: string) => Buffer.from(words).toString('base64');
+
+const fixtureKubeconfig = (marker: string) => `
+apiVersion: v1
+kind: Config
+clusters:
+  - name: hf-c1
+    cluster:
+      server: https://192.0.2.50:6443
+      certificate-authority-data: ${b64(`not a ca ${marker}`)}
+contexts:
+  - name: admin@hf-c1
+    context: { cluster: hf-c1, user: admin@hf-c1 }
+users:
+  - name: admin@hf-c1
+    user:
+      client-certificate-data: ${b64(`not a certificate ${marker}`)}
+      client-key-data: ${b64(`not a key ${marker}`)}
+current-context: admin@hf-c1
+`;
+
+const TARGET = { cluster: 'c1', mount: 'talos-c1' };
+const props = (): KubeconfigProps => ({
+  context: 'admin@hf-c1',
+  node: '198.51.100.10',
+  target: TARGET,
+});
+
+const run = <A, E>(
+  effect: Effect.Effect<A, E, ChildProcessSpawner.ChildProcessSpawner>,
+  handler: (c: FakeCall) => { stdout?: string; stderr?: string; exitCode?: number },
+  calls: FakeCall[] = [],
+) =>
+  Effect.runPromise(
+    Effect.provideService(
+      effect,
+      ChildProcessSpawner.ChildProcessSpawner,
+      fakeSpawner(handler, calls),
+    ),
+  );
+
+describe('reconcile — CREATE writes talosctl kubeconfig output into the vault, never a host path', () => {
+  it('mints the temp file, writes its content to vault via stdin, cleans up the temp file', async () => {
+    const calls: FakeCall[] = [];
+    let outPath = '';
+    const handler = (call: FakeCall) => {
+      if (call.command === 'bao' && call.args[1] === 'get') {
+        return { stdout: JSON.stringify({ data: { data: { talosconfig: 'fake-talosconfig' } } }) };
+      }
+      if (call.command === 'bao' && call.args[1] === 'put') return {};
+      if (call.command === 'talosctl' && call.args[0] === 'kubeconfig') {
+        outPath = call.args[1] ?? '';
+        writeFileSync(outPath, fixtureKubeconfig('create'));
+        return {};
+      }
+      throw new Error(`unexpected call ${JSON.stringify(call)}`);
+    };
+    const result = (await run(
+      reconcile(props(), undefined),
+      handler,
+      calls,
+    )) as KubeconfigAttributes;
+
+    assert.equal(result.endpoint, 'https://192.0.2.50:6443');
+    assert.equal(result.context, 'admin@hf-c1');
+    assert.equal(result.connection.auth.kind, 'kubeconfig');
+    // ⛔ I2 (LAND red team): NEVER undefined — an undefined `path` here would let the stock
+    // KubeConfigAdapter fall back to $KUBECONFIG/~/.kube/config. It must be a path that can never
+    // resolve, so a consumer that isn't yet wired to mintKubeconfig fails loudly instead of quietly
+    // reaching the operator's own cluster.
+    const authPath = (result.connection.auth as { path?: string }).path;
+    assert.ok(typeof authPath === 'string' && authPath.length > 0);
+
+    const put = calls.find((c) => c.command === 'bao' && c.args[1] === 'put');
+    assert.ok(put);
+    // ⛔ C2 (LAND red team): `=-`, never `=@-` — see credentials-write.ts's own header.
+    assert.deepEqual(put.args, ['kv', 'put', 'talos-c1/kubeconfig', 'kubeconfig=-']);
+    assert.equal(put.stdin, fixtureKubeconfig('create'));
+    assert.ok(!put.args.some((a) => a.includes('not a key')), 'never in argv');
+
+    assert.equal(existsSync(outPath), false, 'the captured temp file must be gone after reconcile');
+  });
+});
+
+describe('reconcile — write-once: a second reconcile never re-runs talosctl kubeconfig', () => {
+  it('confirms from the vault copy instead of minting a new admin cert', async () => {
+    const calls: FakeCall[] = [];
+    const priorOutput: KubeconfigAttributes = {
+      certificateAuthorityFingerprint: 'x',
+      clientCertificateFingerprint: 'x',
+      connection: { auth: { context: 'admin@hf-c1', kind: 'kubeconfig' } },
+      context: 'admin@hf-c1',
+      credentialGeneration: 'x',
+      endpoint: 'https://192.0.2.50:6443',
+    };
+    const handler = (call: FakeCall) => {
+      if (call.command === 'bao' && call.args[1] === 'get') {
+        return {
+          stdout: JSON.stringify({ data: { data: { config: fixtureKubeconfig('confirm') } } }),
+        };
+      }
+      throw new Error(`unexpected call ${JSON.stringify(call)}`);
+    };
+    const result = (await run(
+      reconcile(props(), priorOutput),
+      handler,
+      calls,
+    )) as KubeconfigAttributes;
+
+    assert.equal(result.endpoint, 'https://192.0.2.50:6443');
+    assert.ok(
+      calls.every(
+        (c) => !(c.command === 'talosctl') && !(c.command === 'bao' && c.args[1] === 'put'),
+      ),
+      'a confirm-only reconcile never spawns talosctl or writes the vault again',
+    );
+  });
+});
+
+describe('read — C1 fix: undefined means genuinely absent, never "some read failed"', () => {
+  it('returns undefined (never a defined empty object) when the vault key was never written', async () => {
+    // ⛔ MEASURED against OpenBao v2.6.2: this exit code + stderr text is exactly what `bao kv get`
+    // prints for a genuinely unwritten KV-v2 key — see kubeconfig.ts's `isVaultKeyAbsent` header.
+    const result = await run(read(props()), () => ({
+      exitCode: 2,
+      stderr: 'No value found at talos-c1/data/kubeconfig',
+    }));
+    assert.equal(result, undefined);
+  });
+
+  it('propagates a genuine vault/transport failure instead of reading it as absence', async () => {
+    await assert.rejects(
+      run(read(props()), () => ({ exitCode: 2, stderr: 'permission denied' })),
+      (error: unknown) => error instanceof Error && error.message.includes('permission denied'),
+    );
+  });
+});
+
+describe('read → reconcile chained the way the Alchemy engine drives a cold start (C1 regression)', () => {
+  it('a cold-start read (undefined) followed by reconcile(undefined) actually creates', async () => {
+    // ⛔ Alchemy beta.79 Plan.ts:1303-1352 always calls `read` first when there is no state row; a
+    // DEFINED result there is adopted and forces `update`, so this is the exact sequence that made
+    // Talos.Kubeconfig un-creatable before the C1 fix — see kubeconfig.ts's own `readKubeconfig`
+    // header.
+    const calls: FakeCall[] = [];
+    const coldHandler = () => ({
+      exitCode: 2,
+      stderr: 'No value found at talos-c1/data/kubeconfig',
+    });
+    const readResult = await run(read(props()), coldHandler, calls);
+    assert.equal(
+      readResult,
+      undefined,
+      "the engine's adoption probe must see a genuine cold start",
+    );
+
+    const createHandler = (call: FakeCall) => {
+      if (call.command === 'bao' && call.args[1] === 'get') {
+        // ★ mintTalosconfig reads the `talosconfig` key first — only the `kubeconfig` key itself
+        // is genuinely absent at a cold start.
+        return call.args[3]?.endsWith('/kubeconfig')
+          ? coldHandler()
+          : { stdout: JSON.stringify({ data: { data: { talosconfig: 'fake-talosconfig' } } }) };
+      }
+      if (call.command === 'bao' && call.args[1] === 'put') return {};
+      if (call.command === 'talosctl' && call.args[0] === 'kubeconfig') {
+        writeFileSync(call.args[1] ?? '', fixtureKubeconfig('engine-order'));
+        return {};
+      }
+      throw new Error(`unexpected call ${JSON.stringify(call)}`);
+    };
+    const created = (await run(
+      reconcile(props(), readResult),
+      createHandler,
+    )) as KubeconfigAttributes;
+    assert.equal(created.endpoint, 'https://192.0.2.50:6443');
+    assert.notEqual(created.credentialGeneration, '');
+  });
+});
+
+describe('reconcile — belt-and-suspenders: a defined-but-empty output is treated as absent (C1)', () => {
+  it('a pre-fix-shaped empty output still runs CREATE instead of failing to confirm', async () => {
+    const staleEmptyOutput: KubeconfigAttributes = {
+      certificateAuthorityFingerprint: '',
+      clientCertificateFingerprint: '',
+      connection: { auth: { context: 'admin@hf-c1', kind: 'kubeconfig' } },
+      context: 'admin@hf-c1',
+      credentialGeneration: '',
+      endpoint: '',
+    };
+    const handler = (call: FakeCall) => {
+      if (call.command === 'bao' && call.args[1] === 'get') {
+        return { stdout: JSON.stringify({ data: { data: { talosconfig: 'x' } } }) };
+      }
+      if (call.command === 'bao' && call.args[1] === 'put') return {};
+      if (call.command === 'talosctl' && call.args[0] === 'kubeconfig') {
+        writeFileSync(call.args[1] ?? '', fixtureKubeconfig('stale-empty'));
+        return {};
+      }
+      throw new Error(`unexpected call ${JSON.stringify(call)}`);
+    };
+    const result = (await run(
+      reconcile(props(), staleEmptyOutput),
+      handler,
+    )) as KubeconfigAttributes;
+    assert.notEqual(result.credentialGeneration, '');
+  });
+});
+
+describe('diff', () => {
+  it('plans noop when the vault copy matches state', async () => {
+    const output: KubeconfigAttributes = (await run(
+      reconcile(props(), undefined),
+      (call: FakeCall) => {
+        if (call.command === 'bao' && call.args[1] === 'get') {
+          return { stdout: JSON.stringify({ data: { data: { talosconfig: 'x' } } }) };
+        }
+        if (call.command === 'bao' && call.args[1] === 'put') return {};
+        if (call.command === 'talosctl') {
+          writeFileSync(call.args[1] ?? '', fixtureKubeconfig('diff'));
+          return {};
+        }
+        throw new Error('unexpected');
+      },
+    )) as KubeconfigAttributes;
+
+    const result = await run(diff(props(), output), (call: FakeCall) =>
+      call.args[1] === 'get'
+        ? { stdout: JSON.stringify({ data: { data: { config: fixtureKubeconfig('diff') } } }) }
+        : {},
+    );
+    assert.equal(result?.action, 'noop');
+  });
+});

package/src/talos/kubeconfig.ts

@@ -5,37 +5,53 @@
  *   `--merge=false` keeps it isolated; `-f/--force` overwrites an existing file.
  *
  * ⛔ THE KUBECONFIG FILE CONTAINS A CLIENT CERTIFICATE — IT MUST NOT BE AN ATTRIBUTE. Alchemy
- *   persists attributes unencrypted. This resource:
- *     - writes the file to `runtimePath` at reconcile time (re-minted each deploy),
- *     - persists ONLY public metadata + fingerprints,
- *     - exposes a `connection` field referencing the runtime path for `Kubernetes.ClusterAdapter`.
+ *   persists attributes unencrypted. This resource persists ONLY public metadata + fingerprints,
+ *   never the file's own bytes.
  *
- * ⚠️ `runtimePath` IS PERSISTED AS A STRING, NOT AS FILE CONTENTS. The path is a contract between
- *   this resource and the host filesystem — same pattern as pointing Kubernetes.KubeConfig at
- *   `/opt/homeflare/...` rendered outside Postgres.
+ * ⛔ LANDS IN OPENBAO, NOT A HOST `runtimePath` (K-talos-first-boot, 2026-09-26). The shipped shape
+ *   wrote a cluster-admin kubeconfig to un-vaulted host disk and never removed it — the exact class
+ *   of exposure `talos/credentials.ts`'s own header exists to prevent — and its own `read` depended
+ *   on that file's continued presence, so verifying from any other host planned `update` forever
+ *   (docs/plans/2026-09-26-talos-secrets-flow.md's "Measured today" section). Fixed:
+ *     - CREATE (`output === undefined`) runs `talosctl kubeconfig` into a throwaway, unguessable
+ *       temp path (this file's own `reservedTempPath`), reads it back, and writes its bytes into
+ *       OpenBao at `target.mount`/`kubeconfigKey` via stdin (`credentials-write.ts`'s
+ *       `writeKvValue` — ⛔ never argv) — never to any path a caller could depend on.
+ *     - ⛔ WRITTEN ONCE, NOT RE-MINTED EVERY DEPLOY. `talosctl kubeconfig` always issues a FRESH
+ *       admin client certificate; re-running it every reconcile would rotate credentials for no
+ *       reason and violate O1's write-once-at-bring-up grant on this one key
+ *       (docs/plans/2026-09-26-talos-secrets-flow.md, O1). Once `output` is defined, reconcile only
+ *       reads the vault copy back to confirm it — the same "once" shape `talos-bootstrap.ts` uses
+ *       for a boolean, here for a value.
+ *     - The persisted `connection` carries no usable host path — a consumer materializes its own
+ *       temp file via `credentials.ts`'s `mintKubeconfig`, the same pattern `mintTalosconfig`
+ *       already established. Wiring `Kubernetes.ClusterAdapter` to call it is separate, later work
+ *       (named, not built, in the secrets-flow doc); this only makes the vault-backed read+mint
+ *       step exist for it to call. ⛔ Until that wiring lands, `connection.auth.path` is a sentinel
+ *       that can never resolve to a real file (LAND red team I2, `kubeconfig-attrs.ts`'s own
+ *       header) — an ABSENT path here would let the stock `Kubernetes.KubeConfigAdapter` silently
+ *       fall back to `$KUBECONFIG`/`~/.kube/config` instead of failing loudly.
  */
+import { chmodSync } from 'node:fs';
 import { Resource } from 'alchemy';
 import { isResolved } from 'alchemy/Diff';
 import type { Input } from 'alchemy/Input';
 import type { Connection } from 'alchemy/Kubernetes/Connection';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
-import { mintTalosconfig } from './credentials.ts';
+import { DEFAULT_KUBECONFIG_KEY, mintTalosconfig, readKvValue } from './credentials.ts';
+import { reservedTempPath, writeKvValue } from './credentials-write.ts';
+import { buildAttrs } from './kubeconfig-attrs.ts';
 import type { TalosRequirements, WithTarget } from './resource.ts';
 import { talosctl } from './talosctl.ts';
-import { kubeconfigMetadata, sha256 } from './values.ts';
 
 export interface KubeconfigProps extends WithTarget {
   /** Node that serves `talosctl kubeconfig`. */
   node: string;
   /** Context name inside the generated kubeconfig — not secret. */
   context: string;
-  /**
-   * Host path where talosctl writes the kubeconfig each reconcile.
-   *
-   * ⛔ Must be outside Alchemy state and rotated by redeploy, never copied into attributes.
-   */
-  runtimePath: string;
+  /** OpenBao KV path under `target.mount` for the written kubeconfig. Default `'kubeconfig'`. */
+  kubeconfigKey?: string;
   after?: readonly unknown[];
 }
 
@@ -50,7 +66,11 @@ export interface KubeconfigAttributes {
    * Serializable `Kubernetes.Connection` for downstream workloads.
    *
    * ★ auth.kind `kubeconfig` is the stock ClusterAdapter — provider-roadmap.md names this seam.
-   *   Only `path` and `context` appear here; the adapter reads credentials from disk at call time.
+   *   `path` is a sentinel that can never resolve (LAND red team I2, `kubeconfig-attrs.ts`'s own
+   *   `toConnection` header): the content lives in OpenBao, not at a fixed host path, and a real
+   *   `Kubernetes.ClusterAdapter` wiring is later work, so this must fail rather than silently
+   *   reach the operator's own kubeconfig. A consumer materializes its own scoped temp file via
+   *   `credentials.ts`'s `mintKubeconfig` in the meantime.
    */
   connection: Connection;
 }
@@ -65,92 +85,146 @@ export interface TalosKubeconfig extends Resource<
 
 export const TalosKubeconfig = Resource<TalosKubeconfig>('Talos.Kubeconfig');
 
-const generation = (meta: {
-  endpoint: string;
-  caFingerprint: string;
-  clientFingerprint: string;
-  context: string;
-}) => sha256(`${meta.context}\n${meta.endpoint}\n${meta.caFingerprint}\n${meta.clientFingerprint}`);
+/**
+ * ★ MEASURED AGAINST OPENBAO v2.6.2 (C1 fix, LAND red team, 2026-09-26 — isolated in-memory dev
+ *   server, `env -i`, scratch HOME, no estate credentials; server removed after): `bao kv get` on a
+ *   genuinely unwritten KV-v2 key exits 2 with stderr exactly `No value found at <mount>/data/<key>`
+ *   — `readKvValue`'s Error message embeds that text verbatim. This is the ONLY signal this file
+ *   trusts as "not written yet"; every other failure (a wrong exit code, a different stderr such as
+ *   a permission denial or a network failure) propagates as a real error instead of being read as
+ *   absence.
+ */
+const isVaultKeyAbsent = (error: unknown): boolean =>
+  error instanceof Error && /no value found at/i.test(error.message);
 
-const toConnection = (props: KubeconfigProps): Connection => ({
-  auth: { context: props.context, kind: 'kubeconfig', path: props.runtimePath },
-});
+const readVaultMeta = (props: KubeconfigProps, key: string) =>
+  readKvValue(props.target.mount, key, ['kubeconfig', 'config']).pipe(
+    Effect.catchIf(isVaultKeyAbsent, () => Effect.succeed(undefined)),
+  );
 
-const readFileMeta = (props: KubeconfigProps) =>
+/**
+ * ★ EXPORTED for kubeconfig.test.ts — see talos-bootstrap.ts's own note on the pattern.
+ *
+ * ⛔ C1 FIX (LAND red team, 2026-09-26) — `undefined` NOW MEANS ONLY "the key has never been
+ *   written", NEVER "some read failed". The shipped `Effect.orElseSucceed` folded EVERY failure —
+ *   including a vault outage or wrong mount — into a defined, empty-fingerprint object. Alchemy's
+ *   engine always adopts a defined cold-start `read` result and forces `update` (alchemy beta.79
+ *   `Plan.ts:1303-1352`), so `reconcileKubeconfig`'s write-once branch (`output !== undefined`)
+ *   then tried to CONFIRM a key that had never actually been written, and failed every time —
+ *   `Talos.Kubeconfig` could never be created. Vault content that EXISTS but does not parse as a
+ *   kubeconfig is a different, fail-closed case (below), never treated as absence.
+ */
+export const readKubeconfig = (props: KubeconfigProps) =>
   Effect.gen(function* () {
-    const text = yield* Effect.tryPromise({
-      try: () => Bun.file(props.runtimePath).text(),
-      catch: (cause) => new Error(String(cause)),
-    }).pipe(Effect.orElseSucceed(() => undefined as string | undefined));
-    if (text === undefined) return undefined;
-    const meta = kubeconfigMetadata(text, props.context);
-    if (meta === undefined) return undefined;
-    return {
-      certificateAuthorityFingerprint: meta.caFingerprint,
-      clientCertificateFingerprint: meta.clientFingerprint,
-      connection: toConnection(props),
-      context: props.context,
-      credentialGeneration: generation({ ...meta, context: props.context }),
-      endpoint: meta.endpoint,
-    };
+    const key = props.kubeconfigKey ?? DEFAULT_KUBECONFIG_KEY;
+    const raw = yield* readVaultMeta(props, key);
+    if (raw === undefined) return undefined;
+    const meta = buildAttrs(raw, props);
+    if (meta === undefined) {
+      return yield* Effect.fail(
+        new Error(
+          `${props.target.mount}/${key}: vault content exists but does not parse as a kubeconfig ` +
+            `for context ${props.context} — not a cold start. Fix the KV entry or the pinned ` +
+            'context rather than trusting an empty read.',
+        ),
+      );
+    }
+    return meta;
   });
 
-const read = (props: KubeconfigProps) =>
-  readFileMeta(props).pipe(
-    Effect.map((meta) =>
-      meta === undefined
-        ? {
-            certificateAuthorityFingerprint: '',
-            clientCertificateFingerprint: '',
-            connection: toConnection(props),
-            context: props.context,
-            credentialGeneration: '',
-            endpoint: '',
-          }
-        : meta,
-    ),
-  );
-
-const diff = (news: Input<KubeconfigProps>, output: KubeconfigAttributes | undefined) =>
+export const diffKubeconfig = (
+  news: Input<KubeconfigProps>,
+  output: KubeconfigAttributes | undefined,
+) =>
   Effect.gen(function* () {
     if (output === undefined || !isResolved(news)) return undefined;
-    const live = yield* read(news);
+    const live = yield* readKubeconfig(news);
     if (
-      live.credentialGeneration !== '' &&
-      output.credentialGeneration === live.credentialGeneration &&
-      output.context === live.context &&
-      output.endpoint === live.endpoint
+      live !== undefined &&
+      live.credentialGeneration === output.credentialGeneration &&
+      live.context === output.context &&
+      live.endpoint === output.endpoint
     ) {
       return { action: 'noop' } as const;
     }
     return { action: 'update' } as const;
   });
 
-const reconcile = (props: KubeconfigProps) =>
-  Effect.gen(function* () {
-    const credential = yield* mintTalosconfig(props.target);
-    yield* talosctl(
-      [
-        'kubeconfig',
-        props.runtimePath,
-        '--merge=false',
-        '--force',
-        '--force-context-name',
-        props.context,
-      ],
-      { nodes: [props.node], talosconfigPath: credential.talosconfigPath },
-    );
-    const meta = yield* readFileMeta(props);
-    if (meta === undefined) {
-      return yield* Effect.die(
-        new Error(
-          `${props.runtimePath}: talosctl kubeconfig returned no error but the file is missing ` +
-            'or unparsable. Read back rather than trusting the exit code alone.',
-        ),
+/**
+ * ⛔ WRAPPED IN `Effect.scoped` — same C1-lifetime reasoning as every other Talos resource file:
+ *   `mintTalosconfig` and `reservedTempPath` both contribute `Scope.Scope`, and this is the caller
+ *   that owns their lifetime for the whole reconcile.
+ * ⛔ WRITE-ONCE — see this file's own header. A bring-up already ran; this branch never spawns
+ *   `talosctl kubeconfig` or writes to the vault again.
+ * ⛔ GATED ON `credentialGeneration`, NOT JUST `output !== undefined` (C1 fix, LAND red team,
+ *   belt-and-suspenders alongside the `read` fix above) — `output`'s own type still allows a
+ *   defined-but-empty value (state persisted by a pre-fix build's `emptyAttrs()`, or any future
+ *   caller that hands this function a stale row). Treat that exactly like `undefined` — mint and
+ *   write once — rather than take the confirm-only branch and fail trying to read back a key that
+ *   was never actually written.
+ */
+export const reconcileKubeconfig = (
+  props: KubeconfigProps,
+  output: KubeconfigAttributes | undefined,
+) =>
+  Effect.scoped(
+    Effect.gen(function* () {
+      const key = props.kubeconfigKey ?? DEFAULT_KUBECONFIG_KEY;
+
+      if (output !== undefined && output.credentialGeneration !== '') {
+        const raw = yield* readKvValue(props.target.mount, key, ['kubeconfig', 'config']);
+        const meta = buildAttrs(raw, props);
+        if (meta === undefined) {
+          return yield* Effect.die(
+            new Error(
+              `${props.target.mount}/${key}: vault content no longer parses as a kubeconfig for ` +
+                `context ${props.context}. Read back rather than trusting the write once.`,
+            ),
+          );
+        }
+        return meta;
+      }
+
+      const credential = yield* mintTalosconfig(props.target);
+      const { path: outPath } = yield* reservedTempPath(
+        `${props.target.cluster}-${props.node}-kubeconfig-out`,
       );
-    }
-    return meta;
-  });
+      yield* talosctl(
+        ['kubeconfig', outPath, '--merge=false', '--force', '--force-context-name', props.context],
+        { nodes: [props.node], talosconfigPath: credential.talosconfigPath },
+      );
+      const raw = yield* Effect.tryPromise({
+        catch: (cause) => new Error(`${outPath}: reading generated kubeconfig: ${String(cause)}`),
+        try: () => Bun.file(outPath).text(),
+      });
+      if (raw.trim() === '') {
+        return yield* Effect.die(
+          new Error(
+            `${props.node}: talosctl kubeconfig returned no error but wrote an empty file. Read ` +
+              'back rather than trusting the exit code alone.',
+          ),
+        );
+      }
+      // ⚠️ REASONED, not measured: talosctl's own writer likely already uses 0600 like most Go
+      //   credential writers, but this chmods defensively regardless — same posture as
+      //   credentials.ts's mintKvTempFile.
+      yield* Effect.try({
+        catch: (cause) => new Error(`${outPath}: chmod 0600: ${String(cause)}`),
+        try: () => chmodSync(outPath, 0o600),
+      });
+      const meta = buildAttrs(raw, props);
+      if (meta === undefined) {
+        return yield* Effect.die(
+          new Error(
+            `${props.node}: talosctl kubeconfig wrote a file that does not parse for context ` +
+              `${props.context}.`,
+          ),
+        );
+      }
+      yield* writeKvValue(props.target.mount, key, 'kubeconfig', raw);
+      return meta;
+    }),
+  );
 
 const handlers = {
   delete: () => Effect.void,
@@ -160,10 +234,16 @@ const handlers = {
   }: {
     news: Input<KubeconfigProps>;
     output: KubeconfigAttributes | undefined;
-  }) => diff(news, output),
+  }) => diffKubeconfig(news, output),
   list: () => Effect.succeed([]),
-  read: ({ olds }: { olds: KubeconfigProps }) => read(olds),
-  reconcile: ({ news }: { news: KubeconfigProps }) => reconcile(news),
+  read: ({ olds }: { olds: KubeconfigProps }) => readKubeconfig(olds),
+  reconcile: ({
+    news,
+    output,
+  }: {
+    news: KubeconfigProps;
+    output: KubeconfigAttributes | undefined;
+  }) => reconcileKubeconfig(news, output),
 };
 
 export const TalosKubeconfigProvider = () =>

package/src/talos/machine-config-fixtures.ts

@@ -0,0 +1,86 @@
+/**
+ * Shared fixtures for talos-machine-config.test.ts and machine-config-poll.test.ts — split out
+ * so neither test file needs to duplicate the fake `bao`/`talosctl` dispatcher (2026-09-26, K-A3).
+ *
+ * ⚠️ FIXTURES ONLY. `CONFIG_TEXT` is a plain marker string, never anything resembling a real
+ *   Talos machine config, CA key or bootstrap token. No provider imports this file.
+ */
+import * as Effect from 'effect/Effect';
+import * as ChildProcessSpawner from 'effect/unstable/process/ChildProcessSpawner';
+import { type FakeCall, fakeSpawner } from './fake-process.ts';
+import type { MachineConfigProps } from './talos-machine-config.ts';
+import { configDigest } from './values.ts';
+
+export const CONFIG_TEXT = 'machine:\n  type: worker\n';
+export const PIN = configDigest(CONFIG_TEXT);
+export const TARGET = { cluster: 'c1', mount: 'talos-c1' };
+export const FAST_POLL = {
+  immediate: { intervalMs: 0, maxAttempts: 3 },
+  rebootish: { intervalMs: 0, maxAttempts: 4 },
+};
+
+export const props = (overrides: Partial<MachineConfigProps> = {}): MachineConfigProps => ({
+  configDigest: PIN,
+  configKey: 'nodes/10001',
+  node: '198.51.100.10',
+  target: TARGET,
+  ...overrides,
+});
+
+/** Shape REASONED from talosctl's `get machineconfig -o yaml` — see values.ts's own header. */
+export const wrapperFor = (specText: string, version = '1') =>
+  `node: 198.51.100.10\nmetadata:\n  version: "${version}"\nspec: "${specText.replace(/\n/g, '\\n')}"\n`;
+
+/** Routes fake `bao kv get` (config + talosconfig keys) and `talosctl` calls in one place. */
+export const dispatcher = (opts: {
+  configText?: string;
+  liveWrapper?: () => { stdout?: string; exitCode?: number };
+  applyExitCode?: number;
+  /**
+   * Controls the fix-first #1 maintenance-mode probe (`talosctl version --insecure`), reached only
+   * when the authenticated `get machineconfig` above fails. Defaults to `false` so a bare failing
+   * `liveWrapper` (most tests) still exercises the "both reads fail → propagate" path rather than
+   * silently succeeding at the probe.
+   */
+  maintenanceReachable?: boolean;
+}) => {
+  const configText = opts.configText ?? CONFIG_TEXT;
+  return (call: FakeCall) => {
+    if (call.command === 'bao') {
+      const key = call.args[3] ?? '';
+      if (key.endsWith('/talosconfig')) {
+        return {
+          stdout: JSON.stringify({ data: { data: { talosconfig: 'fake-talosconfig-body' } } }),
+        };
+      }
+      return { stdout: JSON.stringify({ data: { data: { config: configText } } }) };
+    }
+    if (call.command === 'talosctl') {
+      if (call.args[0] === 'apply-config') return { exitCode: opts.applyExitCode ?? 0 };
+      if (call.args[0] === 'version')
+        return (opts.maintenanceReachable ?? false)
+          ? { stdout: 'Client: v1.13.10\nServer: v1.13.10\n' }
+          : { exitCode: 1, stderr: 'dial tcp: connection refused' };
+      if (call.args[0] === 'get')
+        return opts.liveWrapper?.() ?? { stdout: wrapperFor(CONFIG_TEXT) };
+    }
+    throw new Error(`dispatcher: unexpected call ${JSON.stringify(call)}`);
+  };
+};
+
+export const run = <A, E>(
+  effect: Effect.Effect<A, E, ChildProcessSpawner.ChildProcessSpawner>,
+  handler: (c: FakeCall) => { stdout?: string; stderr?: string; exitCode?: number },
+  calls: FakeCall[] = [],
+) =>
+  Effect.runPromise(
+    Effect.provideService(
+      effect,
+      ChildProcessSpawner.ChildProcessSpawner,
+      fakeSpawner(handler, calls),
+    ),
+  );
+
+/** `Data.TaggedError` stamps `_tag`, not `.message` — see talos-errors.ts. */
+export const hasTag = (tag: string) => (error: unknown) =>
+  (error as { _tag?: string } | null)?._tag === tag;