@homeflare/alchemy 0.28.0 → 0.29.0

package/src/caddy/providers.ts

@@ -6,12 +6,28 @@
  * ★ launchdProviders() TOO when the stack uses caddyWithFile(): the file is a launchd-subpath
  *   HostFile, written through that subpath's HostRunner.
  * ⚠️ The default is localCaddyAdmin(): `http://127.0.0.1:2019`, Caddy's default admin listener.
- *   Pass another CaddyAdmin for a unix socket, a narrowed `admin { origins }`, or an SSH forward.
+ *   Pass another CaddyTransport for a unix socket, a narrowed `admin { origins }`, or an SSH
+ *   forward — `localCaddyAdmin({ address, hostHeader })` builds one; a consumer can provide any
+ *   other `{ endpoint, listener, layer }` reaching `@distilled.cloud/caddy`'s own `Credentials`
+ *   and `HttpClient.HttpClient`.
+ *
+ * ⚠️ `Layer.provideMerge`, NEVER PLAIN `Layer.provide`, for `caddyAdminLayer`. `CaddyConfigProvider()`'s
+ *   `read`/`diff`/`reconcile` handlers each still need `CaddyAdminService` and
+ *   `@distilled.cloud/caddy`'s `Credentials`/`HttpClient` — Alchemy's own `Provider.effect` types
+ *   those as part of the LAYER's overall requirement (`ProviderService`'s per-handler `Req` type
+ *   parameters, `alchemy/Provider.ts`), for exactly this reason. Plain `Layer.provide` SEALS a
+ *   layer — it satisfies `CaddyConfigProvider()`'s requirement only for BUILDING the `Provider`
+ *   value (the `admin` in its outer `Effect.gen`), then hides those services from anything that
+ *   runs LATER, when the returned `read`/`diff`/`reconcile` FUNCTIONS actually execute. MEASURED
+ *   2026-09-23: with plain `Layer.provide`, `caddyProviders()`'s own `reconcile` handler dies with
+ *   "Service not found: homeflare/caddy/CaddyAdmin" the moment the ENGINE calls it. `provideMerge`
+ *   feeds `caddyAdminLayer`'s output into `CaddyConfigProvider()`'s requirement AND keeps that same
+ *   output live in the result, so every later handler call still runs with it in context.
  */
 import * as Layer from 'effect/Layer';
-import { type CaddyAdmin, caddyAdminLayer } from './admin.ts';
+import { type CaddyTransport, caddyAdminLayer } from './admin.ts';
 import { CaddyConfigProvider } from './config.ts';
 import { localCaddyAdmin } from './local-admin.ts';
 
-export const caddyProviders = (admin: CaddyAdmin = localCaddyAdmin()) =>
-  CaddyConfigProvider().pipe(Layer.provide(caddyAdminLayer(admin)));
+export const caddyProviders = (transport: CaddyTransport = localCaddyAdmin()) =>
+  CaddyConfigProvider().pipe(Layer.provideMerge(caddyAdminLayer(transport)));

package/src/github/declare-repo-baseline.ts

@@ -8,12 +8,12 @@
  *       visibility: 'private',
  *     });
  *
