@homeflare/alchemy 0.49.0 → 0.50.0

package/docs/kubernetes-ready.md

@@ -0,0 +1,146 @@
+# HomeFlare.Kubernetes.Ready
+
+`@homeflare/alchemy/kubernetes` — a readiness gate for a Kubernetes cluster reached through the
+`talos-openbao` adapter. Walked against `alchemy@2.0.0-beta.81`. Proven offline only (fake `bao`,
+fake apiserver); **not** exercised against a live cluster.
+
+## Why it exists
+
+Upstream ships no readiness resource. `Kubernetes.HelmChart` reconcile returns when server-side
+apply returns, and Alchemy releases every downstream row at that moment. A row chained after the
+Cilium chart would start before one Cilium pod runs. Declare a `Ready` row with
+`after: [chart.objects]` and chain later rows on `ready.ready`.
+
+## Declaring it
+
+```ts
+const cniReady =
+  yield *
+  KubernetesReady('cni-ready', {
+    connection: talosOpenBaoConnection(PINNED_UID), // a literal uid, never an Output
+    checks: [
+      { kind: 'DaemonSet', namespace: 'kube-system', name: 'cilium', minReady: 2 },
+      { kind: 'Deployment', namespace: 'kube-system', name: 'cilium-operator' },
+      { kind: 'CustomResourceDefinition', name: 'ciliumloadbalancerippools.cilium.io' },
+    ],
+    waitTimeout: '10m0s', // Go style h/m/s, default 10m0s
+    pollInterval: '10s', // default 10s
+    after: [cilium.objects],
+  });
+```
+
+Providers: `Layer.mergeAll(Kubernetes.providers(), TalosOpenBaoAdapter(...), KubernetesReadyProvider())`.
+The provider requires `ChildProcessSpawner` (the adapter shells to `bao`).
+
+## What "ready" means
+
+The rules are `kubectl rollout status` (kubectl v0.34.0 `rollout_status.go`), not "Available":
+
+| kind                     | ready when                                                                                                                                                                                       |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| DaemonSet                | `updateStrategy` is `RollingUpdate`, `observedGeneration >= generation`, `updatedNumberScheduled >= minReady`, `numberAvailable - (desiredNumberScheduled - updatedNumberScheduled) >= minReady` |
+| Deployment               | `observedGeneration >= generation`, `updatedReplicas >= spec.replicas`, `replicas == updatedReplicas`, `availableReplicas >= updatedReplicas`                                                    |
+| CustomResourceDefinition | condition `Established` is `True`                                                                                                                                                                |
+
+`minReady` defaults to `desiredNumberScheduled`, and a DaemonSet that wants zero pods is never ready.
+`numberAvailable` also counts available pods of the OLD template, so it is never compared to
+`minReady` alone: subtracting `desired - updated` (the most old pods there can be) leaves a lower
+bound on pods that are both updated and available. Without it, minReady 2 of 4 with two crashlooping
+new pods and two healthy old ones would pass.
+A Deployment whose `Progressing` condition has reason `ProgressDeadlineExceeded` (for the
+generation the controller has observed), and a DaemonSet whose `updateStrategy` is not
+`RollingUpdate` (absent counts as `RollingUpdate`), are typed failures, `KubernetesRolloutFailed`
+(`reason`), not pending.
+
+## Refused at declaration
+
+- `checks` must be non-empty; each needs a known `kind`, a non-empty `name`, a non-empty
+  `namespace` for DaemonSet and Deployment, and `minReady` (DaemonSet only) an integer >= 1:
+  `KubernetesReadyBadCheck { index, problem }`.
+- `after` must hold lazy Outputs of the chart (`chart.objects`): `KubernetesReadyBadAfter { index }`
+  for a plain value, a bare `chart`, or a stable such as `chart.connection`. Those resolve at plan
+  time, so the row would plan `noop` before the chart's update and the gate would be skipped.
+
+## Errors
+
+| outcome                                                        | `read` / `diff` (one pass) | `reconcile` (poll)                                        |
+| -------------------------------------------------------------- | -------------------------- | --------------------------------------------------------- |
+| 404 (`_tag` `KubernetesNotFound`, or `KubernetesApiError` 404) | pending                    | pending                                                   |
+| per-GET timeout (5 s), 5xx, 429, upstream transport `Error`    | read: throws; diff: update | pending, recorded as `lastTransient` (tag + status)       |
+| the same on the connect's identity GET (incl. its 5 s timeout) | propagates                 | connect retried every `pollInterval`, inside the deadline |
+| 401, 403, other 4xx                                            | propagates                 | propagates                                                |
+| uid mismatch, vault (`bao`) failure                            | propagates                 | propagates                                                |
+| any other untagged `Error` (a defect, e.g. an empty namespace) | propagates                 | propagates                                                |
+
+- "Upstream transport `Error`" is only the `Failed Kubernetes ...` wrapper (alchemy `client.ts`).
+- `lastTransient` is the transient of the LAST pass; one that has cleared is not blamed.
+- `read` with no prior output (Alchemy's deferred adoption read on a first create) returns
+  `undefined` without touching the cluster: the row owns nothing to adopt.
+- Every error leaving a GET, the connect's identity GET included, is scrubbed of the response body.
+
+- 404 is matched by tag string with no import, so it is proof against alchemy raising
+  `KubernetesNotFound` instead of `KubernetesApiError` (standing watch: drop the second shape once
+  upstream settles).
+- A deadline fails with `KubernetesReadyTimeout { failing, seconds, lastTransient?, states? }`.
+  `failing` holds **check keys** (`DaemonSet/kube-system/cilium`) only; `states` records per key
+  what the last pass saw: `{ notFound: true }` (a 404 that never resolves) or `{ counts }`
+  (generation and rollout numbers), so a missing object reads differently from a slow rollout.
+- A propagated apiserver refusal is rewrapped as `KubernetesReadyApiError { method, path,
+statusCode }`: upstream's `KubernetesApiError` message quotes up to 1000 bytes of the response
+  body, which this row does not republish.
+- Upstream `readObject` takes no signal, so a timed-out GET abandons its socket rather than
+  aborting it, and process exit is not a bound for a long apply. The poll therefore rations
+  timeouts: after one GET times out the rest of that pass is pending with no GET, and the pause
+  doubles per consecutive timeout (cap 30 s), resetting on a clean pass. Standing watch: drop this
+  when upstream's `readObject` takes an AbortSignal (alchemy PR 1948, per-attempt deadlines).
+- Upstream also retries a transport error itself, for about 40 s (a `spaced` 5 s schedule capped
+  by `recurs(8)`), longer than the per-GET bound, so a dead socket surfaces as the GET timeout.
+
+## Lifecycle
+
+- `read`: one pass, `ready: false` when any check is pending. Never waits.
+- `diff`: refuses a non-literal `connection` (`TalosUidNotLiteral`, also at declaration);
+  `undefined` when unresolved; `replace` when the connection differs (it is in `stables`, so
+  dependants would otherwise see the old one for a deploy; `delete` is a no-op, so nothing live
+  is touched); `noop` when the live pass is ready and the check keys are unchanged; otherwise
+  `update`. It is live on every plan, like `Talos.ClusterHealth`, but a transient (5xx, 429, a
+  timeout, on the connect or a GET) is `update`, never a failed plan: `reconcile` does the
+  waiting. 401/403 and vault failures still propagate.
+- `reconcile`: polls until every check passes or fails typed.
+- `delete` is a no-op and `list` is empty: the row owns nothing in the cluster. `connection` is
+  `stables`, and is copied onto the attributes so the row is `ClusterLike`.
+
+## Secrecy
+
+Attributes are `{ connection, ready, checks }`; the connection is `{ kind, uid }`. No kubeconfig,
+PEM, token or response body reaches an attribute, an error, a log or a file
+(`ready-secrecy.test.ts`).
+
+## Bounded HelmChart (`boundedHelmChartProvider`, ledger row `t10-k1b`)
+
+Upstream's `Kubernetes.HelmChart` has no deadline: alchemy 2.0.0-beta.81's `requestJson` sets no
+timeout and no signal, so a hung apiserver blocks `reconcile`/`read` forever and would hold a 1h
+platform token across a stuck deploy. `boundedHelmChartProvider()` wraps upstream's provider (never
+re-implements it) in `Effect.timeoutOrElse`, failing typed `KubernetesReconcileTimeout { id,
+operation, seconds }`: `HELM_RECONCILE_TIMEOUT = '5m0s'` (render, discovery, ~60 SSA PATCHes) and
+`HELM_READ_TIMEOUT = '1m0s'`.
+
+- Merge it beside `Kubernetes.providers()`: `Layer.mergeAll(Kubernetes.providers(),
+boundedHelmChartProvider())`. A direct `Provider(HelmChart)` service beats the collection
+  (`Provider.ts` `tryFindProviderRegistrationByType`), so the wrapper is the one the engine resolves.
+- `diff`, `delete`, `stables` and `aliases` are upstream's by spread: state identity and replace
+  semantics do not change.
+- The interrupted fiber abandons its socket (upstream takes no signal); the run fails typed and the
+  process exits once main completes. Standing watch: upstream puts no `AbortSignal` on its
+  requests; drop the wrapper when it ships request deadlines (alchemy PR 1948).
+- A malformed override dies at layer build rather than leaving the call unbounded, as
+  `KubernetesReadyBadDuration` naming `Kubernetes.HelmChart` and the field
+  (`reconcileTimeout`/`readTimeout`). The timeout message names the row and seconds only.
+- Errors that pass through (an upstream `KubernetesApiError` quotes up to 1000 bytes of the
+  apiserver body, `client.ts:39-41`) are scrubbed to the body-free `KubernetesReadyApiError`.
+- The read bound rarely fires with the `talos-openbao` adapter: upstream's read only connects, and
+  the kit already caps connect at 10 s and the uid read at 5 s. It is a backstop.
+- `delete` stays unbounded on purpose: every platform row is `retain`, replace cleanup skips
+  deletion of retained rows (alchemy `Apply.ts:1111-1112`), and design §8 only drops state.
+- `isBoundedHelmChartProvider(service)` is true for a service this layer built, so a consuming
+  stack can assert its real `providers` layer resolves the wrapper and not upstream's.

