@homeflare/alchemy 0.27.4 → 0.28.0

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');
+  });
+});

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

@@ -0,0 +1,92 @@
+/**
+ * `GitHub.RepositoryRuleset`'s declared shape — split out of repository-ruleset.ts purely to
+ * keep that file (the provider wiring) under the 250-line cap; nothing here is provider logic.
+ */
+import type { RulesetProps } from 'alchemy/GitHub';
+
+type UpstreamRules = NonNullable<RulesetProps['rules']>;
+
+export interface RepositoryRulesetReviewerRule {
+  readonly filePatterns: readonly string[];
+  readonly minimumApprovals: number;
+  readonly reviewer: { readonly actorId: number; readonly actorType: 'Team' };
+}
+
+export interface RepositoryRulesetPullRequestRule extends NonNullable<
+  UpstreamRules['pullRequest']
+> {
+  /** @default every method GitHub allows — the house baseline always pins `['squash']`. */
+  readonly allowedMergeMethods?: readonly ('merge' | 'squash' | 'rebase')[];
+  readonly requiredReviewers?: readonly RepositoryRulesetReviewerRule[];
+  /** `require_extra_approval_for_unattributed_changes` — see repository-ruleset.ts's H15. Only
+   * `false` is modeled: sending `true` has no house use, and GitHub already defaults absent to
+   * `true`. */
+  readonly extraApprovalForUnattributedChanges?: false;
+}
+
+export interface RepositoryRulesetStatusChecksRule extends NonNullable<
+  UpstreamRules['requiredStatusChecks']
+> {
+  readonly doNotEnforceOnCreate?: boolean;
+}
+
+export interface RepositoryRulesetRules extends Omit<
+  UpstreamRules,
+  'pullRequest' | 'requiredStatusChecks'
+> {
+  /** `undefined`: no opinion (refused if the live ruleset already has one and this is not an
+   * exact-adopt pass-through — see repository-ruleset-guards.ts's `undeclaredLiveRuleRefusal`).
+   * `false`: declare its ABSENCE — either "this repo never had one" (a create, or an adopt
+   * where live already has none, both no-ops) or a deliberate removal of a live rule, which
+   * `ruleNarrowingRefusal` gates behind `acknowledgeRuleNarrowing` (see below). Added 2026-09-23 for
+   * exact-adopt pass-through: `requiredStatusChecks` already had this `false` escape; `deletion`/
+   * `nonFastForward`/etc already have it implicitly (plain `boolean`, so `false` is already a
+   * value); `pullRequest` was the one modeled rule with NO way to express "not present at all" —
+   * a repo like `taslabs-net/taslabs-net` (measured live 2026-09-23: `rules = [deletion,
+   * non_fast_forward]`, no `pull_request`) could not be adopted through this resource without
+   * either refusing to omit the key (a type error) or silently declaring a brand-new rule. */
+  readonly pullRequest?: RepositoryRulesetPullRequestRule | false;
+  /** `undefined`: no opinion (refused if the live ruleset already has one — see
+   * repository-ruleset-guards.ts). `false`: declare its ABSENCE — removes a live one. */
+  readonly requiredStatusChecks?: RepositoryRulesetStatusChecksRule | false;
+}
+
+export interface RepositoryRulesetProps extends Omit<RulesetProps, 'rules'> {
+  readonly rules?: RepositoryRulesetRules;
+  /**
+   * An explicit, reasoned sign-off that THIS declaration deliberately drops a live bypass actor
+   * (`bypassActors` is a strict subset of what is live). Without this, `reconcile` refuses the
+   * write rather than silently loosen a ruleset that already protects something — see
+   * `bypassNarrowingRefusal` in repository-ruleset-narrowing-guards.ts. `reason` is not logged or
+   * sent to GitHub; it exists so the declaration's own diff carries WHY, for the next reader
+   * (S21: a refusal names the fact it checked — this is the human-authored counterpart for the
+   * one case a fact alone cannot settle: "is this narrowing intentional?").
+   *
+   * ⛔ SEPARATE FROM `acknowledgeRuleNarrowing` ON PURPOSE (2026-09-23 review finding: a single
+   *   shared `acknowledgeNarrowing` let one reason worded for a rule drop silently also rubber-
+   *   stamp an unrelated bypass-actor drop in the SAME declaration — a `bypassActors: []` left
+   *   over from an unrelated edit slipped through under a reason that never mentioned bypass at
+   *   all). Each prop authorizes only the narrowing its own guard checks; a declaration that
+   *   narrows both needs both, each with its own reason.
+   *
+   * ⛔ ALSO A STANDING PROP, NOT A ONE-TIME TOKEN — remove it from the declaration once the
+   *   narrowing it describes has landed. Left in place, it keeps disabling the bypass-narrowing
+   *   guard for every future `reconcile` of this resource, not only the change it was written
+   *   for — the same way `rules: { deletion: false }` stays a standing "this rule stays absent"
+   *   fact rather than a one-time action, only here the standing fact is "bypass narrowing needs
+   *   no review", which is a fact you want true for as short a window as possible. A reviewer
+   *   reading a diff that adds a SECOND, unrelated bypass drop under an OLD
+   *   `acknowledgeBypassNarrowing` left over from a prior change is the failure mode this note
+   *   exists to head off.
+   */
+  readonly acknowledgeBypassNarrowing?: { readonly reason: string };
+  /**
+   * The `rules`-side counterpart to `acknowledgeBypassNarrowing` above — an explicit, reasoned
+   * sign-off that THIS declaration deliberately drops a live rule (a modeled rule type declared
+   * `false`/boolean-`false` while the live ruleset still has it). Without this, `reconcile`
+   * refuses the write — see `ruleNarrowingRefusal` in repository-ruleset-narrowing-guards.ts.
+   * Same standing-prop caution as `acknowledgeBypassNarrowing`: remove it once the rule drop it
+   * describes has landed, or it keeps excusing every later rule drop on this resource too.
+   */
+  readonly acknowledgeRuleNarrowing?: { readonly reason: string };
+}

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

