@homeflare/alchemy 0.49.0 → 0.51.0

package/docs/unifi-network-write.md

@@ -0,0 +1,90 @@
+# `Unifi.Network` write scope — what the one PUT may and may not do
+
+`docs/unifi.md` describes the three-way update. This page records the limits placed on it after
+the red team rounds 1 and 2 of PR 377. The only intended consumer is ONE VLAN's
+`ipv6Configuration`: a patch may SET only `ipv6Configuration` and REMOVE only `ipv6Configuration`;
+everything else a whole-object `PUT` could reach is refused with a typed error that carries field
+names only, never values.
+
+| refusal                         | when                                                                        |
+| ------------------------------- | --------------------------------------------------------------------------- |
+| `UnifiFieldNotSettable`         | a patch sets any key but `ipv6Configuration` (`enabled`, `dhcpGuarding`, …) |
+| `UnifiFieldNotRemovable`        | a patch drops any key but `ipv6Configuration`                               |
+| `UnifiManagementNetworkRefused` | the live object has `default: true` (the management LAN)                    |
+| `UnifiImmutableFieldChanged`    | a patch sets or drops `zoneId`, `vlanId`, `management`, `deviceId`          |
+| `UnifiIdentityChanged`          | `olds` names another `siteId`/`networkId` than `news`                       |
+| `UnifiUpdateWouldBeNoop`        | the merged body equals live                                                 |
+
+Every one of them fires after the live GET and before any PUT.
+
+⛔ **Why a removable allowlist.** A key in `patch.unset` is deleted from the PUT body, and the
+controller reads an omitted `dhcpGuarding`/`ipv4Configuration`/`ipv6Configuration` as "off". So
+leaving a field out of a declaration would turn it off on the console. Only `ipv6Configuration`
+(the block this path exists for, and the revert target) may be removed. `network-scope.ts` holds
+the lists (`SETTABLE_KEYS`, `REMOVABLE_KEYS`, `IMMUTABLE_KEYS`); widening them is a kit change.
+
+⚠️ **No version check: a hand edit between the read and the write is overwritten.** The PUT is the
+live GET plus the patch, sent whole; the API offers no ETag or revision, so a change made on the
+console between that GET and the PUT is replaced by the GET's copy. The window is one reconcile.
+
+Non-USER `metadata.origin` is deliberately not handled: there is no rule for it yet.
+
+## The wire guard (`wire-guard.ts`)
+
+⛔ **The allowed PUT is anchored to the configured base URL**, not matched by suffix. The request
+must share the base's origin, its path must be exactly `<base path>/v1/sites/<site>/networks/<id>`,
+and it must carry no query string or fragment. `?force=true`, a nested
+`/v1/sites/OTHER/v1/sites/s/networks/n`, a different base path and `//v1/...` all die before the
+transport. `unifiHandlers` reads the base URL from the same `Credentials` the SDK uses; with none
+the guard allows nothing.
+
+⛔ **`redirect: 'manual'` is set per request, on the calling fiber's `RequestInit`, for EVERY
+guarded request — GETs included — and any 3xx answer dies with `UnifiRefusedRequest`, whatever the
+method.** Effect 4.0.1 `layerMergedContext` lets an outer `FetchHttpClient.RequestInit` REPLACE one
+the layer provides, so a layer-provided `redirect: 'manual'` is silently lost under any consumer
+that sets its own `RequestInit`. The guard reads the fiber's value and merges `redirect: 'manual'`
+over it, the `openbao/bao-http.ts` `overSocket` pattern. `wire-guard-anchor.test.ts` proves it
+against a real `Bun.serve` answering 301/302/303/307/308.
+
+A GET's redirect is refused for the same reason a PUT's is, under both postures: fetch would
+follow it and re-send the request — still carrying the API-key header — to a URL the guard never
+vetted. Before the 2026-10-10 fix only reconcile's GETs ran `manual` (a 3xx surfaced raw and failed
+the SDK decode) while `read`/`diff` followed it silently; one rule everywhere now, fail closed.
+
+⛔ **Where a TLS `RequestInit` must live: on the CALLING FIBER**, provided around the program with
+`Effect.provideService(FetchHttpClient.RequestInit, { tls: … })`, not inside the fetch layer's
+build context (`FetchHttpClient.layer.pipe(Layer.provide(…))`). The guard re-provides `RequestInit` per
+request, merged over the fiber's value, so an option set only inside the layer is overridden on every
+guarded request, GETs included, and a consumer wired that way silently loses its TLS option (it
+fails closed: the handshake is refused, nothing is sent insecurely).
+
+⛔ **Backstop: the response URL must equal the request URL.** If a consumer's own transform provides
+`RequestInit` WITHOUT merging, `manual` is lost and fetch follows a redirect. The guard dies when
+`res.url` differs from `HttpClientRequest.toUrl(res.request)`. The allowed-path check likewise reads
+`toUrl`, so a `setUrlParam` query is seen and refused. Tests: `wire-guard-round2.test.ts`.
+
+⛔ **Refusal messages redact the cloud connector Console ID**: the path segment after `/consoles/`
+becomes `<redacted>`.
+
+## The static check (`write-op-reference.test.ts`)
+
+It harvests the SDK's real write-op export names straight from its own service modules (every
+name starting `create`/`update`/`delete`/`patch`/`execute`/`remove`/`adopt`) and fails any file
+that mentions the SDK's package specifier and contains one of those names as a token anywhere — an
+identifier, a bracket key, a destructured binding, a re-export or a dynamic-import property access
+all read the same way, so one scan catches every syntax form without parsing which one it is. Its
+`WRITE_OP_ALLOWLIST` is exactly `network-update.ts` → `updateNetwork`; any other file naming that
+op, or that file naming `createNetwork`/`deleteNetwork`, is an offense.
+
+## The PUT is attempted once
+
+`updateNetwork` runs under `Retry.none`. The SDK's default policy would replay a write whose first
+attempt may already have landed; a replay then runs against a controller state this reconcile never
+read. A failure surfaces for the operator instead. Reads keep the default policy.
+
+## After a PUT that landed
+
+`UnifiUpdateDidNotConverge` means the PUT LANDED and live now differs from the declaration. It is
+not rolled back. The next deploy sees drift and answers `UnifiLiveDriftedSinceDeploy`, whose
+message names both causes (a hand edit, or an earlier non-converging PUT). Recovery in both cases
+is a re-import of the live object.

