@homeflare/alchemy 0.27.4 → 0.28.0

package/dist/github/repository-ruleset-props.d.ts

@@ -0,0 +1,88 @@
+/**
+ * `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;
+    };
+}
+export {};
+//# sourceMappingURL=repository-ruleset-props.d.ts.map

package/dist/github/repository-ruleset-props.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repository-ruleset-props.d.ts","sourceRoot":"","sources":["../../src/github/repository-ruleset-props.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,KAAK,aAAa,GAAG,WAAW,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;AAExD,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7E;AAED,MAAM,WAAW,gCAAiC,SAAQ,WAAW,CACnE,aAAa,CAAC,aAAa,CAAC,CAC7B;IACC,yFAAyF;IACzF,QAAQ,CAAC,mBAAmB,CAAC,EAAE,SAAS,CAAC,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC,EAAE,CAAC;IAC1E,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,6BAA6B,EAAE,CAAC;IACtE;;iBAEa;IACb,QAAQ,CAAC,mCAAmC,CAAC,EAAE,KAAK,CAAC;CACtD;AAED,MAAM,WAAW,iCAAkC,SAAQ,WAAW,CACpE,aAAa,CAAC,sBAAsB,CAAC,CACtC;IACC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;CACzC;AAED,MAAM,WAAW,sBAAuB,SAAQ,IAAI,CAClD,aAAa,EACb,aAAa,GAAG,sBAAsB,CACvC;IACC;;;;;;;;;;gGAU4F;IAC5F,QAAQ,CAAC,WAAW,CAAC,EAAE,gCAAgC,GAAG,KAAK,CAAC;IAChE;2FACuF;IACvF,QAAQ,CAAC,oBAAoB,CAAC,EAAE,iCAAiC,GAAG,KAAK,CAAC;CAC3E;AAED,MAAM,WAAW,sBAAuB,SAAQ,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC;IACzE,QAAQ,CAAC,KAAK,CAAC,EAAE,sBAAsB,CAAC;IACxC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,QAAQ,CAAC,0BAA0B,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAClE;;;;;;;OAOG;IACH,QAAQ,CAAC,wBAAwB,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACjE"}

package/dist/github/repository-ruleset-reconcile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"repository-ruleset-reconcile.d.ts","sourceRoot":"","sources":["../../src/github/repository-ruleset-reconcile.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,EAAE,2BAA2B,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAEnG,OAAO,EAEL,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC9B,MAAM,gCAAgC,CAAC;AAUxC,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,aAAa,EAEnB,MAAM,+BAA+B,CAAC;AA+CvC;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,GAAG,KAAK,SAAS;IACjD,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,2BAA2B,GAAG,SAAS,CAAC;IACzD,QAAQ,CAAC,iBAAiB,EAAE,CAC1B,KAAK,EAAE,sBAAsB,KAC1B,wBAAwB,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,aAAa,KAAK,2BAA2B,CAAC;CACrE,KAAG,MAAM,CAAC,MAAM,CAAC,2BAA2B,EAAE,sBAAsB,GAAG,KAAK,EAAE,CAAC,CAuF5E,CAAC"}
+{"version":3,"file":"repository-ruleset-reconcile.d.ts","sourceRoot":"","sources":["../../src/github/repository-ruleset-reconcile.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,EAAE,2BAA2B,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAEnG,OAAO,EAEL,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC9B,MAAM,gCAAgC,CAAC;AAgBxC,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,aAAa,EAEnB,MAAM,+BAA+B,CAAC;AA+CvC;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,GAAG,KAAK,SAAS;IACjD,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,2BAA2B,GAAG,SAAS,CAAC;IACzD,QAAQ,CAAC,iBAAiB,EAAE,CAC1B,KAAK,EAAE,sBAAsB,KAC1B,wBAAwB,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,aAAa,KAAK,2BAA2B,CAAC;CACrE,KAAG,MAAM,CAAC,MAAM,CAAC,2BAA2B,EAAE,sBAAsB,GAAG,KAAK,EAAE,CAAC,CAoH5E,CAAC"}

package/dist/github/repository-ruleset.d.ts

@@ -40,38 +40,11 @@
  *   is not hand-rolled — only the choice of Octokit over distilled is a recorded divergence.
  */
 import { Resource } from 'alchemy';
-import type { GitHubCredentials, RulesetProps } from 'alchemy/GitHub';
+import type { GitHubCredentials } from 'alchemy/GitHub';
 import * as Provider from 'alchemy/Provider';
 import { type RulesetRecord } from './repository-ruleset-probe.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;
