@homeflare/alchemy 0.48.1 → 0.50.0

package/src/cloudflare/saas-oidc.ts

@@ -0,0 +1,107 @@
+/**
+ * `HomeFlare.Access.SaasOidcApplication` — a Cloudflare Access SaaS application that makes Access an
+ * OIDC identity provider for one relying party (OpenBao's JWT/OIDC auth, Headlamp, a Kubernetes
+ * API server). Usage and the secret rules: docs/saas-oidc.md.
+ *
+ * 🔴 WHY THIS EXISTS ALONGSIDE `Cloudflare.Access.Application`. Alchemy beta.81's Application has
+ *   no `saas_app` field (its source mentions `saas` only as a type and in two comments), and
+ *   `@distilled.cloud/cloudflare` rc.13 decodes a saas app's GET and create response WITHOUT it, so
+ *   the client id cannot be read back through either. See saas-oidc-api.ts.
+ *
+ * ⛔ THE TYPE ID IS A STATE KEY, AND THIS ONE WAS MOVED, NOT RENAMED. It is the string the
+ *   homeflare-openbao stack's live `OpenBaoOidcSaas` row was written under. A different string would
+ *   make the next plan see a new resource and an orphaned one: a second OIDC app, with a new
+ *   client id and `aud`, and a delete of the live one unless it were retained. `tests` pin it.
+ *
+ * ★ `retain` BY DEFAULT, like every kit resource whose deletion breaks its consumers: deleting the
+ *   app deletes the client id every relying party is configured with. The openbao declaration
+ *   already pipes `RemovalPolicy.retain()`; `delete` stays fully implemented for a declaration
+ *   that opts in with `.pipe(RemovalPolicy.destroy())`.
+ */
+import { Credentials } from '@distilled.cloud/cloudflare/Credentials';
+import * as Cloudflare from 'alchemy/Cloudflare';
+import * as Provider from 'alchemy/Provider';
+import { Resource, type ResourceClass } from 'alchemy/Resource';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as HttpClient from 'effect/http/HttpClient';
+import type { Providers } from './providers.ts';
+import { deleteSaasOidc, readSaasOidc, reconcileSaasOidc } from './saas-oidc-lifecycle.ts';
+import type { SaasOidcApplicationAttributes, SaasOidcApplicationProps } from './saas-oidc-form.ts';
+
+export interface SaasOidcApplication extends Resource<
+  'HomeFlare.Access.SaasOidcApplication',
+  SaasOidcApplicationProps,
+  SaasOidcApplicationAttributes,
+  never,
+  Providers
+> {}
+
+export const SaasOidcApplication: ResourceClass<SaasOidcApplication> =
+  Resource<SaasOidcApplication>('HomeFlare.Access.SaasOidcApplication', {
+    defaultRemovalPolicy: 'retain',
+  });
+
+const accountId = Effect.gen(function* () {
+  const resolved = yield* yield* Cloudflare.CloudflareEnvironment;
+  return resolved.accountId;
+});
+
+/**
+ * ★ `Provider.effect`, CAPTURING THE THREE SERVICES AT BUILD, as MeshNodeProvider does
+ *   (mesh-node.ts): correct whether or not the stack also merges `Cloudflare.providers()`.
+ */
+export const SaasOidcApplicationProvider = () =>
+  Provider.effect(
+    SaasOidcApplication,
+    Effect.gen(function* () {
+      const services = Context.make(
+        Cloudflare.CloudflareEnvironment,
+        yield* Cloudflare.CloudflareEnvironment,
+      ).pipe(
+        Context.add(Credentials, yield* Credentials),
+        Context.add(HttpClient.HttpClient, yield* HttpClient.HttpClient),
+      );
+      // ★ Only the three captured services are provided; `createPhysicalName` still takes
+      //   InstanceId, Stack and Stage from the engine at call time, as in every Alchemy provider.
+      const run = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+        Effect.provideContext(effect, services);
+
+      return SaasOidcApplication.Provider.of({
+        /**
+         * ★ THE ISSUER AND EVERY ENDPOINT ARE STABLE. They depend only on the team domain and the
+         *   client id, and `checkTeam` refuses any team other than the app's own host, so no update
+         *   of this app can move them. Alchemy's plan (Plan.ts `withStables`, beta.81) keeps ONLY
+         *   the listed attributes resolved for consumers of an updated resource; without them, a
+         *   redirect-URI change would leave `app.issuer` unresolved and re-plan every consumer
+         *   (the Talos KubeAuthenticationConfig, so a kube-apiserver restart on each node).
+         * ⚠️ `teamDomain` is NOT listed: state written by the openbao copy has no such attribute,
+         *   so a consumer would read `undefined` on the first plan after the move.
+         */
+        stables: [
+          'applicationId',
+          'aud',
+          'clientId',
+          'accountId',
+          'issuer',
+          'authorizationEndpoint',
+          'tokenEndpoint',
+          'jwksEndpoint',
+          'userinfoEndpoint',
+          'configurationEndpoint',
+        ],
+        /**
+         * ⛔ EMPTY, AND `nuke.skip`. Alchemy's own `Cloudflare.Access.Application` already lists
+         *   every Access application in the account for `alchemy unsafe nuke` (its `list`, saas
+         *   apps included); a second listing here would make nuke delete each app twice.
+         */
+        list: () => Effect.succeed([]),
+        nuke: { skip: true },
+        read: ({ id, olds, output }) =>
+          run(Effect.flatMap(accountId, (account) => readSaasOidc(account, id, olds, output))),
+        reconcile: ({ id, news, output }) =>
+          run(Effect.flatMap(accountId, (account) => reconcileSaasOidc(account, id, news, output))),
+        delete: ({ output }) => run(deleteSaasOidc(output)),
+      });
+    }),
+  );