package/docs/unifi.md

@@ -1,10 +1,9 @@
 # UniFi Network — `@homeflare/alchemy/unifi`
 
-⛔ **READ-ONLY, BY TIM'S RULE (2026-09-24).** `Unifi.Network` and `Unifi.FirewallZone` read and
-adopt; neither has a create, an update body or a working delete. `reconcile`/`delete` both fail
-with a typed `UnifiWriteRefused` naming the policy rather than calling any SDK write operation.
-Lifting the rule is a kit change — a PR that adds a write path, reviewed as one — not a flag a
-stack can pass. See `packages/alchemy/src/unifi/policy.ts`.
+⛔ **ADOPT-ONLY, EXCEPT ONE WRITE (Tim 2026-09-24, lifted for one case 2026-10-10).** Every UniFi
+family reads and adopts; `Unifi.Network` alone may UPDATE (a three-way whole-object PUT, below).
+Create and delete, and every other family's update, fail with a typed `UnifiWriteRefused`. Widening
+the rule is a kit change, not a flag a stack can pass. See `packages/alchemy/src/unifi/policy.ts`.
 
 This page covers `Unifi.Network`/`Unifi.FirewallZone` only. Every other read-only family has its
 own doc, per family (`docs/unifi.md` would breach the 200-line cap otherwise): [`Unifi.DnsPolicy`](./unifi-dns-policy.md), [`Unifi.AclRule`/`Unifi.AclRuleOrdering`](./unifi-acl-rule.md),
@@ -59,7 +58,7 @@ credential, untouched by this family. Only reads were probed, by hand, outside t
 test suite — nothing in this PR's code exercises the vendor API live, and a write path would still
 need its own verification.
 
