@homeflare/alchemy 0.27.3 → 0.28.0

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. */
@@ -129,7 +172,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.test.ts

@@ -0,0 +1,179 @@
+/**
+ * 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.
+ *
+ * `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.
+ */
+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-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)));
 
 /**

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

@@ -0,0 +1,141 @@
+/**
+ * Narrowing refusals — the counterpart to `bypassWideningRefusal`/`undeclaredLiveRuleRefusal` in
+ * repository-ruleset-guards.ts, split into its own file purely to keep both under the 250-line
+ * cap (same reason repository-ruleset-props.ts exists).
+ *
+ * ⛔ WIDENING STAYS UNCONDITIONAL; NARROWING GETS AN ESCAPE HATCH. Widening bypass (granting a
+ *   NEW actor) has no legitimate reason to happen through a deploy — "grant it by hand and adopt
+ *   the change" (repository-ruleset-errors.ts's `BypassActorWidened` message) already covers it,
+ *   and this file does not touch that guard. NARROWING (removing a live bypass actor, or
+ *   dropping a live rule) is different: it is exactly what an EXACT-ADOPT declaration of a repo
+ *   whose live ruleset is narrower than the house baseline needs to express on its very first
+ *   deploy — a caller declaring `taslabs-net/taslabs-net`'s live shape (measured live via `gh
+ *   api repos/taslabs-net/taslabs-net/rulesets/12206080`, 2026-09-23: `bypass_actors:
+ *   [{actor_id: 5, actor_type: "RepositoryRole", bypass_mode: "always"}]`, `rules: [deletion,
+ *   non_fast_forward]`, no `pull_request` rule) is not narrowing anything by declaring exactly
+ *   that shape — it is matching live exactly, and `reconcileRuleset`'s own noop check (comparing
+ *   canonicalized wire forms) makes zero writes for it, same as any other exact match. What
+ *   these guards refuse is a LATER declaration that removes something the CURRENT live state
+ *   still has, without saying why. `acknowledgeBypassNarrowing`/`acknowledgeRuleNarrowing` are
+ *   the "why": a reasoned, deliberate sign-off, not a rubber stamp — see their doc comments on
+ *   `RepositoryRulesetProps` (repository-ruleset-props.ts).
+ *
+ * ⛔ THE TWO ACKNOWLEDGEMENTS ARE DELIBERATELY SEPARATE PROPS, NOT ONE SHARED FLAG (2026-09-23
+ *   review finding). A single `acknowledgeNarrowing` computed once and handed to both guards let
+ *   a reason written for one kind of narrowing silently also excuse the other — a declaration
+ *   dropping BOTH a live rule and a live bypass actor at once needed only one acknowledgement,
+ *   however narrowly worded, to pass both checks. Each guard below now reads its OWN prop.
+ */
+import { bypassKey, liveRuleTypes } from './repository-ruleset-guards.ts';
+import { BypassActorNarrowed, RuleNarrowed } from './repository-ruleset-errors.ts';
+import type { RepositoryRulesetProps, RepositoryRulesetRules } from './repository-ruleset-props.ts';
+import type { RulesetRecord } from './repository-ruleset-probe.ts';
+
+/** `true` only for a non-empty, non-whitespace `reason` on `acknowledgeBypassNarrowing` — a bare
+ * `{}` or a blank string is not an acknowledgement (repository-ruleset.ts's `constraintRefusal`
+ * refuses the latter at plan time; this is the read `bypassNarrowingRefusal` shares). Deliberately
+ * ignorant of `acknowledgeRuleNarrowing` — see the file header. */
+export const isBypassNarrowingAcknowledged = (props: RepositoryRulesetProps): boolean =>
+  props.acknowledgeBypassNarrowing !== undefined &&
+  props.acknowledgeBypassNarrowing.reason.trim().length > 0;
+
+/** The `rules`-side counterpart to `isBypassNarrowingAcknowledged`, reading only
+ * `acknowledgeRuleNarrowing` — see the file header. */
+export const isRuleNarrowingAcknowledged = (props: RepositoryRulesetProps): boolean =>
+  props.acknowledgeRuleNarrowing !== undefined &&
+  props.acknowledgeRuleNarrowing.reason.trim().length > 0;
+
+/**
+ * A live bypass actor the declaration drops, unacknowledged. `undefined` `declared` never
+ * reaches here — same rule as `bypassWideningRefusal`: unmanaged means the live value is
+ * preserved unchanged (repository-ruleset-reconcile.ts), so there is nothing to narrow.
+ */
+export function bypassNarrowingRefusal(input: {
+  readonly owner: string;
+  readonly repository: string;
+  readonly name: string;
+  readonly declared: RepositoryRulesetProps['bypassActors'];
+  readonly live: RulesetRecord | undefined;
+  readonly acknowledged: boolean;
+}): BypassActorNarrowed | undefined {
+  if (input.acknowledged) return undefined;
+  if (input.live === undefined) return undefined;
+  const liveActors = (input.live.bypass_actors ?? []) as {
+    actor_type: unknown;
+    actor_id: unknown;
+    bypass_mode?: unknown;
+  }[];
+  const declaredKeys = new Set(
+    (input.declared ?? []).map((a) =>
+      bypassKey({
+        actor_type: a.actorType,
+        actor_id: a.actorId,
+        bypass_mode: a.bypassMode ?? 'always',
+      }),
+    ),
+  );
+  const narrowed = liveActors.map(bypassKey).filter((k) => !declaredKeys.has(k));
+  if (narrowed.length === 0) return undefined;
+  return new BypassActorNarrowed({
+    owner: input.owner,
+    repository: input.repository,
+    name: input.name,
+    narrowed,
+  });
+}
+
+/** The live rule `type` for the first boolean/`pullRequest` rule the declaration marks `false`
+ * while live still has it — `undefined` when none does. `requiredStatusChecks: false` is
+ * checked by the caller directly (its live-side read needs `required_status_checks`'s own
+ * parameters shape, not just presence, elsewhere in this family — kept out of this helper so it
+ * stays a plain type-to-type comparison). */
+function droppedBooleanOrPullRequestType(
+  rules: RepositoryRulesetRules,
+  live: ReadonlySet<string>,
+): string | undefined {
+  const declaredFalse: readonly [boolean | undefined, string][] = [
+    [rules.creation, 'creation'],
+    [rules.update, 'update'],
+    [rules.deletion, 'deletion'],
+    [rules.requiredLinearHistory, 'required_linear_history'],
+    [rules.requiredSignatures, 'required_signatures'],
+    [rules.nonFastForward, 'non_fast_forward'],
+  ];
+  for (const [declared, type] of declaredFalse) {
+    if (declared === false && live.has(type)) return type;
+  }
+  if (rules.pullRequest === false && live.has('pull_request')) return 'pull_request';
+  return undefined;
+}
+
+/**
+ * A rule the declaration explicitly marks absent (a boolean rule or `pullRequest` declared
+ * `false`, or `requiredStatusChecks: false`) while the LIVE ruleset still has it, unacknowledged
+ * — the drop `undeclaredLiveRuleRefusal` (repository-ruleset-guards.ts) never sees, because an
+ * explicit `false` IS "declared" there (see its own `declaredRuleTypes`).
+ */
+export function ruleNarrowingRefusal(input: {
+  readonly owner: string;
+  readonly repository: string;
+  readonly name: string;
+  readonly declared: RepositoryRulesetProps['rules'];
+  readonly live: RulesetRecord | undefined;
+  readonly acknowledged: boolean;
+}): RuleNarrowed | undefined {
+  if (input.acknowledged) return undefined;
+  const rules = input.declared;
+  if (rules === undefined) return undefined;
+  const live = liveRuleTypes(input.live);
+  const ruleType =
+    droppedBooleanOrPullRequestType(rules, live) ??
+    (rules.requiredStatusChecks === false && live.has('required_status_checks')
+      ? 'required_status_checks'
+      : undefined);
+  if (ruleType === undefined) return undefined;
+  return new RuleNarrowed({
+    owner: input.owner,
+    repository: input.repository,
+    name: input.name,
+    ruleType,
+  });
+}

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