package/src/kubernetes/helm-chart-bounded.test.ts

@@ -0,0 +1,242 @@
+/**
+ * `boundedHelmChartProvider` THROUGH upstream's real `HelmChartProvider`, the real `talos-openbao`
+ * adapter, a fake `bao`, a fake `helm` and the fake apiserver (`talos/fake-apiserver.ts`): a PATCH
+ * that never answers must fail reconcile with the typed timeout, a fast apply must return what
+ * upstream returns, and the layer must be the DIRECT `Provider(HelmChart)` registration.
+ * Deadlines are real (1s): the fake request holds no timer, so nothing stays blocked.
+ */
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { expect, test } from 'bun:test';
+import * as NodeServices from '@effect/platform-node/NodeServices';
+import { HelmChart, HelmChartProvider } from 'alchemy/Kubernetes/HelmChart';
+import * as Kubernetes from 'alchemy/Kubernetes';
+import * as Provider from 'alchemy/Provider';
+import { AlchemyContext } from 'alchemy/AlchemyContext';
+import { Stack } from 'alchemy/Stack';
+import * as Cause from 'effect/Cause';
+import * as Duration from 'effect/Duration';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import * as Layer from 'effect/Layer';
+import * as Option from 'effect/Option';
+import * as ChildProcessSpawner from 'effect/process/ChildProcessSpawner';
+import { TalosOpenBaoAdapter, talosOpenBaoConnection } from '../talos/cluster-adapter.ts';
+import { UIDS, config, helmRow, session, vault } from '../talos/cluster-adapter.fixtures.ts';
+import { fakeApiServer } from '../talos/fake-apiserver.ts';
+import { type FakeHandler, fakeSpawner } from '../talos/fake-process.ts';
+import {
+  HELM_READ_TIMEOUT,
+  HELM_RECONCILE_TIMEOUT,
+  KubernetesReadyBadDuration,
+  boundedHelmChartProvider,
+  isBoundedHelmChartProvider,
+} from './index.ts';
+import { parseGoDuration } from './ready.ts';
+import { KubernetesReconcileTimeout } from './helm-chart-bounded.ts';
+
+const HOST = 'c1.cluster.invalid';
+const NS_PATH = '/api/v1/namespaces/ns-c1';
+const RENDERED = 'apiVersion: v1\nkind: Namespace\nmetadata:\n  name: ns-c1\n';
+
+// The fake `helm` answers the render; every other command is the fake vault's.
+const handler: FakeHandler = (call) =>
+  call.args[0] === 'template' ? { stdout: RENDERED } : vault(call);
+const spawner = Layer.succeed(ChildProcessSpawner.ChildProcessSpawner, fakeSpawner(handler));
+const services = Layer.mergeAll(
+  NodeServices.layer,
+  TalosOpenBaoAdapter(config).pipe(Layer.provide(spawner)),
+  // ⚠️ Last, so the fake spawner shadows NodeServices' real one: no real `helm` or `bao` runs.
+  spawner,
+);
+
+// Kubernetes.providers() builds workload providers that read the ambient Stack at build time.
+const stack = Layer.mergeAll(
+  Layer.succeed(Stack, { name: 'bounded-test', stage: 'test' } as never),
+  Layer.succeed(AlchemyContext, {
+    adopt: false,
+    dev: false,
+    dotAlchemy: join(tmpdir(), 'hf-bounded'),
+  }),
+);
+
+const CHART = 'oci://example.invalid/chart';
+const news = {
+  chart: CHART,
+  cluster: talosOpenBaoConnection('uid-c1'),
+  releaseName: 'r',
+} as never;
+
+type Service = Provider.ProviderService<HelmChart>;
+const run = <A, E>(
+  // The requirements (spawner, FileSystem, Stack...) are all supplied by `services`/`stack` below.
+  provider: Layer.Layer<Provider.Provider<HelmChart>, never, unknown>,
+  body: (s: Service) => Effect.Effect<A, E, never>,
+) =>
+  Effect.runPromise(
+    Effect.gen(function* () {
+      return yield* body((yield* Provider.Provider<HelmChart>(HelmChart.Type)) as Service);
+    }).pipe(Effect.provide(Layer.provideMerge(provider, services))) as Effect.Effect<A, E>,
+  );
+const reconcile = (s: Service) =>
+  s.reconcile({ id: 'cilium', news, output: undefined, session } as never);
+
+test('a PATCH that never answers fails reconcile with the typed timeout inside the deadline', async () => {
+  const api = fakeApiServer(UIDS, [], { [`PATCH ${HOST}${NS_PATH}`]: { hang: true } });
+  const started = Date.now();
+  try {
+    // ★ Distinct deadlines: swapping the two (reconcile on the read bound) would wait an hour.
+    const failure = await run(boundedHelmChartProvider('1s', '1h'), (s) =>
+      reconcile(s).pipe(Effect.flip),
+    );
+    expect(failure).toBeInstanceOf(KubernetesReconcileTimeout);
+    expect(failure).toMatchObject({
+      _tag: 'KubernetesReconcileTimeout',
+      id: 'cilium',
+      operation: 'reconcile',
+      seconds: 1,
+    });
+    expect(Date.now() - started).toBeLessThan(4000);
+    expect(api.seen).toContain(`PATCH ${HOST}${NS_PATH}`);
+    // The message names the row and the seconds, nothing the server said.
+    expect(String(failure)).toBe(
+      'KubernetesReconcileTimeout: Kubernetes.HelmChart cilium: reconcile did not finish within 1s (the apiserver stopped answering)',
+    );
+  } finally {
+    api.restore();
+  }
+});
+
+test('a read whose identity GET never answers fails with the typed timeout on the read bound', async () => {
+  const api = fakeApiServer(UIDS, [HOST]);
+  try {
+    const failure = await run(boundedHelmChartProvider('1h', '1s'), (s) =>
+      (s.read as NonNullable<Service['read']>)
+        .call(s, {
+          id: 'cilium',
+          olds: undefined,
+          output: helmRow({ uid: 'uid-c1' }),
+          session,
+        } as never)
+        .pipe(Effect.flip),
+    );
+    expect(failure).toMatchObject({
+      _tag: 'KubernetesReconcileTimeout',
+      operation: 'read',
+      seconds: 1,
+    });
+  } finally {
+    api.restore();
+  }
+});
+
+test('a fast apply returns exactly the attributes upstream returns', async () => {
+  const api = fakeApiServer(UIDS);
+  try {
+    const bounded = await run(boundedHelmChartProvider(), reconcile);
+    const upstream = await run(HelmChartProvider(), reconcile);
+    expect(bounded).toEqual(upstream);
+    expect(bounded).toMatchObject({ releaseName: 'r', namespace: 'default', chart: CHART });
+    expect(api.seen.some((call) => call.startsWith('PATCH '))).toBe(true);
+  } finally {
+    api.restore();
+  }
+});
+
+test('stables, aliases, diff and delete are upstream by spread', async () => {
+  const [bounded, upstream] = await Promise.all([
+    run(boundedHelmChartProvider(), (s) => Effect.succeed(s)),
+    run(HelmChartProvider(), (s) => Effect.succeed(s)),
+  ]);
+  expect(bounded.stables).toEqual(upstream.stables);
+  expect(bounded.aliases).toEqual(upstream.aliases);
+  expect(Object.keys(bounded).sort()).toEqual(Object.keys(upstream).sort());
+  expect(typeof bounded.diff).toBe('function');
+  expect(typeof bounded.delete).toBe('function');
+});
+
+test('the deadlines are pinned: reconcile 5m0s, read 1m, and they parse as such', async () => {
+  expect(HELM_RECONCILE_TIMEOUT).toBe('5m0s');
+  expect(HELM_READ_TIMEOUT).toBe('1m0s');
+  const ms = (v: string) =>
+    Effect.runPromise(parseGoDuration('x', v)).then((d) => Duration.toMillis(d));
+  expect(await ms(HELM_RECONCILE_TIMEOUT)).toBe(300_000);
+  expect(await ms(HELM_READ_TIMEOUT)).toBe(60_000);
+});
+
+test('a malformed deadline dies at layer build naming Kubernetes.HelmChart and the field', async () => {
+  const dies = async (reconcileTimeout: string, readTimeout: string) => {
+    const exit = await Effect.runPromiseExit(
+      Effect.gen(function* () {
+        return yield* Provider.Provider<HelmChart>(HelmChart.Type);
+      }).pipe(
+        Effect.provide(
+          Layer.provideMerge(boundedHelmChartProvider(reconcileTimeout, readTimeout), services),
+        ),
+      ) as Effect.Effect<unknown>,
+    );
+    return Exit.isFailure(exit) ? Cause.squash(exit.cause) : undefined;
+  };
+  const reconcileBad = await dies('soon', '1m0s');
+  expect(reconcileBad).toBeInstanceOf(KubernetesReadyBadDuration);
+  expect((reconcileBad as Error).message).toBe(
+    "Kubernetes.HelmChart: reconcileTimeout 'soon' is not a duration like 10m0s",
+  );
+  const readBad = await dies('5m0s', '0s');
+  expect((readBad as Error).message).toBe(
+    "Kubernetes.HelmChart: readTimeout '0s' is not a duration like 10m0s",
+  );
+});
+
+test('an apiserver refusal passes through body-free (the needle never leaves)', async () => {
+  const needle = 'NEEDLE-secret-body-9f3a';
+  const api = fakeApiServer(UIDS, [], {
+    [`PATCH ${HOST}${NS_PATH}`]: { body: { message: needle }, status: 422 },
+  });
+  try {
+    const failure = await run(boundedHelmChartProvider(), (s) => reconcile(s).pipe(Effect.flip));
+    expect(failure).toMatchObject({ _tag: 'KubernetesReadyApiError', statusCode: 422 });
+    expect(String(failure)).not.toContain(needle);
+    expect(JSON.stringify(failure)).not.toContain(needle);
+    expect((failure as Error).message).toBe(
+      `Kubernetes.Ready: PATCH ${NS_PATH}?fieldManager=alchemy&force=true responded 422`,
+    );
+  } finally {
+    api.restore();
+  }
+});
+
+test('isBoundedHelmChartProvider is true for the wrapper and false for upstream', async () => {
+  const [bounded, upstream] = await Promise.all([
+    run(boundedHelmChartProvider(), (s) => Effect.succeed(s)),
+    run(HelmChartProvider(), (s) => Effect.succeed(s)),
+  ]);
+  expect(isBoundedHelmChartProvider(bounded)).toBe(true);
+  expect(isBoundedHelmChartProvider(upstream)).toBe(false);
+  expect(isBoundedHelmChartProvider(undefined)).toBe(false);
+  expect(isBoundedHelmChartProvider({ ...bounded })).toBe(false);
+});
+
+test('merged beside Kubernetes.providers() the engine-resolved service enforces the deadline', async () => {
+  const layer = Layer.mergeAll(Kubernetes.providers(), boundedHelmChartProvider('1s', '1h'));
+  const api = fakeApiServer(UIDS, [], { [`PATCH ${HOST}${NS_PATH}`]: { hang: true } });
+  try {
+    const found = await Effect.runPromise(
+      Effect.gen(function* () {
+        const registered = yield* Provider.tryFindProviderRegistrationByType<HelmChart>(
+          HelmChart.Type,
+        );
+        if (Option.isNone(registered)) return yield* Effect.die('no registration');
+        const service = registered.value as unknown as Service;
+        const failure = yield* reconcile(service).pipe(Effect.flip);
+        return { failure, marked: isBoundedHelmChartProvider(service) };
+      }).pipe(
+        Effect.provide(Layer.provideMerge(layer, Layer.merge(services, stack))),
+      ) as Effect.Effect<{ failure: unknown; marked: boolean }>,
+    );
+    expect(found.marked).toBe(true);
+    expect(found.failure).toBeInstanceOf(KubernetesReconcileTimeout);
+  } finally {
+    api.restore();
+  }
+});