@@ -20,6 +20,12 @@ import {
   requiredChecksOmissionRefusal,
   undeclaredLiveRuleRefusal,
 } from './repository-ruleset-guards.ts';
+import {
+  bypassNarrowingRefusal,
+  isBypassNarrowingAcknowledged,
+  isRuleNarrowingAcknowledged,
+  ruleNarrowingRefusal,
+} from './repository-ruleset-narrowing-guards.ts';
 import {
   type RulesetOctokit,
   type RulesetRecord,
@@ -104,6 +110,12 @@ export const reconcileRuleset = <R = never>(input: {
       observed = yield* probeByName(octokit, { owner, repo, name: news.name, target });
     }
 
+    // Deliberately TWO separate reads, not one shared flag — each guard below is authorized
+    // only by the acknowledgement scoped to what it checks (see the file header on
+    // repository-ruleset-narrowing-guards.ts for the 2026-09-23 finding this fixes).
+    const bypassAcknowledged = isBypassNarrowingAcknowledged(news);
+    const ruleAcknowledged = isRuleNarrowingAcknowledged(news);
+
     const bypassRefusal =
       news.bypassActors === undefined
         ? undefined
@@ -116,6 +128,19 @@ export const reconcileRuleset = <R = never>(input: {
           });
     if (bypassRefusal !== undefined) return yield* Effect.fail(bypassRefusal);
 
+    const bypassNarrowRefusal =
+      news.bypassActors === undefined
+        ? undefined
+        : bypassNarrowingRefusal({
+            owner,
+            repository: repo,
+            name: news.name,
+            declared: news.bypassActors,
+            live: observed,
+            acknowledged: bypassAcknowledged,
+          });
+    if (bypassNarrowRefusal !== undefined) return yield* Effect.fail(bypassNarrowRefusal);
+
     const ruleRefusal = undeclaredLiveRuleRefusal({
       owner,
       repository: repo,
@@ -125,6 +150,16 @@ export const reconcileRuleset = <R = never>(input: {
     });
     if (ruleRefusal !== undefined) return yield* Effect.fail(ruleRefusal);
 
+    const ruleNarrowRefusal = ruleNarrowingRefusal({
+      owner,
+      repository: repo,
+      name: news.name,
+      declared: news.rules,
+      live: observed,
+      acknowledged: ruleAcknowledged,
+    });
+    if (ruleNarrowRefusal !== undefined) return yield* Effect.fail(ruleNarrowRefusal);
+
     const checksRefusal = requiredChecksOmissionRefusal({
       owner,
       repository: repo,

package/src/github/repository-ruleset-write-refusals.test.ts

@@ -1,8 +1,12 @@
 /**
  * (ii) The write-recording fake, refusals: duplicate names, bypass widening, an undeclared live
  * rule, required checks omitted, and a never-reported context each make ZERO writes; and a
- * readback mismatch fails even though the write itself "succeeded" (S10). The happy paths
- * (create, noop, update) are repository-ruleset-write.test.ts.
+ * readback mismatch fails even though the write itself "succeeded" (S10). Bypass/rule narrowing
+ * without the matching `acknowledge{Bypass,Rule}Narrowing` are their own file,
+ * repository-ruleset-narrowing.test.ts (split out purely for the 250-line cap). The happy paths
+ * (create, noop, update) are repository-ruleset-write.test.ts; exact-adopt pass-through's own
+ * dedicated fixtures (all 5 live non-empty-bypass shapes) are
+ * repository-ruleset-exact-adopt.test.ts.
  */
 import { describe, expect, test } from 'bun:test';
 import * as Effect from 'effect/Effect';
@@ -94,30 +98,6 @@ describe('refusals make zero writes', () => {
     expect(tagOf(error)).toBe('UndeclaredLiveRule');
   });
 
-  test('the SAME live ruleset with deletion explicitly declared false is a deliberate removal, not 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 = makeRecordingFake({ widgets: live });
-    fake.reportedContexts.add('ci');
-    const declaration = props({
-      rules: { deletion: false, pullRequest: BASE_PULL_REQUEST },
-    });
-    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');
-  });
-
   test('required checks omitted while the live ruleset has them', async () => {
     const live = {
       id: 1,

package/src/github/repository-ruleset.ts

@@ -42,7 +42,7 @@
 import { Resource } from 'alchemy';
 import { Unowned } from 'alchemy/AdoptPolicy';
 import { isResolved } from 'alchemy/Diff';
-import type { GitHubCredentials, RulesetProps } from 'alchemy/GitHub';
+import type { GitHubCredentials } from 'alchemy/GitHub';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
 import {
@@ -52,46 +52,16 @@ import {
 import { RulesetConstraintRefused } from './repository-ruleset-errors.ts';
 import { makeRulesetOctokit } from './repository-ruleset-octokit.ts';
 import { type RulesetRecord, probeByName } from './repository-ruleset-probe.ts';
+import type { RepositoryRulesetProps } from './repository-ruleset-props.ts';
 import { reconcileRuleset } from './repository-ruleset-reconcile.ts';
 
-type UpstreamRules = NonNullable<RulesetProps['rules']>;
-
-export interface RepositoryRulesetReviewerRule {
-  readonly filePatterns: readonly string[];
-  readonly minimumApprovals: number;
-  readonly reviewer: { readonly actorId: number; readonly actorType: 'Team' };
-}
-
-export interface RepositoryRulesetPullRequestRule extends NonNullable<
-  UpstreamRules['pullRequest']
-> {
-  /** @default every method GitHub allows — the house baseline always pins `['squash']`. */
-  readonly allowedMergeMethods?: readonly ('merge' | 'squash' | 'rebase')[];
-  readonly requiredReviewers?: readonly RepositoryRulesetReviewerRule[];
-  /** `require_extra_approval_for_unattributed_changes` — see H15 above. Only `false` is
-   * modeled: sending `true` has no house use, and GitHub already defaults absent to `true`. */
-  readonly extraApprovalForUnattributedChanges?: false;
-}
-
-export interface RepositoryRulesetStatusChecksRule extends NonNullable<
-  UpstreamRules['requiredStatusChecks']
-> {
-  readonly doNotEnforceOnCreate?: boolean;
-}
-
-export interface RepositoryRulesetRules extends Omit<
-  UpstreamRules,
-  'pullRequest' | 'requiredStatusChecks'
-> {
-  readonly pullRequest?: RepositoryRulesetPullRequestRule;
-  /** `undefined`: no opinion (refused if the live ruleset already has one — see
-   * repository-ruleset-guards.ts). `false`: declare its ABSENCE — removes a live one. */
-  readonly requiredStatusChecks?: RepositoryRulesetStatusChecksRule | false;
-}
-
-export interface RepositoryRulesetProps extends Omit<RulesetProps, 'rules'> {
-  readonly rules?: RepositoryRulesetRules;
-}
+export type {
+  RepositoryRulesetProps,
+  RepositoryRulesetPullRequestRule,
+  RepositoryRulesetReviewerRule,
+  RepositoryRulesetRules,
+  RepositoryRulesetStatusChecksRule,
+} from './repository-ruleset-props.ts';
 
 export interface RepositoryRulesetAttributes {
   readonly rulesetId: number;
@@ -124,7 +94,11 @@ export const attrsOf = (r: RulesetRecord): RepositoryRulesetAttributes => ({
 /** Plan-time-only refusals — no live data needed, so these run before any read (schema-codegen's
  * rule: check the form before the "no previous state" branch, never after it). */
 function constraintRefusal(props: RepositoryRulesetProps): RulesetConstraintRefused | undefined {
-  const approvals = props.rules?.pullRequest?.requiredApprovingReviewCount;
+  // `=== false` narrows `pullRequest` out of the `| false` half added for exact-adopt
+  // pass-through (see `RepositoryRulesetRules` above) — a declared absence has no fields to
+  // constrain.
+  const pr = props.rules?.pullRequest === false ? undefined : props.rules?.pullRequest;
+  const approvals = pr?.requiredApprovingReviewCount;
   if (approvals !== undefined) {
     const reason = approvalCountRefusal(approvals);
     if (reason !== undefined) {
@@ -134,7 +108,7 @@ function constraintRefusal(props: RepositoryRulesetProps): RulesetConstraintRefu
       });
     }
   }
-  const methods = props.rules?.pullRequest?.allowedMergeMethods;
+  const methods = pr?.allowedMergeMethods;
   if (methods !== undefined) {
     const reason = allowedMergeMethodsRefusal(methods);
     if (reason !== undefined) {
@@ -144,6 +118,18 @@ function constraintRefusal(props: RepositoryRulesetProps): RulesetConstraintRefu
       });
     }
   }
+  // ⚠️ NO SEPARATE PLAN-TIME CHECK FOR A BLANK `acknowledge{Bypass,Rule}Narrowing.reason` HERE.
+  //   A blank reason is already indistinguishable from "not acknowledged at all" —
+  //   `isBypassNarrowingAcknowledged`/`isRuleNarrowingAcknowledged`
+  //   (repository-ruleset-narrowing-guards.ts) each require a non-empty, trimmed `reason` on
+  //   their OWN prop, and the matching narrowing guard reads that, not presence alone. Adding a
+  //   SECOND check here would refuse with `RulesetConstraintRefused` instead of the more
+  //   specific `BypassActorNarrowed`/`RuleNarrowed` the caller actually needs to act on — and,
+  //   unlike those two (exercised directly through `reconcileRuleset`, injected-octokit fakes
+  //   included), this function is wired only through the real `RepositoryRuleset.Provider`
+  //   (`makeRulesetOctokit` needs live `GitHubCredentials`), which this family's own test
+  //   helpers do not exercise (see `repository-ruleset-test-helpers.ts`'s stub
+  //   `constraintRefusal`) — a check that lives only here would ship untested.
   return undefined;
 }