- * Provide `GitHub.providers()` AND `RepositoryRulesetProvider()` — this subpath ships no
- * provider of its own, the same as `declareRepoPolicy`. Both resources are `retain` and
- * `adopt(true)` ALWAYS, unlike `declareRepoPolicy`'s optional `adopt` — a baseline this widely
- * shared is meant for a checkout adopting the estate's existing repository and ruleset by name,
- * never for creating one out from under a caller who forgot the flag (H1: a name match is not
- * ours until adopted).
+ * Provide `repoPolicyProviders()` (repository-ruleset-providers.ts) — this subpath ships no
+ * provider of its own beyond the ruleset bridge, the same as `declareRepoPolicy`. Both resources
+ * are `retain` and `adopt(true)` ALWAYS, unlike `declareRepoPolicy`'s optional `adopt` — a
+ * baseline this widely shared is meant for a checkout adopting the estate's existing repository
+ * and ruleset by name, never for creating one out from under a caller who forgot the flag (H1: a
+ * name match is not ours until adopted).
  *
  * ⛔ NO IMPORT FROM `@homeflare/config`, either direction — see `renderRepoShape`'s own header
  *   in `packages/config/src/repo-shape/render.ts`. A caller spreads `renderRepoShape(shape)

package/src/github/index.ts

@@ -3,10 +3,13 @@
  * one bridge resource this house builds atop upstream GitHub: `GitHub.RepositoryRuleset`.
  *
  * ⚠️ `declareRepoPolicy`/`declareRepoBaseline` COMPOSE UPSTREAM `GitHub.Repository` PLUS THIS
- *   SUBPATH'S OWN `RepositoryRulesetProvider()` — provide BOTH `GitHub.providers()` and
- *   `RepositoryRulesetProvider()`. Before 2026-09-23 this subpath shipped no provider at all,
- *   composing only vendor resources; `RepositoryRuleset` is the one exception, and
- *   repository-ruleset.ts's header says why upstream's own `Ruleset` cannot fill the gap.
+ *   SUBPATH'S OWN `RepositoryRulesetProvider()` — provide `repoPolicyProviders()`
+ *   (repository-ruleset-providers.ts), the composed `GitHub.providers()` +
+ *   `RepositoryRulesetProvider()` layer that actually typechecks (2026-09-24: writing the two
+ *   side by side leaves `RepositoryRulesetProvider()`'s own `GitHubCredentials` requirement
+ *   unfed). Before 2026-09-23 this subpath shipped no provider at all, composing only vendor
+ *   resources; `RepositoryRuleset` is the one exception, and repository-ruleset.ts's header
+ *   says why upstream's own `Ruleset` cannot fill the gap.
  * ★ WHY THE POLICY HELPERS EXIST. "Open a pull request, let auto-merge land it" is safe only
  *   when five repository properties and four ruleset rules all agree, and every way of getting
  *   one of them wrong is silent — an auto-merge that lands on red, a force push that rewrites
@@ -42,6 +45,7 @@ export {
   type RepositoryRulesetRules,
   type RepositoryRulesetStatusChecksRule,
 } from './repository-ruleset.ts';
+export { repoPolicyProviders } from './repository-ruleset-providers.ts';
 export { RULE_TYPE_COVERAGE, type RepositoryRuleType } from './repository-ruleset-constraints.ts';
 export {
   BypassActorNarrowed,

package/src/github/repo-baseline-data.test.ts

@@ -36,6 +36,19 @@ describe('repoBaselineSettings', () => {
       visibility: undefined,
     });
   });
+
+  // K5 (2026-09-24): zero required checks means `gh pr merge --auto` has nothing to wait for —
+  // GitHub merges a CLEAN pull request immediately, with no review and no green run. Regression
+  // for repoBaselineSettings hardcoding `allowAutoMerge: true` regardless of `checks`.
+  test('zero checks turns auto-merge off — nothing would ever hold a merge back', () => {
+    const settings = repoBaselineSettings({ ...input, checks: [] });
+    expect(settings.allowAutoMerge).toBe(false);
+  });
+
+  test('at least one check keeps auto-merge on', () => {
+    const settings = repoBaselineSettings({ ...input, checks: ['ci'] });
+    expect(settings.allowAutoMerge).toBe(true);
+  });
 });
 
 describe('repoBaselineRuleset', () => {

package/src/github/repo-baseline-data.ts

@@ -21,7 +21,16 @@ export interface RepoBaselineInput {
 
 /** `GitHub.Repository` fields this baseline owns. Every merge-automation caller across the 17
  * tray checkouts uses `--squash` (measured 2026-09-23; the only non-squash mentions are
- * GitLab-era comments in cliff.toml), so squash-only is not a per-repo choice. */
+ * GitLab-era comments in cliff.toml), so squash-only is not a per-repo choice.
+ *
+ * ⛔ K5 (2026-09-24): `allowAutoMerge` FOLLOWS `checks.length`, NOT A HARDCODED `true`. `gh pr
+ *   merge --auto` (and the ruleset's own auto-merge) is a queue only while something is
+ *   outstanding — with zero required status checks there is nothing to wait for, so GitHub
+ *   merges a CLEAN pull request on the spot, with no review and no green run. This is the same
+ *   failure `repo-policy-guards.ts`'s `assertAutoMergeWaits` refuses on the sibling `repoPolicy`
+ *   path (five doors to the same "nothing outstanding" state); this baseline has no `autoMerge`
+ *   opt-out prop to refuse WITH, so the fix here is unconditional rather than a thrown refusal —
+ *   a repo with an empty `checks` list simply never gets auto-merge turned on by this baseline. */
 export function repoBaselineSettings(input: RepoBaselineInput) {
   return {
     owner: input.owner,
@@ -31,7 +40,7 @@ export function repoBaselineSettings(input: RepoBaselineInput) {
     allowSquashMerge: true,
     allowMergeCommit: false,
     allowRebaseMerge: false,
-    allowAutoMerge: true,
+    allowAutoMerge: input.checks.length > 0,
     deleteBranchOnMerge: true,
     hasWiki: false,
   };

package/src/github/repo-policy-stack.test.ts

@@ -0,0 +1,59 @@
+/**
+ * TYPE-LEVEL test — a real `Alchemy.Stack(...)` whose body calls `declareRepoPolicy` AND
+ * `declareRepoBaseline`, wired with the documented `repoPolicyProviders()`. This is the test
+ * that would have caught 2026-09-24's bug (homeflare-builds bump PR 6, tsc TS2345):
+ * `RepositoryRuleset`'s `Resource<>` declaration put `GitHubCredentials` — not
+ * `Provider<RepositoryRuleset>` — in its 5th type parameter, so a stack BODY that only ever
+ * calls `declareRepoPolicy`/`declareRepoBaseline` failed `tsc`, and nothing in this repo's own
+ * `bun run check` exercised that path before now: every existing test in this family drives the
+ * resource's CRUD handlers directly (repository-ruleset-*.test.ts) or the pure form functions
+ * (repo-policy-form.test.ts), never a real `Alchemy.Stack(...)` body.
+ *
+ * ⚠️ BUILT, NEVER RUN. `Alchemy.Stack(...)` returns an unexecuted `Effect` — every combinator
+ *   between here and a runtime (`.pipe`, `Effect.gen`, `Effect.flatMap`, `Object.assign`) is
+ *   itself lazy (MEASURED by reading `alchemy/src/Stack.ts`'s own `Stack`/`make`: no
+ *   `Effect.runSync`/`runPromise` anywhere in the construction path). Building the value is
+ *   enough to make `tsc` check the body's inferred requirement type against `Stack`'s own
+ *   `Req extends StackServices | ProviderServices` constraint — see repository-ruleset.ts's
+ *   file header for what that constraint is and why `GitHubCredentials` used to fail it. This
+ *   test never calls `Effect.runPromise`/`runSync`: no network, no `GitHubCredentials`
+ *   resolved, no state written.
+ *
+ * ⚠️ `.pipe(Effect.orDie)` ON `declareRepoPolicy` IS UNRELATED TO WHAT THIS TEST CHECKS.
+ *   `declareRepoPolicy` refuses a bad policy through `Effect.try`'s `catch`, so its error
+ *   channel is `Error`, not `never` — a separate, pre-existing type surface (present since its
+ *   original PR #98) that `Alchemy.Stack`'s own `eff: Effect.Effect<A, ConfigError, Req>` does
+ *   not accept regardless of the `Req`/`Providers` bug this test targets. Dying on it here keeps
+ *   that surface out of the way without papering over it — a real caller still has to decide how
+ *   to handle a refused policy, which this test deliberately does not answer.
+ */
+import { expect, test } from 'bun:test';
+import * as Alchemy from 'alchemy';
+import * as Effect from 'effect/Effect';
+import { declareRepoBaseline } from './declare-repo-baseline.ts';
+import { declareRepoPolicy } from './repo-policy.ts';
+import { repoPolicyProviders } from './repository-ruleset-providers.ts';
+
+test('declareRepoPolicy and declareRepoBaseline typecheck as one Alchemy.Stack body', () => {
+  const stack = Alchemy.Stack(
+    'repo-policy-typecheck',
+    { providers: repoPolicyProviders(), state: Alchemy.inMemoryState() },
+    Effect.gen(function* () {
+      const policy = yield* declareRepoPolicy('api', {
+        owner: 'taslabs-net',
+        repository: 'api',
+        checks: ['ci', 'secret scan'],
+      }).pipe(Effect.orDie);
+      const baseline = yield* declareRepoBaseline('widgets', {
+        owner: 'taslabs-net',
+        repository: 'widgets',
+        checks: ['ci'],
+        visibility: 'private',
+      });
+      return { policy, baseline };
+    }),
+  );
+  // Not run — see file header. This only proves construction didn't throw synchronously; the
+  // real assertion is `tsc`'s, over the whole expression above.
+  expect(stack).toBeDefined();
+});

package/src/github/repo-policy.ts

@@ -7,8 +7,9 @@
  *       checks: ['ci', 'secret scan'],
  *     });
  *
- * Provide `GitHub.providers()` AND `RepositoryRulesetProvider()`; this subpath adds no GitHub
- * provider of its own.
+ * Provide `repoPolicyProviders()` (repository-ruleset-providers.ts) — the composed
+ * `GitHub.providers()` + `RepositoryRulesetProvider()` layer; this subpath adds no GitHub
+ * provider of its own beyond the ruleset bridge.
  *
  * ★ REWIRED 2026-09-23 onto `GitHub.RepositoryRuleset`, not upstream `GitHub.Ruleset` — the
  *   ADOPT-SAFE bridge documented in repository-ruleset.ts. Only `builds` calls this, and its

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

@@ -123,8 +123,9 @@ export class RequiredChecksOmitted extends Data.TaggedError('RequiredChecksOmitt
   }
 }
 
-/** A context being ADDED to `requiredStatusChecks` has never reported success on the default
- * branch. Requiring it would leave every future pull request pending forever. */
+/** A context being ADDED to `requiredStatusChecks` has never reported success anywhere this
+ * family looks (the default branch's tip, then recent merged PR heads — K2, bounded, not full
+ * history). Requiring it would leave every future pull request pending forever. */
 export class NeverReportedContext extends Data.TaggedError('NeverReportedContext')<{
   readonly owner: string;
   readonly repository: string;
@@ -133,8 +134,9 @@ export class NeverReportedContext extends Data.TaggedError('NeverReportedContext
   override get message(): string {
     return (
       `GitHub.RepositoryRuleset: "${this.context}" has never reported success on ` +
-      `${this.owner}/${this.repository}'s default branch. Requiring it now would leave every ` +
-      'pull request waiting on a check that has never once reported — refused before any write.'
+      `${this.owner}/${this.repository}'s default branch tip or any of its recent merged pull ` +
+      'requests. Requiring it now would leave every pull request waiting on a check that has ' +
+      'never once reported — refused before any write.'
     );
   }
 }

