@homeflare/alchemy 0.48.1 → 0.50.0

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

@@ -0,0 +1,106 @@
+/** The rollout rules on literal bodies (kubectl `rollout_status.go`), no I/O. */
+import { expect, test } from 'bun:test';
+import { type ReadyCheck, checkKey, checksCsv, evaluate } from './ready-checks.ts';
+
+const ds = (status: object, generation = 2, minReady?: number) => ({
+  body: { metadata: { generation }, status },
+  check: {
+    kind: 'DaemonSet',
+    name: 'cilium',
+    namespace: 'kube-system',
+    ...(minReady === undefined ? {} : { minReady }),
+  } as ReadyCheck,
+});
+const dsVerdict = (status: object, generation?: number, minReady?: number) => {
+  const { body, check } = ds(status, generation, minReady);
+  return evaluate(check, body);
+};
+const fullDs = {
+  desiredNumberScheduled: 3,
+  numberAvailable: 3,
+  numberReady: 3,
+  observedGeneration: 2,
+  updatedNumberScheduled: 3,
+};
+
+test('DaemonSet: ready only when the generation is seen and updated and available reach minReady', () => {
+  expect(dsVerdict(fullDs)).toBe('ready');
+  // stale generation, numberReady 3: the OLD pods look healthy while the new spec is unseen
+  expect(dsVerdict({ ...fullDs, observedGeneration: 1 })).toBe('pending');
+  // updated 0 with numberReady 3: nothing is on the new template yet
+  expect(dsVerdict({ ...fullDs, updatedNumberScheduled: 0 })).toBe('pending');
+  // numberAvailable below the bar although numberReady is 3
+  expect(dsVerdict({ ...fullDs, numberAvailable: 1 })).toBe('pending');
+});
+
+test('DaemonSet: minReady 2 passes 2/3, minReady 3 does not, default is desiredNumberScheduled', () => {
+  // all 3 on the new template, one down: 2 updated-and-available meets minReady 2
+  const two = { ...fullDs, numberAvailable: 2, numberReady: 2 };
+  expect(dsVerdict(two, 2, 2)).toBe('ready');
+  expect(dsVerdict(two, 2, 3)).toBe('pending');
+  expect(dsVerdict(two)).toBe('pending');
+});
+
+test('DaemonSet: a set that wants zero pods is not ready', () => {
+  expect(dsVerdict({ desiredNumberScheduled: 0, observedGeneration: 2 })).toBe('pending');
+  expect(dsVerdict({ observedGeneration: 2 }, 2, 0)).toBe('pending');
+});
+
+const dep: ReadyCheck = { kind: 'Deployment', name: 'cilium-operator', namespace: 'kube-system' };
+const depBody = (status: object, replicas = 2, generation = 4) => ({
+  metadata: { generation },
+  spec: { replicas },
+  status: { observedGeneration: 4, ...status },
+});
+const rolled = { availableReplicas: 2, replicas: 2, updatedReplicas: 2 };
+
+test('Deployment: ready only on the full rollout counts', () => {
+  expect(evaluate(dep, depBody(rolled))).toBe('ready');
+  expect(evaluate(dep, depBody(rolled, 2, 5))).toBe('pending'); // generation not observed
+  // Available with updatedReplicas < replicas: the old ReplicaSet still serves
+  expect(evaluate(dep, depBody({ ...rolled, updatedReplicas: 1 }))).toBe('pending');
+  // surplus old replicas still running: replicas != updatedReplicas
+  expect(evaluate(dep, depBody({ ...rolled, replicas: 3 }))).toBe('pending');
+  expect(evaluate(dep, depBody({ ...rolled, availableReplicas: 1 }))).toBe('pending');
+  // scaled up to 2 but the controller has made only 1 (status is self-consistent at 1)
+  const one = { availableReplicas: 1, replicas: 1, updatedReplicas: 1 };
+  expect(evaluate(dep, depBody(one))).toBe('pending');
+  // scaled DOWN 3 -> 2, all three on the new template and available: kubectl reports this rolled
+  // out (it waits only while updated < desired), so Ready does too
+  const down = { availableReplicas: 3, replicas: 3, updatedReplicas: 3 };
+  expect(evaluate(dep, depBody(down))).toBe('ready');
+});
+
+test('Deployment: ProgressDeadlineExceeded is failed, but only for the generation the controller saw', () => {
+  const exceeded = { conditions: [{ reason: 'ProgressDeadlineExceeded', type: 'Progressing' }] };
+  expect(evaluate(dep, depBody({ ...rolled, ...exceeded }))).toBe('failed');
+  expect(evaluate(dep, depBody({ ...exceeded, observedGeneration: 3 }))).toBe('pending');
+  const fine = { conditions: [{ reason: 'NewReplicaSetAvailable', type: 'Progressing' }] };
+  expect(evaluate(dep, depBody({ ...rolled, ...fine }))).toBe('ready');
+});
+
+test('CRD: ready only when Established is True', () => {
+  const crd: ReadyCheck = { kind: 'CustomResourceDefinition', name: 'ciliumthings.cilium.io' };
+  const cond = (status: string) => ({ status: { conditions: [{ status, type: 'Established' }] } });
+  expect(evaluate(crd, cond('True'))).toBe('ready');
+  expect(evaluate(crd, cond('False'))).toBe('pending');
+  expect(
+    evaluate(crd, { status: { conditions: [{ status: 'True', type: 'NamesAccepted' }] } }),
+  ).toBe('pending');
+});
+
+test('a missing or non-object body is pending, never ready', () => {
+  for (const body of [undefined, null, 'ok', 7]) expect(evaluate(dep, body)).toBe('pending');
+});
+
+test('check keys are names and thresholds only', () => {
+  const checks: ReadyCheck[] = [
+    { kind: 'DaemonSet', minReady: 2, name: 'cilium', namespace: 'kube-system' },
+    dep,
+    { kind: 'CustomResourceDefinition', name: 'x.cilium.io' },
+  ];
+  expect(checkKey(checks[0] as ReadyCheck)).toBe('DaemonSet/kube-system/cilium:min=2');
+  expect(checksCsv(checks)).toBe(
+    'DaemonSet/kube-system/cilium:min=2,Deployment/kube-system/cilium-operator,CustomResourceDefinition/x.cilium.io',
+  );
+});