@@ -0,0 +1,210 @@
+/**
+ * Narrowing refusals (repository-ruleset-narrowing-guards.ts), split out of
+ * repository-ruleset-write-refusals.test.ts purely to keep both files under the 250-line cap.
+ * `acknowledgeRuleNarrowing`/`acknowledgeBypassNarrowing` are the escape hatches: without the
+ * matching one, dropping a live rule or a live bypass actor is refused; with a non-empty reason
+ * on the RIGHT prop, it writes exactly what was declared. The two are intentionally separate
+ * props, not one shared flag — see the 'mixed narrowing' describe block below and the file
+ * header on repository-ruleset-narrowing-guards.ts for the 2026-09-23 finding this fixes. The
+ * dedicated exact-adopt fixtures (all 5 live non-empty-bypass shapes, none of which are
+ * "narrowing" — they match live exactly) are repository-ruleset-exact-adopt.test.ts.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { makeGetOnlyFake, makeRecordingFake } from './repository-ruleset-fake-octokit.ts';
+import {
+  BASE_PULL_REQUEST,
+  fails,
+  props,
+  reconcileAgainst,
+  reconcileWithOctokit,
+  tagOf,
+} from './repository-ruleset-test-helpers.ts';
+
+describe('rule narrowing', () => {
+  // Regression for the gap the exact-adopt pass-through work closed 2026-09-23: an explicit
+  // `false` alone used to be enough to drop a live rule, with no record of WHY. It is now also
+  // gated on `acknowledgeRuleNarrowing` — see repository-ruleset-narrowing-guards.ts.
+  test('dropping a live rule (deletion declared false) without acknowledgeRuleNarrowing is refused', async () => {
+    const live = {
+      id: 1,
+      name: 'main',
+      enforcement: 'active',
+      bypass_actors: [],
+      conditions: {},
+      rules: [
+        { type: 'deletion' },
+        { type: 'pull_request', parameters: { required_approving_review_count: 0 } },
+      ],
+    };
+    const fake = makeGetOnlyFake({ widgets: live });
+    const declaration = props({
+      rules: { deletion: false, pullRequest: BASE_PULL_REQUEST },
+    });
+    const error = await fails(reconcileWithOctokit(fake, declaration, { rulesetId: 1 }));
+    expect(tagOf(error)).toBe('RuleNarrowed');
+  });
+
+  test('the SAME drop, acknowledged with a reason, is a deliberate removal and writes once', async () => {
+    const live = {
+      id: 1,
+      name: 'main',
+      enforcement: 'active',
+      bypass_actors: [],
+      conditions: {},
+      rules: [
+        { type: 'deletion' },
+        { type: 'pull_request', parameters: { required_approving_review_count: 0 } },
+      ],
+    };
+    const fake = makeRecordingFake({ widgets: live });
+    fake.reportedContexts.add('ci');
+    const declaration = props({
+      rules: { deletion: false, pullRequest: BASE_PULL_REQUEST },
+      acknowledgeRuleNarrowing: { reason: 'Tim approved dropping delete-protection 2026-09-23' },
+    });
+    await reconcileAgainst(fake, declaration, { rulesetId: 1 }).pipe(Effect.runPromise);
+    expect(fake.writes).toHaveLength(1);
+    expect(fake.writes[0]?.op).toBe('update');
+    const sentTypes = fake.writes[0]?.body?.rules?.map((r) => r.type);
+    expect(sentTypes).not.toContain('deletion');
+  });
+
+  // A blank (or whitespace-only) reason is not an acknowledgement —
+  // `isRuleNarrowingAcknowledged` (repository-ruleset-narrowing-guards.ts) requires a
+  // non-empty, TRIMMED reason, so this is indistinguishable from omitting
+  // `acknowledgeRuleNarrowing` entirely and gets the same refusal.
+  test('acknowledgeRuleNarrowing with a blank reason does not count as acknowledged', async () => {
+    const live = {
+      id: 1,
+      name: 'main',
+      enforcement: 'active',
+      bypass_actors: [],
+      conditions: {},
+      rules: [
+        { type: 'deletion' },
+        { type: 'pull_request', parameters: { required_approving_review_count: 0 } },
+      ],
+    };
+    const fake = makeGetOnlyFake({ widgets: live });
+    const declaration = props({
+      rules: { deletion: false, pullRequest: BASE_PULL_REQUEST },
+      acknowledgeRuleNarrowing: { reason: '   ' },
+    });
+    const error = await fails(reconcileWithOctokit(fake, declaration, { rulesetId: 1 }));
+    expect(tagOf(error)).toBe('RuleNarrowed');
+  });
+
+  // Scoping regression (2026-09-23 review finding): an acknowledgement reasoned for the RULE
+  // drop must not also excuse a bypass-actor drop declared in the SAME declaration.
+  test('acknowledgeRuleNarrowing does not excuse an unrelated bypass-actor drop', async () => {
+    const live = {
+      id: 1,
+      name: 'main',
+      enforcement: 'active',
+      bypass_actors: [{ actor_id: 5, actor_type: 'RepositoryRole', bypass_mode: 'always' }],
+      conditions: {},
+      rules: [
+        { type: 'deletion' },
+        { type: 'pull_request', parameters: { required_approving_review_count: 0 } },
+      ],
+    };
+    const fake = makeGetOnlyFake({ widgets: live });
+    const declaration = props({
+      bypassActors: [],
+      rules: { deletion: false, pullRequest: BASE_PULL_REQUEST },
+      acknowledgeRuleNarrowing: { reason: 'Tim approved dropping delete-protection 2026-09-23' },
+    });
+    const error = await fails(reconcileWithOctokit(fake, declaration, { rulesetId: 1 }));
+    expect(tagOf(error)).toBe('BypassActorNarrowed');
+  });
+});
+
+describe('bypass narrowing', () => {
+  test('dropping a live bypass actor without acknowledgeBypassNarrowing is refused', async () => {
+    const live = {
+      id: 1,
+      name: 'main',
+      enforcement: 'active',
+      bypass_actors: [{ actor_id: 5, actor_type: 'RepositoryRole', bypass_mode: 'always' }],
+      conditions: {},
+      rules: [{ type: 'deletion' }, { type: 'non_fast_forward' }],
+    };
+    const fake = makeGetOnlyFake({ widgets: live });
+    const declaration = props({
+      bypassActors: [],
+      rules: { deletion: true, nonFastForward: true },
+    });
+    const error = await fails(reconcileWithOctokit(fake, declaration, { rulesetId: 1 }));
+    expect(tagOf(error)).toBe('BypassActorNarrowed');
+  });
+
+  test('the SAME drop, acknowledged with a reason, writes the narrowed list', async () => {
+    const live = {
+      id: 1,
+      name: 'main',
+      enforcement: 'active',
+      bypass_actors: [{ actor_id: 5, actor_type: 'RepositoryRole', bypass_mode: 'always' }],
+      conditions: {},
+      rules: [{ type: 'deletion' }, { type: 'non_fast_forward' }],
+    };
+    const fake = makeRecordingFake({ widgets: live });
+    const declaration = props({
+      bypassActors: [],
+      rules: { deletion: true, nonFastForward: true },
+      acknowledgeBypassNarrowing: { reason: 'Tim revoked admin bypass 2026-09-23' },
+    });
+    await reconcileAgainst(fake, declaration, { rulesetId: 1 }).pipe(Effect.runPromise);
+    expect(fake.writes).toHaveLength(1);
+    expect(fake.writes[0]?.body?.bypass_actors).toEqual([]);
+  });
+
+  // Widening stays refused even alongside an acknowledgement — `acknowledgeBypassNarrowing`
+  // gates ONLY narrowing (repository-ruleset-narrowing-guards.ts's file header explains why).
+  test('acknowledgeBypassNarrowing does not excuse widening', async () => {
+    const live = {
+      id: 1,
+      name: 'main',
+      enforcement: 'active',
+      bypass_actors: [],
+      conditions: {},
+      rules: [],
+    };
+    const fake = makeGetOnlyFake({ widgets: live });
+    const declaration = props({
+      bypassActors: [{ actorType: 'OrganizationAdmin' }],
+      acknowledgeBypassNarrowing: { reason: 'irrelevant to widening' },
+    });
+    const error = await fails(reconcileWithOctokit(fake, declaration, { rulesetId: 1 }));
+    expect(tagOf(error)).toBe('BypassActorWidened');
+  });
+
+  // Scoping regression (2026-09-23 review finding), the mirror of the rule-narrowing case
+  // above: an acknowledgement reasoned for the BYPASS drop must not also excuse an unrelated
+  // rule drop declared in the SAME declaration.
+  test('acknowledgeBypassNarrowing does not excuse an unrelated rule drop', async () => {
+    const live = {
+      id: 1,
+      name: 'main',
+      enforcement: 'active',
+      bypass_actors: [{ actor_id: 5, actor_type: 'RepositoryRole', bypass_mode: 'always' }],
+      conditions: {},
+      rules: [
+        { type: 'deletion' },
+        { type: 'pull_request', parameters: { required_approving_review_count: 0 } },
+      ],
+    };
+    const fake = makeGetOnlyFake({ widgets: live });
+    const declaration = props({
+      bypassActors: [],
+      rules: { deletion: false, pullRequest: BASE_PULL_REQUEST },
+      acknowledgeBypassNarrowing: { reason: 'Tim revoked admin bypass 2026-09-23' },
+    });
+    // The bypass drop is acknowledged (so `bypassNarrowingRefusal` passes), but the rule drop
+    // is not — `reconcileRuleset` checks bypass narrowing before rule narrowing, so a REFUSED
+    // rule drop under a bypass-only acknowledgement surfaces as `RuleNarrowed`, proving the
+    // bypass acknowledgement did not also cover it.
+    const error = await fails(reconcileWithOctokit(fake, declaration, { rulesetId: 1 }));
+    expect(tagOf(error)).toBe('RuleNarrowed');
+  });
+});