@homeflare/alchemy 0.28.0 → 0.29.0

package/src/github/repository-ruleset-octokit.ts

@@ -8,14 +8,22 @@
  * should reach the wire. repository-ruleset-wire.test.ts MEASURES this against a real Octokit
  * instance with a fetch shim rather than asserting it from reading the source.
  *
- * ⚠️ "Reported success" is checked at the default branch's CURRENT TIP only, not its full
- *   history — a context that reported success three merges ago and has since started failing
- *   reads as reported (true), and one that has only ever run on a branch nobody has merged
- *   since reads as never-reported (false) until the next merge updates the tip. A full-history
- *   search is disproportionate to what this guard protects against (adding a context that
- *   plainly cannot report), and GitHub's check-runs/statuses APIs are themselves scoped to a
- *   single ref, not "ever, anywhere" — there is no cheaper vendor call that answers the wider
- *   question.
+ * ★ K2 (2026-09-24): "REPORTED SUCCESS" IS THE DEFAULT BRANCH'S TIP, THEN RECENT MERGED PR
+ *   HEADS — NOT FULL HISTORY. The rendered CI (`packages/config/src/repo-shape/ci.ts`) triggers
+ *   on `pull_request` ONLY, deliberately (measured 2026-09-15..22: 613 of 619 main-push runs
+ *   duplicated an already-green PR run, ~41% of the mini's CI load) — so `ci`/`secret scan`/
+ *   `CodeQL` NEVER report on the default branch's tip itself, only on PR heads. Checking the tip
+ *   alone therefore refused adding any of them everywhere, including homeflare-builds' pending
+ *   first ruleset. `contextReportedSuccess` now falls back to `recentMergedHeadShas` — bounded
+ *   (`RECENT_MERGED_PR_LIMIT` heads, from one `per_page`-bounded list call, never the repo's
+ *   full PR history) — so a context that only ever reports on PR heads is no longer refused
+ *   everywhere, while a context that has never reported ANYWHERE (not the tip, not any recent
+ *   merged head) still is: `NeverReportedContext`'s whole purpose survives unchanged.
+ * ⚠️ Still not full history: a context whose only successful run predates
+ *   `RECENT_MERGED_PR_LIMIT` merges ago reads as never-reported until it runs again. Widening
+ *   the bound trades this guard's cost (more vendor calls per newly-required context) against
+ *   its reach; `RECENT_MERGED_PR_LIMIT` is a deliberate, named number for exactly that reason,
+ *   not a magic constant.
  */
 import type { Octokit as OctokitClient } from '@octokit/rest';
 import { GitHubCredentials } from 'alchemy/GitHub';
@@ -37,6 +45,110 @@ const octokitFor = (
 
 const is404 = (e: unknown): boolean => (e as { status?: number } | undefined)?.status === 404;
 
+/** How many of the most-recently-updated MERGED pull requests' head SHAs to check, once the
+ * default branch's own tip has no reported success — see the file header (K2). */
+export const RECENT_MERGED_PR_LIMIT = 10;
+/** How many closed PRs to list (in one bounded call) to find up to `RECENT_MERGED_PR_LIMIT`
+ * merged ones among them — larger than the limit because `state: 'closed'` also returns PRs
+ * closed without merging, sorted by `updated_at`, not `merged_at` (the REST API has no
+ * merged-only list). A GitHub API list call has no `merged` filter, so this is `100` — GitHub's
+ * own per-page maximum, not a smaller round number — to keep unmerged churn (e.g. Dependabot
+ * PRs closed without merging, which still bump `updated_at`) from crowding out real merges in a
+ * repo with heavy PR traffic (2026-09-24 review finding: a smaller page risked under-reaching in
+ * exactly the kind of repo this fix targets). Still bounded, still one call, still never the
+ * repo's full history — a repo whose last `RECENT_MERGED_PR_LIMIT` merges don't even fit in the
+ * last 100 closed PRs is treated the same as one with too little history: fewer heads found,
+ * same "still refused" fallback. */
+const RECENT_CLOSED_PR_PAGE_SIZE = 100;
+
+/** Whether `context` reported success for a single ref — a branch tip or a PR head SHA, both
+ * checked the same way (checks + statuses, exactly as GitHub's own UI does). Takes a plain
+ * `OctokitClient`, not an Effect service, so it and its caller below are testable directly
+ * against a real `@octokit/rest` instance with a fetch shim (repository-ruleset-octokit.test.ts)
+ * — no `GitHubCredentials` layer needed, mirroring `desiredWireRuleset`'s pure-function seam. */
+export const hasRefReportedSuccess = (
+  octokit: OctokitClient,
+  owner: string,
+  repo: string,
+  ref: string,
+  context: string,
+): Effect.Effect<boolean, Error> =>
+  Effect.gen(function* () {
+    const [checkRuns, statuses] = yield* Effect.all([
+      Effect.tryPromise({
+        try: () => octokit.rest.checks.listForRef({ owner, repo, ref, check_name: context }),
+        catch: asError,
+      }),
+      Effect.tryPromise({
+        try: () => octokit.rest.repos.listCommitStatusesForRef({ owner, repo, ref }),
+        catch: asError,
+      }),
+    ]);
+    const checkReported = checkRuns.data.check_runs.some(
+      (run) => run.name === context && run.conclusion === 'success',
+    );
+    const statusReported = statuses.data.some(
+      (status) => status.context === context && status.state === 'success',
+    );
+    return checkReported || statusReported;
+  });
+
+/** The head SHAs of up to `RECENT_MERGED_PR_LIMIT` most-recently-updated MERGED pull requests
+ * against `base` — one bounded list call (`RECENT_CLOSED_PR_PAGE_SIZE` closed PRs), filtered to
+ * merged, then capped. Never paginates further: a repo whose last `RECENT_MERGED_PR_LIMIT`
+ * merges are all older than its last `RECENT_CLOSED_PR_PAGE_SIZE` closed PRs simply yields fewer
+ * than the limit, same as a repo with too little history — both are the "still refused" case. */
+export const recentMergedHeadShas = (
+  octokit: OctokitClient,
+  owner: string,
+  repo: string,
+  base: string,
+): Effect.Effect<readonly string[], Error> =>
+  Effect.gen(function* () {
+    const closed = yield* Effect.tryPromise({
+      try: () =>
+        octokit.rest.pulls.list({
+          owner,
+          repo,
+          state: 'closed',
+          base,
+          sort: 'updated',
+          direction: 'desc',
+          per_page: RECENT_CLOSED_PR_PAGE_SIZE,
+        }),
+      catch: asError,
+    });
+    return closed.data
+      .filter((pr) => pr.merged_at !== null)
+      .slice(0, RECENT_MERGED_PR_LIMIT)
+      .map((pr) => pr.head.sha);
+  });
+
+/** The full K2 answer: the default branch's tip, then (only if the tip has no success) up to
+ * `RECENT_MERGED_PR_LIMIT` recent merged PR heads, short-circuiting on the first success. `false`
+ * only once every one of those has been checked and none reported — the case
+ * `NeverReportedContext` exists to refuse. */
+export const contextReportedSuccess = (
+  octokit: OctokitClient,
+  owner: string,
+  repo: string,
+  context: string,
+): Effect.Effect<boolean, Error> =>
+  Effect.gen(function* () {
+    const repository = yield* Effect.tryPromise({
+      try: () => octokit.rest.repos.get({ owner, repo }),
+      catch: asError,
+    });
+    const ref = repository.data.default_branch;
+    if (yield* hasRefReportedSuccess(octokit, owner, repo, ref, context)) return true;
+
+    const heads = yield* recentMergedHeadShas(octokit, owner, repo, ref);
+    for (const sha of heads) {
+      if (yield* hasRefReportedSuccess(octokit, owner, repo, sha, context)) return true;
+    }
+    return false;
+  });
+
 export const makeRulesetOctokit = (baseUrl: string | undefined): RealRulesetOctokit => ({
   list: ({ owner, repo }) =>
     Effect.gen(function* () {
@@ -114,27 +226,6 @@ export const makeRulesetOctokit = (baseUrl: string | undefined): RealRulesetOcto
   hasContextReportedSuccess: ({ owner, repo, context }) =>
     Effect.gen(function* () {
       const octokit = yield* octokitFor(baseUrl);
-      const repository = yield* Effect.tryPromise({
-        try: () => octokit.rest.repos.get({ owner, repo }),
-        catch: asError,
-      });
-      const ref = repository.data.default_branch;
-      const [checkRuns, statuses] = yield* Effect.all([
-        Effect.tryPromise({
-          try: () => octokit.rest.checks.listForRef({ owner, repo, ref, check_name: context }),
-          catch: asError,
-        }),
-        Effect.tryPromise({
-          try: () => octokit.rest.repos.listCommitStatusesForRef({ owner, repo, ref }),
-          catch: asError,
-        }),
-      ]);
-      const checkReported = checkRuns.data.check_runs.some(
-        (run) => run.name === context && run.conclusion === 'success',
-      );
-      const statusReported = statuses.data.some(
-        (status) => status.context === context && status.state === 'success',
-      );
-      return checkReported || statusReported;
+      return yield* contextReportedSuccess(octokit, owner, repo, context);
     }),
 });

package/src/github/repository-ruleset-probe.ts

@@ -71,7 +71,8 @@ export interface RulesetOctokit<R = never> {
     readonly repo: string;
     readonly rulesetId: number;
   }) => Effect.Effect<void, Error, R>;
-  /** Whether `context` has ever reported success against the repository's default branch —
+  /** Whether `context` has reported success against the repository's default branch tip OR a
+   * recent merged PR head (K2, bounded — see repository-ruleset-octokit.ts's file header) —
    * backs the `NeverReportedContext` guard. */
   readonly hasContextReportedSuccess: (input: {
     readonly owner: string;

package/src/github/repository-ruleset-props.ts

@@ -18,10 +18,13 @@ export interface RepositoryRulesetPullRequestRule extends NonNullable<
   /** @default every method GitHub allows — the house baseline always pins `['squash']`. */
   readonly allowedMergeMethods?: readonly ('merge' | 'squash' | 'rebase')[];
   readonly requiredReviewers?: readonly RepositoryRulesetReviewerRule[];
-  /** `require_extra_approval_for_unattributed_changes` — see repository-ruleset.ts's H15. Only
-   * `false` is modeled: sending `true` has no house use, and GitHub already defaults absent to
-   * `true`. */
-  readonly extraApprovalForUnattributedChanges?: false;
+  /** `require_extra_approval_for_unattributed_changes` — see repository-ruleset.ts's H15.
+   * Both values are modeled (K1, 2026-09-23): 8 live rulesets carry `true` (aop, cloudflareforms,
+   * doesthishelp-workeropen, homeflare-anyauth, homeflare-desktop, loggarr, magictransit,
+   * proxmox-tb4 — re-read live via `gh api repos/taslabs-net/<repo>/rulesets/<id>`,
+   * 2026-09-23), and this resource declares exactly what is live or it cannot adopt them —
+   * `undefined` stays "no opinion" (GitHub defaults an absent key to `true`). */
+  readonly extraApprovalForUnattributedChanges?: boolean;
 }
 
 export interface RepositoryRulesetStatusChecksRule extends NonNullable<

package/src/github/repository-ruleset-providers.ts

@@ -0,0 +1,46 @@
+/**
+ * `repoPolicyProviders` — the documented stack wiring for `RepositoryRuleset` (directly, or
+ * through `declareRepoPolicy` / `declareRepoBaseline`): `GitHub.providers()` and
+ * `RepositoryRulesetProvider()`, composed so the whole thing typechecks and needs nothing
+ * further from the stack.
+ *
+ *     providers: repoPolicyProviders()
+ *
+ * ⛔ WHY THIS EXISTS — MEASURED 2026-09-24 (homeflare-builds bump PR 6, tsc). Writing the two
+ *   providers side by side, `Layer.mergeAll(GitHub.providers(), RepositoryRulesetProvider())`,
+ *   type-errors: `RepositoryRulesetProvider()`'s handlers call `octokitFor`, which needs
+ *   `GitHubCredentials` — a requirement of the PROVIDER's layer, correctly inferred by
+ *   `Provider.succeed` from `repositoryRulesetHandlers` in repository-ruleset.ts. Merging two
+ *   layers does not thread one's output into the other's requirement; `RepositoryRulesetProvider()`
+ *   still needs `GitHubCredentials` fed in. `GitHub.providers()` is the only thing here that
+ *   resolves credentials (env, stored PAT, `gh` CLI, or OAuth — see `alchemy/src/GitHub/
+ *   Providers.ts`), and — because it chains `Layer.provideMerge(Credentials.fromAuthProvider(…))`
+ *   internally rather than `Layer.provide` — its own OUTPUT includes `GitHubCredentials`
+ *   alongside `GitHub.Providers`. `Layer.provideMerge(github)` on `RepositoryRulesetProvider()`
+ *   both supplies that requirement AND keeps `github`'s own output merged in for any
+ *   `GitHub.Repository`/`GitHub.Ruleset` the caller also declares. `github` is built once and
+ *   referenced twice below — Effect's layer memoization (by reference) builds it once, not
+ *   twice, not twice against the auth provider either.
+ *
+ * ★ THIS IS ONLY HALF OF 2026-09-24's FIX. The other half — `RepositoryRuleset`'s own `Resource<>`
+ *   declaration no longer naming `GitHubCredentials` in its 5th (`Providers`) slot — lives in
+ *   repository-ruleset.ts's file header; that half is what let a stack BODY calling
+ *   `declareRepoPolicy`/`declareRepoBaseline` typecheck at all. Composing the providers
+ *   correctly, as this function does, does not by itself fix a body that still requires
+ *   `GitHubCredentials` directly.
+ *
+ * ⚠️ DON'T ALSO MERGE A SEPARATE `GitHub.providers()` CALL IN. `github` here is one Layer
+ *   object referenced twice, which Effect's layer memoization (by reference, ADVERSARIAL
+ *   REVIEW 2026-09-24: confirmed against `effect@4.0.0-rc.115`'s own `MemoMap`) builds once. A
+ *   stack that ALSO writes its own `GitHub.providers()` alongside this function's result is a
+ *   second, distinct Layer object — a genuine second credential resolution, not shared with
+ *   this one. Get every GitHub resource's providers from this one call.
+ */
+import * as GitHub from 'alchemy/GitHub';
+import * as Layer from 'effect/Layer';
+import { RepositoryRulesetProvider } from './repository-ruleset.ts';
+
+export const repoPolicyProviders = (options?: GitHub.ProvidersOptions) => {
+  const github = GitHub.providers(options);
+  return Layer.mergeAll(github, RepositoryRulesetProvider().pipe(Layer.provideMerge(github)));
+};

package/src/github/repository-ruleset-wire.test.ts

@@ -32,35 +32,46 @@ function makeCapturingFetch(captured: CapturedRequest[]): typeof fetch {
 }
 
 describe('does Octokit forward an untyped extra body field to the wire?', () => {
-  test('require_extra_approval_for_unattributed_changes survives createRepoRuleset', async () => {
-    const captured: CapturedRequest[] = [];
-    const octokit = new Octokit({
-      auth: 'fake-token-not-a-real-credential',
-      request: { fetch: makeCapturingFetch(captured) },
-    });
+  // K1 (2026-09-23): both values are modeled now, not only `false` — 8 live rulesets (aop,
+  // cloudflareforms, doesthishelp-workeropen, homeflare-anyauth, homeflare-desktop, loggarr,
+  // magictransit, proxmox-tb4; re-read live 2026-09-23) carry `true`, so this measurement needs
+  // both, not just the one value this resource used to be able to send.
+  test.each([false, true])(
+    'require_extra_approval_for_unattributed_changes: %p survives createRepoRuleset',
+    async (value) => {
+      const captured: CapturedRequest[] = [];
+      const octokit = new Octokit({
+        auth: 'fake-token-not-a-real-credential',
+        request: { fetch: makeCapturingFetch(captured) },
+      });
 
-    const body = desiredWireRuleset({
-      owner: 'taslabs-net',
-      repository: 'widgets',
-      name: 'main',
-      rules: {
-        pullRequest: {
-          requiredApprovingReviewCount: 0,
-          allowedMergeMethods: ['squash'],
-          extraApprovalForUnattributedChanges: false,
+      const body = desiredWireRuleset({
+        owner: 'taslabs-net',
+        repository: 'widgets',
+        name: 'main',
+        rules: {
+          pullRequest: {
+            requiredApprovingReviewCount: 0,
+            allowedMergeMethods: ['squash'],
+            extraApprovalForUnattributedChanges: value,
+          },
         },
-      },
-    });
+      });
 
-    await octokit.rest.repos.createRepoRuleset({ owner: 'taslabs-net', repo: 'widgets', ...body });
+      await octokit.rest.repos.createRepoRuleset({
+        owner: 'taslabs-net',
+        repo: 'widgets',
+        ...body,
+      });
 
-    expect(captured).toHaveLength(1);
-    const sent = captured[0]?.body as {
-      rules?: { type: string; parameters?: Record<string, unknown> }[];
-    };
-    const pr = sent?.rules?.find((r) => r.type === 'pull_request');
-    // MEASURED: this is what actually crossed the wire, not what Octokit's types say is legal.
-    expect(pr?.parameters?.require_extra_approval_for_unattributed_changes).toBe(false);
-    expect(pr?.parameters?.allowed_merge_methods).toEqual(['squash']);
-  });
+      expect(captured).toHaveLength(1);
+      const sent = captured[0]?.body as {
+        rules?: { type: string; parameters?: Record<string, unknown> }[];
+      };
+      const pr = sent?.rules?.find((r) => r.type === 'pull_request');
+      // MEASURED: this is what actually crossed the wire, not what Octokit's types say is legal.
+      expect(pr?.parameters?.require_extra_approval_for_unattributed_changes).toBe(value);
+      expect(pr?.parameters?.allowed_merge_methods).toEqual(['squash']);
+    },
+  );
 });

package/src/github/repository-ruleset.ts

@@ -38,11 +38,33 @@
  *   meant to allow. `octokitFor`/`GitHubCredentials` are upstream's own EXPORTED building
  *   blocks (S23's second clause: reuse Alchemy's own client construction), so the client itself
  *   is not hand-rolled — only the choice of Octokit over distilled is a recorded divergence.
+ *
+ * ⛔ CREDENTIALS BELONG TO THE PROVIDER'S LAYER, NOT THE RESOURCE'S DECLARATION — MEASURED
+ *   2026-09-24 (homeflare-builds bump PR 6, tsc TS2345). The `Resource<Type, Props, Attributes,
+ *   Binding, Providers>` 5th type parameter had `GitHubCredentials` here; that puts the
+ *   credential requirement on every `yield* RepositoryRuleset(...)` CALL SITE (see
+ *   `alchemy/src/Resource.ts#ResourceClass`: `Req = R["Providers"] extends undefined ?
+ *   Provider<R> : R["Providers"]`), so a STACK BODY that merely declares the resource would
+ *   itself need `GitHubCredentials` in its own effect context — which a stack body cannot
+ *   produce (`Alchemy.Stack`'s own type, `alchemy/src/Stack.ts#ProviderServices`, is a closed
+ *   union of tagged marker interfaces — `ProviderCollectionLike | Provider<any> |
+ *   EnvironmentLike | CredentialsLike | DockerLike` — and `GitHubCredentials` matches none of
+ *   them structurally). VERIFIED against upstream `Ruleset` (`node_modules/alchemy/src/GitHub/
+ *   Ruleset.ts`): its 5th slot is `GitHub.Providers`, the ProviderCollection tag `GitHub.
+ *   providers()` OUTPUTS — never the raw `GitHubCredentials` service upstream's OWN provider
+ *   handlers pull in via `octokitFor`. `GitHubCredentials` stays confined to the PROVIDER's
+ *   layer requirement (`Provider.succeed`'s inferred `ReadReq | DiffReq | ReconcileReq |
+ *   DeleteReq`, below), never the declaration's. Omitting the 5th parameter here defaults it to
+ *   `undefined`, so the declaration's own requirement becomes `Provider<RepositoryRuleset>` —
+ *   itself a `Provider<any>`, a real `ProviderServices` member — matching the pattern a
+ *   standalone (non-collection) resource actually needs. See `repoPolicyProviders()` in
+ *   repository-ruleset-providers.ts for the layer composition this now requires (the provider
+ *   still needs `GitHubCredentials` fed in — that half of the fix was already correct, per
+ *   `docs/repository-ruleset.md`).
  */
 import { Resource } from 'alchemy';
 import { Unowned } from 'alchemy/AdoptPolicy';
 import { isResolved } from 'alchemy/Diff';
-import type { GitHubCredentials } from 'alchemy/GitHub';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
 import {
@@ -75,8 +97,10 @@ export interface RepositoryRuleset extends Resource<
   'GitHub.RepositoryRuleset',
   RepositoryRulesetProps,
   RepositoryRulesetAttributes,
-  never,
-  GitHubCredentials
+  never
+  // ⛔ NO 5th (`Providers`) ARGUMENT — see the file header. Defaulting it to `undefined` makes
+  // a `yield* RepositoryRuleset(...)` call site require `Provider<RepositoryRuleset>`, not
+  // `GitHubCredentials`; the credential requirement lives on the PROVIDER below instead.
 > {}
 
 export const RepositoryRuleset = Resource<RepositoryRuleset>('GitHub.RepositoryRuleset', {

package/src/litellm/fake-litellm.ts

@@ -1,22 +1,35 @@
 /**
- * A loopback `Bun.serve` fake of LiteLLM's `/config/pass_through_endpoint` routes — TEST ONLY,
- * never imported by `index.ts` (the netbox/proxmox house convention for test-only helpers).
+ * A fake of LiteLLM's `/config/pass_through_endpoint` routes for tests — TEST ONLY, never imported
+ * by `index.ts` (the netbox/forgejo house convention for test-only helpers). Mirrors
+ * `../netbox/fake-netbox.ts`/`../forgejo/fake-forgejo.ts`: a `fetch` function handed to Effect's
+ * real `FetchHttpClient` through its `Fetch` reference, so a test exercises distilled's REAL path
+ * assembly, JSON encode/decode and status→typed-error matching (`BadRequest`, `NotFound`, …) —
+ * nothing about that matching is re-implemented here, only the wire responses a scenario needs.
  *
  * ★ MODELS THE WHOLE-FIELD READ-MODIFY-WRITE ON PURPOSE. `general_settings.pass_through_endpoints`
- *   is ONE field (client.ts's header), so every mutation here reads the CURRENT row list, waits
- *   (so two concurrent requests can interleave), then writes back what it captured — not what is
- *   there by the time it writes. Two `create` calls that race lose one row, exactly like the
- *   vendor field would without the client's per-base-URL semaphore serialising them.
+ *   is ONE field (operations.ts's header), so every mutation here reads the CURRENT row list,
+ *   awaits (so two concurrent calls can interleave — no real socket needed, `fetch` is just an
+ *   async function the runtime awaits), then writes back what it captured — not what is there by
+ *   the time it writes. Two `create` calls that race lose one row, exactly like the vendor field
+ *   would without `operations.ts`'s per-base-URL semaphore serialising them.
  * ⚠️ WHAT THIS FAKE DOES NOT MODEL: PROXY_ADMIN vs. a lesser role for most routes (any correct
- *   bearer token is accepted); and update-of-a-missing-id, which is not measured at the tag — this
- *   fake 400s it, the same status a missing delete gets, as a documented TEST SIMPLIFICATION, not a
- *   vendor fact (docs/litellm.md says so too). `forbidDelete` is the one exception: it models the
- *   real asymmetry client.ts's header describes — `DELETE` routes through
- *   `update_config_general_settings`, which 400s `not_allowed_access` for a non-PROXY_ADMIN caller
- *   (or a disconnected DB) on a row that is genuinely still live, the SAME status a missing-id
- *   delete gets (proxy_server.py:16389-16416 at v1.100.0).
+ *   bearer token is accepted). `forbidDelete` is the one exception: it models the real asymmetry
+ *   `operations.ts`'s header describes — `DELETE` routes through `update_config_general_settings`,
+ *   which 400s `not_allowed_access` for a non-PROXY_ADMIN caller (or a disconnected DB) on a row
+ *   that is genuinely still live, the SAME status a missing-id delete gets (proxy_server.py:
+ *   16389-16416 at v1.100.0).
+ * ⚠️ UPDATE-OF-A-MISSING-ID IS 404, NOT 400 — corrected by this migration. The retired hand-rolled
+ *   fake 400'd it as "not measured at the tag, a documented test simplification". The distilled
+ *   SDK's own `patches/misc/update_pass_through_endpoints_*.json` cites the real source
+ *   (`pass_through_endpoints.py`'s `update_pass_through_endpoints` at the tag): unlike DELETE, this
+ *   route raises a genuine, unambiguous `HTTPException(404)` for a missing id, distinct from the
+ *   400 `update_config_general_settings` raises for the trailing auth/DB-disconnected write. This
+ *   fake now matches that measured vendor behaviour.
  */
-import type { PassThroughGenericEndpoint } from './generated/pass-through.ts';
+import type { PassThroughGenericEndpoint } from '@distilled.cloud/litellm/misc';
+
+/** RFC 2606 placeholder — never a real host. Shared across tests, like `../netbox/fake-netbox.ts`. */
+export const FAKE_BASE = 'https://litellm.example.com';
 
 export interface FakeRequest {
   readonly method: string;
@@ -24,15 +37,17 @@ export interface FakeRequest {
 }
 
 export interface FakeLitellm {
-  readonly url: string;
+  readonly fetch: typeof globalThis.fetch;
   readonly rows: () => readonly PassThroughGenericEndpoint[];
   readonly requests: () => readonly FakeRequest[];
-  readonly stop: () => void;
 }
 
 const RACE_WINDOW_MS = 15;
 const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
 
+const json = (status: number, body: unknown) =>
+  new Response(JSON.stringify(body), { headers: { 'content-type': 'application/json' }, status });
+
 export const startFakeLitellm = (options?: {
   readonly masterKey?: string;
   readonly seed?: readonly PassThroughGenericEndpoint[];
@@ -44,73 +59,63 @@ export const startFakeLitellm = (options?: {
   let rows: PassThroughGenericEndpoint[] = [...(options?.seed ?? [])];
   const requests: FakeRequest[] = [];
 
-  const json = (status: number, body: unknown) =>
-    new Response(JSON.stringify(body), { headers: { 'content-type': 'application/json' }, status });
+  const fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+    const request =
+      input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+    const url = new URL(request.url);
+    requests.push({ method: request.method, path: `${url.pathname}${url.search}` });
+    const auth = request.headers.get('authorization');
+    if (auth !== `Bearer ${masterKey}`) return json(401, { detail: 'invalid api key' });
+    if (
+      url.pathname !== '/config/pass_through_endpoint' &&
+      !url.pathname.startsWith('/config/pass_through_endpoint/')
+    ) {
+      return json(404, { detail: 'not found' });
+    }
 
-  const server = Bun.serve({
-    // ⚠️ Loopback, not the wildcard default — see proxmox/fake-pve-lxc.ts for the race.
-    hostname: '127.0.0.1',
-    port: 0,
-    fetch: async (req) => {
-      const url = new URL(req.url);
-      requests.push({ method: req.method, path: url.pathname });
-      const auth = req.headers.get('authorization');
-      if (auth !== `Bearer ${masterKey}`) return json(401, { detail: 'invalid api key' });
-      if (
-        url.pathname !== '/config/pass_through_endpoint' &&
-        !url.pathname.startsWith('/config/pass_through_endpoint/')
-      ) {
-        return json(404, { detail: 'not found' });
-      }
+    if (request.method === 'GET') {
+      const endpointId = url.searchParams.get('endpoint_id');
+      const filtered = endpointId === null ? rows : rows.filter((row) => row.id === endpointId);
+      return json(200, { endpoints: filtered });
+    }
 
-      if (req.method === 'GET') {
-        const endpointId = url.searchParams.get('endpoint_id');
-        const filtered = endpointId === null ? rows : rows.filter((row) => row.id === endpointId);
-        return json(200, { endpoints: filtered });
-      }
+    if (request.method === 'POST' && url.pathname === '/config/pass_through_endpoint') {
+      const body = (await request.json()) as PassThroughGenericEndpoint;
+      const before = rows; // ★ captured before the window — the race the semaphore prevents
+      await sleep(RACE_WINDOW_MS);
+      rows = [...before, { ...body, is_from_config: false }];
+      return json(200, { body: {} });
+    }
 
-      if (req.method === 'POST' && url.pathname === '/config/pass_through_endpoint') {
-        const body = (await req.json()) as PassThroughGenericEndpoint;
-        const before = rows; // ★ captured before the window — the race the semaphore prevents
-        await sleep(RACE_WINDOW_MS);
-        rows = [...before, { ...body, is_from_config: false }];
-        return json(200, {});
-      }
-
-      if (req.method === 'POST' && url.pathname.startsWith('/config/pass_through_endpoint/')) {
-        const id = decodeURIComponent(url.pathname.slice('/config/pass_through_endpoint/'.length));
-        const patch = (await req.json()) as Partial<PassThroughGenericEndpoint>;
-        const before = rows;
-        await sleep(RACE_WINDOW_MS);
-        const index = before.findIndex((row) => row.id === id);
-        if (index === -1) return json(400, { detail: `No pass-through endpoint with id=${id}` });
-        // ⚠️ `exclude_none`-shaped: only keys the patch actually carries are merged, matching
-        //   client.ts's `updateBody` never sending an unset/null field (pass-through-form.ts).
-        const merged = { ...before[index], ...patch };
-        rows = before.map((row, i) => (i === index ? (merged as PassThroughGenericEndpoint) : row));
-        return json(200, {});
-      }
+    if (request.method === 'POST' && url.pathname.startsWith('/config/pass_through_endpoint/')) {
+      const id = decodeURIComponent(url.pathname.slice('/config/pass_through_endpoint/'.length));
+      const patch = (await request.json()) as Partial<PassThroughGenericEndpoint>;
+      const before = rows;
+      await sleep(RACE_WINDOW_MS);
+      const index = before.findIndex((row) => row.id === id);
+      // ⚠️ 404, not 400 — see the file header.
+      if (index === -1) return json(404, { detail: `Endpoint with ID '${id}' not found` });
+      // ⚠️ `exclude_none`-shaped: only keys the patch actually carries are merged, matching
+      //   operations.ts's `updateBody` never sending an unset/null field (pass-through-form.ts).
+      const merged = { ...before[index], ...patch };
+      rows = before.map((row, i) => (i === index ? (merged as PassThroughGenericEndpoint) : row));
+      return json(200, { body: {} });
+    }
 
-      if (req.method === 'DELETE' && url.pathname === '/config/pass_through_endpoint') {
-        const id = url.searchParams.get('endpoint_id');
-        if (forbidDelete) return json(400, { error: 'not_allowed_access' });
-        const before = rows;
-        await sleep(RACE_WINDOW_MS);
-        if (!before.some((row) => row.id === id)) {
-          return json(400, { detail: `No pass-through endpoint with id=${String(id)}` });
-        }
-        rows = before.filter((row) => row.id !== id);
-        return json(200, { endpoints: rows });
+    if (request.method === 'DELETE' && url.pathname === '/config/pass_through_endpoint') {
+      const id = url.searchParams.get('endpoint_id');
+      if (forbidDelete) return json(400, { error: 'not_allowed_access' });
+      const before = rows;
+      await sleep(RACE_WINDOW_MS);
+      if (!before.some((row) => row.id === id)) {
+        return json(400, { detail: `No pass-through endpoint with id=${String(id)}` });
       }
+      rows = before.filter((row) => row.id !== id);
+      return json(200, { endpoints: rows });
+    }
 
-      return json(405, { detail: `unhandled ${req.method} ${url.pathname}` });
-    },
-  });
+    return json(405, { detail: `unhandled ${request.method} ${url.pathname}` });
+  }) as typeof globalThis.fetch;
 
-  return {
-    requests: () => [...requests],
-    rows: () => [...rows],
-    stop: () => server.stop(true),
-    url: server.url.toString().replace(/\/$/, ''),
-  };
+  return { fetch, requests: () => [...requests], rows: () => [...rows] };
 };

package/src/litellm/fake-stack.ts

@@ -12,13 +12,13 @@
  * ★ NOT alchemy/Test/Bun — same reasoning as openbao/fake-stack.ts: no CLI profile/credentials
  *   files, no file logger. Just the provider, an in-memory state store, and the stack's services.
  */
+import { credentials } from '@distilled.cloud/litellm/Credentials';
 import * as Alchemy from 'alchemy';
 import { AdoptPolicy } from 'alchemy/AdoptPolicy';
 import { provideFreshArtifactStore } from 'alchemy/Artifacts';
 import * as Effect from 'effect/Effect';
 import * as Layer from 'effect/Layer';
 import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
-import { type LitellmCreds, litellmCredentialsLayerFor } from './credentials.ts';
 import { LiteLLMPassThroughEndpointProvider } from './pass-through-endpoint.ts';
 
 /** The planned action for each resource, deletions included, keyed by FQN. */
@@ -53,13 +53,20 @@ const actionsOf = (plan: PlanView): Planned => {
 /**
  * ⚠️ CREDENTIALS/HTTPCLIENT ARE PROVIDED AROUND `deploy`, NOT BAKED INTO THE PROVIDER LAYER.
  *   `Provider.effect`'s own construction effect is `Effect.succeed(...)` (pass-through-endpoint.ts)
- *   — it never actually reads `LitellmCredentials`/`HttpClient`; only the HANDLERS it returns do,
- *   and those run later, whenever `Apply.ts` calls `provider.reconcile`/`read`/`delete`. Effect
+ *   — it never actually reads `Credentials`/`HttpClient`; only the HANDLERS it returns do, and
+ *   those run later, whenever `Apply.ts` calls `provider.reconcile`/`read`/`delete`. Effect
  *   resolves a `yield*`'s service from whatever ambient context wraps the CALL SITE, so the layers
  *   those handlers need must wrap the whole plan+apply pipeline below, exactly where openbao's
  *   fake-stack.ts wraps `BaoEnv` around its own `deploy`.
+ * ★ `fetchFn` IS `startFakeLitellm(...).fetch` (fake-litellm.ts) — this harness never opens a real
+ *   socket; `FetchHttpClient.Fetch` is the seam the SDK's protocol layer calls through, same as
+ *   `../netbox/fake-netbox.ts`'s `fakeNetboxLayer`.
  */
-export const fakeStack = (creds: LitellmCreds, name = 'PassThroughStack'): FakeStack => {
+export const fakeStack = (
+  creds: { readonly apiKey: string; readonly baseUrl: string },
+  fetchFn: typeof globalThis.fetch,
+  name = 'PassThroughStack',
+): FakeStack => {
   const state = Alchemy.inMemoryState();
   const providers = LiteLLMPassThroughEndpointProvider();
   const stack = Alchemy.Stack as unknown as (
@@ -83,8 +90,9 @@ export const fakeStack = (creds: LitellmCreds, name = 'PassThroughStack'): FakeS
     }).pipe(
       options.adopt === undefined ? (e) => e : Effect.provideService(AdoptPolicy, options.adopt),
       Effect.provideService(Alchemy.Stage, 'test'),
-      Effect.provide(litellmCredentialsLayerFor(creds)),
+      Effect.provide(credentials(creds)),
       Effect.provide(FetchHttpClient.layer),
+      Effect.provide(Layer.succeed(FetchHttpClient.Fetch, fetchFn)),
       Effect.scoped,
     );