package/src/github/repository-ruleset-exact-adopt-k1.test.ts

@@ -0,0 +1,109 @@
+/**
+ * K1 (2026-09-23): `extraApprovalForUnattributedChanges` now declares `true`, not only `false`
+ * — split out of repository-ruleset-exact-adopt.test.ts purely to keep that file under the
+ * 250-line cap, not because the case is unrelated: this is the exact gap that file's own header
+ * named as blocking a true zero-write adopt for aop/magictransit/loggarr/
+ * doesthishelp-workeropen (all four carry `require_extra_approval_for_unattributed_changes:
+ * true` live).
+ *
+ * `gh api repos/taslabs-net/aop/rulesets/14572279`, re-read 2026-09-23 for this PR — the FULL
+ * record (not H15's own caution about paraphrasing was heeded the hard way: an earlier revision
+ * of this fixture hand-typed only the fields the design doc had quoted, which omitted
+ * `dismiss_stale_reviews_on_push: true` and `required_reviewers: []` — both of which
+ * `buildPullRequestRule` always sends, so a fixture missing them can never truly noop; the "zero
+ * writes" assertion below caught it): `bypass_actors: [{actor_id: 5, actor_type:
+ * "RepositoryRole", bypass_mode: "always"}]`, `rules: [deletion, non_fast_forward, pull_request]`,
+ * and the full `pull_request` parameters are `required_approving_review_count: 0`,
+ * `dismiss_stale_reviews_on_push: true`, `required_reviewers: []`, `require_code_owner_review:
+ * false`, `require_last_push_approval: false`, `required_review_thread_resolution: false`,
+ * `require_extra_approval_for_unattributed_changes: true`,
+ * `allowed_merge_methods: [merge, squash, rebase]`.
+ */
+import { describe, expect, test } from 'bun:test';
+import { makeRecordingFake } from './repository-ruleset-fake-octokit.ts';
+import {
+  BASE_PULL_REQUEST,
+  props,
+  reconcileWithOctokit,
+  run,
+} from './repository-ruleset-test-helpers.ts';
+
+const AOP_LIVE = {
+  id: 14572279,
+  name: 'main',
+  target: 'branch',
+  enforcement: 'active',
+  bypass_actors: [{ actor_id: 5, actor_type: 'RepositoryRole', bypass_mode: 'always' }],
+  conditions: { ref_name: { include: ['~DEFAULT_BRANCH'], exclude: [] } },
+  rules: [
+    { type: 'deletion' },
+    { type: 'non_fast_forward' },
+    {
+      type: 'pull_request',
+      parameters: {
+        required_approving_review_count: 0,
+        dismiss_stale_reviews_on_push: true,
+        required_reviewers: [],
+        require_code_owner_review: false,
+        require_last_push_approval: false,
+        required_review_thread_resolution: false,
+        require_extra_approval_for_unattributed_changes: true,
+        allowed_merge_methods: ['merge', 'squash', 'rebase'],
+      },
+    },
+  ],
+};
+
+describe('K1: extraApprovalForUnattributedChanges completes exact-adopt', () => {
+  // Unlike repository-ruleset-exact-adopt.test.ts's bypass-only fixture (which deliberately
+  // keeps `BASE_PULL_REQUEST`'s `false`/`[squash]` to prove bypass round-trips on its own), this
+  // declares aop's FULL live `pull_request` shape — methods AND the extra-approval flag — so
+  // the whole ruleset, not just `bypassActors`, is now a genuine zero-write adopt.
+  test('aop: full live shape, extra-approval flag included, makes zero writes', async () => {
+    const fake = makeRecordingFake({ aop: AOP_LIVE });
+    const declaration = props({
+      repository: 'aop',
+      bypassActors: [{ actorType: 'RepositoryRole', actorId: 5, bypassMode: 'always' }],
+      rules: {
+        deletion: true,
+        nonFastForward: true,
+        pullRequest: {
+          ...BASE_PULL_REQUEST,
+          dismissStaleReviewsOnPush: true,
+          allowedMergeMethods: ['merge', 'squash', 'rebase'],
+          extraApprovalForUnattributedChanges: true,
+        },
+      },
+    });
+    await run(reconcileWithOctokit(fake.octokit, declaration, { rulesetId: 14572279 }));
+    expect(fake.writes).toHaveLength(0);
+  });
+
+  // The counterpart failure mode: declaring `false` against a live `true` is real drift (not a
+  // narrowing/widening question — that guard family is about `bypassActors` and rule presence,
+  // not this field's value) and must still produce exactly one `update`, never a silent noop.
+  test('aop: declaring false against a live true is drift, not a noop', async () => {
+    const fake = makeRecordingFake({ aop: AOP_LIVE });
+    const declaration = props({
+      repository: 'aop',
+      bypassActors: [{ actorType: 'RepositoryRole', actorId: 5, bypassMode: 'always' }],
+      rules: {
+        deletion: true,
+        nonFastForward: true,
+        pullRequest: {
+          ...BASE_PULL_REQUEST,
+          dismissStaleReviewsOnPush: true,
+          allowedMergeMethods: ['merge', 'squash', 'rebase'],
+          extraApprovalForUnattributedChanges: false,
+        },
+      },
+    });
+    await run(reconcileWithOctokit(fake.octokit, declaration, { rulesetId: 14572279 }));
+    expect(fake.writes).toHaveLength(1);
+    const pr = fake.writes[0]?.body?.rules?.find((r) => r.type === 'pull_request');
+    expect(
+      (pr as { parameters: Record<string, unknown> } | undefined)?.parameters
+        .require_extra_approval_for_unattributed_changes,
+    ).toBe(false);
+  });
+});