package/src/kubernetes/helm-chart-bounded.ts

@@ -0,0 +1,110 @@
+/**
+ * `boundedHelmChartProvider`: upstream's `Kubernetes.HelmChart` provider with a wall-clock deadline
+ * on `reconcile` and `read`. Wrapped, never re-implemented (alchemy-provider-standard: use what
+ * Alchemy ships).
+ *
+ * ⛔ WHY (measured 2026-10-09, alchemy 2.0.0-beta.81): `requestJson` in `Kubernetes/internal/client.ts`
+ *   sets no timeout and no signal on any request, and retries transport errors only. A hung apiserver
+ *   therefore blocks a HelmChart reconcile or read forever, holding the 1h platform token across a
+ *   stuck deploy. The deadline turns that into a typed `KubernetesReconcileTimeout`.
+ * ★ A DIRECT `Provider(HelmChart)` layer, not a collection member: the engine checks the direct
+ *   service before any collection (`Provider.ts` `tryFindProviderRegistrationByType`), so merging
+ *   this beside `Kubernetes.providers()` makes the wrapper win with no change to upstream's layer.
+ * ⚠️ The interrupted fiber ABANDONS its socket (upstream takes no signal). The run then fails typed
+ *   and the process exits once main completes, so a dangling socket cannot hold anything.
+ * `diff`, `delete`, `stables` and `aliases` come from upstream by spread, so state identity and
+ * replace semantics are exactly upstream's.
+ */
+import { HelmChart, HelmChartProvider } from 'alchemy/Kubernetes/HelmChart';
+import * as Provider from 'alchemy/Provider';
+import type * as Context from 'effect/Context';
+import * as Data from 'effect/Data';
+import * as Duration from 'effect/Duration';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { scrubbed } from './ready-classify.ts';
+import { parseGoDuration } from './ready.ts';
+
+/** A render + discovery + ~60 server-side-apply PATCHes fit well inside this. */
+export const HELM_RECONCILE_TIMEOUT = '5m0s';
+/** `read` is one connect (identity GET): a minute is generous. */
+export const HELM_READ_TIMEOUT = '1m0s';
+
+/** The deadline passed with no answer from the apiserver. Names the row and seconds only. */
+export class KubernetesReconcileTimeout extends Data.TaggedError('KubernetesReconcileTimeout')<{
+  readonly id: string;
+  readonly operation: 'reconcile' | 'read';
+  readonly seconds: number;
+}> {
+  override get message(): string {
+    return `Kubernetes.HelmChart ${this.id}: ${this.operation} did not finish within ${this.seconds}s (the apiserver stopped answering)`;
+  }
+}
+
+const bound = <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+  deadline: Duration.Duration,
+  id: string,
+  operation: 'reconcile' | 'read',
+): Effect.Effect<A, E | KubernetesReconcileTimeout, R> =>
+  effect.pipe(
+    // ⛔ Upstream's `KubernetesApiError` quotes up to 1000 bytes of the apiserver body
+    //   (`client.ts:39-41`): scrub it to a body-free error, as `Kubernetes.Ready` does.
+    Effect.mapError((error) => scrubbed(error) as E),
+    Effect.timeoutOrElse({
+      duration: deadline,
+      orElse: () =>
+        Effect.fail(
+          new KubernetesReconcileTimeout({ id, operation, seconds: Duration.toSeconds(deadline) }),
+        ),
+    }),
+  );
+
+// `Provider(type)` is typed as an Effect; at runtime it is the service key the engine looks up.
+const HelmChartKey = Provider.Provider<HelmChart>(HelmChart.Type) as unknown as Context.Service<
+  Provider.Provider<HelmChart>,
+  Provider.ProviderService<HelmChart>
+>;
+
+const BOUNDED = Symbol.for('@homeflare/alchemy/kubernetes/boundedHelmChartProvider');
+
+/** True for a service built by `boundedHelmChartProvider`: lets a stack test its real layer. */
+export const isBoundedHelmChartProvider = (service: unknown): boolean =>
+  typeof service === 'object' &&
+  service !== null &&
+  (service as Record<symbol, unknown>)[BOUNDED] === true;
+
+/**
+ * ⛔ A malformed duration dies at layer build (`Effect.orDie`), never becomes a silent unbounded
+ *   call: a bad override cannot quietly drop the deadline.
+ */
+export const boundedHelmChartProvider = (
+  reconcileTimeout: string = HELM_RECONCILE_TIMEOUT,
+  readTimeout: string = HELM_READ_TIMEOUT,
+) =>
+  Layer.effect(
+    HelmChartKey,
+    Effect.gen(function* () {
+      const inner = yield* HelmChartKey;
+      const reconcileDeadline = yield* parseGoDuration(
+        'reconcileTimeout',
+        reconcileTimeout,
+        'Kubernetes.HelmChart',
+      );
+      const innerRead = inner.read?.bind(inner);
+      const readDeadline = yield* parseGoDuration(
+        'readTimeout',
+        readTimeout,
+        'Kubernetes.HelmChart',
+      );
+      const service = {
+        ...inner,
+        reconcile: (input) =>
+          bound(inner.reconcile(input), reconcileDeadline, input.id, 'reconcile'),
+        ...(innerRead === undefined
+          ? {}
+          : { read: (input) => bound(innerRead(input), readDeadline, input.id, 'read') }),
+      } satisfies Provider.ProviderService<HelmChart>;
+      return Object.defineProperty(service, BOUNDED, { value: true });
+    }).pipe(Effect.orDie),
+  ).pipe(Layer.provide(HelmChartProvider()));