-## Adopt is the default posture, and it never writes
+## Adopt is the default posture, and the one write is a three-way Network update
 
 `adopt(true)` is piped onto every resource by its convenience constructor (`network(...)`,
 `firewallZone(...)`) — H5. A cold read of a live match answers `Unowned(attrs)` (H1, the
@@ -68,36 +67,36 @@ objects carry no tag or metadata field this stack could stamp), and `adopt(true)
 a silent bind instead of an `OwnedBySomeoneElse` refusal — the deploy never needs `--adopt`.
 
 ⚠️ **A forced post-adoption reconcile still runs once (H6), and it still makes no write.**
-Beta.79 forces one `reconcile` call after every cold adoption whether or not `diff` said noop.
+Beta.81 forces one `reconcile` call after every cold adoption whether or not `diff` said noop.
 `resource.ts`'s `reconcile` handles this the same way `discord/resource.ts` does: it reads the
-live object again and only refuses when it is missing (would need a create) or drifted (would
-need a write); an exact match returns the live attributes and calls nothing.
+live object again; an exact match returns the live attributes and calls nothing, a missing object
+refuses `create`, and drift refuses `update` unless the row has prior state (`olds` AND `output`)
+and a `Unifi.Network` spec: then `update-reconcile.ts` refuses if live differs from `olds` (a hand
+edit), else PUTs live-plus-the-`news≠olds`-patch (`network-update.ts`; a dropped key is removed).
+
+The limits on that PUT (removable allowlist, management LAN, immutable fields, anchored path,
+no retry) are in [`unifi-network-write.md`](./unifi-network-write.md).
 
 ## `list` answers `[]`
 
 `GET /v1/sites/{siteId}/networks` answers every network on the site. Adoption stays explicit —
 the same reasoning `Proxmox.User`'s and NetBox's own `list` give.
 
-## Defense in depth: GET-only at the wire (2026-09-26)
-
-`policy.ts`'s `UnifiWriteRefused` stops write INTENT at `reconcile`/`delete` — this family calls
-no SDK write op anywhere today. `GetOnlyHttpClient` (`resource.ts`, barrel-exported so
-`homeflare-network`'s own import-layer guard can reuse it instead of re-implementing the same
-wrap), installed in `unifiHandlers`'s `withCredentials`, stops the same thing one layer lower, AT
-THE WIRE: it wraps whatever `HttpClient` the caller provides so ANY non-`GET` method dies with
-`UnifiNonGetRequest` (its message carries the request PATH only, never the host — a cloud
-connector's base URL embeds the account's Console ID) before the request reaches the transport —
-a backstop for a future resource file that, by mistake, called an SDK write operation directly.
-`write-op-reference.test.ts` is the matching static check: it harvests the SDK's real write-op
-export names straight from its own service modules (every name starting
-`create`/`update`/`delete`/`patch`/`execute`/`remove`/`adopt`) and fails any file that mentions
-the SDK's package specifier and contains one of those names as a token anywhere — an identifier, a
-bracket key, a destructured binding, a re-export or a dynamic-import property access all read the
-same way, so one scan catches every syntax form without parsing which one it is.
-`get-only-guard.test.ts` proves the wire guard's mechanism directly against a fake `HttpClient`,
-AND that `unifiHandlers` actually installs it (a handler-level probe, not just the mechanism in
-isolation — `network.test.ts`/`firewall-zone.test.ts` call the lower-level `unifiOperations(spec)`
-directly and never exercise `withCredentials` at all).
+## Defense in depth: GET-only at the wire, one per-row exception (2026-09-26, 2026-10-10)
+
+`policy.ts`'s `UnifiWriteRefused` stops write INTENT at `reconcile`/`delete`. `wire-guard.ts`'s
+`guardedHttpClient(allow)` (`GetOnlyHttpClient` = empty list; barrel-exported so `homeflare-network`'s
+import-layer guard can reuse it), installed in `unifiHandlers`, stops it one layer lower, AT THE
+WIRE: any non-`GET` dies with `UnifiRefusedRequest` (alias `UnifiNonGetRequest`; PATH only, never
+the host — a cloud base URL embeds the Console ID) unless `(method, path)` matches the row's own
+allow entry, `PUT /v1/sites/<siteId>/networks/<networkId>`, supplied only to `reconcile` and only
+by a spec with `update`. The guard also sets fetch `redirect: 'manual'` on every request, GETs
+included, and dies on any 3xx answer (fetch would re-send the request — a PUT with its body, a GET
+with the API key — to a URL the guard never saw).
+`wire-guard.test.ts` proves the guard directly against a fake `HttpClient`, AND that
+`unifiHandlers` installs it (the family tests call `unifiOperations(spec)` and never exercise
+`withCredentials`). The static check `write-op-reference.test.ts` is described in
+[`unifi-network-write.md`](./unifi-network-write.md).
 
 ## Pagination helper
 
@@ -144,8 +143,7 @@ UniFi Network Integration API **10.4.57** (OpenAPI 3.1.0, 44 paths), via
 (`docs/distilled-interim.md`). Traps in the underlying API that this read-only family cannot
 trigger but a future write path must respect — whole-object `PUT`, ordering endpoints that
 replace the whole list, `removeDevice` unadopting and factory-resetting hardware — are recorded
-in the distilled package's own `README.md` and in the estate's `docs/unifi-api-notes.md`
-(outside this repo).
+in the distilled package's own `README.md` (`packages/distilled-unifi-network`).
 
 ## Spec-version check against the live-measured console (2026-09-24)
 
@@ -192,8 +190,10 @@ attributed, declared or compared. Both declaration renderers and both `matches`
 `value == null` / `deepEqual(..., { stripNullish: true })` consistently, per `network-form.ts`'s
 own header. No departure found — nothing in this family needed changing.
 
-⚠️ **Correction (2026-09-26):** the line above is no longer true as written. `resource.ts` now
-has exactly one `Effect.die` — `GetOnlyHttpClient`'s guard (see "Defense in depth" above) —
-classified in its own comment per distilled-doctrine's "classify every die/orDie": it raises a
-NEW defect for a failure mode outside every generated SDK operation's declared error union, never
-converts an existing typed failure the way `orDie` would. Still no `Effect.orDie` anywhere.
+⚠️ **Correction (2026-09-26, recounted 2026-10-10):** the line above is no longer true as written.
+The family has exactly TWO `Effect.die` call sites, both in `wire-guard.ts`'s guard (see "Defense
+in depth" above): the request-side refusal of a non-GET off the row's allow list, and the
+response-side refusal of a 3xx answer. Each raises a NEW defect for a failure mode outside every
+generated SDK operation's declared error union, per distilled-doctrine's "classify every
+die/orDie" — neither converts an existing typed failure the way `orDie` would. Still no
+`Effect.orDie` anywhere.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.49.0",
+  "version": "0.51.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';