package/src/kubernetes/ready-checks.ts

@@ -0,0 +1,165 @@
+/**
+ * Readiness evaluators for `HomeFlare.Kubernetes.Ready`: pure functions over one object's JSON,
+ * plus the typed errors of the gate. No I/O here, so every rule is testable on a literal body.
+ *
+ * ★ ROLLOUT SEMANTICS, NOT "Available". Copied from `kubectl rollout status` (kubectl v0.34.0
+ *   `pkg/polymorphichelpers/rollout_status.go:75-89` Deployment, `:107-114` DaemonSet), because a
+ *   gate that only reads `Available`/`numberReady` passes on the OLD ReplicaSet or pods while a
+ *   new generation is still rolling out (T10 design v3, red-team round 2, finding 1). The first
+ *   rule of both is `status.observedGeneration >= metadata.generation`: until the controller has
+ *   seen the latest spec, every count below describes a spec that no longer exists.
+ * ⚠️ A body that is missing or not an object is PENDING, never ready: an empty 200 must not open
+ *   the gate.
+ */
+import { type KeyState, KubernetesReadyBadCheck } from './ready-errors.ts';
+
+export type ReadyCheck =
+  | {
+      readonly kind: 'DaemonSet';
+      readonly namespace: string;
+      readonly name: string;
+      readonly minReady?: number;
+    }
+  | { readonly kind: 'Deployment'; readonly namespace: string; readonly name: string }
+  | { readonly kind: 'CustomResourceDefinition'; readonly name: string };
+
+/** `failed` is terminal (kubectl reports it as an error), `pending` is "look again". */
+export type Verdict = 'ready' | 'pending' | 'failed';
+
+/** Check keys only: names are public, no body byte ever reaches a key, an error or an attribute. */
+export const checkKey = (check: ReadyCheck): string => {
+  switch (check.kind) {
+    case 'DaemonSet':
+      return `DaemonSet/${check.namespace}/${check.name}${
+        check.minReady === undefined ? '' : `:min=${check.minReady}`
+      }`;
+    case 'Deployment':
+      return `Deployment/${check.namespace}/${check.name}`;
+    case 'CustomResourceDefinition':
+      return `CustomResourceDefinition/${check.name}`;
+  }
+};
+
+export const checksCsv = (checks: readonly ReadyCheck[]): string => checks.map(checkKey).join(',');
+
+/**
+ * Declaration-time validation (round 1, finding 3): a check that can never be satisfied is a typed
+ * refusal, not a 10 minute timeout. ⚠️ Upstream's path builder THROWS for a namespaced kind with an
+ * empty namespace (`objects.ts:189-192`), which would otherwise be read as a transport transient.
+ */
+export const validateChecks = (checks: unknown): KubernetesReadyBadCheck | undefined => {
+  if (!Array.isArray(checks) || checks.length === 0) {
+    return new KubernetesReadyBadCheck({ index: 0, problem: 'must list at least one check' });
+  }
+  for (const [index, raw] of checks.entries()) {
+    const check = obj(raw);
+    const bad = (problem: string) => new KubernetesReadyBadCheck({ index, problem });
+    const kind = check['kind'];
+    if (kind !== 'DaemonSet' && kind !== 'Deployment' && kind !== 'CustomResourceDefinition') {
+      return bad('has an unknown kind');
+    }
+    if (typeof check['name'] !== 'string' || check['name'] === '') {
+      return bad('needs a non-empty name');
+    }
+    if (kind !== 'CustomResourceDefinition') {
+      if (typeof check['namespace'] !== 'string' || check['namespace'] === '') {
+        return bad(`needs a non-empty namespace (${kind} is namespaced)`);
+      }
+    }
+    const min = check['minReady'];
+    if (min !== undefined && (kind !== 'DaemonSet' || !Number.isInteger(min) || Number(min) < 1)) {
+      return bad('minReady is an integer >= 1 and only applies to a DaemonSet');
+    }
+  }
+  return undefined;
+};
+
+export type Json = Record<string, unknown>;
+export const obj = (value: unknown): Json =>
+  typeof value === 'object' && value !== null ? (value as Json) : {};
+export const num = (value: unknown): number => (typeof value === 'number' ? value : 0);
+
+/** The numbers a pass saw, for `KubernetesReadyTimeout.states`: counts and generations only. */
+export const countsOf = (check: ReadyCheck, body: unknown): KeyState => {
+  const status = obj(obj(body)['status']);
+  const names =
+    check.kind === 'DaemonSet'
+      ? [
+          'observedGeneration',
+          'desiredNumberScheduled',
+          'updatedNumberScheduled',
+          'numberAvailable',
+        ]
+      : check.kind === 'Deployment'
+        ? ['observedGeneration', 'replicas', 'updatedReplicas', 'availableReplicas']
+        : [];
+  const counts = Object.fromEntries(names.map((name) => [name, num(status[name])]));
+  return { counts: { generation: num(obj(obj(body)['metadata'])['generation']), ...counts } };
+};
+const conditions = (status: Json): Json[] =>
+  Array.isArray(status['conditions']) ? status['conditions'].map(obj) : [];
+
+/** kubectl `rollout_status.go:107-114`; `minReady` defaults to `desiredNumberScheduled`. */
+const daemonSet = (body: Json, minReady: number | undefined): Verdict => {
+  const status = obj(body['status']);
+  // ⛔ kubectl checks the strategy first (`:104-106`). The apiserver defaults the type, so an
+  //   absent one is RollingUpdate; `OnDelete` never rolls by itself, so waiting cannot end.
+  const strategy = obj(obj(body['spec'])['updateStrategy'])['type'];
+  if (strategy !== undefined && strategy !== 'RollingUpdate') return 'failed';
+  const generation = num(obj(body['metadata'])['generation']);
+  if (num(status['observedGeneration']) < generation) return 'pending';
+  const desired = num(status['desiredNumberScheduled']);
+  const need = minReady ?? desired;
+  // ⚠️ A DaemonSet that wants zero pods (no node matched yet) has rolled out nothing.
+  if (need < 1) return 'pending';
+  const updated = num(status['updatedNumberScheduled']);
+  // ⛔ `numberAvailable` also counts AVAILABLE OLD-TEMPLATE pods, so comparing it to `minReady`
+  //   alone passes a broken upgrade: minReady 2 of 4 with two crashlooping new pods and two healthy
+  //   old ones reads as 2 updated and 2 available. At most `desired - updated` of the available
+  //   pods are old, so the difference is a LOWER BOUND on pods both updated and available (round 1,
+  //   finding 1; kubectl gets there by demanding updated == desired).
+  const oldAtMost = Math.max(desired - updated, 0);
+  return updated >= need && num(status['numberAvailable']) - oldAtMost >= need
+    ? 'ready'
+    : 'pending';
+};
+
+/** kubectl `rollout_status.go:75-89`. */
+const deployment = (body: Json): Verdict => {
+  const status = obj(body['status']);
+  const generation = num(obj(body['metadata'])['generation']);
+  if (num(status['observedGeneration']) < generation) return 'pending';
+  // ★ Checked after the generation rule, as kubectl does: a deadline condition left over from
+  //   the previous spec must not fail a rollout the controller has not looked at yet.
+  const exceeded = conditions(status).some(
+    (c) => c['type'] === 'Progressing' && c['reason'] === 'ProgressDeadlineExceeded',
+  );
+  if (exceeded) return 'failed';
+  const desired =
+    obj(body['spec'])['replicas'] === undefined ? 1 : num(obj(body['spec'])['replicas']);
+  const updated = num(status['updatedReplicas']);
+  // kubectl rollout_status.go waits only while updated < desired, so updated >= desired is the
+  // same rule (a scale-down can briefly report more updated replicas than spec.replicas).
+  return updated >= desired &&
+    num(status['replicas']) === updated &&
+    num(status['availableReplicas']) >= updated
+    ? 'ready'
+    : 'pending';
+};
+
+const established = (body: Json): Verdict =>
+  conditions(obj(body['status'])).some((c) => c['type'] === 'Established' && c['status'] === 'True')
+    ? 'ready'
+    : 'pending';
+
+export const evaluate = (check: ReadyCheck, body: unknown): Verdict => {
+  if (typeof body !== 'object' || body === null) return 'pending';
+  switch (check.kind) {
+    case 'DaemonSet':
+      return daemonSet(body as Json, check.minReady);
+    case 'Deployment':
+      return deployment(body as Json);
+    case 'CustomResourceDefinition':
+      return established(body as Json);
+  }
+};

