@homeflare/alchemy 0.38.0 → 0.40.0

package/src/talos/machine-config-poll.test.ts

@@ -0,0 +1,57 @@
+/**
+ * Bounded-poll-per-mode acceptance tests from docs/plans/2026-09-26-talos-stack-first-boot.md's
+ * "Converged" section — exercised through `reconcileMachineConfig` with `FAST_POLL` (a test-only
+ * seam, see machine-config-poll.ts's own header) so the ~10s/~2m production caps never run here.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import {
+  CONFIG_TEXT,
+  FAST_POLL,
+  dispatcher,
+  hasTag,
+  props,
+  run,
+  wrapperFor,
+} from './machine-config-fixtures.ts';
+import type { ApplyMode } from './resource.ts';
+import { reconcileMachineConfig } from './talos-machine-config.ts';
+
+describe('reconcileMachineConfig — bounded poll per mode', () => {
+  const rebootish: ApplyMode = 'reboot';
+  const immediate: ApplyMode = 'no-reboot';
+
+  it("no-reboot converges via a single successful read-back ('read-back')", async () => {
+    const out = await run(
+      reconcileMachineConfig(props({ mode: immediate }), undefined, FAST_POLL),
+      dispatcher({}),
+    );
+    assert.equal(out.converged, 'read-back');
+  });
+
+  it("reboot/auto tolerate a transient miss then converge ('accepted')", async () => {
+    let attempt = 0;
+    const out = await run(
+      reconcileMachineConfig(props({ mode: rebootish }), undefined, FAST_POLL),
+      dispatcher({
+        liveWrapper: () => {
+          attempt += 1;
+          return attempt < 2
+            ? { exitCode: 1, stderr: 'node rebooting' }
+            : { stdout: wrapperFor(CONFIG_TEXT) };
+        },
+      }),
+    );
+    assert.equal(out.converged, 'accepted');
+  });
+
+  it('raises TalosConvergenceTimeout, never a silent pass, when the cap expires', async () => {
+    await assert.rejects(
+      run(
+        reconcileMachineConfig(props({ mode: rebootish }), undefined, FAST_POLL),
+        dispatcher({ liveWrapper: () => ({ exitCode: 1, stderr: 'still unreachable' }) }),
+      ),
+      hasTag('TalosConvergenceTimeout'),
+    );
+  });
+});

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

@@ -0,0 +1,82 @@
+/**
+ * Post-apply convergence for `Talos.MachineConfig` — split out of talos-machine-config.ts
+ * (2026-09-26, K-A3) once the bounded-poll logic needed its own header. See
+ * docs/plans/2026-09-26-talos-stack-first-boot.md, "Converged" and "Bootstrap" sections.
+ *
+ * ⛔ NO SILENT `converged: false` HERE. A single attempt's own transport failure is swallowed
+ *   ONLY inside the bounded loop below — a rebooting node's API is legitimately unreachable for a
+ *   while — but the loop AS A WHOLE never swallows: running out of attempts always raises
+ *   `TalosConvergenceTimeout`, never a quiet `false`. That distinction is read()'s job, not
+ *   reconcile's — see talos-machine-config.ts.
+ * ⚠️ SHORT INTERVALS, A LOW CAP, NEVER ONE LONG SLEEP — the house timeout rule, and the specific
+ *   reason talosctl's own `health` gate has a 20-minute `--wait-timeout`: a single blocking wait
+ *   that long would hide whether THIS process is still alive from anything watching it.
+ */
+import * as Effect from 'effect/Effect';
+import type { ApplyMode } from './resource.ts';
+import { TalosConvergenceTimeout } from './talos-errors.ts';
+
+/**
+ * Modes whose apply can trigger a full install + reboot. REASONED, Talos v1.13 CLI reference.
+ * ⛔ `'staged'` is deliberately absent — resource.ts's own header explains why (fix-first #2).
+ */
+const isRebootish = (mode: ApplyMode) => mode === 'reboot' || mode === 'auto';
+
+/**
+ * ★ TWO POLICIES, ONE PER MODE CLASS — REASONED, no live cluster to time this against yet.
+ *   `no-reboot` never drops the API, so a handful of quick retries covers only ordinary
+ *   config-propagation lag. `reboot`/`auto` can drop the API for a full boot cycle, so the cap is
+ *   longer and the interval coarser. Both stay well inside the house rule above.
+ */
+export type PollPolicy = { readonly intervalMs: number; readonly maxAttempts: number };
+
+const POLICY: { readonly immediate: PollPolicy; readonly rebootish: PollPolicy } = {
+  immediate: { intervalMs: 2_000, maxAttempts: 5 }, // ~10s cap
+  rebootish: { intervalMs: 5_000, maxAttempts: 24 }, // ~2m cap
+};
+
+/**
+ * Run `check` until it reports `true` or `maxAttempts` is spent, sleeping `intervalMs` between
+ * attempts. A per-attempt failure counts as "not yet" and does not end the loop early.
+ */
+const pollUntilMatch = <E, R>(
+  check: Effect.Effect<boolean, E, R>,
+  policy: { readonly intervalMs: number; readonly maxAttempts: number },
+): Effect.Effect<boolean, never, R> =>
+  Effect.gen(function* () {
+    for (let attempt = 1; attempt <= policy.maxAttempts; attempt++) {
+      const matched = yield* check.pipe(Effect.orElseSucceed(() => false));
+      if (matched) return true;
+      if (attempt < policy.maxAttempts) yield* Effect.sleep(policy.intervalMs);
+    }
+    return false;
+  });
+
+/**
+ * Confirm convergence per `mode`'s policy, or fail with `TalosConvergenceTimeout`.
+ *
+ * Returns which CLAIM was proven, never a boolean — `'read-back'` for the immediate policy
+ * (no-reboot), `'accepted'` for the reboot-tolerant one (reboot/auto): state records which kind of
+ * confirmation actually happened, per the design doc's `converged` field.
+ *
+ * ⚠️ `policies` IS A TEST SEAM, NOT A PROP. `talos-machine-config.ts` never passes it, so
+ *   production always runs the REASONED defaults above; tests pass tiny intervals so a bounded
+ *   poll test finishes in milliseconds instead of the real ~10s/~2m caps.
+ */
+export const confirmConverged = <E, R>(
+  node: string,
+  mode: ApplyMode,
+  check: Effect.Effect<boolean, E, R>,
+  policies: { readonly immediate: PollPolicy; readonly rebootish: PollPolicy } = POLICY,
+): Effect.Effect<'read-back' | 'accepted', TalosConvergenceTimeout, R> =>
+  Effect.gen(function* () {
+    const rebootish = isRebootish(mode);
+    const policy = rebootish ? policies.rebootish : policies.immediate;
+    const matched = yield* pollUntilMatch(check, policy);
+    if (!matched) {
+      return yield* Effect.fail(
+        new TalosConvergenceTimeout({ attempts: policy.maxAttempts, mode, node }),
+      );
+    }
+    return rebootish ? 'accepted' : 'read-back';
+  });

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

