@homeflare/alchemy 0.27.4 → 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,13 +45,16 @@ 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,
   BypassActorWidened,
   DuplicateRuleset,
   NeverReportedContext,
   ReadbackMismatch,
   RequiredChecksOmitted,
+  RuleNarrowed,
   RulesetConstraintRefused,
   UndeclaredLiveRule,
   type RepositoryRulesetError,

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

@@ -43,6 +43,49 @@ export class BypassActorWidened extends Data.TaggedError('BypassActorWidened')<{
   }
 }
 
+/** A declared `bypassActors` drops an actor the live ruleset has, with no
+ * `acknowledgeBypassNarrowing` on the declaration. Unlike widening, narrowing is not always
+ * wrong — an exact-adopt declaration that matches live exactly narrows nothing — so this is
+ * refused only when live genuinely has more than the declaration keeps, and it is escapable
+ * (`BypassActorWidened` is not): see `bypassNarrowingRefusal` in
+ * repository-ruleset-narrowing-guards.ts. */
+export class BypassActorNarrowed extends Data.TaggedError('BypassActorNarrowed')<{
+  readonly owner: string;
+  readonly repository: string;
+  readonly name: string;
+  readonly narrowed: readonly string[];
+}> {
+  override get message(): string {
+    return (
+      `GitHub.RepositoryRuleset "${this.name}" on ${this.owner}/${this.repository}: the ` +
+      `declaration drops a bypass actor the live ruleset has (${this.narrowed.join(', ')}), and ` +
+      'the declaration carries no `acknowledgeBypassNarrowing`. Add one with a reason once the ' +
+      'removal is deliberate, or restore the actor to match live.'
+    );
+  }
+}
+
+/** A rule type the declaration explicitly marks absent (`false`) while the live ruleset still
+ * has it, with no `acknowledgeRuleNarrowing` on the declaration — see `ruleNarrowingRefusal` in
+ * repository-ruleset-narrowing-guards.ts. Distinct from `UndeclaredLiveRule`: that one fires on
+ * SILENCE (the declaration says nothing); this one fires on an EXPLICIT, but unacknowledged,
+ * removal. */
+export class RuleNarrowed extends Data.TaggedError('RuleNarrowed')<{
+  readonly owner: string;
+  readonly repository: string;
+  readonly name: string;
+  readonly ruleType: string;
+}> {
+  override get message(): string {
+    return (
+      `GitHub.RepositoryRuleset "${this.name}" on ${this.owner}/${this.repository}: the ` +
+      `declaration drops a live "${this.ruleType}" rule, and carries no ` +
+      '`acknowledgeRuleNarrowing`. Add one with a reason once the removal is deliberate, or ' +
+      'declare the rule to match live.'
+    );
+  }
+}
+
 /** A live rule's `type` is neither modeled nor explicitly refused by RULE_TYPE_COVERAGE, or is
  * refused and present live anyway. The PUT replaces `rules` wholesale, so silently omitting a
  * live rule type would drop it — this fails the plan by name instead. */
@@ -80,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;
@@ -90,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.'
     );
   }
 }