-}
+import type { RepositoryRulesetProps } from './repository-ruleset-props.ts';
+export type { RepositoryRulesetProps, RepositoryRulesetPullRequestRule, RepositoryRulesetReviewerRule, RepositoryRulesetRules, RepositoryRulesetStatusChecksRule, } from './repository-ruleset-props.ts';
 export interface RepositoryRulesetAttributes {
     readonly rulesetId: number;
     readonly nodeId: string | undefined;
@@ -85,5 +58,4 @@ export declare const RepositoryRuleset: import("alchemy").ResourceClass<Reposito
 export declare const attrsOf: (r: RulesetRecord) => RepositoryRulesetAttributes;
 export declare const repositoryRulesetHandlers: Provider.ProviderService<RepositoryRuleset, GitHubCredentials, never, never, GitHubCredentials, GitHubCredentials, never, never, never>;
 export declare const RepositoryRulesetProvider: () => import("effect/Layer").Layer<Provider.Provider<RepositoryRuleset>, never, GitHubCredentials>;
-export {};
 //# sourceMappingURL=repository-ruleset.d.ts.map

package/dist/github/repository-ruleset.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"repository-ruleset.d.ts","sourceRoot":"","sources":["../../src/github/repository-ruleset.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGnC,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAQ7C,OAAO,EAAE,KAAK,aAAa,EAAe,MAAM,+BAA+B,CAAC;AAGhF,KAAK,aAAa,GAAG,WAAW,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;AAExD,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7E;AAED,MAAM,WAAW,gCAAiC,SAAQ,WAAW,CACnE,aAAa,CAAC,aAAa,CAAC,CAC7B;IACC,yFAAyF;IACzF,QAAQ,CAAC,mBAAmB,CAAC,EAAE,SAAS,CAAC,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC,EAAE,CAAC;IAC1E,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,6BAA6B,EAAE,CAAC;IACtE;iGAC6F;IAC7F,QAAQ,CAAC,mCAAmC,CAAC,EAAE,KAAK,CAAC;CACtD;AAED,MAAM,WAAW,iCAAkC,SAAQ,WAAW,CACpE,aAAa,CAAC,sBAAsB,CAAC,CACtC;IACC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;CACzC;AAED,MAAM,WAAW,sBAAuB,SAAQ,IAAI,CAClD,aAAa,EACb,aAAa,GAAG,sBAAsB,CACvC;IACC,QAAQ,CAAC,WAAW,CAAC,EAAE,gCAAgC,CAAC;IACxD;2FACuF;IACvF,QAAQ,CAAC,oBAAoB,CAAC,EAAE,iCAAiC,GAAG,KAAK,CAAC;CAC3E;AAED,MAAM,WAAW,sBAAuB,SAAQ,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC;IACzE,QAAQ,CAAC,KAAK,CAAC,EAAE,sBAAsB,CAAC;CACzC;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC;AAED,MAAM,WAAW,iBAAkB,SAAQ,QAAQ,CACjD,0BAA0B,EAC1B,sBAAsB,EACtB,2BAA2B,EAC3B,KAAK,EACL,iBAAiB,CAClB;CAAG;AAEJ,eAAO,MAAM,iBAAiB,oDAE5B,CAAC;AAEH,eAAO,MAAM,OAAO,MAAO,aAAa,KAAG,2BAMzC,CAAC;AA4BH,eAAO,MAAM,yBAAyB,yIAkEpC,CAAC;AAEH,eAAO,MAAM,yBAAyB,oGAC0B,CAAC"}
+{"version":3,"file":"repository-ruleset.d.ts","sourceRoot":"","sources":["../../src/github/repository-ruleset.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGnC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAQ7C,OAAO,EAAE,KAAK,aAAa,EAAe,MAAM,+BAA+B,CAAC;AAChF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAG5E,YAAY,EACV,sBAAsB,EACtB,gCAAgC,EAChC,6BAA6B,EAC7B,sBAAsB,EACtB,iCAAiC,GAClC,MAAM,+BAA+B,CAAC;AAEvC,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC;AAED,MAAM,WAAW,iBAAkB,SAAQ,QAAQ,CACjD,0BAA0B,EAC1B,sBAAsB,EACtB,2BAA2B,EAC3B,KAAK,EACL,iBAAiB,CAClB;CAAG;AAEJ,eAAO,MAAM,iBAAiB,oDAE5B,CAAC;AAEH,eAAO,MAAM,OAAO,MAAO,aAAa,KAAG,2BAMzC,CAAC;AA4CH,eAAO,MAAM,yBAAyB,yIAkEpC,CAAC;AAEH,eAAO,MAAM,yBAAyB,oGAC0B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.27.4",
+  "version": "0.28.0",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",
@@ -94,8 +94,12 @@
     "access": "public"
   },
   "dependencies": {
+    "@distilled.cloud/caddy": "npm:@homeflare/distilled-caddy@0.2.0",
+    "@distilled.cloud/litellm": "npm:@homeflare/distilled-litellm@0.2.0",
     "@distilled.cloud/netbox": "npm:@homeflare/distilled-netbox@0.3.0",
-    "@distilled.cloud/proxmox": "npm:@homeflare/distilled-proxmox@0.2.0"
+    "@distilled.cloud/paperless-ngx": "npm:@homeflare/distilled-paperless-ngx@0.3.0",
+    "@distilled.cloud/proxmox": "npm:@homeflare/distilled-proxmox@0.2.0",
+    "@distilled.cloud/proxmox-backup": "npm:@homeflare/distilled-proxmox-backup@0.2.0"
   },
   "peerDependencies": {
     "@distilled.cloud/cloudflare": "1.0.0-rc.12",

package/src/github/index.ts

@@ -44,11 +44,13 @@ export {
 } from './repository-ruleset.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/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,
+  });
+}