@homeflare/alchemy 0.28.0 → 0.29.1

package/dist/proxmox/members.d.ts

@@ -1,11 +1,4 @@
-/**
- * C1 cluster members: ordered failover, last-good preference, transport classification.
- *
- * ★ ANY MEMBER'S :8006 API MANAGES THE WHOLE CLUSTER — PVE proxies node paths itself — so the
- *   provider reaches the cluster through whichever member is up, not through one pinned node.
- *
- * ⛔ NEVER cluster-c1.example.com: it resolves to 192.0.2.250, which nothing serves.
- */
+import type * as Duration from 'effect/Duration';
 import * as Effect from 'effect/Effect';
 import * as HttpClient from 'effect/unstable/http/HttpClient';
 import type * as HttpClientRequest from 'effect/unstable/http/HttpClientRequest';
@@ -14,6 +7,21 @@ import type { PveTarget } from './credentials.ts';
 export declare const PVE_API_PORT = 8006;
 /** Strict TLS, always :8006 — each node's certificate carries its mgmt name as a SAN. */
 export declare const pveApiBase: (member: string) => string;
+/**
+ * Bound on ONE member attempt, shared by `client.ts`'s `executeOnCluster` and
+ * `distilled-pve.ts`'s `runPveWith` — both loop over `orderedMembers` and both call this file's
+ * classifiers, so one constant keeps them in the same failure-mode boundary.
+ *
+ * ⛔ MEASURED GAP, FIXED 2026-09-24: before this, NOTHING bounded a single attempt. A member that
+ *   accepted the TCP connection but never answered hung the whole call forever — the for-loop
+ *   never produced a failure for `isTransportFailure`/`isPreSendTransport` to classify, so it
+ *   never advanced to a healthy member. `isTimeoutCause` below existed already (written for this
+ *   exact case, per its own comment: "no answer after connect") but nothing ever called
+ *   `Effect.timeout` to produce one.
+ * ★ TB4 (the live 3-member cluster, `homeflare-proxmox/src/target.ts`) waits at most 3× this
+ *   before `PveClusterExhausted` — well under S26's ~90-second ceiling on a bounded wait.
+ */
+export declare const MEMBER_TIMEOUT: Duration.Input;
 /** ⚠️ TESTS ONLY — resets sticky member choice between cases. */
 export declare const resetLastGoodForTest: () => void;
 export declare const noteGoodMember: (target: PveTarget, member: string) => void;
@@ -24,9 +32,16 @@ export declare const orderedMembers: (target: PveTarget) => readonly string[];
  * ★ TransportError | InvalidUrlError | EncodeError occur before a response exists; StatusCodeError
  *   and kin include a response. client.execute does NOT filter status, so HTTP answers are never
  *   TransportError — only the transport layer is.
+ * ★ `Cause.TimeoutError` (from `MEMBER_TIMEOUT` below, via `Effect.timeout`) counts too — a read
+ *   with no side effect to duplicate fails over on ANY transport failure, a hang included.
  */
 export declare const isTransportFailure: (cause: unknown) => boolean;