package/src/github/repository-ruleset-exact-adopt.test.ts

@@ -14,15 +14,20 @@
  *   Integration 29110 is `always`, not the reverse) — see repository-ruleset-narrowing-guards.ts
  *   for the guard these fixtures exercise.
  *
- * `taslabs-net` is the only one of the 5 whose FULL ruleset (bypass AND rules) is provable as a
- * true zero-write adopt today: its live `pull_request` rules (aop/magictransit/loggarr/
- * doesthishelp-workeropen) all carry `require_extra_approval_for_unattributed_changes: true`,
- * which this resource cannot yet declare (K1 — a separate, later PR; H15's comment on
- * `extraApprovalForUnattributedChanges` explains why only `false` is modeled today). The other
- * 4 fixtures below prove the narrower claim K1 does not gate: that this resource's `bypassActors`
- * round-trips an arbitrary `actor_id`/`actor_type`/`bypass_mode` combination — single-actor by
- * role, single-actor by integration, and multi-actor with mixed modes — onto the wire exactly as
- * declared, with neither `BypassActorWidened` nor `BypassActorNarrowed` firing on a match.
+ * ★ K1 LANDED 2026-09-23: `extraApprovalForUnattributedChanges` now declares `true`, not only
+ *   `false` — the gap this file's earlier revision named as blocking a true zero-write adopt for
+ *   aop/magictransit/loggarr/doesthishelp-workeropen (all four carry
+ *   `require_extra_approval_for_unattributed_changes: true` live). The 4 fixtures below still
+ *   prove the narrower claim: that `bypassActors` round-trips an arbitrary
+ *   `actor_id`/`actor_type`/`bypass_mode` combination — single-actor by role, single-actor by
+ *   integration, and multi-actor with mixed modes — onto the wire exactly as declared, with
+ *   neither `BypassActorWidened` nor `BypassActorNarrowed` firing on a match; their declarations
+ *   still use `BASE_PULL_REQUEST` (`extraApprovalForUnattributedChanges: false`), so each is
+ *   still a genuine `update`, not a noop — that keeps this file's original point (bypass alone
+ *   round-trips) legible on its own. The case K1 unblocks — `aop`'s FULL live shape, extra-
+ *   approval flag included, as a true zero-write adopt — is proven in
+ *   repository-ruleset-exact-adopt-k1.test.ts, split out purely to keep this file under the
+ *   250-line cap.
  */
 import { describe, expect, test } from 'bun:test';
 import { makeGetOnlyFake, makeRecordingFake } from './repository-ruleset-fake-octokit.ts';

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

