@intentius/chant-lexicon-k8s 0.18.19 → 0.18.21

package/src/generated/lexicon-k8s.json

@@ -108,6 +108,11 @@
     "kind": "property",
     "lexicon": "k8s"
   },
+  "AppProject_Status": {
+    "resourceType": "K8s::Argo::AppProject.status",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "AppProject_SyncWindow": {
     "resourceType": "K8s::Argo::AppProject.syncWindows",
     "kind": "property",
@@ -142,6 +147,11 @@
     "kind": "property",
     "lexicon": "k8s"
   },
+  "ApplicationSet_Status": {
+    "resourceType": "K8s::Argo::ApplicationSet.status",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "ApplicationSet_Strategy": {
     "resourceType": "K8s::Argo::ApplicationSet.strategy",
     "kind": "property",
@@ -182,6 +192,11 @@
     "kind": "property",
     "lexicon": "k8s"
   },
+  "Application_Status": {
+    "resourceType": "K8s::Argo::Application.status",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "Application_SyncPolicy": {
     "resourceType": "K8s::Argo::Application.syncPolicy",
     "kind": "property",
@@ -284,6 +299,11 @@
     "kind": "property",
     "lexicon": "k8s"
   },
+  "CertificateRequest_Status": {
+    "resourceType": "K8s::CertManager::CertificateRequest.status",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "CertificateSigningRequest": {
     "resourceType": "K8s::Certificates::CertificateSigningRequest",
     "kind": "resource",
@@ -333,6 +353,11 @@
     "kind": "property",
     "lexicon": "k8s"
   },
+  "Certificate_Status": {
+    "resourceType": "K8s::CertManager::Certificate.status",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "Certificate_Subject": {
     "resourceType": "K8s::CertManager::Certificate.subject",
     "kind": "property",
@@ -355,6 +380,11 @@
     "kind": "property",
     "lexicon": "k8s"
   },
+  "Challenge_Status": {
+    "resourceType": "K8s::Acme::Challenge.status",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "ClusterIssuer": {
     "resourceType": "K8s::CertManager::ClusterIssuer",
     "kind": "resource",
@@ -377,6 +407,11 @@
     "kind": "property",
     "lexicon": "k8s"
   },
+  "ClusterIssuer_Status": {
+    "resourceType": "K8s::CertManager::ClusterIssuer.status",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "ClusterIssuer_Vault": {
     "resourceType": "K8s::CertManager::ClusterIssuer.vault",
     "kind": "property",
@@ -553,6 +588,11 @@
     "kind": "property",
     "lexicon": "k8s"
   },
+  "CrdbCluster_Status": {
+    "resourceType": "K8s::Crdb::CrdbCluster.status",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "CrdbCluster_Toleration": {
     "resourceType": "K8s::Crdb::CrdbCluster.tolerations",
     "kind": "property",
@@ -820,6 +860,11 @@
     "kind": "property",
     "lexicon": "k8s"
   },
+  "GRPCRoute_Status": {
+    "resourceType": "K8s::Gateway::GRPCRoute.status",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "Gateway": {
     "resourceType": "K8s::Gateway::Gateway",
     "kind": "resource",
@@ -839,6 +884,11 @@
     "kind": "property",
     "lexicon": "k8s"
   },
+  "GatewayClass_Status": {
+    "resourceType": "K8s::Gateway::GatewayClass.status",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "Gateway_Address": {
     "resourceType": "K8s::Gateway::Gateway.addresses",
     "kind": "property",
@@ -854,6 +904,11 @@
     "kind": "property",
     "lexicon": "k8s"
   },
+  "Gateway_Status": {
+    "resourceType": "K8s::Gateway::Gateway.status",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "GcsFaultToleranceOptions": {
     "resourceType": "K8s::Ray::RayCluster.gcsFaultToleranceOptions",
     "kind": "property",
@@ -903,6 +958,11 @@
     "kind": "property",
     "lexicon": "k8s"
   },
+  "HTTPRoute_Status": {
+    "resourceType": "K8s::Gateway::HTTPRoute.status",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "HeadGroupSpec": {
     "resourceType": "K8s::Ray::RayCluster.headGroupSpec",
     "kind": "property",
@@ -1048,6 +1108,11 @@
     "kind": "property",
     "lexicon": "k8s"
   },
+  "Issuer_Status": {
+    "resourceType": "K8s::CertManager::Issuer.status",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "Issuer_Vault": {
     "resourceType": "K8s::CertManager::Issuer.vault",
     "kind": "property",
@@ -1334,6 +1399,11 @@
     "kind": "property",
     "lexicon": "k8s"
   },
+  "Order_Status": {
+    "resourceType": "K8s::Acme::Order.status",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "OrphanedResources": {
     "resourceType": "K8s::Argo::AppProject.orphanedResources",
     "kind": "property",
@@ -1623,6 +1693,11 @@
     "kind": "property",
     "lexicon": "k8s"
   },
+  "RayCluster_Status": {
+    "resourceType": "K8s::Ray::RayCluster.status",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "RayCluster_WorkerGroupSpec": {
     "resourceType": "K8s::Ray::RayCluster.workerGroupSpecs",
     "kind": "property",
@@ -1640,6 +1715,11 @@
     "kind": "property",
     "lexicon": "k8s"
   },
+  "RayJob_Status": {
+    "resourceType": "K8s::Ray::RayJob.status",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "RayJob_SubmitterConfig": {
     "resourceType": "K8s::Ray::RayJob.submitterConfig",
     "kind": "property",
@@ -1667,6 +1747,11 @@
     "kind": "property",
     "lexicon": "k8s"
   },
+  "RayService_Status": {
+    "resourceType": "K8s::Ray::RayService.status",
+    "kind": "property",
+    "lexicon": "k8s"
+  },
   "RayService_UpgradeStrategy": {
     "resourceType": "K8s::Ray::RayService.upgradeStrategy",
     "kind": "property",

package/src/op/activities/argo.ts

@@ -1,6 +1,6 @@
 import { exec } from "node:child_process";
 import { promisify } from "node:util";
-import { safeHeartbeat, sleep } from "@intentius/chant/op";
+import { readinessFor, waitForReady, ReadinessFailedError, type ResourceFetcher } from "./wait-for-ready";
 
 const execAsync = promisify(exec);
 
@@ -8,13 +8,16 @@ const execAsync = promisify(exec);
  * waitForArgoSync — block until an Argo CD Application reports
  * `health=Healthy && sync=Synced`.
  *
- * This activity is intentionally **dependency-light**: though it now lives in the
- * k8s lexicon (#809), it must not import the lexicon's generated Argo CRD types —
- * its signature is primitives-only (app name / namespace / server), so a Temporal
- * worker can load it without pulling in the declarable surface. It reads the
- * Application's status either via `kubectl get application` (default) or the Argo
- * CD REST API (when `server` is given), so an Op can gate procedural steps on a
- * declarative apply that Argo owns.
+ * As of #957 this is a thin wrapper over the generic `waitForReady`: the
+ * Healthy/Synced ready condition and the Degraded/Missing terminal condition
+ * live in the shared readiness registry (`argoproj.io/Application`), so there is
+ * a single poll loop. This activity keeps its own status **fetchers** because
+ * Argo exposes a REST API that `kubectl` can't cover; it adapts them into a
+ * `ResourceFetcher` for `waitForReady`.
+ *
+ * It stays **dependency-light** — primitives-only signature (app name /
+ * namespace / server), no generated Argo CRD types — so a Temporal worker loads
+ * it cheaply.
  */
 
 export interface WaitForArgoSyncArgs {
@@ -51,9 +54,6 @@ export type ArgoStatusFetcher = (
   signal?: AbortSignal,
 ) => Promise<ArgoAppStatus>;
 
-/** Health states that will never become Healthy without intervention. */
-const TERMINAL_UNHEALTHY = new Set(["Degraded", "Missing"]);
-
 /** Error thrown when the Application reaches a terminal unhealthy state. */
 export class ArgoSyncFailedError extends Error {
   constructor(message: string) {
@@ -111,8 +111,13 @@ export const defaultArgoStatusFetcher: ArgoStatusFetcher = (args, signal) =>
 /**
  * Poll until the Application is Healthy and Synced. Throws
  * `ArgoSyncFailedError` if it reaches a terminal unhealthy state (Degraded /
- * Missing). Heartbeats every poll so the `argoSync` profile's 60s heartbeat
- * timeout never trips.
+ * Missing).
+ *
+ * Delegates the poll loop, heartbeat, and ready/terminal evaluation to the
+ * generic `waitForReady` using the shared `argoproj.io/Application` readiness
+ * spec. The Argo `ArgoStatusFetcher` is adapted into a `ResourceFetcher` that
+ * shapes `{health, sync}` into the `status.health.status` / `status.sync.status`
+ * paths the spec reads — so the REST-API path is preserved.
  *
  * @param fetcher injectable status reader (defaults to kubectl/REST). Tests pass
  *   a fake to drive Healthy/Progressing/Degraded transitions.
@@ -122,26 +127,37 @@ export async function waitForArgoSync(
   signal?: AbortSignal,
   fetcher: ArgoStatusFetcher = defaultArgoStatusFetcher,
 ): Promise<ArgoAppStatus> {
-  const interval = args.intervalMs ?? 15_000;
-  let attempt = 0;
-
-  while (true) {
-    if (signal?.aborted) throw new Error("waitForArgoSync aborted");
-    attempt++;
+  const spec = readinessFor("argoproj.io", "Application");
 
-    const status = await fetcher(args, signal);
-    safeHeartbeat({ step: "waitForArgoSync", app: args.appName, attempt, ...status });
+  // Adapt the Argo status fetcher into the object shape the spec's paths read.
+  const resourceFetcher: ResourceFetcher = async (_a, s) => {
+    const status = await fetcher(args, s);
+    return { status: { health: { status: status.health }, sync: { status: status.sync } } };
+  };
 
-    if (TERMINAL_UNHEALTHY.has(status.health)) {
+  try {
+    const obj = await waitForReady(
+      {
+        kind: "application",
+        name: args.appName,
+        namespace: args.namespace ?? "argocd",
+        group: "argoproj.io",
+        spec,
+        intervalMs: args.intervalMs ?? 15_000,
+      },
+      signal,
+      resourceFetcher,
+    );
+    const status = (obj as { status: { health: { status: string }; sync: { status: string } } }).status;
+    return { health: status.health.status, sync: status.sync.status };
+  } catch (err) {
+    // Preserve the Argo-specific error type (the argoSync profile marks it
+    // non-retryable) while reusing the generic terminal detection.
+    if (err instanceof ReadinessFailedError) {
       throw new ArgoSyncFailedError(
-        `Argo Application "${args.appName}" is ${status.health} (sync=${status.sync}) — it will not become Healthy without intervention.`,
+        `Argo Application "${args.appName}" reached a terminal unhealthy state (Degraded / Missing) — it will not become Healthy without intervention.`,
       );
     }
-
-    if (status.health === "Healthy" && status.sync === "Synced") {
-      return status;
-    }
-
-    await sleep(interval, signal);
+    throw err;
   }
 }

package/src/op/activities/index.ts

@@ -19,3 +19,22 @@ export type { K3dUpArgs, K3dDownArgs } from "./k3d";
 
 export { waitForArgoSync, defaultArgoStatusFetcher, ArgoSyncFailedError } from "./argo";
 export type { WaitForArgoSyncArgs, ArgoAppStatus, ArgoStatusFetcher } from "./argo";
+
+export {
+  waitForReady,
+  defaultResourceFetcher,
+  ReadinessFailedError,
+  readinessFor,
+  isReady,
+  firstTerminal,
+  DEFAULT_READINESS,
+  READINESS_OVERRIDES,
+} from "./wait-for-ready";
+export type {
+  WaitForReadyArgs,
+  ResourceFetcher,
+  ReadinessSpec,
+  ReadinessMatch,
+  ConditionMatch,
+  PathMatch,
+} from "./wait-for-ready";

package/src/op/activities/wait-for-ready.test.ts

@@ -0,0 +1,105 @@
+import { describe, test, expect } from "vitest";
+import {
+  waitForReady,
+  ReadinessFailedError,
+  readinessFor,
+  isReady,
+  firstTerminal,
+  DEFAULT_READINESS,
+  type ResourceFetcher,
+  type ReadinessSpec,
+} from "./wait-for-ready";
+// The k8sWait profile marks ReadinessFailedError non-retryable for this activity.
+import { TEMPORAL_ACTIVITY_PROFILES } from "@intentius/chant-lexicon-temporal/config";
+
+/** A fetcher returning a scripted sequence of objects, repeating the last. */
+function scriptedFetcher(sequence: Array<Record<string, unknown>>): ResourceFetcher {
+  let i = 0;
+  return async () => {
+    const obj = sequence[Math.min(i, sequence.length - 1)];
+    i++;
+    return obj;
+  };
+}
+
+const ready = (conds: Array<{ type: string; status: string }>, extra: Record<string, unknown> = {}) => ({
+  metadata: { generation: 1 },
+  status: { observedGeneration: 1, conditions: conds, ...extra },
+});
+
+const fast = { kind: "certificate", name: "tls", intervalMs: 0 };
+
+describe("readiness model", () => {
+  test("default spec = Ready condition True + observedGeneration", () => {
+    expect(readinessFor(undefined, "Certificate")).toBe(DEFAULT_READINESS);
+    expect(isReady(ready([{ type: "Ready", status: "True" }]), DEFAULT_READINESS)).toBe(true);
+    expect(isReady(ready([{ type: "Ready", status: "False" }]), DEFAULT_READINESS)).toBe(false);
+    expect(isReady(ready([]), DEFAULT_READINESS)).toBe(false);
+  });
+
+  test("observedGeneration lagging metadata.generation blocks readiness", () => {
+    const obj = { metadata: { generation: 5 }, status: { observedGeneration: 4, conditions: [{ type: "Ready", status: "True" }] } };
+    expect(isReady(obj, DEFAULT_READINESS)).toBe(false);
+  });
+
+  test("absent observedGeneration does not block", () => {
+    const obj = { metadata: { generation: 5 }, status: { conditions: [{ type: "Ready", status: "True" }] } };
+    expect(isReady(obj, DEFAULT_READINESS)).toBe(true);
+  });
+
+  test("Argo override uses health/sync, not a Ready condition", () => {
+    const spec = readinessFor("argoproj.io", "Application");
+    expect(spec).not.toBe(DEFAULT_READINESS);
+    const healthy = { status: { health: { status: "Healthy" }, sync: { status: "Synced" } } };
+    const progressing = { status: { health: { status: "Progressing" }, sync: { status: "Synced" } } };
+    const degraded = { status: { health: { status: "Degraded" }, sync: { status: "OutOfSync" } } };
+    expect(isReady(healthy, spec)).toBe(true);
+    expect(isReady(progressing, spec)).toBe(false);
+    expect(firstTerminal(degraded, spec)).toBeDefined();
+    expect(firstTerminal(healthy, spec)).toBeUndefined();
+  });
+});
+
+describe("waitForReady", () => {
+  test("resolves once the Ready condition flips True", async () => {
+    const fetcher = scriptedFetcher([
+      ready([{ type: "Ready", status: "False" }]),
+      ready([{ type: "Ready", status: "False" }]),
+      ready([{ type: "Ready", status: "True" }]),
+    ]);
+    const obj = await waitForReady(fast, undefined, fetcher);
+    expect((obj as any).status.conditions[0].status).toBe("True");
+  });
+
+  test("polls past not-ready reads instead of returning early", async () => {
+    let calls = 0;
+    const fetcher: ResourceFetcher = async () => {
+      calls++;
+      return calls < 3 ? ready([{ type: "Ready", status: "False" }]) : ready([{ type: "Ready", status: "True" }]);
+    };
+    await waitForReady(fast, undefined, fetcher);
+    expect(calls).toBe(3);
+  });
+
+  test("throws ReadinessFailedError on a terminal state", async () => {
+    const spec: ReadinessSpec = {
+      ready: [{ conditionType: "Ready", status: "True" }],
+      terminal: [{ path: "status.phase", equals: "Failed" }],
+    };
+    const fetcher = scriptedFetcher([{ status: { phase: "Failed" } }]);
+    await expect(
+      waitForReady({ ...fast, spec }, undefined, fetcher),
+    ).rejects.toBeInstanceOf(ReadinessFailedError);
+  });
+
+  test("k8sWait marks ReadinessFailedError non-retryable", () => {
+    expect(TEMPORAL_ACTIVITY_PROFILES.k8sWait.retry?.nonRetryableErrorTypes).toContain("ReadinessFailedError");
+  });
+
+  test("explicit spec wins over the registry", async () => {
+    const spec: ReadinessSpec = { ready: [{ path: "status.state", equals: "running" }], observedGeneration: false };
+    const fetcher = scriptedFetcher([{ status: { state: "running" } }]);
+    const obj = await waitForReady({ kind: "widget", name: "w", intervalMs: 0, spec }, undefined, fetcher);
+    expect((obj as any).status.state).toBe("running");
+  });
+});

package/src/op/activities/wait-for-ready.ts

@@ -0,0 +1,211 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import { safeHeartbeat, sleep } from "@intentius/chant/op";
+
+const execAsync = promisify(exec);
+
+/**
+ * waitForReady — block until any operator-backed Kubernetes resource reports
+ * ready, driven by a data-only **readiness spec** rather than per-CRD code.
+ *
+ * Like `waitForArgoSync`, this activity is intentionally **dependency-light**:
+ * its signature is primitives + a plain readiness spec, so a Temporal worker
+ * loads it without importing the generated CRD declarable surface. It reads the
+ * resource via `kubectl get -o json` (injectable for tests) and evaluates the
+ * spec's predicates. It generalizes the bespoke `waitForArgoSync` /
+ * `waitForStack` waits — see #365.
+ */
+
+// ── Readiness spec (plain data — no generated-type imports) ──────────
+
+/** Match a Kubernetes-style `status.conditions[]` entry by `type`. */
+export interface ConditionMatch {
+  conditionType: string;
+  /** Required `status` of that condition (default "True"). */
+  status?: string;
+}
+
+/** Match a value at a dot-path into the fetched object. */
+export interface PathMatch {
+  /** e.g. "status.health.status". */
+  path: string;
+  /** Holds when the value strictly equals this. */
+  equals?: string | number | boolean;
+  /** Holds when the value is one of these. */
+  oneOf?: Array<string | number>;
+  // With neither `equals` nor `oneOf`, holds when the value is present (non-null).
+}
+
+export type ReadinessMatch = ConditionMatch | PathMatch;
+
+export interface ReadinessSpec {
+  /** All must hold for the resource to be ready. */
+  ready: ReadinessMatch[];
+  /** If any holds, fail fast — the resource will not become ready. */
+  terminal?: ReadinessMatch[];
+  /**
+   * Also require `status.observedGeneration >= metadata.generation` when both
+   * are present. Default true — most operators set `observedGeneration`.
+   */
+  observedGeneration?: boolean;
+}
+
+/**
+ * The generic default (kstatus-style): a `Ready` condition of `True` and
+ * `observedGeneration` caught up. Covers cert-manager, Gateway API, KubeRay,
+ * and the CockroachDB operator.
+ */
+export const DEFAULT_READINESS: ReadinessSpec = {
+  ready: [{ conditionType: "Ready", status: "True" }],
+  observedGeneration: true,
+};
+
+/**
+ * Per-resource overrides keyed by `"<group>/<kind>"`. Argo's `Application`
+ * reports `health`/`sync`, not a `Ready` condition — the case that proves the
+ * override is necessary (#365).
+ */
+export const READINESS_OVERRIDES: Record<string, ReadinessSpec> = {
+  "argoproj.io/Application": {
+    ready: [
+      { path: "status.health.status", equals: "Healthy" },
+      { path: "status.sync.status", equals: "Synced" },
+    ],
+    terminal: [{ path: "status.health.status", oneOf: ["Degraded", "Missing"] }],
+    observedGeneration: false,
+  },
+};
+
+/** Resolve the readiness spec for a resource: registry override, else default. */
+export function readinessFor(group: string | undefined, kind: string): ReadinessSpec {
+  return READINESS_OVERRIDES[`${group ?? ""}/${kind}`] ?? DEFAULT_READINESS;
+}
+
+// ── Predicate evaluation ────────────────────────────────────────────
+
+function getPath(obj: unknown, path: string): unknown {
+  return path.split(".").reduce<unknown>(
+    (o, k) => (o != null && typeof o === "object" ? (o as Record<string, unknown>)[k] : undefined),
+    obj,
+  );
+}
+
+function isCondition(m: ReadinessMatch): m is ConditionMatch {
+  return (m as ConditionMatch).conditionType !== undefined;
+}
+
+function matchCondition(obj: unknown, m: ConditionMatch): boolean {
+  const conds = getPath(obj, "status.conditions");
+  if (!Array.isArray(conds)) return false;
+  const c = conds.find((x) => x && typeof x === "object" && (x as Record<string, unknown>).type === m.conditionType);
+  return !!c && String((c as Record<string, unknown>).status) === (m.status ?? "True");
+}
+
+function matchPath(obj: unknown, m: PathMatch): boolean {
+  const v = getPath(obj, m.path);
+  if (m.equals !== undefined) return v === m.equals;
+  if (m.oneOf !== undefined) return m.oneOf.includes(v as string | number);
+  return v !== undefined && v !== null;
+}
+
+function matches(obj: unknown, m: ReadinessMatch): boolean {
+  return isCondition(m) ? matchCondition(obj, m) : matchPath(obj, m);
+}
+
+function observedGenerationReady(obj: unknown): boolean {
+  const gen = getPath(obj, "metadata.generation");
+  const obs = getPath(obj, "status.observedGeneration");
+  if (typeof gen === "number" && typeof obs === "number") return obs >= gen;
+  return true; // absent on either side → don't block
+}
+
+/** True when every `ready` predicate holds (and observedGeneration is caught up). */
+export function isReady(obj: unknown, spec: ReadinessSpec): boolean {
+  if (spec.observedGeneration !== false && !observedGenerationReady(obj)) return false;
+  return spec.ready.every((m) => matches(obj, m));
+}
+
+/** The first matching `terminal` predicate, if any — the resource is wedged. */
+export function firstTerminal(obj: unknown, spec: ReadinessSpec): ReadinessMatch | undefined {
+  return spec.terminal?.find((m) => matches(obj, m));
+}
+
+// ── Activity ────────────────────────────────────────────────────────
+
+/** Thrown when the resource reaches a terminal state. Mark non-retryable. */
+export class ReadinessFailedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ReadinessFailedError";
+  }
+}
+
+export interface WaitForReadyArgs {
+  /** Resource kind/type as `kubectl get` accepts it (e.g. "certificate", "raycluster.ray.io"). */
+  kind: string;
+  /** Resource name. */
+  name: string;
+  /** Namespace (omit for cluster-scoped). */
+  namespace?: string;
+  /** kubectl context. */
+  context?: string;
+  /** API group, used to pick a readiness override when `spec` is not given. */
+  group?: string;
+  /** Explicit readiness spec — wins over the registry/default. */
+  spec?: ReadinessSpec;
+  /** Poll interval in ms (default 15000). Heartbeats every poll. */
+  intervalMs?: number;
+}
+
+/** Pluggable resource reader — overridden in tests with a fake. */
+export type ResourceFetcher = (
+  args: WaitForReadyArgs,
+  signal?: AbortSignal,
+) => Promise<Record<string, unknown>>;
+
+/** Read the resource via `kubectl get -o json`. */
+async function fetchViaKubectl(args: WaitForReadyArgs, signal?: AbortSignal): Promise<Record<string, unknown>> {
+  const ns = args.namespace ? `-n ${args.namespace}` : "";
+  const ctx = args.context ? `--context ${args.context}` : "";
+  const { stdout } = await execAsync(`kubectl get ${args.kind} ${args.name} ${ns} ${ctx} -o json`, { signal });
+  return JSON.parse(stdout) as Record<string, unknown>;
+}
+
+export const defaultResourceFetcher: ResourceFetcher = (args, signal) => fetchViaKubectl(args, signal);
+
+/**
+ * Poll until the resource satisfies its readiness spec. Throws
+ * `ReadinessFailedError` on a terminal state. Heartbeats every poll so the
+ * `k8sWait` profile's 60s heartbeat timeout never trips.
+ *
+ * @param fetcher injectable reader (defaults to kubectl). Tests pass a fake to
+ *   drive not-ready → ready / terminal transitions.
+ */
+export async function waitForReady(
+  args: WaitForReadyArgs,
+  signal?: AbortSignal,
+  fetcher: ResourceFetcher = defaultResourceFetcher,
+): Promise<Record<string, unknown>> {
+  const spec = args.spec ?? readinessFor(args.group, args.kind);
+  const interval = args.intervalMs ?? 15_000;
+  let attempt = 0;
+
+  while (true) {
+    if (signal?.aborted) throw new Error("waitForReady aborted");
+    attempt++;
+
+    const obj = await fetcher(args, signal);
+    safeHeartbeat({ step: "waitForReady", kind: args.kind, name: args.name, attempt });
+
+    const term = firstTerminal(obj, spec);
+    if (term) {
+      throw new ReadinessFailedError(
+        `${args.kind}/${args.name} reached a terminal state (${JSON.stringify(term)}) — it will not become ready without intervention.`,
+      );
+    }
+
+    if (isReady(obj, spec)) return obj;
+
+    await sleep(interval, signal);
+  }
+}