@homeflare/alchemy 0.48.1 → 0.50.0

package/src/kubernetes/ready-secrecy.test.ts

@@ -0,0 +1,131 @@
+/**
+ * Secrecy of `HomeFlare.Kubernetes.Ready`: no PEM marker, kubeconfig byte or apiserver response
+ * body reaches an attribute, an error, a log line, or a file. The vault is the fake `bao` of the
+ * adapter fixtures (it serves a kubeconfig with PEM blocks); the apiserver bodies carry a needle.
+ */
+import { expect, spyOn, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import * as Cause from 'effect/Cause';
+import * as Logger from 'effect/Logger';
+import * as References from 'effect/References';
+import type { FakeObject } from '../talos/fake-apiserver.ts';
+import { vault } from '../talos/cluster-adapter.fixtures.ts';
+import { diffReady, readReady, reconcileReady } from './ready.ts';
+import {
+  CRD_PATH,
+  DEP_PATH,
+  DS_PATH,
+  connection,
+  crdCheck,
+  depCheck,
+  driven,
+  dsCheck,
+  get,
+  readyCrd,
+  readyDep,
+  readyDs,
+  withCluster,
+} from './ready.fixtures.ts';
+
+const BODY_NEEDLE = 'apiserver-body-needle-7f3a';
+const pemMarker = `-----${'BEGIN'}`;
+const b64 = (text: string) => Buffer.from(text).toString('base64');
+const props = {
+  checks: [dsCheck, depCheck, crdCheck],
+  connection,
+  waitTimeout: '20s',
+  pollInterval: '5s',
+};
+
+// The vault's own document is the needle source: every field value the fake `bao` serves.
+const served = JSON.parse(
+  vault({ args: ['talos-c1/data/kubeconfig'], command: 'bao' }).stdout ?? '{}',
+) as {
+  data: { data: { kubeconfig: string } };
+};
+const needles = [
+  BODY_NEEDLE,
+  pemMarker,
+  served.data.data.kubeconfig,
+  b64(`${pemMarker} CERTIFICATE-----`),
+  b64(`${pemMarker} PRIVATE KEY-----`),
+  'client-key-data',
+  'certificate-authority-data',
+];
+const leaks = (text: string) => needles.filter((needle) => text.includes(needle));
+const dump = (value: unknown) =>
+  JSON.stringify(value, value instanceof Object ? Object.getOwnPropertyNames(value) : undefined) +
+  String(value);
+
+const ready: Record<string, FakeObject> = {
+  [get(CRD_PATH)]: { body: readyCrd },
+  [get(DEP_PATH)]: { body: readyDep },
+  [get(DS_PATH)]: { body: readyDs },
+};
+
+test('attributes, errors and logs of every path carry no vault or response byte', async () => {
+  const logged: string[] = [];
+  const capture = Logger.layer([
+    Logger.make(({ message }) => void logged.push(JSON.stringify(message))),
+  ]);
+  const saved = { ...console };
+  for (const level of ['log', 'debug', 'info', 'warn', 'error'] as const) {
+    console[level] = (...args: unknown[]) => void logged.push(args.map(String).join(' '));
+  }
+  const writes = [spyOn(Bun, 'write'), spyOn(Bun, 'spawn')];
+  const outputs: unknown[] = [];
+  try {
+    const attempt = async (
+      objects: Record<string, FakeObject>,
+      run: Effect.Effect<unknown, unknown, never>,
+    ) => {
+      const exit = await withCluster(
+        objects,
+        driven(
+          run.pipe(
+            Effect.provideService(References.MinimumLogLevel, 'All'),
+            Effect.provide(capture),
+          ),
+          100,
+        ) as never,
+      );
+      const result = exit as Exit.Exit<unknown, unknown>;
+      outputs.push(Exit.isSuccess(result) ? result.value : Cause.squash(result.cause));
+    };
+    const failing = (entry: FakeObject): Record<string, FakeObject> => ({
+      ...ready,
+      [get(DEP_PATH)]: { ...entry, body: { message: BODY_NEEDLE } },
+    });
+    for (const entry of [
+      { status: 200 },
+      { status: 404 },
+      { status: 503 },
+      { status: 403 },
+      { status: 429 },
+    ]) {
+      for (const run of [
+        readReady(props),
+        reconcileReady(props),
+        diffReady(props as never, { checks: '', connection, ready: false }),
+      ]) {
+        await attempt(failing(entry), run as never);
+      }
+    }
+    await attempt(ready, reconcileReady(props) as never);
+  } finally {
+    Object.assign(console, saved);
+    for (const spy of writes) {
+      expect(spy).not.toHaveBeenCalled();
+      spy.mockRestore();
+    }
+  }
+  expect(outputs.length).toBeGreaterThan(10);
+  expect(leaks(outputs.map(dump).join('\n'))).toEqual([]);
+  expect(leaks(logged.join('\n'))).toEqual([]);
+});
+
+test('the probe can fail: a response body quoted into an error is caught by the needle check', () => {
+  const quoted = new Error(`GET responded 503: ${JSON.stringify({ message: BODY_NEEDLE })}`);
+  expect(leaks(dump(quoted))).toEqual([BODY_NEEDLE]);
+});

package/src/kubernetes/ready.fixtures.ts

@@ -0,0 +1,103 @@
+/**
+ * Shared harness for the `HomeFlare.Kubernetes.Ready` tests: the REAL `talos-openbao` adapter over a
+ * fake `bao` and the fake apiserver (`talos/fake-apiserver.ts`), so uid proof, `readObject` and the
+ * TLS-free request path all run for real. Nothing leaves the process.
+ */
+import * as Effect from 'effect/Effect';
+import * as Fiber from 'effect/Fiber';
+import * as Layer from 'effect/Layer';
+import * as TestClock from 'effect/testing/TestClock';
+import * as ChildProcessSpawner from 'effect/process/ChildProcessSpawner';
+import { TalosOpenBaoAdapter, talosOpenBaoConnection } from '../talos/cluster-adapter.ts';
+import { UIDS, config, vault } from '../talos/cluster-adapter.fixtures.ts';
+import { type FakeHandler, fakeSpawner } from '../talos/fake-process.ts';
+import { type FakeObject, fakeApiServer } from '../talos/fake-apiserver.ts';
+import type { ReadyCheck } from './ready-checks.ts';
+
+export const HOST = 'c1.cluster.invalid';
+export const connection = talosOpenBaoConnection('uid-c1');
+
+export const DS_PATH = `/apis/apps/v1/namespaces/kube-system/daemonsets/cilium`;
+export const DEP_PATH = `/apis/apps/v1/namespaces/kube-system/deployments/cilium-operator`;
+export const CRD_PATH = `/apis/apiextensions.k8s.io/v1/customresourcedefinitions/x.cilium.io`;
+
+export const dsCheck: ReadyCheck = { kind: 'DaemonSet', name: 'cilium', namespace: 'kube-system' };
+export const depCheck: ReadyCheck = {
+  kind: 'Deployment',
+  name: 'cilium-operator',
+  namespace: 'kube-system',
+};
+export const crdCheck: ReadyCheck = { kind: 'CustomResourceDefinition', name: 'x.cilium.io' };
+
+export const checksOf = (): ReadyCheck[] => [dsCheck, depCheck, crdCheck];
+
+export const readyDs = {
+  metadata: { generation: 2 },
+  status: {
+    desiredNumberScheduled: 3,
+    numberAvailable: 3,
+    numberReady: 3,
+    observedGeneration: 2,
+    updatedNumberScheduled: 3,
+  },
+};
+export const readyDep = {
+  metadata: { generation: 4 },
+  spec: { replicas: 2 },
+  status: { availableReplicas: 2, observedGeneration: 4, replicas: 2, updatedReplicas: 2 },
+};
+export const readyCrd = { status: { conditions: [{ status: 'True', type: 'Established' }] } };
+
+export const get = (path: string) => `GET ${HOST}${path}`;
+
+export const IDENTITY_PATH = '/api/v1/namespaces/kube-system';
+
+/**
+ * A live table whose `key` answers `entries[n]` on the n-th request (the last one thereafter):
+ * a cluster that is flaky for a while and then recovers, without real timers.
+ */
+export const sequence = (
+  objects: Record<string, FakeObject>,
+  key: string,
+  entries: readonly (FakeObject | undefined)[],
+): Record<string, FakeObject> => {
+  let calls = 0;
+  return new Proxy(objects, {
+    get: (target, prop) => {
+      if (prop !== key) return target[prop as string];
+      return entries[Math.min(calls++, entries.length - 1)];
+    },
+  });
+};
+
+/**
+ * Run `effect` against the fake cluster. `objects` is the live table: a test may mutate it from
+ * inside `effect`. The fake `https` module is restored on every exit path.
+ */
+export const withCluster = async <A, E>(
+  objects: Record<string, FakeObject>,
+  effect: Effect.Effect<A, E, ChildProcessSpawner.ChildProcessSpawner | never>,
+  handler: FakeHandler = vault,
+) => {
+  const api = fakeApiServer(UIDS, [], objects);
+  const spawner = Layer.succeed(ChildProcessSpawner.ChildProcessSpawner, fakeSpawner(handler));
+  try {
+    const layer = Layer.mergeAll(TalosOpenBaoAdapter(config).pipe(Layer.provide(spawner)), spawner);
+    return await Effect.runPromise(
+      effect.pipe(Effect.provide(layer), Effect.provide(TestClock.layer())) as Effect.Effect<A, E>,
+    );
+  } finally {
+    api.restore();
+  }
+};
+
+/** Drive TestClock until `effect` settles (virtual seconds, no real waiting). */
+export const driven = <A, E, R>(effect: Effect.Effect<A, E, R>, seconds = 1000) =>
+  Effect.gen(function* () {
+    const fiber = yield* Effect.forkChild(Effect.exit(effect));
+    for (let i = 0; i < seconds; i++) {
+      yield* Effect.yieldNow;
+      yield* TestClock.adjust('1 second');
+    }
+    return yield* Fiber.join(fiber);
+  });

package/src/kubernetes/ready.test.ts

@@ -0,0 +1,205 @@
+/**
+ * The `HomeFlare.Kubernetes.Ready` handlers through the real adapter: read, reconcile, diff, and the
+ * failures that must propagate. Fake `bao` and fake apiserver only; time is TestClock's.
+ */
+import { expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import * as Duration from 'effect/Duration';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import * as Cause from 'effect/Cause';
+import * as Output from 'alchemy/Output';
+import { talosOpenBaoConnection } from '../talos/cluster-adapter.ts';
+import type { FakeObject } from '../talos/fake-apiserver.ts';
+import { KubernetesReady, diffReady, parseGoDuration, readReady, reconcileReady } from './ready.ts';
+import {
+  CRD_PATH,
+  DEP_PATH,
+  DS_PATH,
+  HOST,
+  connection,
+  crdCheck,
+  depCheck,
+  driven,
+  dsCheck,
+  get,
+  readyCrd,
+  readyDep,
+  readyDs,
+  withCluster,
+} from './ready.fixtures.ts';
+
+const checks = [dsCheck, depCheck, crdCheck];
+const props = (extra: object = {}) => ({ checks, connection, ...extra });
+const allReady = (): Record<string, FakeObject> => ({
+  [get(CRD_PATH)]: { body: readyCrd },
+  [get(DEP_PATH)]: { body: readyDep },
+  [get(DS_PATH)]: { body: readyDs },
+});
+const settle = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+  driven(effect, 700).pipe(
+    Effect.map((exit) =>
+      Exit.isSuccess(exit)
+        ? { ok: exit.value }
+        : { error: Cause.squash(exit.cause) as { _tag?: string } },
+    ),
+  );
+const csv = checks
+  .map((c) =>
+    c.kind === 'CustomResourceDefinition'
+      ? `${c.kind}/${c.name}`
+      : `${c.kind}/${c.namespace}/${c.name}`,
+  )
+  .join(',');
+const prior = (ready = true) => ({ checks: csv, connection, ready });
+
+test('read: ready:true when every check passes, false when one is pending (404 included)', async () => {
+  expect((await withCluster(allReady(), readReady(props()))).ready).toBe(true);
+  const stale = {
+    ...allReady(),
+    [get(DS_PATH)]: { body: { ...readyDs, status: { ...readyDs.status, observedGeneration: 1 } } },
+  };
+  expect((await withCluster(stale, readReady(props()))).ready).toBe(false);
+  const missing = { ...allReady(), [get(CRD_PATH)]: { status: 404 } };
+  expect((await withCluster(missing, readReady(props()))).ready).toBe(false);
+});
+
+test('read propagates 5xx, 429 and a hung GET (only a poll tolerates them)', async () => {
+  for (const [entry, tag] of [
+    [{ status: 503 }, 'KubernetesReadyApiError'],
+    [{ status: 429 }, 'KubernetesReadyApiError'],
+    [{ hang: true }, 'KubernetesReadyGetTimeout'],
+  ] as const) {
+    const out = await withCluster(
+      { ...allReady(), [get(DEP_PATH)]: entry },
+      settle(readReady(props())),
+    );
+    expect((out as { error: { _tag: string } }).error._tag).toBe(tag);
+  }
+});
+
+test('reconcile: all ready returns ready attributes; a never-ready check times out with its key', async () => {
+  const ok = await withCluster(allReady(), settle(reconcileReady(props())));
+  expect(ok).toEqual({ ok: { checks: csv, connection, ready: true } });
+  const bad = {
+    ...allReady(),
+    [get(DS_PATH)]: {
+      body: { ...readyDs, status: { ...readyDs.status, updatedNumberScheduled: 0 } },
+    },
+  };
+  const out = (await withCluster(
+    bad,
+    settle(reconcileReady(props({ waitTimeout: '30s', pollInterval: '5s' }))),
+  )) as {
+    error: Record<string, unknown>;
+  };
+  expect(out.error['_tag']).toBe('KubernetesReadyTimeout');
+  expect(out.error['failing']).toEqual(['DaemonSet/kube-system/cilium']);
+  expect(out.error['seconds']).toBe(30);
+});
+
+test('401 and 403 propagate through read and reconcile, never become pending', async () => {
+  for (const status of [401, 403]) {
+    const objects = { ...allReady(), [get(DS_PATH)]: { status } };
+    for (const run of [readReady(props()), reconcileReady(props())]) {
+      const out = (await withCluster(objects, settle(run))) as {
+        error: { _tag: string; statusCode: number };
+      };
+      expect(out.error).toMatchObject({ _tag: 'KubernetesReadyApiError', statusCode: status });
+    }
+  }
+});
+
+test('a bao failure propagates (a vault outage is not "not ready yet")', async () => {
+  const down = () => ({ exitCode: 2, stderr: 'permission denied' });
+  for (const run of [readReady(props()), reconcileReady(props())]) {
+    const out = (await withCluster(allReady(), settle(run), down)) as { error: Error };
+    expect(String(out.error)).not.toContain('KubernetesReadyTimeout');
+    expect(out.error).toBeDefined();
+  }
+});
+
+test('a uid mismatch is the typed identity error, before any check is read', async () => {
+  const objects = allReady();
+  const other = { ...props(), connection: talosOpenBaoConnection('uid-c1') };
+  // the apiserver answers a different kube-system uid than the pin
+  const out = await withCluster(
+    {
+      ...objects,
+      [`GET ${HOST}/api/v1/namespaces/kube-system`]: { body: { metadata: { uid: 'uid-other' } } },
+    },
+    settle(readReady(other)),
+  );
+  expect((out as { error: { _tag: string } }).error._tag).toBe('TalosClusterIdentityMismatch');
+});
+
+test('diff: noop when ready and unchanged; update when pending, changed checks or connection', async () => {
+  const run = (
+    objects: Record<string, FakeObject>,
+    output: ReturnType<typeof prior> | undefined,
+    news = props(),
+  ) => withCluster(objects, diffReady(news as never, output));
+  expect(await run(allReady(), prior())).toEqual({ action: 'noop' });
+  expect(await run(allReady(), undefined)).toBeUndefined();
+  expect(await run(allReady(), { ...prior(), checks: 'DaemonSet/kube-system/other' })).toEqual({
+    action: 'update',
+  });
+  // connection is `stables`: a changed (or missing) one REPLACES, so dependants see the new one
+  expect(
+    await run(allReady(), { ...prior(), connection: talosOpenBaoConnection('uid-c2') }),
+  ).toEqual({ action: 'replace' });
+  const { connection: _gone, ...legacy } = prior();
+  expect(await run(allReady(), legacy as never)).toEqual({ action: 'replace' });
+  const pending = { ...allReady(), [get(CRD_PATH)]: { status: 404 } };
+  expect(await run(pending, prior())).toEqual({ action: 'update' });
+});
+
+test('diff refuses a non-literal connection with the typed error, and so does declaration', async () => {
+  const bad = {
+    ...props(),
+    connection: {
+      auth: { kind: 'talos-openbao', uid: Output.literal('uid-c1') as unknown as string },
+    },
+  };
+  const error = await withCluster(allReady(), Effect.flip(diffReady(bad as never, prior())));
+  expect((error as { _tag: string })._tag).toBe('TalosUidNotLiteral');
+  const declared = await Effect.runPromise(
+    Effect.flip(KubernetesReady('x', bad as never) as never),
+  );
+  expect((declared as { _tag: string })._tag).toBe('TalosUidNotLiteral');
+});
+
+test('durations: Go style accepted, anything else typed-refused', async () => {
+  const ms = (v: string) => Effect.runPromise(parseGoDuration('waitTimeout', v));
+  expect(Duration.toMillis(await ms('10m0s'))).toBe(600_000);
+  expect(Duration.toMillis(await ms('1h30m'))).toBe(5_400_000);
+  for (const bad of ['', '10', 'ten minutes', '10m0', '1.5s', '0s', '0m0s', '0h']) {
+    const e = await Effect.runPromise(Effect.flip(parseGoDuration('waitTimeout', bad)));
+    expect(e._tag).toBe('KubernetesReadyBadDuration');
+  }
+});
+
+test('a long adversarial duration is refused fast (no polynomial backtracking)', async () => {
+  const hostiles = [`${'1'.repeat(10_000)}x`, `${'1h'.repeat(5_000)}x`, `${'9'.repeat(30)}s`];
+  for (const hostile of hostiles) {
+    const started = performance.now();
+    const e = await Effect.runPromise(Effect.flip(parseGoDuration('waitTimeout', hostile)));
+    // A generous sanity bound only (a loaded CI runner must not flake it); the regression guard is
+    // the deterministic source check below.
+    expect(performance.now() - started).toBeLessThan(1000);
+    expect(e._tag).toBe('KubernetesReadyBadDuration');
+    // The message quotes a bounded prefix, never the whole hostile value.
+    expect(e.message.length).toBeLessThan(120);
+  }
+  // ⛔ Deterministic guard for CodeQL js/polynomial-redos #18: the parser is the anchored, bounded
+  //   regex with a length cap, never the old unanchored `(\d+)([hms])` with `g`.
+  const source = readFileSync(new URL('./ready.ts', import.meta.url), 'utf8');
+  expect(source).toContain('/^(?:(\\d{1,4})h)?(?:(\\d{1,4})m)?(?:(\\d{1,6})s)?$/');
+  expect(source).toContain('MAX_DURATION_LENGTH = 20');
+  expect(source).not.toContain('(\\d+)([hms])/g');
+  // The anchored form takes h, m, s once each and in that order only.
+  for (const bad of ['5s1m', '1m1m', '1h 1m']) {
+    const e = await Effect.runPromise(Effect.flip(parseGoDuration('waitTimeout', bad)));
+    expect(e._tag).toBe('KubernetesReadyBadDuration');
+  }
+});

package/src/kubernetes/ready.ts

@@ -0,0 +1,188 @@
+/**
+ * `HomeFlare.Kubernetes.Ready` — a readiness gate other rows depend on via `after`/Output edges.
+ *
+ * ★ WHY IT EXISTS. Upstream ships no readiness resource: `Kubernetes.HelmChart` reconcile returns
+ *   when server-side apply returns, and `Apply` releases the downstream rows at that moment, so a
+ *   row chained after the Cilium chart would start before one Cilium pod runs (T10 design v3 §2).
+ * ★ SEMANTICS are `kubectl rollout status` (`ready-checks.ts`), the polling rules are in
+ *   `ready-poll.ts`. Reconcile polls to `waitTimeout`; `read`/`diff` take ONE pass, so a plan is
+ *   live (like `Talos.ClusterHealth`) but never waits.
+ * ⛔ `connection` IS A LITERAL `talos-openbao` CONNECTION, refused otherwise at declaration and in
+ *   `diff` (`literal-connection.ts`), and it is copied onto the attributes so this row is
+ *   `ClusterLike` (`stables`, as upstream's `HelmChart`). It carries a uid, never a credential.
+ * ⛔ NO SECRET REACHES ANYTHING THIS ROW WRITES: errors and attributes name check keys, counts and
+ *   an error tag + status only, never a response body.
+ * ⚠️ `delete` is a no-op and `list` is empty: the row owns nothing in the cluster.
+ *
+ * Walked against alchemy@2.0.0-beta.81 (`Kubernetes/internal/client.ts` `readObject`,
+ * `KubernetesApiError`); only the fake apiserver was used. Not exercised against a live cluster.
+ */
+import { Resource } from 'alchemy';
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import type { Output } from 'alchemy/Output';
+import * as Provider from 'alchemy/Provider';
+import * as Duration from 'effect/Duration';
+import * as Effect from 'effect/Effect';
+import type { TalosOpenBaoConnection } from '../talos/cluster-adapter.ts';
+import { literalConnectionRefusal, withLiteralConnection } from '../talos/literal-connection.ts';
+import type { TalosRequirements } from '../talos/resource.ts';
+import { type ReadyCheck, checksCsv } from './ready-checks.ts';
+import { connectForDiff, connectOnce, connectTolerant } from './ready-connect.ts';
+import { declaredReady } from './ready-declare.ts';
+import { KubernetesReadyBadDuration } from './ready-errors.ts';
+import { pass, poll } from './ready-poll.ts';
+
+export interface ReadyProps {
+  /** Literal `talos-openbao` connection (uid proven at connect). */
+  connection: TalosOpenBaoConnection;
+  checks: readonly ReadyCheck[];
+  /** Reconcile deadline, Go style. Default `10m0s`. */
+  waitTimeout?: string;
+  /** Pause between passes, Go style. Default `10s`. */
+  pollInterval?: string;
+  /**
+   * Ordering edge: lazy Outputs of the chart, e.g. `[chart.objects]`. ⛔ Not `chart.connection` or
+   * any other stable: those resolve at plan time and the row would plan `noop` before the chart
+   * updates (refused at declaration, `ready-declare.ts`).
+   */
+  after?: readonly Output<unknown>[];
+}
+
+export interface ReadyAttributes {
+  connection: TalosOpenBaoConnection;
+  ready: boolean;
+  /** The check keys, comma separated: a changed list is an `update`. */
+  checks: string;
+}
+
+export interface KubernetesReady extends Resource<
+  'HomeFlare.Kubernetes.Ready',
+  ReadyProps,
+  ReadyAttributes,
+  never,
+  TalosRequirements
+> {}
+
+// ⛔ Declaration-time literal guard: a fresh resource skips `diff` (see `withLiteralConnection`).
+export const KubernetesReady = declaredReady(
+  withLiteralConnection(Resource<KubernetesReady>('HomeFlare.Kubernetes.Ready')),
+);
+
+const HOUR_MS = 3_600_000;
+const MINUTE_MS = 60_000;
+const SECOND_MS = 1000;
+
+// ⛔ Anchored with bounded repeats, in h-m-s order: the former unanchored `(\d+)([hms])` with `g` was
+//   CodeQL js/polynomial-redos #18 once `boundedHelmChartProvider` made it reachable from exported
+//   parameters. Length is capped first, so no input can make the match slow.
+const GO_DURATION = /^(?:(\d{1,4})h)?(?:(\d{1,4})m)?(?:(\d{1,6})s)?$/;
+const MAX_DURATION_LENGTH = 20;
+
+/**
+ * `10m0s`, `90s`, `1h30m`: whole-number Go durations in h/m/s. Anything else is typed-refused.
+ * `resource` names the row in the refusal (`Kubernetes.Ready` unless the caller is another one).
+ */
+export const parseGoDuration = (field: string, value: string, resource?: string) =>
+  Effect.gen(function* () {
+    const refuse = () =>
+      Effect.fail(
+        new KubernetesReadyBadDuration({
+          field,
+          value,
+          ...(resource === undefined ? {} : { resource }),
+        }),
+      );
+    const match = value.length > MAX_DURATION_LENGTH ? null : GO_DURATION.exec(value);
+    if (match === null || value === '') return yield* refuse();
+    const [, h, m, s] = match;
+    const ms = Number(h ?? 0) * HOUR_MS + Number(m ?? 0) * MINUTE_MS + Number(s ?? 0) * SECOND_MS;
+    // A zero poll interval would spin a full pass of GETs per scheduler tick against the apiserver,
+    // and a zero wait fails before a single pass: both are refused (DeepSeek read of PR 373).
+    if (ms <= 0) return yield* refuse();
+    return Duration.millis(ms);
+  });
+
+const attributes = (props: ReadyProps, ready: boolean): ReadyAttributes => ({
+  checks: checksCsv(props.checks),
+  connection: props.connection,
+  ready,
+});
+
+/** ⚠️ A row saved before `connection` existed has none at runtime: missing means "update". */
+const sameConnection = (left: TalosOpenBaoConnection, right: TalosOpenBaoConnection | undefined) =>
+  right?.auth?.kind === left.auth.kind &&
+  right.auth.uid === left.auth.uid &&
+  !Object.hasOwn(right.auth, 'cluster');
+
+/** One pass: `ready` only when every check is ready. A terminal failure is not ready either. */
+export const readReady = (props: ReadyProps) =>
+  Effect.gen(function* () {
+    const transport = yield* connectOnce(props.connection);
+    const result = yield* pass(transport, props.checks, false);
+    return attributes(props, result.pending.length === 0 && result.failed.length === 0);
+  });
+
+/**
+ * ⛔ The `diff` pass: a transient (connect or GET) yields `undefined`, which diff turns into
+ * `update`, so a CNI rollout never fails a plan and `reconcile` does the waiting. 401/403, vault
+ * failures and a uid mismatch still propagate.
+ */
+const readReadyForDiff = (props: ReadyProps) =>
+  Effect.gen(function* () {
+    const transport = yield* connectForDiff(props.connection);
+    if (transport === undefined) return undefined;
+    const result = yield* pass(transport, props.checks, true);
+    const settled = result.pending.length === 0 && result.failed.length === 0;
+    return settled ? attributes(props, true) : undefined;
+  });
+
+export const reconcileReady = (props: ReadyProps) =>
+  Effect.gen(function* () {
+    const waitTimeout = yield* parseGoDuration('waitTimeout', props.waitTimeout ?? '10m0s');
+    const pollInterval = yield* parseGoDuration('pollInterval', props.pollInterval ?? '10s');
+    const connect = connectTolerant(props.connection, pollInterval);
+    yield* poll(connect, props.checks, waitTimeout, pollInterval);
+    return attributes(props, true);
+  });
+
+export const diffReady = (news: Input<ReadyProps>, output: ReadyAttributes | undefined) =>
+  Effect.gen(function* () {
+    // ⛔ Refuse an Output connection while it is still an Input (`literal-connection.ts`).
+    const refused = literalConnectionRefusal((news as { connection?: unknown }).connection);
+    if (refused !== undefined) return yield* Effect.fail(refused);
+    if (output === undefined || !isResolved(news)) return undefined;
+    // ⛔ `connection` is in `stables`: dependants read it off the saved row, so a changed one must
+    //   REPLACE (as upstream's HelmChart does, `HelmChart.ts:243-251`) or they would see the old
+    //   connection for one more deploy. `delete` is a no-op, so a replace touches nothing live.
+    //   A legacy row with no connection counts as changed.
+    if (!sameConnection(news.connection, output.connection)) return { action: 'replace' } as const;
+    const live = yield* readReadyForDiff(news);
+    return live !== undefined && live.checks === output.checks
+      ? ({ action: 'noop' } as const)
+      : ({ action: 'update' } as const);
+  });
+
+export const readHandler = ({
+  olds,
+  output,
+}: {
+  olds: ReadyProps;
+  output: ReadyAttributes | undefined;
+}) => (output === undefined ? Effect.succeed(undefined) : readReady(olds));
+
+const handlers = {
+  delete: () => Effect.void,
+  diff: ({ news, output }: { news: Input<ReadyProps>; output: ReadyAttributes | undefined }) =>
+    diffReady(news, output),
+  list: () => Effect.succeed([]),
+  // ⛔ No prior output means Alchemy's deferred adoption read on a first create: the row owns
+  //   nothing, so there is nothing to adopt, and a one-pass read would fail the install on the
+  //   first 5xx before `reconcile` could poll through it (round 1, finding 2).
+  read: readHandler,
+  reconcile: ({ news }: { news: ReadyProps }) => reconcileReady(news),
+  stables: ['connection'] as (keyof ReadyAttributes)[],
+};
+
+export const KubernetesReadyProvider = () =>
+  Provider.effect(KubernetesReady, Effect.succeed(KubernetesReady.Provider.of(handlers)));

package/src/talos/fake-apiserver.ts

@@ -18,11 +18,22 @@ type FakeResponse = EventEmitter & { statusCode?: number };
 
 /**
  * `uids` maps an apiserver hostname to the kube-system uid it reports; `hang` lists hostnames that
- * accept the request and never answer.
+ * accept the request and never answer. `objects` (K1, `HomeFlare.Kubernetes.Ready`) answers a
+ * `'GET host /path'` key with its `status` and JSON `body`; `hang: true` accepts and never
+ * answers, `error` fails the request like a socket error. The table is read per request, so a
+ * test may mutate it between polls.
  */
+export type FakeObject = {
+  readonly status?: number;
+  readonly body?: unknown;
+  readonly hang?: boolean;
+  readonly error?: string;
+};
+
 export const fakeApiServer = (
   uids: Readonly<Record<string, string>>,
   hang: readonly string[] = [],
+  objects: Record<string, FakeObject> = {},
 ) => {
   const seen: string[] = [];
   const fake = ((
@@ -35,13 +46,20 @@ export const fakeApiServer = (
     request.write = () => undefined;
     request.end = () => {
       if (hang.includes(options.hostname)) return;
+      const object = objects[`${options.method} ${options.hostname}${path}`];
+      if (object?.hang === true) return;
+      if (object?.error !== undefined) {
+        request.emit('error', new Error(object.error));
+        return;
+      }
       const response = new EventEmitter() as FakeResponse;
-      response.statusCode = 200;
+      response.statusCode = object?.status ?? 200;
       callback(response);
       const isIdentity = options.method === 'GET' && path === '/api/v1/namespaces/kube-system';
       const uid = isIdentity ? uids[options.hostname] : 'u1';
       const metadata = uid === undefined ? {} : { uid };
-      response.emit('data', Buffer.from(JSON.stringify({ metadata })));
+      const payload = object === undefined ? { metadata } : (object.body ?? {});
+      response.emit('data', Buffer.from(JSON.stringify(payload)));
       response.emit('end');
     };
     return request;