@@ -50,11 +50,15 @@ function buildPullRequestRule(rule: RepositoryRulesetPullRequestRule): WireRule
         minimum_approvals: r.minimumApprovals,
         reviewer: { id: r.reviewer.actorId, type: r.reviewer.actorType },
       })),
-      // ⛔ Only ever sent as `false` (H15) — see repository-ruleset.ts for why this exists at
-      //   all and repository-ruleset-wire.test.ts for whether Octokit forwards it untyped.
+      // Sent as declared, `true` or `false` (K1, 2026-09-23) — see repository-ruleset.ts's H15
+      // for why this field exists here at all (Octokit, not distilled) and
+      // repository-ruleset-wire.test.ts for whether Octokit forwards it untyped for both values.
       ...(rule.extraApprovalForUnattributedChanges === undefined
         ? {}
-        : { require_extra_approval_for_unattributed_changes: false }),
+        : {
+            require_extra_approval_for_unattributed_changes:
+              rule.extraApprovalForUnattributedChanges,
+          }),
     },
     // The extension field above has no home in Octokit's own rule union (H15) — the cast is
     // the only place that gap is bridged.

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

@@ -182,8 +182,9 @@ export const newlyRequiredContexts = (
     .filter((c) => !liveContexts.has(c));
 };
 