@@ -0,0 +1,118 @@
+/**
+ * `Talos.MachineConfig`'s read path — split out of talos-machine-config.ts (2026-09-26, fix-first
+ * #1/#2 on PR 307's red team) once the ownership-aware read needed its own header, the same reason
+ * machine-config-poll.ts and talos-errors.ts were split out before it. Only `import type` comes
+ * back from talos-machine-config.ts, so there is no runtime cycle between the two files.
+ */
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import * as Effect from 'effect/Effect';
+import * as Result from 'effect/Result';
+import { mintTalosconfig } from './credentials.ts';
+import type { MachineConfigAttributes, MachineConfigProps } from './talos-machine-config.ts';
+import { talosctl } from './talosctl.ts';
+import { configDigest, extractMachineConfigSpec } from './values.ts';
+
+/**
+ * Single live read: `talosctl get machineconfig v1alpha1`, extract `spec`, hash it. No retry, no
+ * swallow.
+ *
+ * ⛔ THE ID IS NEVER OMITTED (fix-first #2, PR 307 red team). An unfiltered `get machineconfig`
+ *   lists `persistent` AND `v1alpha1`, sorted by id — `persistent` first — so a caller that does not
+ *   name `v1alpha1` gets whichever the SDK's `doc[0]` happens to be, never provably the applied
+ *   config (values.ts's own multi-document guard is the second half of this fix).
+ * ★ `endpoints: [props.node]` (fix-first #5, same review) — without it talosctl falls back to the
+ *   talosconfig context's own endpoints, which may be a control-plane VIP that only comes up AFTER
+ *   bootstrap; every pre-bootstrap call in this file targets the node directly instead.
+ */
+export const liveSpecDigest = (props: MachineConfigProps, talosconfigPath: string) =>
+  talosctl(['get', 'machineconfig', 'v1alpha1', '-o', 'yaml'], {
+    endpoints: [props.node],
+    nodes: [props.node],
+    talosconfigPath,
+  }).pipe(
+    Effect.flatMap((wrapperYaml) => {
+      const spec = extractMachineConfigSpec(wrapperYaml);
+      return spec === undefined
+        ? Effect.fail(
+            new Error(
+              `${props.node}: get machineconfig v1alpha1 returned no string 'spec' field — see ` +
+                'values.ts extractMachineConfigSpec for the expected shape.',
+            ),
+          )
+        : Effect.succeed(configDigest(spec));
+    }),
+  );
+
+/**
+ * ★ MAINTENANCE-MODE PROBE (fix-first #1, PR 307 red team). A freshly booted node has no
+ *   talosconfig auth yet, so the AUTHENTICATED read above fails there exactly the same way it would
+ *   against a genuinely unreachable node — the two must not be confused (a real transport failure
+ *   silently read as "not created" would let a cold-start plan skip straight past a broken node).
+ *   `--insecure` distinguishes them: REASONED from the published Talos quickstart
+ *   (`talosctl -n <ip> version --insecure` is the documented way to confirm a maintenance-mode node
+ *   before its first apply) — not measured on a live cluster. Success here means "nothing applied
+ *   yet", never "converged", and never returns config content.
+ */
+const probeMaintenanceMode = (props: MachineConfigProps, talosconfigPath: string) =>
+  talosctl(['version'], {
+    endpoints: [props.node],
+    insecure: true,
+    nodes: [props.node],
+    talosconfigPath,
+  }).pipe(
+    Effect.as(true),
+    Effect.orElseSucceed(() => false),
+  );
+
+/**
+ * ⛔ NO SWALLOWING. A transport failure here propagates as its own error (TalosError or the
+ *   shape error above) — never as `converged: false`. A false only means "read succeeded, and
+ *   genuinely differs" (docs/plans/2026-09-26-talos-stack-first-boot.md, acceptance test 3).
+ * ⛔ THREE-WAY COLD-START ANSWER, NOT TWO (fix-first #1). Alchemy's engine calls this exact
+ *   function as its adoption probe with no prior state (alchemy beta.79 Plan.ts:1302-1318) and
+ *   again to recover an interrupted create (`:1413-1450`) — both hand it nothing to distinguish
+ *   "not created" from "already configured". Answering only "attrs or error" (the shipped shape)
+ *   meant a maintenance-mode node's expected auth failure aborted the plan instead of reaching
+ *   CREATE, and a genuinely different node's matching-cluster-CA-but-wrong-content read landed as a
+ *   plain, unbranded attrs object — a silent adopt with no `adopt()`, breaking first-boot acceptance
+ *   test 1 ("zero adopts"). Now: authenticated read fails but the maintenance probe succeeds →
+ *   `undefined` (not created); authenticated read succeeds and the digest matches → plain attrs
+ *   (ours); succeeds and differs → `Unowned` (exists, not proven ours — the digest match IS this
+ *   family's ownership proof, not a state-row lookup like `ownership/probe.ts`'s generic
+ *   `ownedRead`, which answers a different question: "did OUR state row create this name", not
+ *   "does this node hold OUR pinned content"); both reads fail → the authenticated error propagates.
+ *
+ * ★ EXPORTED (like proxmox/ceph-daemon.ts's `reconcileDaemon`) so tests call it directly with a
+ *   fake `ChildProcessSpawner` instead of driving it through the full Alchemy engine.
+ */
+export const readMachineConfig = (props: MachineConfigProps) =>
+  Effect.scoped(
+    Effect.gen(function* () {
+      const credential = yield* mintTalosconfig(props.target);
+      const outcome = yield* Effect.result(liveSpecDigest(props, credential.talosconfigPath));
+      if (Result.isFailure(outcome)) {
+        const reachable = yield* probeMaintenanceMode(props, credential.talosconfigPath);
+        return reachable ? undefined : yield* Effect.fail(outcome.failure);
+      }
+      const attrs = {
+        configDigest: props.configDigest,
+        converged: outcome.success === props.configDigest ? ('read-back' as const) : false,
+        mode: props.mode ?? 'auto',
+        node: props.node,
+      } satisfies MachineConfigAttributes;
+      return attrs.converged === false ? Unowned(attrs) : attrs;
+    }),
+  );
+
+export const diffMachineConfig = (
+  news: Input<MachineConfigProps>,
+  output: MachineConfigAttributes | undefined,
+) =>
+  Effect.gen(function* () {
+    if (output === undefined || !isResolved(news)) return undefined;
+    const live = yield* readMachineConfig(news);
+    if (live !== undefined && live.converged !== false) return { action: 'noop' } as const;
+    return { action: 'update' } as const;
+  });