package/src/kubernetes/ready-classify.ts

@@ -0,0 +1,76 @@
+/**
+ * Error classification for `HomeFlare.Kubernetes.Ready`, shared by the poll (`ready-poll.ts`) and
+ * the connect (`ready-connect.ts`).
+ *
+ * ⛔ ERROR CLASSES (T10 design v3 §2, round-2 findings 3b and 8, round-1 finding 3):
+ *   - 404 is PENDING everywhere. Version-proof: `_tag === 'KubernetesNotFound'` OR a
+ *     `KubernetesApiError` with `statusCode === 404` (beta.81 raises the latter,
+ *     `Kubernetes/internal/client.ts:32-37`; a later alchemy may raise the former). Matched by
+ *     tag string, no import, so neither shape needs a kit release.
+ *   - TRANSIENT, tolerated only inside a poll or its connect: a per-GET timeout, the identity
+ *     timeout, `KubernetesApiError` 5xx/429, and upstream's transport error, which is the plain
+ *     `Error` whose message starts `Failed Kubernetes ` (`client.ts:146-148`).
+ *   - ⚠️ ANY OTHER UNTAGGED `Error` IS A DEFECT AND PROPAGATES. It used to count as transport, which
+ *     made upstream's path-builder throw for an empty namespace (`objects.ts:189-192`) and a
+ *     failing `bao` (`credentials.ts` plain `Error`s) look like a slow rollout for ten minutes.
+ *   - Everything else propagates: 401/403/other 4xx, vault failures (the ClusterHealth rule).
+ */
+import * as Data from 'effect/Data';
+import type { LastTransient } from './ready-errors.ts';
+
+interface Tagged {
+  readonly _tag?: unknown;
+  readonly statusCode?: unknown;
+  readonly message?: unknown;
+}
+
+export const isNotFound = (error: unknown): boolean => {
+  const e = error as Tagged | null;
+  return (
+    e?._tag === 'KubernetesNotFound' || (e?._tag === 'KubernetesApiError' && e.statusCode === 404)
+  );
+};
+
+/** Upstream's transport failure wrapper (`client.ts:146-148`); its message names no body. */
+const UPSTREAM_TRANSPORT = /^Failed Kubernetes /;
+
+/** The tolerable-in-a-poll classes, as a record of tag + status; `undefined` means propagate. */
+export const transientOf = (error: unknown): LastTransient | undefined => {
+  const e = error as Tagged | null;
+  if (e?._tag === 'KubernetesReadyGetTimeout') return { tag: 'KubernetesReadyGetTimeout' };
+  if (e?._tag === 'TalosClusterIdentityTimeout') return { tag: 'TalosClusterIdentityTimeout' };
+  if (e?._tag === 'KubernetesApiError') {
+    const status = typeof e.statusCode === 'number' ? e.statusCode : 0;
+    return status >= 500 || status === 429 ? { status, tag: 'KubernetesApiError' } : undefined;
+  }
+  return error instanceof Error && e?._tag === undefined && UPSTREAM_TRANSPORT.test(error.message)
+    ? { tag: 'TransportError' }
+    : undefined;
+};
+
+/**
+ * A propagated apiserver refusal (401/403/other 4xx, or any status in a single pass). ⛔ Upstream's
+ * `KubernetesApiError` message quotes up to 1000 bytes of the response body (`client.ts:38-42`);
+ * a body is the server's text, not ours to republish into logs and run output, so it is dropped.
+ */
+export class KubernetesReadyApiError extends Data.TaggedError('KubernetesReadyApiError')<{
+  readonly method: string;
+  readonly path: string;
+  readonly statusCode: number;
+}> {
+  override get message(): string {
+    return `Kubernetes.Ready: ${this.method} ${this.path} responded ${this.statusCode}`;
+  }
+}
+
+/** ⛔ Wrap every error that leaves a GET, the identity GET of connect included (round 1, finding 4). */
+export const scrubbed = (error: unknown): unknown => {
+  const e = error as { _tag?: unknown; method?: unknown; path?: unknown; statusCode?: unknown };
+  return e?._tag === 'KubernetesApiError'
+    ? new KubernetesReadyApiError({
+        method: String(e.method),
+        path: String(e.path),
+        statusCode: Number(e.statusCode),
+      })
+    : error;
+};