-/** Fails on the first newly-required context that has never reported success on the default
- * branch — checked once here (reconcile's observe step) and again by the standalone checker. */
+/** Fails on the first newly-required context that has never reported success anywhere this
+ * family looks (the default branch's tip, then recent merged PR heads — K2) — checked once here
+ * (reconcile's observe step) and again by the standalone checker. */
 export const refuseUnreportedContexts = <R = never>(
   octokit: RulesetOctokit<R>,
   owner: string,

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

@@ -0,0 +1,141 @@
+/**
+ * K2 (2026-09-24): MEASURES `contextReportedSuccess` (repository-ruleset-octokit.ts) against a
+ * real `@octokit/rest` instance with a fetch shim (no network) — the same pattern
+ * repository-ruleset-wire.test.ts uses for H15, applied here to the "which ref did we check"
+ * question instead of "did the wire field survive". The shim routes by URL path, not by call
+ * order, so these tests exercise the SAME sequencing the real implementation performs: default
+ * branch tip first, then (only if the tip has nothing) recent merged PR heads, bounded.
+ *
+ * Both sides the guard exists to hold: accept a context that reports only on a recent merged PR
+ * head (the case K2 fixes — CI runs on `pull_request` only, never the tip), and still refuse one
+ * that reports nowhere, tip or any recent merged head, INCLUDING one whose only success is
+ * older than `RECENT_MERGED_PR_LIMIT` merges ago (the bound is real, not decorative).
+ */
+import { describe, expect, test } from 'bun:test';
+import { Octokit } from '@octokit/rest';
+import * as Effect from 'effect/Effect';
+import { RECENT_MERGED_PR_LIMIT, contextReportedSuccess } from './repository-ruleset-octokit.ts';
+
+interface CheckRun {
+  readonly name: string;
+  readonly conclusion: string | null;
+}
+interface Status {
+  readonly context: string;
+  readonly state: string;
+}
+interface MergedPull {
+  readonly merged_at: string | null;
+  readonly head: { readonly sha: string };
+}
+
+interface Fixture {
+  readonly defaultBranch: string;
+  readonly checkRuns?: Readonly<Record<string, readonly CheckRun[]>>;
+  readonly statuses?: Readonly<Record<string, readonly Status[]>>;
+  /** Already in the order GitHub's `sort: updated, direction: desc` would return — most
+   * recently updated first. */
+  readonly closedPulls?: readonly MergedPull[];
+}
+
+/** Routes by URL path, not call order — GET .../pulls, GET .../commits/{ref}/check-runs, GET
+ * .../commits/{ref}/statuses, else the bare repo GET (`default_branch`). `captured` records
+ * every URL so a test can assert a ref was — or, for boundedness, was NEVER — looked up. */
+function makeServingFetch(fx: Fixture, captured: string[]): typeof fetch {
+  const respond = (body: unknown) =>
+    new Response(JSON.stringify(body), {
+      status: 200,
+      headers: { 'content-type': 'application/json' },
+    });
+  return (async (input: Parameters<typeof fetch>[0]) => {
+    const url = String(input);
+    captured.push(url);
+    if (/\/pulls(\?|$)/.test(url)) return respond(fx.closedPulls ?? []);
+    const commits = /\/commits\/([^/?]+)\/(check-runs|statuses)/.exec(url);
+    if (commits) {
+      const [, ref, kind] = commits;
+      if (kind === 'check-runs') {
+        const runs = fx.checkRuns?.[ref as string] ?? [];
+        return respond({ total_count: runs.length, check_runs: runs });
+      }
+      return respond(fx.statuses?.[ref as string] ?? []);
+    }
+    return respond({ default_branch: fx.defaultBranch });
+  }) as typeof fetch;
+}
+
+const octokitOver = (fx: Fixture, captured: string[] = []) =>
+  new Octokit({
+    auth: 'fake-token-not-a-real-credential',
+    request: { fetch: makeServingFetch(fx, captured) },
+  });
+
+const run = (eff: Effect.Effect<boolean, Error>): Promise<boolean> => Effect.runPromise(eff);
+
+describe('contextReportedSuccess', () => {
+  test('accepts a context that reports only on a recent merged PR head, not the tip', async () => {
+    const octokit = octokitOver({
+      defaultBranch: 'main',
+      checkRuns: { sha2: [{ name: 'ci', conclusion: 'success' }] },
+      closedPulls: [
+        { merged_at: '2026-09-20T00:00:00Z', head: { sha: 'sha3' } },
+        { merged_at: '2026-09-19T00:00:00Z', head: { sha: 'sha2' } },
+        { merged_at: '2026-09-18T00:00:00Z', head: { sha: 'sha1' } },
+      ],
+    });
+    const reported = await run(
+      contextReportedSuccess(octokit, 'taslabs-net', 'homeflare-builds', 'ci'),
+    );
+    expect(reported).toBe(true);
+  });
+
+  test('refuses a context that reports nowhere — tip or any recent merged head', async () => {
+    const octokit = octokitOver({
+      defaultBranch: 'main',
+      closedPulls: [
+        { merged_at: '2026-09-20T00:00:00Z', head: { sha: 'sha3' } },
+        { merged_at: '2026-09-19T00:00:00Z', head: { sha: 'sha2' } },
+      ],
+    });
+    const reported = await run(
+      contextReportedSuccess(octokit, 'taslabs-net', 'homeflare-builds', 'ci'),
+    );
+    expect(reported).toBe(false);
+  });
+
+  test('a success older than RECENT_MERGED_PR_LIMIT merges ago is still refused — the bound is real', async () => {
+    // RECENT_MERGED_PR_LIMIT (10) merged PRs report nothing; only the 11th (oldest returned,
+    // outside the bound) reports `ci` — proves the function stops at the limit rather than
+    // scanning everything the list call happened to return.
+    const closedPulls: MergedPull[] = Array.from({ length: RECENT_MERGED_PR_LIMIT }, (_, i) => ({
+      merged_at: `2026-09-${String(20 - i)}T00:00:00Z`,
+      head: { sha: `within-bound-${String(i)}` },
+    }));
+    closedPulls.push({ merged_at: '2026-08-01T00:00:00Z', head: { sha: 'beyond-bound' } });
+    const captured: string[] = [];
+    const octokit = octokitOver(
+      {
+        defaultBranch: 'main',
+        checkRuns: { 'beyond-bound': [{ name: 'ci', conclusion: 'success' }] },
+        closedPulls,
+      },
+      captured,
+    );
+    const reported = await run(
+      contextReportedSuccess(octokit, 'taslabs-net', 'homeflare-builds', 'ci'),
+    );
+    expect(reported).toBe(false);
+    expect(captured.some((url) => url.includes('/commits/beyond-bound/'))).toBe(false);
+  });
+
+  test('the default branch tip alone is still enough — no fallback needed', async () => {
+    const octokit = octokitOver({
+      defaultBranch: 'main',
+      statuses: { main: [{ context: 'secret scan', state: 'success' }] },
+    });
+    const reported = await run(
+      contextReportedSuccess(octokit, 'taslabs-net', 'homeflare-kit', 'secret scan'),
+    );
+    expect(reported).toBe(true);
+  });
+});