package/src/talos/resource.ts

@@ -29,3 +29,22 @@ export type TalosRequirements = ChildProcessSpawner.ChildProcessSpawner;
 
 /** Every resource names which cluster's OpenBao mount it uses. */
 export type WithTarget = { target: TalosTarget };
+
+/**
+ * `talosctl apply-config -m/--mode`. Lives here, not in talos-machine-config.ts, so
+ * talos-errors.ts can name it in `TalosConvergenceTimeout` without importing that file back
+ * (machine-config-poll.ts -> talos-errors.ts -> talos-machine-config.ts would cycle).
+ *
+ * ★ K-A3 DROPPED THE `insecure` PROP THAT USED TO SIT BESIDE THIS TYPE. A fixed `insecure` prop
+ *   fails in both directions (`true` breaks every later update, `false` breaks the very first
+ *   apply against a node with no talosconfig auth yet), so `Talos.MachineConfig` now derives it
+ *   itself: CREATE (`output === undefined`) applies `--insecure`, UPDATE never does.
+ * ⛔ `'staged'` AND `'try'` ARE DROPPED (fix-first #2, PR 307 red team). `try` reverts itself after
+ *   its timeout, so a bounded poll that later reads the reverted config would see it never match
+ *   the pin and re-run `apply-config` on every deploy — the poll would be "confirming" a change
+ *   `try` had already undone. `staged` defers the write to the NEXT reboot rather than applying it,
+ *   which `isRebootish` (machine-config-poll.ts) cannot honestly claim `'accepted'` for without a
+ *   reboot ever happening — the reboot for a staged config is a separate, later operator action
+ *   this package does not drive. Both need their own design work, not a poll-policy guess.
+ */
+export type ApplyMode = 'auto' | 'no-reboot' | 'reboot';