package/src/kubernetes/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Kubernetes helpers for Alchemy that upstream does not ship.
+ *
+ * ⛔ A DELIBERATELY SMALL BARREL (the `talos/index.ts` rule): the resource, its provider, its
+ *   props and the typed errors a stack can `catchTag`. The evaluators and the poll stay internal.
+ */
+export {
+  HELM_READ_TIMEOUT,
+  HELM_RECONCILE_TIMEOUT,
+  KubernetesReconcileTimeout,
+  boundedHelmChartProvider,
+  isBoundedHelmChartProvider,
+} from './helm-chart-bounded.ts';
+export {
+  KubernetesReady,
+  KubernetesReadyProvider,
+  type ReadyAttributes,
+  type ReadyProps,
+} from './ready.ts';
+export type { ReadyCheck } from './ready-checks.ts';
+export {
+  KubernetesReadyBadAfter,
+  KubernetesReadyBadCheck,
+  KubernetesReadyBadDuration,
+  KubernetesReadyTimeout,
+  KubernetesRolloutFailed,
+} from './ready-errors.ts';
+export { KubernetesReadyApiError, KubernetesReadyGetTimeout } from './ready-poll.ts';

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

@@ -0,0 +1,124 @@
+/**
+ * Socket rationing of the poll (upstream `readObject` takes no signal, so a timed-out GET abandons
+ * its socket) and the `diff` tolerance of transients. Fake apiserver in hung mode; time is TestClock's.
+ */
+import { expect, test } from 'bun:test';
+import * as Cause from 'effect/Cause';
+import * as Duration from 'effect/Duration';
+import * as Exit from 'effect/Exit';
+import { connectCluster } from 'alchemy/Kubernetes/internal/client';
+import type { FakeObject } from '../talos/fake-apiserver.ts';
+import { poll } from './ready-poll.ts';
+import { diffReady } 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 checks = [dsCheck, depCheck, crdCheck];
+const allReady = (): Record<string, FakeObject> => ({
+  [get(CRD_PATH)]: { body: readyCrd },
+  [get(DEP_PATH)]: { body: readyDep },
+  [get(DS_PATH)]: { body: readyDs },
+});
+
+/** A live table that counts the GETs each key receives (the fake reads the table once per request). */
+const counting = (objects: Record<string, FakeObject>) => {
+  const counts: Record<string, number> = {};
+  const table = new Proxy(objects, {
+    get: (target, prop) => {
+      counts[prop as string] = (counts[prop as string] ?? 0) + 1;
+      return target[prop as string];
+    },
+  });
+  return { counts, table };
+};
+
+const prior = {
+  checks: [
+    'DaemonSet/kube-system/cilium',
+    'Deployment/kube-system/cilium-operator',
+    'CustomResourceDefinition/x.cilium.io',
+  ].join(','),
+  connection,
+  ready: true,
+};
+
+test('a hung apiserver costs few GETs over 10 minutes: back-off doubles the pause, capped at 30 s', async () => {
+  const { counts, table } = counting({ ...allReady(), [get(DS_PATH)]: { hang: true } });
+  const exit = await withCluster(
+    table,
+    driven(
+      poll(() => connectCluster(connection), checks, Duration.minutes(10), Duration.seconds(10)),
+      700,
+    ),
+  );
+  expect(Exit.isFailure(exit)).toBe(true);
+  // 5 s timeout + pause 20, 30, 30 ...: about 18 GETs. Without back-off it is about 40.
+  expect(counts[get(DS_PATH)]).toBeGreaterThan(10);
+  expect(counts[get(DS_PATH)]).toBeLessThan(25);
+});
+
+test('once a GET times out, the rest of that pass issues no GET and is pending', async () => {
+  const { counts, table } = counting({ ...allReady(), [get(DS_PATH)]: { hang: true } });
+  const exit = await withCluster(
+    table,
+    driven(
+      poll(() => connectCluster(connection), checks, Duration.minutes(2), Duration.seconds(10)),
+      200,
+    ),
+  );
+  const error = Cause.squash((exit as Exit.Failure<unknown, unknown>).cause) as {
+    failing: string[];
+  };
+  expect(counts[get(DEP_PATH)] ?? 0).toBe(0);
+  expect(counts[get(CRD_PATH)] ?? 0).toBe(0);
+  expect(error.failing).toHaveLength(3);
+});
+
+for (const [name, entry] of [
+  ['a 503', { status: 503, body: { secret: 'x' } }],
+  ['a 429', { status: 429 }],
+  ['a hung GET', { hang: true }],
+] as const) {
+  test(`diff returns update on ${name} instead of failing the plan`, async () => {
+    const objects = { ...allReady(), [get(DEP_PATH)]: entry };
+    const out = await withCluster(
+      objects,
+      driven(diffReady({ checks, connection } as never, prior), 30),
+    );
+    expect(Exit.isSuccess(out)).toBe(true);
+    expect((out as Exit.Success<unknown>).value).toEqual({ action: 'update' });
+  });
+}
+
+test('diff returns update when the connect itself hits a 503; 401/403 still fail the plan', async () => {
+  const identity = get('/api/v1/namespaces/kube-system');
+  const ok = await withCluster(
+    { ...allReady(), [identity]: { status: 503 } },
+    driven(diffReady({ checks, connection } as never, prior), 30),
+  );
+  expect((ok as Exit.Success<unknown>).value).toEqual({ action: 'update' });
+  for (const status of [401, 403]) {
+    const out = await withCluster(
+      { ...allReady(), [get(DS_PATH)]: { status } },
+      driven(diffReady({ checks, connection } as never, prior), 30),
+    );
+    expect(Exit.isFailure(out)).toBe(true);
+    expect(
+      (Cause.squash((out as Exit.Failure<unknown, unknown>).cause) as { statusCode: number })
+        .statusCode,
+    ).toBe(status);
+  }
+});