@@ -129,7 +174,9 @@ export class ReadbackMismatch extends Data.TaggedError('ReadbackMismatch')<{
 export type RepositoryRulesetError =
   | DuplicateRuleset
   | BypassActorWidened
+  | BypassActorNarrowed
   | UndeclaredLiveRule
+  | RuleNarrowed
   | RequiredChecksOmitted
   | NeverReportedContext
   | RulesetConstraintRefused

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

@@ -0,0 +1,184 @@
+/**
+ * Exact-adopt pass-through, proven against the 5 live rulesets the red team found this resource
+ * could not express before 2026-09-23 (design critique, "strongest_failure": `repoBaselineRuleset()`
+ * hardcodes `bypassActors: []` and an unconditional `pullRequest` rule; every one of these 5
+ * repos' live ruleset has a non-empty `bypass_actors`, and one — `taslabs-net/taslabs-net` — has
+ * no live `pull_request` rule at all). This file proves the underlying `RepositoryRuleset`
+ * resource (not the convenience `repoBaselineRuleset()`, which intentionally keeps its baseline
+ * defaults — see repo-baseline-data.ts) can express all 5 shapes, and that declaring one exactly
+ * is never treated as narrowing.
+ *
+ * ⚠️ RE-READ LIVE 2026-09-23 via `gh api repos/taslabs-net/<repo>/rulesets/<id>`, not copied
+ *   from the design doc's own paraphrase — `bypass_mode` differs from the design critique's
+ *   prose for `doesthishelp-workeropen` (measured: RepositoryRole 5 is `pull_request` mode and
+ *   Integration 29110 is `always`, not the reverse) — see repository-ruleset-narrowing-guards.ts
+ *   for the guard these fixtures exercise.
+ *
+ * ★ 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';
+import {
+  BASE_PULL_REQUEST,
+  props,
+  reconcileWithOctokit,
+  run,
+} from './repository-ruleset-test-helpers.ts';
+
+describe('exact-adopt pass-through — live shapes measured 2026-09-23', () => {
+  // The critical case: a non-empty bypass_actors AND an absent pull_request rule, both at once.
+  // `gh api repos/taslabs-net/taslabs-net/rulesets/12206080`.
+  test('taslabs-net/taslabs-net: non-empty bypass, no pull_request rule — zero-write adopt', async () => {
+    const live = {
+      id: 12206080,
+      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' }],
+    };
+    const fake = makeGetOnlyFake({ 'taslabs-net': live });
+    const declaration = props({
+      repository: 'taslabs-net',
+      bypassActors: [{ actorType: 'RepositoryRole', actorId: 5, bypassMode: 'always' }],
+      rules: { deletion: true, nonFastForward: true },
+    });
+    const attrs = await run(reconcileWithOctokit(fake, declaration, { rulesetId: 12206080 }));
+    expect(attrs.rulesetId).toBe(12206080);
+  });
+
+  // `gh api repos/taslabs-net/aop/rulesets/14572279` — single RepositoryRole actor, mode
+  // "always". Live `pull_request` also carries the K1 flag, so the write below is an `update`,
+  // not a noop — the point here is that `bypassActors` alone sends back exactly what was
+  // declared, and neither narrowing nor widening guard fires on a matching bypass list.
+  test('aop: single RepositoryRole actor round-trips exactly', async () => {
+    const 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 } },
+      ],
+    };
+    const fake = makeRecordingFake({ aop: live });
+    const declaration = props({
+      repository: 'aop',
+      bypassActors: [{ actorType: 'RepositoryRole', actorId: 5, bypassMode: 'always' }],
+      rules: { deletion: true, nonFastForward: true, pullRequest: BASE_PULL_REQUEST },
+    });
+    await run(reconcileWithOctokit(fake.octokit, declaration, { rulesetId: 14572279 }));
+    expect(fake.writes[0]?.body?.bypass_actors).toEqual([
+      { actor_id: 5, actor_type: 'RepositoryRole', bypass_mode: 'always' },
+    ]);
+  });
+
+  // `gh api repos/taslabs-net/loggarr/rulesets/12323114` — a single Integration (Dependabot)
+  // actor with `bypass_mode: "pull_request"`, not `"always"`.
+  test('loggarr: single Integration actor, pull_request bypass mode, round-trips exactly', async () => {
+    const live = {
+      id: 12323114,
+      name: 'main',
+      target: 'branch',
+      enforcement: 'active',
+      bypass_actors: [{ actor_id: 29110, actor_type: 'Integration', bypass_mode: 'pull_request' }],
+      conditions: { ref_name: { include: ['~DEFAULT_BRANCH'], exclude: [] } },
+      rules: [
+        { type: 'deletion' },
+        { type: 'non_fast_forward' },
+        { type: 'pull_request', parameters: { required_approving_review_count: 0 } },
+      ],
+    };
+    const fake = makeRecordingFake({ loggarr: live });
+    const declaration = props({
+      repository: 'loggarr',
+      bypassActors: [{ actorType: 'Integration', actorId: 29110, bypassMode: 'pull_request' }],
+      rules: { deletion: true, nonFastForward: true, pullRequest: BASE_PULL_REQUEST },
+    });
+    await run(reconcileWithOctokit(fake.octokit, declaration, { rulesetId: 12323114 }));
+    expect(fake.writes[0]?.body?.bypass_actors).toEqual([
+      { actor_id: 29110, actor_type: 'Integration', bypass_mode: 'pull_request' },
+    ]);
+  });
+
+  // `gh api repos/taslabs-net/doesthishelp-workeropen/rulesets/12504824` — TWO actors with
+  // DIFFERENT modes each (the design critique's own "(both)" shorthand for this repo).
+  test('doesthishelp-workeropen: two actors, mixed bypass modes, round-trip exactly', async () => {
+    const live = {
+      id: 12504824,
+      name: 'main',
+      target: 'branch',
+      enforcement: 'active',
+      bypass_actors: [
+        { actor_id: 5, actor_type: 'RepositoryRole', bypass_mode: 'pull_request' },
+        { actor_id: 29110, actor_type: 'Integration', 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 } },
+      ],
+    };
+    const fake = makeRecordingFake({ 'doesthishelp-workeropen': live });
+    const declaration = props({
+      repository: 'doesthishelp-workeropen',
+      bypassActors: [
+        { actorType: 'RepositoryRole', actorId: 5, bypassMode: 'pull_request' },
+        { actorType: 'Integration', actorId: 29110, bypassMode: 'always' },
+      ],
+      rules: { deletion: true, nonFastForward: true, pullRequest: BASE_PULL_REQUEST },
+    });
+    await run(reconcileWithOctokit(fake.octokit, declaration, { rulesetId: 12504824 }));
+    expect(fake.writes[0]?.body?.bypass_actors).toEqual([
+      { actor_id: 5, actor_type: 'RepositoryRole', bypass_mode: 'pull_request' },
+      { actor_id: 29110, actor_type: 'Integration', bypass_mode: 'always' },
+    ]);
+  });
+
+  // `gh api repos/taslabs-net/magictransit/rulesets/10470003` — same single-actor shape as
+  // `aop`, kept as its own case because it is one of the 5 the design's own census named.
+  test('magictransit: single RepositoryRole actor round-trips exactly', async () => {
+    const live = {
+      id: 10470003,
+      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 } },
+      ],
+    };
+    const fake = makeRecordingFake({ magictransit: live });
+    const declaration = props({
+      repository: 'magictransit',
+      bypassActors: [{ actorType: 'RepositoryRole', actorId: 5, bypassMode: 'always' }],
+      rules: { deletion: true, nonFastForward: true, pullRequest: BASE_PULL_REQUEST },
+    });
+    await run(reconcileWithOctokit(fake.octokit, declaration, { rulesetId: 10470003 }));
+    expect(fake.writes[0]?.body?.bypass_actors).toEqual([
+      { actor_id: 5, actor_type: 'RepositoryRole', bypass_mode: 'always' },
+    ]);
+  });
+});

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

@@ -14,7 +14,10 @@ import {
 } from './repository-ruleset-errors.ts';
 import type { RulesetOctokit, RulesetRecord } from './repository-ruleset-probe.ts';
 
-const bypassKey = (a: { actor_type: unknown; actor_id: unknown; bypass_mode?: unknown }) =>
+/** Exported: repository-ruleset-narrowing-guards.ts reuses the identical key so a widened and a
+ * narrowed actor are never computed by two independently-drifting definitions of "the same
+ * actor". */
+export const bypassKey = (a: { actor_type: unknown; actor_id: unknown; bypass_mode?: unknown }) =>
   `${String(a.actor_type)}:${String(a.actor_id ?? '')}:${String(a.bypass_mode ?? 'always')}`;
 
 /**
@@ -56,7 +59,10 @@ export function bypassWideningRefusal(input: {
   });
 }
 
-const liveRuleTypes = (live: RulesetRecord | undefined): Set<string> =>
+/** Exported for the same reason as `bypassKey` — repository-ruleset-narrowing-guards.ts's
+ * `ruleNarrowingRefusal` needs the identical live-type set `undeclaredLiveRuleRefusal` computes,
+ * not a second reading of `live.rules` that could disagree with this one. */
+export const liveRuleTypes = (live: RulesetRecord | undefined): Set<string> =>
   new Set((live?.rules ?? []).map((r) => String(r.type)));
 
 /**
@@ -176,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,