package/src/talos/secrets-gate.test.ts

@@ -0,0 +1,63 @@
+/**
+ * Acceptance test 2 from docs/plans/2026-09-26-talos-secrets-flow.md: "no talos prop, attribute or
+ * argv carries config bytes; state fixtures contain no PEM or token strings (grep gate in the
+ * family's tests)." PR 307 shipped every other acceptance test from the design suite but not this
+ * one (PR 307 red team, minor #4) — the builder's "every acceptance test covered" claim was wrong.
+ *
+ * ★ A POSITIVE CONTROL WOULD DEFEAT THE PURPOSE HERE. Unlike lxc-interior.test.ts's "prove PVE
+ *   really has no such endpoint", this file's job is to prove NOTHING in this family's own source
+ *   ever grew a byte-carrying field — there is no "real" case where a match should be found. The
+ *   props/attributes shape checks are the load-bearing half: they fail loudly if a `config` or
+ *   `configFile` field is ever added back next to `configKey`/`configDigest`.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import type { MachineConfigAttributes, MachineConfigProps } from './talos-machine-config.ts';
+
+const TALOS_DIR = import.meta.dir;
+
+/** Every `.ts` file this family owns — source, tests and fixtures alike. Never node_modules. */
+const talosFiles = () =>
+  readdirSync(TALOS_DIR)
+    .filter((name) => name.endsWith('.ts'))
+    .map((name) => join(TALOS_DIR, name));
+
+describe('secrets gate — acceptance test 2', () => {
+  it('no file in this family embeds PEM material or a bootstrap-token shape', () => {
+    const pem = /-----BEGIN [A-Z ]+-----/;
+    // `talosctl gen secrets`' bootstrap token is a `<14>.<28>` lowercase-alnum id.secret pair
+    // (REASONED from the published config schema) — never generated anywhere in this family.
+    const bootstrapToken = /\b[a-z0-9]{14}\.[a-z0-9]{28}\b/;
+    for (const file of talosFiles()) {
+      const text = readFileSync(file, 'utf8');
+      assert.equal(pem.test(text), false, `${file}: looks like it embeds a PEM block`);
+      assert.equal(
+        bootstrapToken.test(text),
+        false,
+        `${file}: looks like it embeds a bootstrap token`,
+      );
+    }
+  });
+
+  it('MachineConfigProps carries a key and a digest, never config bytes', () => {
+    const sample: MachineConfigProps = {
+      configDigest: 'x',
+      configKey: 'nodes/10001',
+      node: '198.51.100.10',
+      target: { cluster: 'c1', mount: 'talos-c1' },
+    };
+    assert.deepEqual(Object.keys(sample).sort(), ['configDigest', 'configKey', 'node', 'target']);
+  });
+
+  it('MachineConfigAttributes carries a digest and a claim, never config bytes', () => {
+    const sample: MachineConfigAttributes = {
+      configDigest: 'x',
+      converged: false,
+      mode: 'auto',
+      node: '198.51.100.10',
+    };
+    assert.deepEqual(Object.keys(sample).sort(), ['configDigest', 'converged', 'mode', 'node']);
+  });
+});