package/docs/peers.md

@@ -29,6 +29,8 @@ asserted against that field; change the field first, then copy its `overrides` b
     "@effect/platform-node": "4.0.1",
     "@effect/platform-node-shared": "4.0.1",
     "@effect/platform-bun": "4.0.1",
+    "@effect/sql-d1": "4.0.1",
+    "@effect/sql-sqlite-do": "4.0.1",
     "rolldown": "1.2.8",
     "redis": "6.3.0"
   }
@@ -50,6 +52,7 @@ next rc and breaks at import. Pin the whole set.
 | `rolldown` → 1.2.9 via vite's `~1.2.6` (measured 2026-09-16)                                | `GET …/rolldown-1.2.9.tgz - 404` at `bun add`                                                            |
 | no `mime` (measured 2026-09-17 against Alchemy 78)                                          | `Cannot find package 'mime'` from cloudflare-runtime                                                     |
 | `redis` → 6.3.0 via the `>=5.0.0 <7.0.0` peer of platform-node/sql-pg (measured 2026-09-30) | `No version matching "6.3.0" found for specifier "@redis/time-series" (but package exists)` at `bun add` |
+| `@effect/sql-d1`/`-sqlite-do` → 4.0.2 via alchemy's `^4.0.0` (measured 2026-10-09)          | unmet peer: 4.0.2 wants `effect ^4.0.2`, the contract pins 4.0.1                                         |
 
 Alchemy 78 adapted to rc.115 — that first row is why we used to pin 112, not a reason to
 stay there. The override is still the only thing that holds the set together.