-/** Pre-send only: connection refused, DNS, a certificate refused — never a timeout after connect. */
+/**
+ * Pre-send only: connection refused, DNS, a certificate refused — never a timeout after connect.
+ * ⛔ `Cause.TimeoutError` (MEMBER_TIMEOUT firing) falls through to `false` here on purpose, same
+ *   as any other non-`HttpClientError` cause: the request may already have reached the member, so
+ *   a write must not repeat it elsewhere.
+ */
 export declare const isPreSendTransport: (cause: unknown) => boolean;
 export declare const describeTransport: (cause: unknown) => string;
 export type MemberAttempt = {
@@ -46,8 +61,12 @@ export type PveMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
  * ★ Reads fail over on any transport failure, including timeout — no side effect to duplicate.
  *   MEASURED 2026-09-14: full C1 plans stayed all-noop with the first member refused (127.0.0.1)
  *   and with it unresolvable (n9.invalid).
+ *
+ * @param timeout Bound on ONE member's attempt — defaults to `MEMBER_TIMEOUT`. A test passes a
+ *   short one to prove failover happens without waiting out the real bound; production code never
+ *   overrides it.
  */
-export declare const executeOnCluster: (target: PveTarget, method: PveMethod, path: string, build: (apiBase: string) => HttpClientRequest.HttpClientRequest) => Effect.Effect<HttpClientResponse.HttpClientResponse, {
+export declare const executeOnCluster: (target: PveTarget, method: PveMethod, path: string, build: (apiBase: string) => HttpClientRequest.HttpClientRequest, timeout?: Duration.Input) => Effect.Effect<HttpClientResponse.HttpClientResponse, {
     readonly tag: 'cluster';
     readonly method: PveMethod;
     readonly path: string;

package/dist/proxmox/members.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"members.d.ts","sourceRoot":"","sources":["../../src/proxmox/members.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,UAAU,MAAM,iCAAiC,CAAC;AAE9D,OAAO,KAAK,KAAK,iBAAiB,MAAM,wCAAwC,CAAC;AACjF,OAAO,KAAK,KAAK,kBAAkB,MAAM,yCAAyC,CAAC;AACnF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC,yFAAyF;AACzF,eAAO,MAAM,UAAU,WAAY,MAAM,WAA0D,CAAC;AAKpG,iEAAiE;AACjE,eAAO,MAAM,oBAAoB,YAAgC,CAAC;AAElE,eAAO,MAAM,cAAc,WAAY,SAAS,UAAU,MAAM,SAE/D,CAAC;AAEF,6DAA6D;AAC7D,eAAO,MAAM,cAAc,WAAY,SAAS,KAAG,SAAS,MAAM,EAIjE,CAAC;AA2CF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,UAAW,OAAO,KAAG,OAInD,CAAC;AAEF,qGAAqG;AACrG,eAAO,MAAM,kBAAkB,UAAW,OAAO,KAAG,OASnD,CAAC;AAEF,eAAO,MAAM,iBAAiB,UAAW,OAAO,KAAG,MAGlD,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9E,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;AAE1D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,WACnB,SAAS,UACT,SAAS,QACX,MAAM,SACL,CAAC,OAAO,EAAE,MAAM,KAAK,iBAAiB,CAAC,iBAAiB,KAC9D,MAAM,CAAC,MAAM,CACd,kBAAkB,CAAC,kBAAkB,EACrC;IACE,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;CAC7C,EACD,UAAU,CAAC,UAAU,CAmCnB,CAAC"}
+{"version":3,"file":"members.d.ts","sourceRoot":"","sources":["../../src/proxmox/members.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,UAAU,MAAM,iCAAiC,CAAC;AAE9D,OAAO,KAAK,KAAK,iBAAiB,MAAM,wCAAwC,CAAC;AACjF,OAAO,KAAK,KAAK,kBAAkB,MAAM,yCAAyC,CAAC;AACnF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC,yFAAyF;AACzF,eAAO,MAAM,UAAU,WAAY,MAAM,WAA0D,CAAC;AAEpG;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,KAAoB,CAAC;AAK3D,iEAAiE;AACjE,eAAO,MAAM,oBAAoB,YAAgC,CAAC;AAElE,eAAO,MAAM,cAAc,WAAY,SAAS,UAAU,MAAM,SAE/D,CAAC;AAEF,6DAA6D;AAC7D,eAAO,MAAM,cAAc,WAAY,SAAS,KAAG,SAAS,MAAM,EAIjE,CAAC;AA2CF;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,UAAW,OAAO,KAAG,OAKnD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,UAAW,OAAO,KAAG,OASnD,CAAC;AAEF,eAAO,MAAM,iBAAiB,UAAW,OAAO,KAAG,MAIlD,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9E,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;AAE1D;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,gBAAgB,WACnB,SAAS,UACT,SAAS,QACX,MAAM,SACL,CAAC,OAAO,EAAE,MAAM,KAAK,iBAAiB,CAAC,iBAAiB,YACtD,QAAQ,CAAC,KAAK,KACtB,MAAM,CAAC,MAAM,CACd,kBAAkB,CAAC,kBAAkB,EACrC;IACE,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;CAC7C,EACD,UAAU,CAAC,UAAU,CAqCnB,CAAC"}

package/docs/caddy-admin.md

@@ -13,7 +13,7 @@ The overview is [caddy.md](./caddy.md).
 - **`admin { origins … }`** narrowed, or **an SSH-forwarded port** (Caddy checks the Host against
   ITS port): pass `hostHeader: 'localhost:2019'`.
 - **Another host's Caddy** (SSH later): forward its socket or port to loopback here and point a
-  `localCaddyAdmin()` at it, or implement `CaddyAdmin` over your own route. Never expose :2019.
+  `localCaddyAdmin()` at it, or implement `CaddyTransport` over your own route. Never expose :2019.
 - **A Caddyfile cannot strand the provider.** Before loading, the adapted `admin` block is refused
   if it turns the API off, listens off loopback or somewhere the transport does not reach (another
   port, socket or loopback address: `[::1]` is not `127.0.0.1`, and `localhost` binds IPv4), allows

package/docs/caddy.md

@@ -3,7 +3,8 @@
 Declare a running Caddy's config as Caddyfile text and apply it through Caddy's own admin API:
 `POST /load` to apply (a graceful reload), `GET /config/` to detect drift. `caddyWithFile()` also
 writes the same Caddyfile to the file Caddy starts from, with launchd's `HostFile`, so a restart
-keeps it. Every admin call goes through one injectable `CaddyAdmin` transport.
+keeps it. Every admin call goes through `@distilled.cloud/caddy`'s typed operations, over one
+injectable `CaddyTransport` (`Credentials` + `HttpClient.HttpClient`).
 
 ```ts
 import * as Effect from 'effect/Effect';
@@ -193,7 +194,7 @@ it by hand at its admin API.
 - ⚠️ **Bootstrap race.** Where Caddy is not running yet, the config can reach the admin API before
   its launchd job has Caddy listening. The transport retries a refused connection (`retries`,
   `retryDelayMs`; default 2 × 500 ms) — raise them, or rerun the deploy.
-- ⚠️ One `CaddyAdmin` per stack: the transport picks the Caddy, not a prop. Pointing it at another
+- ⚠️ One `CaddyTransport` per stack: the transport picks the Caddy, not a prop. Pointing it at another
   Caddy plans an update; the old one keeps what it had. ⛔ State vouches only for the Caddy it was
   applied to, so the apply loads there only if it serves nothing, runs the declared config or the
   one last stored — anything else needs `--adopt`.

package/docs/credentials.md

@@ -29,3 +29,19 @@ Framework `TokenAuthentication` scheme — NOT `Bearer`, measured against this e
 instance) is built by the package's protocol layer, not by this package. ⛔ The token is never a
 prop: Alchemy persists attributes unencrypted, so nothing stored in a stack file may be a
 credential.
+
+The Paperless subpath (2026-09-24, moved onto `@distilled.cloud/paperless-ngx` — same route) also
+resolves credentials through the SDK's own `CredentialsFromEnv`, reading `PAPERLESS_URL` /
+`PAPERLESS_TOKEN` — the same two variable names the retired hand-rolled `credentials.ts` read.
+`Authorization: Token <value>` (Paperless-ngx's own DRF `TokenAuthentication`, same scheme as
+NetBox) is built by the package's protocol layer. Baked directly into each of the four
+`xxxProvider()`s (`paperlessProviders()` no longer takes a credentials-layer override — see the
+migration's changeset), the same way the Forgejo and NetBox subpaths above do.
+
+The LiteLLM subpath (2026-09-24, moved onto `@distilled.cloud/litellm` — see
+[distilled-interim.md](./distilled-interim.md)) resolves credentials the same way, through the
+SDK's own `CredentialsFromEnv` layer, which reads `LITELLM_PROXY_URL` / `LITELLM_PROXY_API_KEY` —
+the same two variable names the retired hand-rolled `credentials.ts` read (LiteLLM's own `litellm`
+CLI client's variable names, not a house choice), still resolved on the calling fiber per request,
+never captured at module scope. `Authorization: Bearer <value>` is built by the package's protocol
+layer, not by this package. ⛔ The key is never a prop, for the same reason as above.

package/docs/litellm.md

@@ -1,11 +1,15 @@
 # LiteLLM — `@homeflare/alchemy/litellm`
 
 `LiteLLM.PassThroughEndpoint` declares one row of LiteLLM's `/config/pass_through_endpoint`
-family: a route on the proxy that forwards requests to an upstream target, generated from
-LiteLLM **1.100.0**'s own OpenAPI document (`codegen/manifest.json`'s `litellm-openapi` entry —
-vendor code at tag `v1.100.0`, dumped by the vendor's own `gen-api-types.mjs`, cross-checked
-byte-identically against the tag's committed `schema.d.ts`; NOT a live read, because the reference
-proxy's `/openapi.json` could not be reached when this was walked — see the manifest entry's note).
+family: a route on the proxy that forwards requests to an upstream target. Every call goes
+through `@distilled.cloud/litellm`'s typed `misc` operations (2026-09-24, moved off a hand-rolled
+`client.ts`/`generated/pass-through.ts` the same way `/netbox` and `/forgejo` did —
+[distilled-interim.md](./distilled-interim.md); not published upstream yet, so aliased onto
+`@homeflare/distilled-litellm`). Its types are generated from LiteLLM **1.100.0**'s own OpenAPI
+document (the distilled clone's own `packages/litellm/README.md` has the provenance: vendor code
+at tag `v1.100.0`, dumped by the vendor's own `gen-api-types.mjs`, cross-checked byte-identically
+against the tag's committed `schema.d.ts`; NOT a live read, because the reference proxy's
+`/openapi.json` could not be reached when this was walked).
 
 ## What is DB-backed and API-managed, versus config-file only
 
@@ -21,11 +25,13 @@ Measured at 1.100.0 (`schema.prisma`, `pass_through_endpoints.py`, and the mini'
 
 ## Credentials
 
-Reads `LITELLM_PROXY_URL` and `LITELLM_PROXY_API_KEY` at call time — LiteLLM's own variable
-names, the ones its `litellm` CLI reads (`litellm/proxy/client/cli/main.py` at the tag). No
-default URL. The key must be LiteLLM's master key or another `PROXY_ADMIN` key:
-`update_config_general_settings`, the function every mutation goes through, is `PROXY_ADMIN`
-only. Never a prop — see [docs/credentials.md](./credentials.md) for the house rule.
+Reads `LITELLM_PROXY_URL` and `LITELLM_PROXY_API_KEY` at call time, through
+`@distilled.cloud/litellm`'s own `CredentialsFromEnv` — the same two variable names LiteLLM's own
+`litellm` CLI reads (`litellm/proxy/client/cli/main.py` at the tag), unchanged by the move off the
+retired hand-rolled `credentials.ts`. No default URL. The key must be LiteLLM's master key or
+another `PROXY_ADMIN` key: `update_config_general_settings`, the function every mutation goes
+through, is `PROXY_ADMIN` only. Never a prop — see [docs/credentials.md](./credentials.md) for the
+house rule.
 
 ## Refusals
 
@@ -59,9 +65,11 @@ two rows on the same path, which this resource never allows.
 ## The whole-field write, and why every mutation is serialised
 
 Every pass-through endpoint lives in ONE `general_settings.pass_through_endpoints` list. Create,
-update and delete are each a read-modify-write of that WHOLE list. `client.ts` wraps every
-mutating call in a per-base-URL `Effect` semaphore, so two of THIS PROCESS's own calls never
-race each other — two endpoints declared in the same deploy both survive.
+update and delete are each a read-modify-write of that WHOLE list. `operations.ts` wraps every
+mutating call — now the SDK's typed operations, not a hand-rolled client — in a per-base-URL
+`Effect` semaphore, so two of THIS PROCESS's own calls never race each other — two endpoints
+declared in the same deploy both survive. The SDK has no opinion on this: it is a quirk of how
+THIS vendor stores the resource, not a distilled protocol concern.
 
 ⛔ **What the semaphore does not cover.** It serialises this package's own writes within one
 process. It cannot serialise against the LiteLLM UI, another stack, or a second concurrent

package/docs/paperless.md

@@ -4,6 +4,18 @@ Four resources — `Paperless.Tag`, `Paperless.DocumentType`, `Paperless.Storage
 `Paperless.CustomField` — the taxonomy Paperless-ngx writes through Django's internal models,
 create-or-update and never deleted by default. Workflows and mail accounts are a later slice.
 
+## Moved onto `@distilled.cloud/paperless-ngx` (2026-09-24)
+
+🔴 Every wire call in this family now goes through `@distilled.cloud/paperless-ngx`'s typed
+operations (`tags.createTag`, `documentTypes.listDocumentTypes`, …) with
+`Effect.catchTag('NotFound', …)` at each resource file's own `getById`, the same route
+`forgejo/*` and `netbox/*` took — see [distilled-interim.md](./distilled-interim.md) and this
+migration's changeset for the full story. `client.ts`, `errors.ts` and `credentials.ts` are gone.
+The rest of this document — locate-by-name-then-id (PR 163), `owner: null` on create, the
+create-only `dataType`, `retain` by default — is the family's OWN behaviour, unchanged by the
+transport swap and proved unchanged by `tag.test.ts`/`tag-identity.test.ts` against a fake that
+speaks the real distilled protocol.
+
 ## Credentials
 
 Two environment variables, read **at call time**, never props:

package/docs/peers.md

@@ -64,3 +64,8 @@ automatically for every consumer that installs `@homeflare/alchemy` — nothing
 peer install line, and nothing for `peers.test.ts` to check. When the real package ships
 upstream, the alias's target changes (or the entry becomes a normal peer, matching
 `@distilled.cloud/forgejo` above) and this line still does not change for it.
+
+★ **`@distilled.cloud/litellm` (added 2026-09-24, moving `/litellm` off a hand-rolled
+`HttpClient` client the same way `/netbox` did) is the same shape**: aliased onto
+`@homeflare/distilled-litellm@0.2.0` as a plain `dependencies` entry, not a peer — nothing to
+add here, nothing for `peers.test.ts` to check.

package/docs/repo-policy.md

@@ -18,7 +18,22 @@ Effect.gen(function* () {
 });
 ```
 
-Provide `GitHub.providers()` **and** `RepositoryRulesetProvider()` from this subpath.
+Provide `repoPolicyProviders()` from this subpath as the stack's `providers` — the composed
+`GitHub.providers()` + `RepositoryRulesetProvider()` layer:
+
+```ts
+import { repoPolicyProviders } from '@homeflare/alchemy/github';
+
+// providers: repoPolicyProviders()
+```
+
+⛔ **Writing the two providers side by side does not typecheck** (measured 2026-09-24,
+homeflare-builds bump PR 6): `RepositoryRulesetProvider()`'s handlers need `GitHubCredentials`,
+and merging layers does not thread one's output into another's requirement.
+`repoPolicyProviders()` feeds `GitHub.providers()` into `RepositoryRulesetProvider()` with
+`Layer.provideMerge` so the composed layer needs nothing further — see
+[repository-ruleset.md](./repository-ruleset.md#providers) for the full account.
+
 ⚠️ **Rewired 2026-09-23**: the ruleset half now composes this house's own
 `GitHub.RepositoryRuleset` (see [repository-ruleset.md](./repository-ruleset.md)), not
 upstream `GitHub.Ruleset` — every hazard [below](#-the-ruleset-half-has-hazards-of-its-own)

package/docs/repository-ruleset.md

@@ -30,10 +30,44 @@ Effect.gen(function* () {
 });
 ```
 
-Provide **both** `GitHub.providers()` (for `GitHub.Repository`, if declared alongside) and
-`RepositoryRulesetProvider()` — this is a separate `Provider`, registered under its own
-type string (`GitHub.RepositoryRuleset`), not inside upstream's `GitHub.Providers`
-collection. The two coexist in one stack without any change to upstream's own code.
+This is a separate `Provider`, registered under its own type string
+(`GitHub.RepositoryRuleset`), not inside upstream's `GitHub.Providers` collection — the two
+coexist in one stack without any change to upstream's own code.
+
+## Providers
+
+Provide `repoPolicyProviders()` (`@homeflare/alchemy/github`) as the stack's `providers`, not
+`GitHub.providers()` and `RepositoryRulesetProvider()` written side by side:
+
+```ts
+import { repoPolicyProviders } from '@homeflare/alchemy/github';
+
+// providers: repoPolicyProviders()
+```
+
+⛔ **The side-by-side form does not typecheck** — measured 2026-09-24 (homeflare-builds bump PR
+6, tsc TS2345), two separate bugs stacked on top of each other:
+
+1. **The layer** still requires `GitHubCredentials` when the two providers are merged plainly:
+   `RepositoryRulesetProvider()`'s handlers call `octokitFor`, which needs it, and merging two
+   layers does not thread one's output into the other's requirement. `repoPolicyProviders()`
+   feeds `GitHub.providers()` into `RepositoryRulesetProvider()` with `Layer.provideMerge`
+   instead of a plain merge. `GitHub.providers()` resolves credentials internally and — because
+   it chains `provideMerge`, not `provide`, onto its own auth layer — re-exposes
+   `GitHubCredentials` in its own output too, so this both satisfies the requirement and keeps
+   `GitHub.Providers` available for any `GitHub.Repository`/`GitHub.Ruleset` declared alongside.
+2. **The declaration** failed to typecheck on its own, even with the layer fixed, whenever a
+   stack body called `RepositoryRuleset` — directly, or via
+   `declareRepoPolicy`/`declareRepoBaseline`. `RepositoryRuleset`'s `Resource<>` declaration put
+   `GitHubCredentials` in the 5th (`Providers`) type parameter, which puts the credential
+   requirement on the DECLARATION itself, not just the provider. A stack body cannot supply
+   `GitHubCredentials` this way — `Alchemy.Stack`'s own `ProviderServices` type is a closed
+   union that `GitHubCredentials` does not structurally match (see repository-ruleset.ts's file
+   header for the full trace against `alchemy/src/Resource.ts` and `alchemy/src/Stack.ts`).
+   Upstream's own `GitHub.Ruleset` never makes this mistake: its 5th slot is `GitHub.Providers`
+   (the collection tag), never the raw credential service. `RepositoryRuleset` now omits the
+   5th parameter, defaulting its declaration requirement to `Provider<RepositoryRuleset>`
+   instead.
 
 ## Type string: H14
 
@@ -55,12 +89,12 @@ exported credential service.
 
 ## What it models beyond upstream `RulesetProps`
 
-| field                                             | upstream `Ruleset` | this resource      |
-| ------------------------------------------------- | ------------------ | ------------------ |
-| `pullRequest.allowedMergeMethods`                 | no                 | yes                |
-| `pullRequest.requiredReviewers`                   | no                 | yes                |
-| `pullRequest.extraApprovalForUnattributedChanges` | no                 | `false` only (H15) |
-| `requiredStatusChecks.doNotEnforceOnCreate`       | no                 | yes                |
+| field                                             | upstream `Ruleset` | this resource            |
+| ------------------------------------------------- | ------------------ | ------------------------ |
+| `pullRequest.allowedMergeMethods`                 | no                 | yes                      |
+| `pullRequest.requiredReviewers`                   | no                 | yes                      |
+| `pullRequest.extraApprovalForUnattributedChanges` | no                 | `true`/`false` (K1, H15) |
+| `requiredStatusChecks.doNotEnforceOnCreate`       | no                 | yes                      |
 
 `RULE_TYPE_COVERAGE` in `repository-ruleset-constraints.ts` classifies every rule type
 Octokit's own installed types know (21 of them — see the file for the 27.0.0-vs-29.0.1
@@ -79,9 +113,11 @@ being silently dropped by the wholesale `rules` PUT.
   see `undeclaredLiveRuleRefusal`'s own comment for the concrete scenario (forgetting
   `deletion: true` would otherwise silently drop branch-deletion protection) that made
   this the general case rather than a special one.
-- **Adding a required check that has never reported success** on the default branch's
-  current tip (checks + statuses): refused before any write. Documented limitation: this
-  checks the current tip only, not full history (repository-ruleset-octokit.ts).
+- **Adding a required check that has never reported success**: refused before any write.
+  Checked at the default branch's current tip, then (K2) up to `RECENT_MERGED_PR_LIMIT`
+  recent merged PR heads — bounded, not full history (repository-ruleset-octokit.ts). The
+  fallback exists because the rendered CI runs on `pull_request` only, so `ci`/`secret
+scan`/`CodeQL` never report on the tip itself.
 - **A readback mismatch**: after any write, an INDEPENDENT `GET` — never the write's own
   response — is compared against what was sent for the approval count, merge methods and
   the extension flag. A mismatch fails the plan.
@@ -110,5 +146,9 @@ caller, the same as upstream `GitHub.Ruleset`.
   what a create sends, zero writes on a noop or a refusal, exactly one update on real
   drift, and the readback check.
 - `repository-ruleset-wire.test.ts` — the H15 measurement against a real Octokit instance.
+- `repository-ruleset-octokit.test.ts` — the K2 measurement, same real-Octokit-with-fetch-
+  shim pattern as the wire test: a context reporting only on a recent merged PR head is
+  accepted, one reporting nowhere (tip or any recent merged head) is still refused, and
+  one reporting only past `RECENT_MERGED_PR_LIMIT` stays refused too (the bound is real).
 - `repository-ruleset-coverage.test.ts` — the rule-type coverage change detector (the
   completeness guarantee itself is enforced by `tsc`, not this file — see its header).

package/docs/upstream-conformance.md

@@ -69,17 +69,73 @@ then tidiness.
    (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
    load on Node but break the Effect-only rule.
-5. **`launchd`, `linux` and `caddy` have promise-based seams (H3).** `HostRunner` and
-   `CaddyAdmin` are plain `async` interfaces, with `node:child_process`, `node:fs/promises`
-   and `node:http` behind them, and failures are untyped `Error` (S19, S21). The stated
-   reason is that a consumer implements plain async functions. Upstream meets the same need
-   by letting a caller provide `FileSystem`, `ChildProcessSpawner` or `CommandExecutor`
-   layers, and `alchemy/Util/AtomicFile.writeFileAtomic` covers the temp-and-rename write.
+5. **`launchd` and `linux` still have promise-based seams (H3).** `HostRunner` is a plain
+   `async` interface, with `node:child_process` and `node:fs/promises` behind it, and
+   failures are untyped `Error` (S19, S21). The stated reason is that a consumer implements
+   plain async functions. Upstream meets the same need by letting a caller provide
+   `FileSystem`, `ChildProcessSpawner` or `CommandExecutor` layers, and
+   `alchemy/Util/AtomicFile.writeFileAtomic` covers the temp-and-rename write.
    ⚠️ Only in part. `local-runner.ts` creates its temp file with `O_EXCL`, mode 0600 and
    `chown` before `chmod`, and it refuses a planted symlink. `writeFileAtomic` writes with
    default flags and mode, `chmod`s afterwards, and never `chown`s.
    **Decision:** maintainer. These families are also host-specific, so "house-only" is a
    valid answer.
+
+   ✅ **S23 fixed 2026-09-24** (branch `claude2/distilled-caddy-migrate`): `caddy/*` no
+   longer has a promise-based seam at all. `Caddy.Config` now calls
+   `@distilled.cloud/caddy`'s typed `admin` operations (`adaptConfig`, `loadConfig`,
+   `getConfig`), `catchTag`-able via `Caddy.CaddyOpError`, with `isUnreachable`
+   (caddy-http-client.ts) replacing the old `CaddyUnreachableError` class as a type guard
+   over the SDK's own `HttpClientError`. The old `CaddyAdmin`/`CaddyAdminRequest`/
+   `CaddyAdminResponse`/`CaddyAdminError` interfaces and `admin-calls.ts`'s hand-rolled
+   `POST /adapt`/`POST /load`/`GET /config/` calls are gone. `local-admin.ts`'s measured
+   unix-socket-plus-loopback transport (Host/Origin headers, ECONNREFUSED/ENOENT-only
+   retry) survives as caddy-http-client.ts, now built as an Effect `HttpClient.HttpClient`
+   the SDK's own protocol runs over, instead of a raw `node:http` promise interface — still
+   `node:http`, not `FetchHttpClient`, because only `node:http` dials a unix socket on both
+   Bun and Node (`FetchHttpClient`'s `unix` option is Bun-only). The `LoadRefused` 200-trap
+   (a refused `/load` that still answers 200) is now first-class in the SDK's own
+   `protocol.ts`, not re-detected in this package. A genuine SDK gap this migration found
+   and patched in the distilled clone (never in this resource): `AdaptConfig`/`LoadConfig`'s
+   `config` field is Caddyfile TEXT under a caller-chosen `Content-Type`, which
+   `buildRequest`'s generic `HttpBody()` cascade has no seam for (no static `bodyMediaType`
+   for a dynamically-typed body) — it fell to the JSON-body default, which both
+   `JSON.stringify`d the Caddyfile text and overwrote the caller's `Content-Type` with
+   `application/json`. Fixed in `protocol.ts`'s `encode`, shipped as
+   `@homeflare/distilled-caddy@0.2.1` (a patch changeset). A second, unrelated finding: the
+   SDK's own default `Caddy.Retry` policy treats ANY `HttpClientError` with a
+   `TransportError` reason as retryable — including an ECONNRESET well after a `POST /load`
+   was accepted — which would have re-sent an already-accepted load past the point
+   admin-calls.ts's original module doc says never to. `local-admin.ts` now disables it
+   (`Layer.succeed(Caddy.Retry.Retry, { while: () => false })`), leaving
+   caddy-http-client.ts's own narrower retry (ECONNREFUSED/ENOENT only) as the one retry
+   policy in play. State did not move: props and attributes stay byte-identical, proven by
+   the family's existing tests (updated only where the typed-error message text itself
+   changed) plus fake-caddy.ts, a real HTTP server, so every test already drives the real
+   distilled wire protocol.
+   ⛔ **Alchemy trap found along the way, house-wide, not caddy-specific:** a
+   `Provider.effect(...)` layer built with `SomeLayer.pipe(Layer.provide(depsLayer))` seals
+   `depsLayer`'s services away from the provider's OWN `read`/`diff`/`reconcile` handlers
+   when THEY run later — `Layer.provide` satisfies the provider's construction-time
+   requirement and then hides it, so a handler that itself does `yield* SomeService` (as
+   `Provider.effect`'s own `ReadReq`/`DiffReq`/`ReconcileReq` type parameters invite)
+   dies with "Service not found" the moment the engine calls it, not when the layer is
+   built. `Layer.provideMerge` is the fix — it feeds the dependency's output into the
+   provider's requirement AND keeps that output live in the result. `providers.ts`'s
+   `caddyProviders()` and this family's tests were the ones actually broken by it, but any
+   family whose provider handlers read a service from context has the same exposure.
+
+   **File-size note, added in the `claude2/distilled-caddy-followup` review pass:** the
+   `encode()` fix above grew `packages/distilled-caddy/src/protocol.ts` from 243 to 294
+   lines, past the house's 250-line code-file cap — the original PR didn't flag this. Left
+   as-is on purpose, not split: `distilled-interim.md` treats all of
+   `packages/distilled-*/src/**` as copied-not-edited vendor code (⛔ "src/ is copied,
+   never hand-edited in the kit"; already exempt from `.oxfmtrc.json`/`.oxlintrc.json` for
+   the identical reason), which is the AGENTS.md line-cap rule's own carve-out for
+   "vendored code." Its source of truth is branch `homeflare/caddy` in the distilled clone
+   — a split belongs there first, then gets copied forward on the next regeneration, not
+   decided unilaterally in this kit copy.
+
 6. **`openbao/*` has no upstream equivalent, and it conforms on the contract** (Effect
    `HttpClient`, strict `Unowned`, retain). It diverges in three ways:
    - 30 `Effect.die` sites in non-test source, several of them on `diff` and
@@ -121,18 +177,69 @@ HttpClient` client. The old status-carrying `NetboxError` and its `cause.status
    - ⛔ **Still diverges on credentials (S24):** `NETBOX_TOKEN` / `NETBOX_URL` are read at
      call time, now through the SDK's `CredentialsFromEnv` rather than a hand-rolled
      `token()` — same divergence, unchanged by the transport swap.
-10. **Every family repeats `list: () => Effect.succeed([])`**, 30 times, and only
+10. **`litellm/*` has no upstream equivalent** (LiteLLM has no upstream Alchemy family, the
+    same situation `openbao/*` is in above), and conforms on the transport contract.
+    - ✅ **S23 fixed 2026-09-24** (branch `claude2/litellm-distilled`, mirroring the NetBox
+      migration above, decision 43). `LiteLLM.PassThroughEndpoint` now calls
+      `@distilled.cloud/litellm`'s typed `misc` operations (`operations.ts`) instead of a
+      hand-rolled `Effect HttpClient` client. The old status-carrying `LitellmBadRequestError`
+      family is gone: every failure the four operations declare (`BadRequest`, `NotFound` on
+      update, `UnprocessableEntity`, plus the shared `Unauthorized`/`TooManyRequests`/server
+      errors) is the SDK's own typed error, `catchTag`'d — `deletePassThroughEndpoint`'s
+      re-list-on-ambiguous-`BadRequest` trick (S21: a status-and-a-real-read decision, never
+      body text) is unchanged, now keyed on the tag instead of the status code. The
+      per-base-URL write semaphore this vendor's whole-list storage forces (docs/litellm.md)
+      is unchanged too — the SDK has no opinion on it, so it stays one layer above the typed
+      calls, in `operations.ts`. `client.ts` and the kit's own hand-generated
+      `generated/pass-through.ts` are both deleted (the SDK's `misc.PassThroughGenericEndpoint`
+      is the same shape, generated from the same LiteLLM 1.100.0 OpenAPI document — see
+      `codegen/manifest.json`'s `litellm-openapi` entry, left in place and unconsumed rather
+      than deleted, the same pattern the two UniFi entries already establish). Not published
+      upstream yet, so aliased onto `@homeflare/distilled-litellm@0.2.0` as a plain
+      `dependencies` entry, not a peer — [distilled-interim.md](./distilled-interim.md). State
+      did not move: props/attributes stay byte-identical, proven by the family's unchanged
+      existing tests (now against a fake LiteLLM exercising the real distilled protocol
+      through `FetchHttpClient.Fetch`, not a loopback `Bun.serve`) plus the engine-level
+      replace test through `fake-stack.ts`. No stack in this estate currently imports
+      `litellmProviders`/`LiteLLM.PassThroughEndpoint` (measured 2026-09-24 across
+      homeflare-landscape's own repositories, including this one's `stacks/`), so there is no
+      live plan to re-run.
+    - ⛔ **Still diverges on credentials (S24):** `LITELLM_PROXY_URL` / `LITELLM_PROXY_API_KEY`
+      are read at call time, now through the SDK's `CredentialsFromEnv` rather than a
+      hand-rolled `resolveCreds` — same divergence, unchanged by the transport swap.
+    - ✅ **S20 fixed 2026-09-24** (same branch, PR review pass): `CredentialsFromEnv` ended in
+      `Effect.orDie`, so a missing/misspelled env var died as an engine-crashing defect
+      instead of the typed `ConfigError` `LitellmOpError` already declared — a regression
+      this migration made newly reachable (the retired hand-rolled `credentials.ts` failed
+      typed). Fixed at the source: `@distilled.cloud/litellm`'s own `credentials.ts`
+      (`homeflare/litellm@4ad19154`, commit local, not pushed — S22), copied forward here.
+      `netbox/*`'s `CredentialsFromEnv` has the identical `orDie` shape and is unfixed —
+      out of scope for this item; tracked as its own follow-up (task `task_3bbe1684`).
+11. **Every family repeats `list: () => Effect.succeed([])`**, 30 times, and only
     `R2BucketLock` and `MeshNode` 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.
-11. **Resource JSDoc is not in upstream's generator format.** Zero files use `@resource`,
+12. **Resource JSDoc is not in upstream's generator format.** Zero files use `@resource`,
     `**Example:**` or `### Section` (S31, H10). **Decision:** maintainer, because it moves
     the house's glyph rationale into `//` comments.
-12. **Tests never use `alchemy/Test/Bun`.** Every lifecycle is proven against loopback
+13. **Tests never use `alchemy/Test/Bun`.** Every lifecycle is proven against loopback
     fakes (S28, H12). Live suites need a place to run, and that is a maintainer decision.
 
 ## Conforms
 
+- **`paperless/*` (`Tag`, `DocumentType`, `StoragePath`, `CustomField`)** — ✅ **S23 fixed
+  2026-09-24** (branch `claude2/distilled-paperless-family`, decision 43, mirroring the
+  netbox/forgejo migrations above). Every call now goes through `@distilled.cloud/paperless-ngx`'s
+  typed operations, `catchTag('NotFound', …)` replaced the status-carrying `PaperlessError`
+  union, and `client.ts`/`errors.ts`/`credentials.ts` are deleted. The shared
+  `matching.ts`/`matching-locate.ts` engine (locate-by-name before state, by `output.id` after —
+  PR 163) is unchanged in shape. Not published upstream yet, aliased onto
+  `@homeflare/distilled-paperless-ngx@0.3.0` — [distilled-interim.md](./distilled-interim.md).
+  State did not move: props/attributes stay byte-identical, proven by `tag.test.ts` and the full
+  PR 163 regression suite (`tag-identity.test.ts`) against a fake exercising the real distilled
+  protocol. ⛔ **Still diverges on credentials (S24):** `PAPERLESS_URL`/`PAPERLESS_TOKEN` are read
+  at call time, now through the SDK's `CredentialsFromEnv` — same divergence, unchanged by the
+  transport swap.
 - **`github/RepositoryRuleset`** (added 2026-09-23) closes the hazard the row above names:
   probes by name (`read`/`reconcile` both), answers `Unowned` on a cold name match (H1),
   normalizes before comparing so a matching live ruleset is a true noop, and refuses
@@ -196,7 +303,7 @@ among them `Fly/Secret.ts` and `Railway/Variable.ts`. They were listed under a b
 | `launchd/sudo-stage.ts`                                    | `node:fs/promises`, `node:os`, `node:path`   | —   | `FileSystem`, `Path`                         |
 | `launchd/job-form.ts`                                      | `node:crypto` (`createHash`)                 | —   | allowed in `Effect.sync`                     |
 | `linux/ssh-runner.ts`                                      | `node:child_process`, `node:crypto`          | yes | H3 above                                     |
-| `caddy/local-admin.ts`                                     | `node:http` (unix socket)                    | yes | H3 above                                     |
+| `caddy/caddy-http-client.ts`                               | `node:http`, `node:stream` (unix socket)     | yes | inherent — an Effect `HttpClient`, not H3 ⚠️ |
 | `proxmox/write-only.ts`, `pbs-notification-target-wire.ts` | `node:crypto`, `node:buffer`                 | —   | allowed in `Effect.sync` ⚠️                  |
 | `proxmox/provision-cli-fake.ts`                            | `Bun.spawn`, `node:fs`                       | —   | test-only; move out of `src/`                |
 
@@ -209,6 +316,15 @@ The ⚠️ rows:
 - `proxmox/write-only.ts`: a salted scrypt seal with `timingSafeEqual`. No Alchemy helper
   replaces it. A plain `sha256` would make a write-only secret cheap to brute-force from
   state, and it would change the persisted seal format.
+- `caddy/caddy-http-client.ts`: unlike `launchd/local-runner.ts` and `linux/ssh-runner.ts`
+  (H3, plain `async` interfaces), this is already the Effect `HttpClient.HttpClient` the
+  distilled SDK's own protocol runs on — `node:http` here is the same kind of unavoidable,
+  bottom-of-the-stack platform adapter `@effect/platform-node`'s own `NodeHttpClient.ts` is,
+  extended with `socketPath` dialing (that module has none) because a unix socket is the
+  measured transport a local Caddy needs and neither `FetchHttpClient` (Bun-only `unix`
+  option) nor stock `NodeHttpClient` (URL-only) speaks one on both Bun and Node. There is no
+  more-portable replacement to point to; the file already conforms to S19 (no async/await,
+  no raw `Promise` — `Effect.callback`/`Effect.tryPromise` throughout).
 
 Test runners: 51 files import `node:test`/`node:assert` (openbao 42, proxmox 7, forgejo 1,
 talos 1), and 126 import `bun:test`. S43 says `bun:test`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.28.0",
+  "version": "0.29.1",
   "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",
@@ -94,7 +94,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@distilled.cloud/caddy": "npm:@homeflare/distilled-caddy@0.2.0",
+    "@distilled.cloud/caddy": "npm:@homeflare/distilled-caddy@0.2.2",
     "@distilled.cloud/litellm": "npm:@homeflare/distilled-litellm@0.2.0",
     "@distilled.cloud/netbox": "npm:@homeflare/distilled-netbox@0.3.0",
     "@distilled.cloud/paperless-ngx": "npm:@homeflare/distilled-paperless-ngx@0.3.0",
@@ -103,7 +103,10 @@
   },
   "peerDependencies": {
     "@distilled.cloud/cloudflare": "1.0.0-rc.12",
+    "@distilled.cloud/discord": "1.0.0-rc.12",
     "@distilled.cloud/forgejo": "1.0.0-rc.12",
+    "@distilled.cloud/google-workspace": "1.0.0-rc.12",
+    "@distilled.cloud/grafana": "1.0.0-rc.12",
     "@effect/platform-node": "4.0.0-rc.115",
     "@effect/sql-pg": "4.0.0-rc.115",
     "alchemy": "2.0.0-beta.79",

package/src/caddy/admin-address.ts

@@ -0,0 +1,71 @@
+/**
+ * Parses a `localCaddyAdmin()` address into a dial target and the listener Caddy checks requests
+ * against — pure, so admin-guard.ts and local-admin.ts's tests exercise it with no transport at all.
+ *
+ * ★ LOOPBACK OR A UNIX SOCKET, NOTHING ELSE. The admin API is unauthenticated plaintext; an address
+ *   off this machine means it is reachable from the network, which decision 23 forbids. Reaching
+ *   another host's Caddy means forwarding its socket or port to here (SSH), never exposing :2019.
+ * ★ HOST, AS CADDY's OWN CLI SENDS IT (cmd/commandfuncs.go AdminAPIRequest): `host:port`, over TCP.
+ *   MEASURED against a Mac host's Caddy 2.11.4: any other Host gets 403 `host not allowed`, a
+ *   forwarded port included — hence `hostHeader`.
+ */
+import type { CaddyAdminListener } from './admin.ts';
+
+export type Target =
+  | { readonly kind: 'tcp'; readonly host: string; readonly port: number }
+  | { readonly kind: 'unix'; readonly socketPath: string };
+
+export const DEFAULT_ADMIN_ADDRESS = 'http://127.0.0.1:2019';
+
+const UNIX = 'unix://';
+const HOST_PORT = /^(?:[A-Za-z0-9.-]+|\[[0-9A-Fa-f:.]+\]):\d{1,5}$/;
+
+const refuse = (address: string, why: string): Error =>
+  new Error(`Caddy admin address ${JSON.stringify(address)}: ${why}`);
+
+const isLoopback = (hostname: string): boolean =>
+  hostname === 'localhost' || hostname === '[::1]' || /^127(?:\.\d{1,3}){3}$/.test(hostname);
+
+/** The dial target and listener for an address, or a refusal naming what is wrong with it. */
+export const parseAdminAddress = (
+  address: string,
+  hostHeader?: string,
+): { target: Target; listener: CaddyAdminListener } => {
+  if (hostHeader !== undefined && !HOST_PORT.test(hostHeader)) {
+    throw refuse(address, `hostHeader ${JSON.stringify(hostHeader)} must be host:port`);
+  }
+  if (address.startsWith(UNIX)) {
+    const socketPath = address.slice(UNIX.length);
+    if (!socketPath.startsWith('/')) throw refuse(address, 'the socket path must be absolute');
+    return { listener: { kind: 'unix', path: socketPath }, target: { kind: 'unix', socketPath } };
+  }
+  let url: URL;
+  try {
+    url = new URL(address);
+  } catch {
+    throw refuse(address, 'not a URL (http://127.0.0.1:2019 or unix:///path)');
+  }
+  // ⛔ Caddy's local admin endpoint is plaintext by design; its TLS one (`admin.remote`, mTLS on
+  //   :2021) is a different, network-facing API this transport deliberately does not speak.
+  if (url.protocol !== 'http:') throw refuse(address, 'only http:// (loopback) or unix://');
+  if (!isLoopback(url.hostname)) {
+    throw refuse(address, 'not loopback — the admin API is unauthenticated; forward it to here');
+  }
+  if (url.pathname !== '/' || url.search !== '' || url.username !== '') {
+    throw refuse(address, 'no path, query or credentials — the API lives at the root');
+  }
+  const port = url.port === '' ? 80 : Number(url.port);
+  // ⚠️ NOT `url.host`: WHATWG URL drops a default port (`http://127.0.0.1:80` has host
+  //   `127.0.0.1`), and Caddy compares the Host against `host:port` (admin.go allowedOrigins), so
+  //   a portless Host is a 403 on every call. The Caddy CLI always sends the port (JoinHostPort).
+  const host = hostHeader ?? `${url.hostname}:${String(port)}`;
+  return {
+    listener: {
+      hostHeader: host,
+      kind: 'tcp',
+      port: Number(host.slice(host.lastIndexOf(':') + 1)),
+    },
+    // ★ `hostname` keeps IPv6 brackets; node:http wants them off.
+    target: { host: url.hostname.replace(/^\[(.*)\]$/, '$1'), kind: 'tcp', port },
+  };
+};