package/src/talos/talos-bootstrap-etcd.ts

@@ -0,0 +1,71 @@
+/**
+ * `Talos.Bootstrap`'s etcd-members probe and split-brain guard — split out of talos-bootstrap.ts
+ * (LAND, 2026-09-26, I4 fix) once adding the guard pushed that file over the 250-line cap, the same
+ * reason machine-config-read.ts was split out of talos-machine-config.ts before it. Only
+ * `import type` comes back from talos-bootstrap.ts, so there is no runtime cycle between the files.
+ */
+import * as Effect from 'effect/Effect';
+import type { BootstrapProps } from './talos-bootstrap.ts';
+import { TalosReBootstrapRefused } from './talos-errors.ts';
+import { talosctl } from './talosctl.ts';
+
+/**
+ * REASONED: `talosctl get etcdmembers -o json` should list members after bootstrap.
+ * ⚠️ NOT MEASURED — first live deploy confirms the resource type name.
+ * ⛔ NO SWALLOWING (K-talos-first-boot) — a transport failure propagates as its own error; only a
+ *   SUCCESSFUL read may conclude presence or absence. Every caller decides for itself what a
+ *   failure here means (talos-bootstrap.ts's `read`/`reconcile`, and `assertNoLivePeers` below), so
+ *   it is not decided here.
+ */
+export const isBootstrapped = (props: BootstrapProps, talosconfigPath: string) =>
+  talosctl(['get', 'etcdmembers', '-o', 'json'], {
+    nodes: [props.node],
+    talosconfigPath,
+  }).pipe(Effect.map((text) => text.includes('"id"') || text.includes('"member"')));
+
+/**
+ * ⛔ I4 FIX (LAND red team, 2026-09-26) — THE CREATE PATH ONLY CHECKED THIS NODE. If the state row
+ *   is lost (wrong `--stage`, an FQN rename, a wiped state store) while the cluster already lives on
+ *   OTHER control-plane nodes, the cold-start adoption read on THIS node comes back empty, plan
+ *   calls `create`, and `talosctl bootstrap` runs here too — a SECOND, isolated etcd cluster: split
+ *   brain. Before bootstrapping, every OTHER declared control-plane node (`props.peers`) must show a
+ *   successful, EMPTY etcd-members read — proof no cluster already exists anywhere this row knows
+ *   about. A peer that already has members, or a peer whose read fails, refuses bootstrap exactly
+ *   like an already-bootstrapped confirmation failure does (same typed error, same "hand it to a
+ *   human" posture) — a genuinely fresh cluster has no peers with members yet, so this never blocks
+ *   a real first boot.
+ * ⚠️ `peers` IS OPTIONAL, SO THIS GUARD IS OPT-IN — an existing single-control-plane declaration
+ *   keeps working unguarded; a consuming stack with more than one control-plane node (decision 66:
+ *   3, one per TB4 node) SHOULD list the other two here to get the protection.
+ * ★ `Effect.all` over a mapped array, not `Effect.forEach` — oxlint's unicorn/no-array-for-each
+ *   matches the method NAME and cannot tell Effect's from Array's (same pattern as
+ *   openbao/cloudflare-permission-groups.ts).
+ */
+export const assertNoLivePeers = (props: BootstrapProps, talosconfigPath: string) =>
+  Effect.all(
+    (props.peers ?? []).map((peer) =>
+      isBootstrapped({ ...props, node: peer }, talosconfigPath).pipe(
+        Effect.matchEffect({
+          onFailure: (cause) =>
+            Effect.fail(
+              new TalosReBootstrapRefused({
+                detail: `peer ${peer}: live read failed before bootstrap: ${String(cause)}`,
+                node: props.node,
+              }),
+            ),
+          onSuccess: (hasMembers) =>
+            hasMembers
+              ? Effect.fail(
+                  new TalosReBootstrapRefused({
+                    detail:
+                      `peer ${peer} already reports etcd members — a cluster may already exist; ` +
+                      'refusing to bootstrap a second one',
+                    node: props.node,
+                  }),
+                )
+              : Effect.void,
+        }),
+      ),
+    ),
+    { discard: true },
+  );