package/src/kubernetes/ready-connect.ts

@@ -0,0 +1,52 @@
+/**
+ * Connect for `HomeFlare.Kubernetes.Ready`. `connectCluster` reads the vault and then makes the
+ * cluster-identity GET (`talos/cluster-identity.ts`), so it reaches the apiserver too.
+ *
+ * ⛔ A SINGLE PASS (`read`/`diff`) connects once; only errors are scrubbed. Upstream's
+ *   `KubernetesApiError` message quotes up to 1000 bytes of the response body (`client.ts:38-42`),
+ *   and a 401/403/5xx on the identity GET carries it (round 1, finding 4).
+ * ★ A POLL retries the connect on the poll's transients (identity timeout, 5xx, 429, upstream's
+ *   transport error) every `pollInterval` until the poll's own deadline: on a first install the
+ *   apiserver is exactly what a CNI rollout is restarting (round 1, finding 2). Vault failures,
+ *   401/403, a uid mismatch and any untagged defect still propagate at once.
+ */
+import { connectCluster } from 'alchemy/Kubernetes/internal/client';
+import type { ClusterTransport } from 'alchemy/Kubernetes/ClusterAdapter';
+import type * as Duration from 'effect/Duration';
+import * as Effect from 'effect/Effect';
+import { scrubbed, transientOf } from './ready-classify.ts';
+import type { LastTransient } from './ready-errors.ts';
+
+type Connection = Parameters<typeof connectCluster>[0];
+
+/** Connect once. */
+export const connectOnce = (connection: Connection) =>
+  connectCluster(connection).pipe(Effect.mapError(scrubbed));
+
+/**
+ * Connect once for `diff`: a transient is `undefined` (the plan says `update`, `reconcile` waits);
+ * everything else fails scrubbed. ⚠️ Classified BEFORE scrubbing: the scrubbed 5xx loses its tag.
+ */
+export const connectForDiff = (connection: Connection) =>
+  Effect.gen(function* () {
+    const attempt = yield* Effect.result(connectCluster(connection));
+    if (attempt._tag === 'Success') return attempt.success as ClusterTransport;
+    return transientOf(attempt.failure) === undefined
+      ? yield* Effect.fail(scrubbed(attempt.failure))
+      : undefined;
+  });
+
+/** Connect, retrying transients until the caller's deadline interrupts. */
+export const connectTolerant =
+  (connection: Connection, pollInterval: Duration.Duration) =>
+  (note: (transient: LastTransient) => Effect.Effect<void>) =>
+    Effect.gen(function* () {
+      while (true) {
+        const attempt = yield* Effect.result(connectCluster(connection));
+        if (attempt._tag === 'Success') return attempt.success as ClusterTransport;
+        const transient = transientOf(attempt.failure);
+        if (transient === undefined) return yield* Effect.fail(scrubbed(attempt.failure));
+        yield* note(transient);
+        yield* Effect.sleep(pollInterval);
+      }
+    });

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

