@homeflare/alchemy 0.48.1 → 0.50.0

package/docs/cloudflared-tunnel.md

@@ -0,0 +1,136 @@
+# CloudflaredTunnel — a Cloudflare Tunnel without its token in state
+
+`CloudflaredTunnel` (`Cloudflare.CloudflaredTunnel`) declares a Cloudflare Tunnel of the cloudflared
+kind (`cfd_tunnel`): the object whose `<id>.cfargotunnel.com` target DNS records point at and whose
+remote configuration holds the ingress rules. It declares **the tunnel object only**: no ingress
+rules, no routes, no DNS record, no connector Deployment. Those are separate declarations that name
+this tunnel's `id`. Read 2026-10-09 against `alchemy@2.0.0-beta.81` and
+`@distilled.cloud/cloudflare@1.0.0-rc.13`.
+
+## Why not `Cloudflare.Tunnel.Tunnel`
+
+- ⛔ **It puts the connector token in state.** Its `reconcile`, `read` and `list` call
+  `getTunnelCloudflaredToken` and keep the result as `token: Redacted<string>`
+  (`alchemy/src/Cloudflare/Tunnel/Tunnel.ts`). Alchemy's state encoder writes a `Redacted` value as
+  `{"__redacted__": "<the value>"}` (`alchemy/src/State/StateEncoding.ts`, `encodeState`, which
+  LocalState, HttpStateStore and PostgresState all call before writing). The state store is not
+  encrypted, and the token is what `cloudflared tunnel run --token` accepts, so anyone who can read
+  state can run a connector for the tunnel and receive its traffic.
+- **Its plans need a Write token.** The token endpoint is expected to need a Write permission, so even a plan
+  would. **UNVERIFIED for `cfd_tunnel`**: the only citation is the sibling Mesh node token endpoint
+  ("Cloudflare One Connectors Write", per its API reference, read 2026-09-21; see
+  `src/cloudflare/mesh-node-form.ts`), and the `cfd_tunnel` token endpoint's permission was not
+  read. `CloudflaredTunnel` never calls it, so a plan does not depend on the answer.
+
+`CloudflaredTunnel` follows the same pattern as [MeshNode](./mesh-node.md): attributes with no
+secret, adoption by exact name, `retain` by default. The type string is `CloudflaredTunnel`, not
+`Tunnel`, so it cannot be confused with upstream's `Cloudflare.Tunnel.Tunnel` in a stack that uses both.
+
+## Declaring a tunnel
+
+```ts
+import { CloudflaredTunnel, providers as homeflareCloudflare } from '@homeflare/alchemy/cloudflare';
+
+// providers: Layer.mergeAll(Cloudflare.providers(), homeflareCloudflare()),
+const admin = yield * CloudflaredTunnel('k8s-admin', { name: 'k8s-admin' });
+// admin.id → the tunnel UUID: `${admin.id}.cfargotunnel.com` is the DNS target
+```
+
+| prop   | type     | notes                                                                 |
+| ------ | -------- | --------------------------------------------------------------------- |
+| `name` | `string` | Unique per account. The identity used for adoption. Renames in place. |
+
+Attributes: `id`, `accountId` and `name`. ★ There is no `status`: it moves as connectors attach and
+drop, so a stored copy would make every `alchemy drift` flag the tunnel; read health from the API
+or the metrics. ⛔ There is no token, secret or `tunnelSecret` attribute, and none is sent. The request schema documents `tunnel_secret` as the password for a _locally-managed_ tunnel
+(`@distilled.cloud/cloudflare@1.0.0-rc.13`, `src/services/zero_trust.ts`, `CreateTunnelCloudflaredRequest`);
+this resource always sends `config_src: "cloudflare"`. **UNVERIFIED**: that Cloudflare itself generates and
+keeps a secret when `tunnel_secret` is omitted for such a tunnel; the schema says only that the field is optional. `accountId` is not a secret; it is what
+`read` and `delete` address, so they never act on whatever account the environment names today.
+
+The account and credentials come from Alchemy's own Cloudflare environment
+(`Cloudflare.CloudflareApiLive()`): an Alchemy profile, or `CLOUDFLARE_API_TOKEN` and
+`CLOUDFLARE_ACCOUNT_ID` in CI.
+
+### Remotely configured only
+
+The tunnel is always created with `config_src: "cloudflare"` (managed through the API and the Zero
+Trust dashboard), sent explicitly. The SDK types the field as optional (`local` or `cloudflare`)
+and does not document the default (`CreateTunnelCloudflaredRequest`, `zero_trust.ts`). It is
+create-only: the PATCH body has `name` and `tunnelSecret` only. A tunnel found by name whose
+`config_src` is `local` is **refused on adoption** with a sentence and left untouched, because its
+ingress is a YAML file on its origin and remote rules would be accepted and never applied.
+⚠️ UNVERIFIED: that every real GET/list response carries `config_src`. A response without it is
+accepted; only an explicit `local` is refused.
+
+## The token is not this resource's business
+
+Whatever installs the connector fetches the token at that moment and hands it straight to the
+workload's secret store (`GET /accounts/{id}/cfd_tunnel/{id}/token`, which needs a Write
+permission). It must not go into Alchemy state, a log line or a CI variable. No function in this
+package calls that endpoint, `observe` copies named fields only, and
+`cloudflared-tunnel-state.test.ts` proves the persisted state holds no token. ⚠️ Never deploy with
+`DISTILLED_DEBUG_HTTP` set: distilled prints the start of every response body.
+
+## What each change does
+
+| change                 | answer                  | what happens on Cloudflare                                                                                           |
+| ---------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `name`                 | `update`                | `PATCH`. The id, connectors and `cfargotunnel.com` target survive.                                                   |
+| account (provider env) | `replace`, create-first | A new tunnel in the new account. Under `retain` the old one stays.                                                   |
+| nothing                | none                    | Zero writes and no token read. An existing row's plan makes no request (`diff` is pure); the cold probe is one list. |
+
+⛔ **Removal policy: `retain` by default**, like MeshNode and the other kit resources whose deletion
+breaks their consumers. Deleting a tunnel drops its remote configuration and orphans every DNS record
+that targets it; a new tunnel has a new id and token. Dropping the declaration or `alchemy destroy`
+leaves the tunnel live and only drops it from state. Opt a declaration into deletion with
+`.pipe(RemovalPolicy.destroy())`. ⚠️ Under `retain` an account-change replace leaves the old tunnel
+live and unmanaged.
+
+## Adoption
+
+An existing tunnel is found by **exact** name among `cfd_tunnel`s and returned `Unowned`. Alchemy
+refuses to take it over until the resource is wrapped in `adopt(true)` (or `--adopt` is passed). A
+deleted tunnel, a tunnel of another type (a `warp_connector` Mesh node shares the name space) and a
+prefix match are never matched, and a name that matches two live tunnels is refused. Adoption is
+idempotent: the adopted row holds the id, so a repeat deploy takes the owned path and writes
+nothing. ⛔ The name probe runs only when there is **no** stored row. A stored id that the API no
+longer resolves (deleted out of band) reads as missing, never as a same-named tunnel: `alchemy drift`
+treats what `read` returns as already ours, so a probe there would write a foreign tunnel into this
+row without `adopt(true)`. Drift reports it missing and recreates, and the create refuses and
+names the holder. Without `adopt(true)`, a create whose name is held by another tunnel refuses and names the
+holder; it never converges on it, and the sentence says not to delete it.
+
+An interrupted create (the tunnel was made, its state was not saved) is found the same way on the
+next plan, so it too needs `adopt(true)`. ⚠️ distilled retries a create after a lost response or a
+5xx, and the retry is answered code 1013 by the tunnel the first attempt made: the error then names
+that tunnel's id and is not adopted silently, because a concurrent creator looks the same.
+
+## Deleting
+
+`delete` runs only under `RemovalPolicy.destroy()`. It addresses the **stored id and account**,
+never a name: it reads that id first, does nothing when the tunnel is already gone or soft-deleted,
+and refuses an empty id before any request. The API refuses a delete while connectors are attached
+("The tunnel must have no active connections", the SDK's own doc on `deleteTunnelCloudflared`); that
+error passes through unchanged, so scale cloudflared to zero first. No retry loop is added: a
+connector does not detach within seconds on its own. A tunnel that vanishes between the pre-read and
+the DELETE is a successful delete: the 404 reaches the caller as `NotFound` at runtime though the SDK's
+typed error union omits it (`protocol.ts`, `HTTP_STATUS_MAP`), so it is matched by tag name and caught. ⚠️ UNVERIFIED against the real API: the fake
+answers 404 / code 1002 there, the same shape `getTunnelCloudflared` documents.
+
+`list` is empty and `nuke` skips this type: Alchemy's own `Tunnel.Tunnel` already enumerates every
+`cfd_tunnel` for `alchemy unsafe nuke` (fetching each token to do it), and a second listing would
+delete each tunnel twice.
+
+## Tests
+
+Three test files in `src/cloudflare/` (plus `cloudflared-tunnel-harness.ts`, their shared helpers)
+run the provider against a fake API (`fake-tunnel.ts`) that hands out a token on every surface it can:
+
+- `cloudflared-tunnel.test.ts`: the lifecycle; the create body is `{name, config_src}` and no
+  request ever touches `/token`.
+- `cloudflared-tunnel-edges.test.ts`: each refusal and recovery, written to fail when its guard
+  is deleted.
+- `cloudflared-tunnel-state.test.ts`: Alchemy's real plan/apply, then `encodeState` over the stored
+  rows: no `__redacted__` marker, no `token` key, no token value, with a negative control showing
+  the same encoder does write a `Redacted` token. Also the removal policy and adoption.

package/docs/credentials.md

@@ -3,7 +3,7 @@
 Moved out of the README (2026-09-21) to make room under its 200-line cap; the text is unchanged.
 
 `CLOUDFLARE_API_TOKEN` is read from the environment at call time, never at module scope.
-`MeshNode` instead resolves credentials and the account the way `Cloudflare.providers()` does
+`MeshNode` and `CloudflaredTunnel` instead resolve credentials and the account the way `Cloudflare.providers()` does
 (an Alchemy profile, or `CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID` in CI).
 
 ⛔ **Mint a short-lived, scoped token** — do not reuse a long-lived one, and never a Global

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/ownership.md

@@ -100,8 +100,9 @@ escalating to `--adopt` only on `OwnedBySomeoneElse`
 ([inspecting state](https://alchemy.run/cli/inspecting-state#recover-from-bad-state)). For the
 families above that escalation always comes (decided 2026-09-21): an object whose row is gone is
 `Unowned`, so the deploy needs `--adopt`, or `adopt(true)` on its declaration. `MeshNode`
-([mesh-node.md](./mesh-node.md)) and `R2BucketLock` (`src/cloudflare/r2-bucket-lock.ts`) need it
-too. A `CaddyConfig` running the declared config re-imports without it, and so does every family
+([mesh-node.md](./mesh-node.md)), `CloudflaredTunnel`
+([cloudflared-tunnel.md](./cloudflared-tunnel.md)), `SaasOidcApplication` ([saas-oidc.md](./saas-oidc.md)) and
+`R2BucketLock` (`src/cloudflare/r2-bucket-lock.ts`) need it too. A `CaddyConfig` running the declared config re-imports without it, and so does every family
 whose `read` never answers `Unowned`: the `pveHandlers` resources (Limits), the `forgejoHandlers`
 resources and the Talos resources. Read the takeover first with `hf-adopt-verify`
 ([adopt-verify.md](./adopt-verify.md)).

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/docs/saas-oidc.md

@@ -0,0 +1,185 @@
+# SaasOidcApplication — Access as an OIDC provider, with no client secret in state
+
+`SaasOidcApplication` (`HomeFlare.Access.SaasOidcApplication`) declares a Cloudflare Access **SaaS
+application** of auth type `oidc`: Access acts as the OpenID Connect provider for one relying
+party (OpenBao's OIDC auth, Headlamp, a Kubernetes API server). It exposes the issuer, the client
+id and the JWKS endpoint as attributes, so the relying party's configuration can be declared from
+them. Read 2026-10-09 against `alchemy@2.0.0-beta.81` and
+`@distilled.cloud/cloudflare@1.0.0-rc.13`.
+
+## Why not `Cloudflare.Access.Application`
+
+- **It cannot send or read `saas_app`.** Its source mentions `saas` only as an app type and in two
+  comments (`Cloudflare/Access/Application.ts`, beta.81). An OIDC app is the `saas_app` object.
+- **The SDK drops it on the way back.** The request type carries `saasApp`
+  (`AccessApplicationsCreateRequestSaasAppOIDCSaaSApp`), so create and update use it. But a fake
+  API that answered a full `saas_app` decoded, for both `getAccessApplicationForAccount` and
+  `createAccessApplicationForAccount`, to `{ domain, type, id, aud, name, policies }` (measured
+  2026-10-09). So the client id, redirect URIs, scopes and grants are read from the wire JSON by
+  one raw `GET /accounts/{account_id}/access/apps/{app_id}`, over the same `HttpClient` and
+  credentials the SDK uses. That one read is the only hand-written call; it adds no path.
+  ❓ **Open question for Tim (lane contract 1, SDKs over hand-rolling):** the raw GET exists only
+  because rc.13 decodes the GET without `saas_app`. Approve it until upstream decodes the field, or
+  hold this resource.
+- Track upstream: when Alchemy's `Access.Application` gains `saas_app` (and distilled decodes it),
+  this resource should be retired in its favour. Nothing is filed upstream from here.
+
+## At a glance
+
+```ts
+import { SaasOidcApplication } from '@homeflare/alchemy/cloudflare';
+
+const app = yield * SaasOidcApplication('Headlamp', { teamDomain, policies, saasApp });
+// app.issuer, app.clientId, app.jwksEndpoint
+```
+
+- ⛔ **The client secret is never read, stored or logged.** A public client declares
+  `allowPkceWithoutClientSecret: true` with the PKCE grant, and then no secret exists.
+- ⛔ **The type id is a state key** (moved from homeflare-openbao verbatim) and it **retains on
+  destroy**: deleting the app deletes the client id every relying party uses.
+
+## Declaring an app
+
+```ts
+import { SaasOidcApplication, providers } from '@homeflare/alchemy/cloudflare';
+
+// providers: Layer.mergeAll(Cloudflare.providers(), providers()),
+const headlamp =
+  yield *
+  SaasOidcApplication('Headlamp', {
+    name: 'Headlamp',
+    teamDomain: 'example.cloudflareaccess.com',
+    policies: [adminPolicyId],
+    saasApp: {
+      authType: 'oidc',
+      redirectUris: ['https://headlamp.example.com/oidc-callback'],
+      scopes: ['openid', 'email', 'groups'],
+      grantTypes: ['authorization_code_with_pkce'],
+      accessTokenLifetime: '15m',
+      allowPkceWithoutClientSecret: true, // a public client: no secret exists
+    },
+  });
+// headlamp.issuer, headlamp.clientId, headlamp.jwksEndpoint
+```
+
+| prop                                           | notes                                                                                        |
+| ---------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `teamDomain`                                   | **Required.** Bare hostname of the Zero Trust team, no scheme or path.                       |
+| `applicationId`                                | Optional. Set it to adopt a known live app; otherwise the app is found by exact `name`.      |
+| `name`                                         | Optional. Defaults to a physical name from the logical id.                                   |
+| `policies`                                     | Reusable Access policy ids, in ascending precedence. The order is declared: a reorder syncs. |
+| `sessionDuration`, `allowedIdps`               | Optional. Written on create and on any sync. `sessionDuration` defaults to `24h`.            |
+| `autoRedirectToIdentity`, `appLauncherVisible` | Optional. `appLauncherVisible` defaults to `false`.                                          |
+| `saasApp.redirectUris`, `scopes`, `grantTypes` | The OIDC client's settings.                                                                  |
+| `saasApp.accessTokenLifetime`                  | `m` or `h` units, `1m` to `24h` (the SDK field doc).                                         |
+| `saasApp.refreshTokenLifetime`                 | Optional. Needed for the `refresh_tokens` grant.                                             |
+| `saasApp.allowPkceWithoutClientSecret`         | `true` = public client. Needs the `authorization_code_with_pkce` grant (refused otherwise).  |
+
+Attributes: everything above that Cloudflare reports, plus `applicationId`, `aud`, `clientId`,
+`accountId`, `teamDomain`, `domain`, and the OIDC URLs `issuer`
+(`https://<teamDomain>/cdn-cgi/access/sso/oidc/<clientId>`), `authorizationEndpoint`,
+`tokenEndpoint`, `jwksEndpoint`, `userinfoEndpoint` and `configurationEndpoint`.
+
+★ **The team domain is a prop, not a constant.** The openbao copy this came from hardcoded one
+account's. A declared `teamDomain` that disagrees with the host Cloudflare reports in the app's own
+`domain` is refused before any write to an existing app, so the issuer cannot point at a different
+team. When Cloudflare reports no `domain` at all, the team already recorded in the row stands in: a
+declaration that changes it is refused too (the issuer is a declared stable and cannot move).
+
+★ **A first create is checked against the account's organization, when it can be read.** No app
+exists to compare, so before the first write the resource reads the Zero Trust organization
+(`GET /accounts/{account_id}/access/organizations`, the SDK's `listOrganizationsForAccount`; its
+`auth_domain` is the team domain, the same read Alchemy's `Access.Organization` does) and refuses a
+`teamDomain` that differs, with **no write**. It is one attempt, so a token that may not read it does
+not wait on retries.
+
+⚠️ **Known limit: that read needs a token permission the app write does not.** Cloudflare's docs
+(read 2026-10-09, not measured against a live token) give `Access: Organizations Read` (or
+`Access: Organizations, Identity Providers, and Groups Read`) for it, and `Access: Apps and Policies
+Write` for creating the app. Where the token cannot read the organization (a 401 or 403, or no
+organization), the check gives no answer and the create goes on as before: a wrong `teamDomain` then
+writes one app, the post-write check fails the run, and a live app is left with no state row.
+**Cleanup:** the next run finds it by name as `Unowned`; fix the `teamDomain` and declare
+`adopt(true)`, or delete the stray app in the Zero Trust dashboard. **To close the limit**, add
+`Access: Organizations Read` to the token the deploy runs with. Any other failure of the read (a
+throttle, a 5xx) fails the run before a write; run again.
+
+## The client secret
+
+⛔ **It is never read, stored or logged by this package.** The SDK schema's own doc says the secret
+is "only returned on POST request". The create response is decoded by the SDK (which drops it, see
+above); the raw read copies named fields and has no field for it; the attributes have none.
+`saas-oidc-state.test.ts` serialises the whole in-memory state after a create whose fake response
+hands a secret out, and asserts it is absent.
+
+⚠️ **Two paths where the SDK itself holds or prints the raw body** (`@distilled.cloud/cloudflare`
+rc.13, `protocol.ts`), so "never logged" is a claim about this package, not about the SDK:
+
+1. `DISTILLED_DEBUG_HTTP` makes it `console.error` the first 400 characters of every response
+   (line 334). A write refuses to run while it is set. **This one stays an operator-only switch:**
+   the package can refuse to run, it cannot stop the SDK printing, so never set it for a deploy.
+2. A response that fails schema validation becomes `CloudflareParseError({ body, cause })`
+   (lines 452-457), and `body` is the whole parsed response, a create response with its secret
+   included. **Sanitized in this package:** every SDK call of the resource (create, update, list,
+   delete, and the organization read) catches that tag at the call and fails with a `SaasOidcError`
+   that names the operation and carries no body, no response field and no cause
+   (`saas-oidc-error.ts`). `saas-oidc-parse-error.test.ts` forces the error with a fake
+   `client_secret` planted and checks the message, the fields, `String(err)`, `JSON.stringify(err)`
+   and the printed cause. The raw `GET` is not an SDK call and never builds that error.
+   The error exists only under strict response validation (`ResponseValidation.strict`, which
+   neither Alchemy nor this kit turns on; the default is lenient). Measured 2026-10-09: rc.13
+   decodes a create or update response against `S.Unknown`, so it cannot raise the error for those
+   two today; the catch stays so a later SDK that types them cannot start leaking.
+
+Neither exposes anything for a public PKCE client, which has no secret.
+
+- **A public client has no secret to keep** (`allowPkceWithoutClientSecret: true` with the PKCE
+  grant). That is the design for Headlamp (Q6 of the Kubernetes platform decisions).
+- **A confidential client's secret is out of band.** This resource does not capture it. How to
+  obtain or rotate it for an existing app is UNVERIFIED here (no documented rotate verb was read);
+  homeflare-openbao keeps its live one in the macOS Keychain.
+- UNVERIFIED: whether Cloudflare still returns a `client_secret` on POST for a PKCE-without-secret
+  app. It does not matter here, since it is dropped either way.
+
+## Adopting the openbao app, and the state key
+
+⛔ **The type id `HomeFlare.Access.SaasOidcApplication` is kept verbatim.** Alchemy state rows are
+keyed by it, and homeflare-openbao's live `OpenBaoOidcSaas` row was written under it. A different
+id plans a second app (new client id, new `aud`) beside the orphaned live one. The state test
+seeds a row in the old shape (no `teamDomain`) and proves the next deploy updates it in place:
+no create, no delete, the same application and client ids.
+
+- State written before `teamDomain` existed still reads: the host from the app's own `domain`
+  stands in until the next reconcile stores the declared one.
+- homeflare-openbao's stack must merge this package's `providers()` (the kit's collection) where it
+  merged `Cloudflare.providers()` for this type, and add `teamDomain` to its declaration.
+- An **owned** row whose app was deleted out of band reads as gone, never as a same-named app; the
+  next reconcile then creates a new one (a new client id). The name fallback is for a cold read.
+- A live app is `Unowned` until the declaration says `adopt(true)`, like every kit resource.
+
+## What a change does
+
+- **The issuer and every endpoint are `stables`**: an update (a redirect URI, a policy) leaves
+  `app.issuer` and the others resolved for consumers at plan time, so a Talos
+  `KubeAuthenticationConfig` that reads them is not re-planned. `teamDomain` is deliberately not
+  stable (the openbao row has no such attribute). `saas-oidc-stable.test.ts` runs the engine.
+
+- **Created** when no app has the id or the exact name. Names are not unique in Access, so two
+  saas apps with the declared name are refused: set `applicationId`.
+- **Synced** (one PUT of the whole declaration) when the name, auth type, redirect URIs, scopes,
+  grant types, either token lifetime, the PKCE flag or the policies differ. Order is ignored for
+  redirect URIs, scopes and grant types. **It is not ignored for `policies`:** they are declared in
+  ascending precedence, so a reorder is drift (the live order is read from each policy's
+  `precedence`).
+- ⚠️ **Not drift-checked:** `sessionDuration`, `allowedIdps`, `autoRedirectToIdentity`,
+  `appLauncherVisible`, `appLauncherUrl`. They are written on create and on any sync, but a change
+  to only those does not trigger one. This is carried over from the openbao copy unchanged.
+- A matching live app is **zero writes**.
+- An `applicationId` that is not a `saas` app is refused, never rewritten.
+- Retries follow Alchemy's own `retryTransientAccessError` (same file as above): a freshly created
+  policy still propagating, and 403 as Cloudflare's throttle. About 45 seconds, then it fails.
+
+⛔ **Removal policy: `retain` by default**, because deleting the app deletes the client id every
+relying party is configured with. `delete` stays fully implemented (an app already gone is a
+success): opt in with `.pipe(RemovalPolicy.destroy())`. `list` is empty and `nuke` is skipped:
+Alchemy's own `Access.Application` already lists every Access app, saas ones included.

package/docs/upstream-conformance-families.md

@@ -72,7 +72,7 @@ HttpClient` client. The old status-carrying `NetboxError` and its `cause.status
       in lifecycle operations; it is not a separate credentials-layer prohibition. The same
       shape in NetBox is therefore not an S20 follow-up. See [LiteLLM's Q6 resolution](./litellm.md#credentials).
 11. **Every family repeats `list: () => Effect.succeed([])`**, 30 times, and only
-    `R2BucketLock` and `MeshNode` declare `nuke`. The constructor already defaults `list`
+    `R2BucketLock`, `MeshNode` and `CloudflaredTunnel` declare `nuke`. The constructor already defaults `list`
     (S12). **Fix:** write the reason where it differs, and declare `nuke: { skip: true }`
     where nuke must never reach the object.
 12. **Resource JSDoc is not in upstream's generator format.** Zero files use `@resource`,

package/docs/upstream-conformance.md

@@ -66,6 +66,9 @@ then tidiness.
    type string `Cloudflare.MeshNode` sits inside upstream's own namespace (H14).
    **Options:** contribute `ha` upstream and raise the token-in-state concern, then switch;
    or keep the house resource as a recorded divergence. **Decision:** maintainer.
+   `cloudflare/CloudflaredTunnel` is the same divergence for `Cloudflare.Tunnel.Tunnel`
+   ([cloudflared-tunnel.md](./cloudflared-tunnel.md)): the token in state is the concern to raise
+   upstream, and its type string `Cloudflare.CloudflaredTunnel` also sits in upstream's namespace (H14).
 4. **Unguarded `Bun.*`, and the `node:*` modules upstream names, in shipped provider code**
    (S42). This is listed in [the Bun line](#the-bun-line). The exported `Bun.*` paths crash
    under Node, which is the runtime this package promises its consumers. The `node:*` paths

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.48.1",
+  "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"
       },