package/src/talos/talos-bootstrap.test.ts

@@ -0,0 +1,218 @@
+/**
+ * `Talos.Bootstrap` "once means once" — docs/plans/2026-09-26-talos-stack-first-boot.md's
+ * acceptance test 4, K-talos-first-boot. Fully offline: fake-process.ts fakes `bao`/`talosctl`,
+ * nothing real spawns.
+ */
+import assert from 'node:assert/strict';
+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 {
+  diffBootstrap as diff,
+  readBootstrap as read,
+  reconcileBootstrap as reconcile,
+} from './talos-bootstrap.ts';
+
+const TARGET = { cluster: 'c1', mount: 'talos-c1' };
+const props = () => ({ node: '198.51.100.10', target: TARGET });
+
+const bootstrapped = () => (call: FakeCall) => {
+  if (call.command === 'bao')
+    return { stdout: JSON.stringify({ data: { data: { talosconfig: 'x' } } }) };
+  if (call.args[0] === 'get') return { stdout: '{"id":"member-1"}' };
+  throw new Error(`unexpected call ${JSON.stringify(call)}`);
+};
+
+/** Absent until `bootstrap` is spawned, then present — models the CREATE path's before/after read. */
+const notBootstrapped = () => {
+  let ranBootstrap = false;
+  return (call: FakeCall) => {
+    if (call.command === 'bao')
+      return { stdout: JSON.stringify({ data: { data: { talosconfig: 'x' } } }) };
+    if (call.args[0] === 'bootstrap') {
+      ranBootstrap = true;
+      return {};
+    }
+    if (call.args[0] === 'get') return { stdout: ranBootstrap ? '{"id":"member-1"}' : '[]' };
+    throw new Error(`unexpected call ${JSON.stringify(call)}`);
+  };
+};
+
+const etcdReadFails = () => (call: FakeCall) => {
+  if (call.command === 'bao')
+    return { stdout: JSON.stringify({ data: { data: { talosconfig: 'x' } } }) };
+  if (call.args[0] === 'get') return { exitCode: 1, stderr: 'dial tcp: connection refused' };
+  throw new Error(`unexpected call ${JSON.stringify(call)}`);
+};
+
+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('read — answers presence/absence, no swallowing', () => {
+  it('returns undefined (absence) on a successful read with no members', async () => {
+    const result = await run(read(props()), notBootstrapped());
+    assert.equal(result, undefined);
+  });
+
+  it('returns attrs when members are present', async () => {
+    const result = await run(read(props()), bootstrapped());
+    assert.deepEqual(result, { bootstrapped: true, node: props().node });
+  });
+
+  it('propagates a transport failure instead of reporting absence', async () => {
+    await assert.rejects(run(read(props()), etcdReadFails()));
+  });
+});
+
+describe('diff — trusts state, never touches the live cluster once bootstrapped', () => {
+  it('reports noop for output.bootstrapped=true WITHOUT any live call', async () => {
+    const calls: FakeCall[] = [];
+    const result = await run(
+      diff(props(), { bootstrapped: true, node: props().node }),
+      etcdReadFails(), // would reject if actually called
+      calls,
+    );
+    assert.deepEqual(result, { action: 'noop' });
+    assert.equal(calls.length, 0, 'diff must not call bao/talosctl once bootstrapped is true');
+  });
+
+  it('returns undefined (defer) when there is no prior output', async () => {
+    const result = await run(diff(props(), undefined), bootstrapped());
+    assert.equal(result, undefined);
+  });
+});
+
+describe('reconcile — once means once (acceptance test 4)', () => {
+  it('CREATE path (output undefined): bootstraps once when absent', async () => {
+    const calls: FakeCall[] = [];
+    const result = await run(reconcile(props(), undefined), notBootstrapped(), calls);
+    assert.deepEqual(result, { bootstrapped: true, node: props().node });
+    assert.equal(calls.filter((c) => c.args[0] === 'bootstrap').length, 1);
+  });
+
+  it('CREATE path: already bootstrapped (adopted) never spawns bootstrap', async () => {
+    const calls: FakeCall[] = [];
+    await run(reconcile(props(), undefined), bootstrapped(), calls);
+    assert.ok(calls.every((c) => c.args[0] !== 'bootstrap'));
+  });
+
+  it('a failing confirmation read against bootstrapped state never spawns bootstrap, and refuses', async () => {
+    const calls: FakeCall[] = [];
+    await assert.rejects(
+      run(reconcile(props(), { bootstrapped: true, node: props().node }), etcdReadFails(), calls),
+      (error: unknown) => (error as { _tag?: string } | null)?._tag === 'TalosReBootstrapRefused',
+    );
+    assert.ok(
+      calls.every((c) => c.args[0] !== 'bootstrap'),
+      'never re-bootstrap on a failing read',
+    );
+  });
+
+  it('an empty (successful) confirmation read against bootstrapped state never spawns bootstrap, and refuses', async () => {
+    const calls: FakeCall[] = [];
+    await assert.rejects(
+      run(reconcile(props(), { bootstrapped: true, node: props().node }), notBootstrapped(), calls),
+      (error: unknown) => (error as { _tag?: string } | null)?._tag === 'TalosReBootstrapRefused',
+    );
+    assert.ok(
+      calls.every((c) => c.args[0] !== 'bootstrap'),
+      'never re-bootstrap on an empty read',
+    );
+  });
+
+  it('a successful confirmation read against bootstrapped state confirms without spawning bootstrap', async () => {
+    const calls: FakeCall[] = [];
+    const result = await run(
+      reconcile(props(), { bootstrapped: true, node: props().node }),
+      bootstrapped(),
+      calls,
+    );
+    assert.deepEqual(result, { bootstrapped: true, node: props().node });
+    assert.ok(calls.every((c) => c.args[0] !== 'bootstrap'));
+  });
+});
+
+describe('reconcile — I4 fix: split-brain peer guard (acceptance-adjacent, LAND red team)', () => {
+  const propsWithPeers = () => ({
+    node: '198.51.100.10',
+    peers: ['198.51.100.11', '198.51.100.12'],
+    target: TARGET,
+  });
+
+  const nodeArg = (call: FakeCall) => {
+    const idx = call.args.indexOf('--nodes');
+    return idx === -1 ? undefined : call.args[idx + 1];
+  };
+
+  it('bootstraps once every peer proves genuinely empty', async () => {
+    const calls: FakeCall[] = [];
+    const handler = (call: FakeCall) => {
+      if (call.command === 'bao')
+        return { stdout: JSON.stringify({ data: { data: { talosconfig: 'x' } } }) };
+      if (call.args[0] === 'bootstrap') return {};
+      if (call.args[0] === 'get') {
+        const target = nodeArg(call);
+        const ranBootstrap = calls.some((c) => c.args[0] === 'bootstrap');
+        return target === propsWithPeers().node
+          ? { stdout: ranBootstrap ? '{"id":"member-1"}' : '[]' }
+          : { stdout: '[]' }; // both peers stay empty the whole time
+      }
+      throw new Error(`unexpected call ${JSON.stringify(call)}`);
+    };
+    const result = await run(reconcile(propsWithPeers(), undefined), handler, calls);
+    assert.deepEqual(result, { bootstrapped: true, node: propsWithPeers().node });
+    assert.equal(calls.filter((c) => c.args[0] === 'bootstrap').length, 1);
+  });
+
+  it('refuses, and never spawns bootstrap, when a peer already reports etcd members', async () => {
+    const calls: FakeCall[] = [];
+    const handler = (call: FakeCall) => {
+      if (call.command === 'bao')
+        return { stdout: JSON.stringify({ data: { data: { talosconfig: 'x' } } }) };
+      if (call.args[0] === 'get') {
+        return nodeArg(call) === '198.51.100.11'
+          ? { stdout: '{"id":"member-1"}' }
+          : { stdout: '[]' };
+      }
+      throw new Error(`unexpected call ${JSON.stringify(call)}`);
+    };
+    await assert.rejects(
+      run(reconcile(propsWithPeers(), undefined), handler, calls),
+      (error: unknown) => (error as { _tag?: string } | null)?._tag === 'TalosReBootstrapRefused',
+    );
+    assert.ok(
+      calls.every((c) => c.args[0] !== 'bootstrap'),
+      'a peer that may already anchor a cluster must never see a second bootstrap',
+    );
+  });
+
+  it('refuses, and never spawns bootstrap, when a peer read fails', async () => {
+    const calls: FakeCall[] = [];
+    const handler = (call: FakeCall) => {
+      if (call.command === 'bao')
+        return { stdout: JSON.stringify({ data: { data: { talosconfig: 'x' } } }) };
+      if (call.args[0] === 'get') {
+        return nodeArg(call) === '198.51.100.11'
+          ? { exitCode: 1, stderr: 'dial tcp: connection refused' }
+          : { stdout: '[]' };
+      }
+      throw new Error(`unexpected call ${JSON.stringify(call)}`);
+    };
+    await assert.rejects(
+      run(reconcile(propsWithPeers(), undefined), handler, calls),
+      (error: unknown) => (error as { _tag?: string } | null)?._tag === 'TalosReBootstrapRefused',
+    );
+    assert.ok(calls.every((c) => c.args[0] !== 'bootstrap'));
+  });
+});