@@ -0,0 +1,85 @@
+/**
+ * Declaration-time refusals of `HomeFlare.Kubernetes.Ready` (round 1, findings 3 and 5): checks that
+ * can never pass, and an `after` that would let the gate be skipped.
+ */
+import { expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as Output from 'alchemy/Output';
+import { declarationRefusal, declaredReady } from './ready-declare.ts';
+import { KubernetesReady } from './ready.ts';
+import { connection, crdCheck, depCheck, dsCheck } from './ready.fixtures.ts';
+
+const refusal = (extra: object) =>
+  declarationRefusal({ checks: [dsCheck, depCheck, crdCheck], connection, ...extra }) as
+    | { _tag: string; index: number; problem?: string }
+    | undefined;
+const badCheck = (check: object) => refusal({ checks: [check] });
+
+test('valid checks and no `after` are accepted', () => {
+  expect(refusal({})).toBeUndefined();
+  expect(refusal({ checks: [{ ...dsCheck, minReady: 2 }] })).toBeUndefined();
+});
+
+test('an empty list, an empty name, a missing namespace and a bad minReady are typed refusals', () => {
+  expect(refusal({ checks: [] })?._tag).toBe('KubernetesReadyBadCheck');
+  for (const check of [
+    { ...dsCheck, name: '' },
+    { ...depCheck, namespace: '' },
+    { kind: 'Deployment', name: 'x' },
+    { kind: 'DaemonSet', name: 'x', namespace: undefined },
+    { ...dsCheck, minReady: 0 },
+    { ...dsCheck, minReady: 1.5 },
+    { ...dsCheck, minReady: '2' },
+    { ...depCheck, minReady: 1 },
+    { ...crdCheck, name: '' },
+    { kind: 'Pod', name: 'x', namespace: 'y' },
+  ]) {
+    expect(badCheck(check)?._tag).toBe('KubernetesReadyBadCheck');
+  }
+});
+
+// REAL property expressions of a chart (round 2: a plain-object stand-in hid that `chart.connection`
+// passed). Only `chart.objects` stays lazy while the chart updates; every other property is a stable.
+const chart = Output.of({ LogicalId: 'chart', Type: 'Kubernetes.HelmChart' } as never);
+const prop = (name: string) => new Output.PropExpr(chart as never, name as never);
+const lazy = prop('objects');
+const stableLike = { auth: { kind: 'talos-openbao', uid: 'uid-c1' } };
+
+test('`after` accepts only chart.objects and refuses every other shape (a chart stable resolves at plan time)', () => {
+  expect(refusal({ after: [lazy] })).toBeUndefined();
+  for (const stable of ['connection', 'releaseName', 'namespace']) {
+    expect(refusal({ after: [prop(stable)] })).toMatchObject({
+      _tag: 'KubernetesReadyBadAfter',
+      index: 0,
+    });
+  }
+  expect(refusal({ after: [Output.literal([{ kind: 'Deployment' }])] })).toMatchObject({
+    _tag: 'KubernetesReadyBadAfter',
+    index: 0,
+  });
+  expect(refusal({ after: [stableLike] })).toMatchObject({
+    _tag: 'KubernetesReadyBadAfter',
+    index: 0,
+  });
+  // a bare `chart` is a ResourceExpr whose stables resolve at plan time: also refused
+  expect(refusal({ after: [chart] })).toMatchObject({ _tag: 'KubernetesReadyBadAfter', index: 0 });
+  expect(refusal({ after: [lazy, 'chart'] })).toMatchObject({
+    _tag: 'KubernetesReadyBadAfter',
+    index: 1,
+  });
+});
+
+test('declaration fails with the typed error for plain props and for a props Effect', async () => {
+  const bad = { checks: [{ ...depCheck, namespace: '' }], connection };
+  const plain = await Effect.runPromise(Effect.flip(KubernetesReady('x', bad as never) as never));
+  expect((plain as { _tag: string })._tag).toBe('KubernetesReadyBadCheck');
+  // the props-Effect branch, over a stand-in constructor (the real one needs a Stack to run)
+  const wrapped = declaredReady((_id: string, props: unknown) => props);
+  const viaEffect = wrapped('x', Effect.succeed(bad)) as Effect.Effect<unknown, { _tag: string }>;
+  expect((await Effect.runPromise(Effect.flip(viaEffect)))._tag).toBe('KubernetesReadyBadCheck');
+  const after = { checks: [dsCheck], connection, after: [stableLike] };
+  const skipped = await Effect.runPromise(
+    Effect.flip(KubernetesReady('x', after as never) as never),
+  );
+  expect((skipped as { _tag: string })._tag).toBe('KubernetesReadyBadAfter');
+});

package/src/kubernetes/ready-declare.ts

@@ -0,0 +1,50 @@
+/**
+ * Declaration-time guards for `HomeFlare.Kubernetes.Ready` (the `withLiteralConnection` shape): a
+ * fresh resource with unresolved inputs skips `diff`, so anything that must be refused has to be
+ * refused when the resource is DECLARED. Plain props fail the declaring Effect; a props Effect
+ * fails once it yields.
+ *
+ * ⛔ `checks`: a check that can never be satisfied (empty name, a namespaced kind with no
+ *   namespace, `minReady` below 1) is a typed `KubernetesReadyBadCheck`, not a 10 minute timeout
+ *   (`validateChecks`, round 1 finding 3).
+ * ⛔ `after`: ONLY `chart.objects` (a `PropExpr` whose identifier is `objects`) orders the row after
+ *   the chart's UPDATE. Any other property of the chart (`chart.connection`, `chart.releaseName`)
+ *   is a stable that Alchemy fills from state while the chart updates, so it resolves to a plain
+ *   value at plan time, Ready plans `noop` and the gate is silently skipped; a bare `chart`
+ *   resolves to its stables the same way (round 1 finding 5; round 2: a property-expression test,
+ *   not a plain-object stand-in, proved `chart.connection` slipped through). Every other shape is
+ *   `KubernetesReadyBadAfter`.
+ */
+import { isPropExpr } from 'alchemy/Output';
+import * as Effect from 'effect/Effect';
+import { validateChecks } from './ready-checks.ts';
+import { KubernetesReadyBadAfter } from './ready-errors.ts';
+
+/** The typed refusal for the given props, or `undefined`. */
+export const declarationRefusal = (props: unknown) => {
+  const { after, checks } = (props ?? {}) as { after?: unknown; checks?: unknown };
+  const badCheck = validateChecks(checks);
+  if (badCheck !== undefined) return badCheck;
+  if (after === undefined) return undefined;
+  const list = Array.isArray(after) ? after : [after];
+  const index = list.findIndex((item) => !(isPropExpr(item) && item.identifier === 'objects'));
+  return index === -1 ? undefined : new KubernetesReadyBadAfter({ index });
+};
+
+export const declaredReady = <C extends (...args: never[]) => unknown>(resource: C): C =>
+  new Proxy(resource, {
+    apply: (target, thisArg, args: unknown[]) => {
+      const props = args[1];
+      if (Effect.isEffect(props)) {
+        const checked = props.pipe(
+          Effect.flatMap((resolved) => {
+            const refused = declarationRefusal(resolved);
+            return refused === undefined ? Effect.succeed(resolved) : Effect.fail(refused);
+          }),
+        );
+        return Reflect.apply(target, thisArg, [args[0], checked, ...args.slice(2)]);
+      }
+      const refused = declarationRefusal(props);
+      return refused === undefined ? Reflect.apply(target, thisArg, args) : Effect.fail(refused);
+    },
+  });

package/src/kubernetes/ready-errors.ts

@@ -0,0 +1,102 @@
+/**
+ * The typed errors of `HomeFlare.Kubernetes.Ready` that carry no logic, so a stack can `catchTag`
+ * them. ⛔ Every message names check keys, counts, durations and statuses only: never a response
+ * body, which is the server's text and not ours to republish.
+ */
+import * as Data from 'effect/Data';
+
+/** What the poll recorded when a pass last tolerated a transient error: tag and status, no body. */
+export interface LastTransient {
+  readonly tag: string;
+  readonly status?: number;
+}
+
+/**
+ * What the last pass saw of one check: the object was absent (404), or the numbers it reported.
+ * ★ A 404 that never resolves (a typo'd name, a chart that never creates it) must read differently
+ *   from a slow rollout, without republishing anything the server said (round 1, finding 3).
+ */
+export type KeyState =
+  | { readonly notFound: true }
+  | { readonly counts: Readonly<Record<string, number>> };
+
+const describeState = (state: KeyState | undefined): string => {
+  if (state === undefined) return '';
+  if ('notFound' in state) return ' (not found)';
+  const counts = Object.entries(state.counts).map(([name, value]) => `${name}=${value}`);
+  return counts.length === 0 ? '' : ` (${counts.join(' ')})`;
+};
+
+/** The gate never opened within `waitTimeout`. `failing` holds check keys only. */
+export class KubernetesReadyTimeout extends Data.TaggedError('KubernetesReadyTimeout')<{
+  readonly failing: readonly string[];
+  readonly seconds: number;
+  readonly lastTransient?: LastTransient;
+  /** Per failing key, from the last pass that reached it: `notFound`, or the counts seen. */
+  readonly states?: Readonly<Record<string, KeyState>>;
+}> {
+  override get message(): string {
+    const failing = this.failing.map((key) => `${key}${describeState(this.states?.[key])}`);
+    const last =
+      this.lastTransient === undefined
+        ? ''
+        : `; last transient error ${this.lastTransient.tag}${
+            this.lastTransient.status === undefined ? '' : ` ${this.lastTransient.status}`
+          }`;
+    return `Kubernetes.Ready: not ready within ${this.seconds}s: ${failing.join(', ')}${last}`;
+  }
+}
+
+/**
+ * A rollout that will not finish, which is not pending: a Deployment reported
+ * `ProgressDeadlineExceeded`, or a DaemonSet's `updateStrategy` is not `RollingUpdate` (kubectl
+ * `rollout_status.go:104-106` errors the same way: `OnDelete` pods never roll by themselves).
+ */
+export class KubernetesRolloutFailed extends Data.TaggedError('KubernetesRolloutFailed')<{
+  readonly check: string;
+  readonly reason?: 'ProgressDeadlineExceeded' | 'UpdateStrategyNotRollingUpdate';
+}> {
+  override get message(): string {
+    return this.reason === 'UpdateStrategyNotRollingUpdate'
+      ? `Kubernetes.Ready: ${this.check} does not use the RollingUpdate update strategy`
+      : `Kubernetes.Ready: ${this.check} exceeded its progress deadline (ProgressDeadlineExceeded)`;
+  }
+}
+
+/** A `waitTimeout`/`pollInterval` that is not a Go-style duration (`10m0s`, `90s`, `1h30m`). */
+export class KubernetesReadyBadDuration extends Data.TaggedError('KubernetesReadyBadDuration')<{
+  readonly field: string;
+  readonly value: string;
+  /** The resource whose prop it is; `Kubernetes.Ready` unless the HelmChart bound says otherwise. */
+  readonly resource?: string;
+}> {
+  override get message(): string {
+    // A hostile or typo'd value can be long: the message quotes a bounded prefix only.
+    const shown = this.value.length > 40 ? `${this.value.slice(0, 40)}...` : this.value;
+    return `${this.resource ?? 'Kubernetes.Ready'}: ${this.field} '${shown}' is not a duration like 10m0s`;
+  }
+}
+
+/** A check that can never be satisfied, refused at declaration instead of timing out in 10 m. */
+export class KubernetesReadyBadCheck extends Data.TaggedError('KubernetesReadyBadCheck')<{
+  /** Index into `checks`. */
+  readonly index: number;
+  readonly problem: string;
+}> {
+  override get message(): string {
+    return `Kubernetes.Ready: checks[${this.index}] ${this.problem}`;
+  }
+}
+
+/**
+ * `after` must hold Outputs of the chart (`chart.objects`). ⛔ A plain value, or a stable such as
+ * `chart.connection`, resolves at plan time, so the row would plan `noop` before the chart's
+ * update and the gate would be skipped.
+ */
+export class KubernetesReadyBadAfter extends Data.TaggedError('KubernetesReadyBadAfter')<{
+  readonly index: number;
+}> {
+  override get message(): string {
+    return `Kubernetes.Ready: after[${this.index}] is not chart.objects (the only shape that waits for the chart's update)`;
+  }
+}