@@ -62,6 +65,16 @@ failed outright for that window. The line completed the same hour — every `@re
 sub-package published at 6.3.0 (measured 11:12:19Z) — and the pin moved onto that complete
 set. The pin stays exact because the same class of gap can recur with any future redis minor.
 
+⛔ **`@effect/sql-d1` and `@effect/sql-sqlite-do` (added 2026-10-09, ledger row
+kit-contract-effect-402) are exact in `overrides` because alchemy beta.81 itself depends on
+both at `^4.0.0`** (`npm view alchemy@2.0.0-beta.81 dependencies`). A fresh, lockless install
+resolves `^4.0.0` to 4.0.2, whose peer is `effect ^4.0.2` — an **unmet peer against the
+contract's effect 4.0.1 on every fresh consumer install**; only an already-locked tree hid it
+(the kit's own `bun.lock` said 4.0.1 because it was locked earlier). 4.0.1 peers on
+`effect ^4.0.1`, so the pin holds the D1 / Durable-Object SQL resources on the version the
+kit is tested on — the runtime path is unverified, as no stack uses those resources yet. They
+are overrides, not install-line pins: they arrive transitively through `alchemy`.
+
 ⚠️ `@effect/platform-node` is **required, not optional**: Alchemy's module graph reaches
 `Cloudflare/Workers/WorkerBridge → @effect/platform-node/NodeServices` even when you only
 import the Proxmox subpath.

package/docs/provider-standard.md

@@ -98,6 +98,13 @@ already ships is a finding, even when it works.
   `Redacted` values in plaintext, and only one state store encrypts them.
 - **Bounded waits (S26).** A retry stops after at most 8 to 10 attempts and under about a
   minute. A poll never runs past about 90 seconds.
+  - **The one exception: readiness gates** (`Talos.ClusterHealth`, `Kubernetes.Ready`). For these,
+    waiting IS the resource's job: a CNI or control-plane rollout takes minutes. So the wait may
+    run to a declared `waitTimeout` (default minutes, never unbounded) when ALL of these hold:
+    the timeout is a typed, declared prop; every single request inside it is bounded (a per-call
+    deadline); transient errors are pending, never a retry storm; and the timeout is a typed error
+    naming what was still pending. Any other resource keeps the 90-second rule. (Added
+    2026-10-10 with `Kubernetes.Ready`, PR 373; `Talos.ClusterHealth` already waited 20m.)
 
 ## The Bun line for this package (S42–S45)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.49.0",
+  "version": "0.50.0",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",
@@ -55,6 +55,10 @@
       "types": "./dist/talos/index.d.ts",
       "default": "./dist/talos/index.js"
     },
+    "./kubernetes": {
+      "types": "./dist/kubernetes/index.d.ts",
+      "default": "./dist/kubernetes/index.js"
+    },
     "./proxmox": {
       "types": "./dist/proxmox/index.d.ts",
       "default": "./dist/proxmox/index.js"
@@ -181,6 +185,8 @@
         "@effect/platform-bun": "4.0.1",
         "@effect/platform-node": "4.0.1",
         "@effect/platform-node-shared": "4.0.1",
+        "@effect/sql-d1": "4.0.1",
+        "@effect/sql-sqlite-do": "4.0.1",
         "rolldown": "1.2.8",
         "redis": "6.3.0"
       },

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';