@homeflare/alchemy 0.13.0 → 0.14.0

package/README.md

@@ -162,6 +162,13 @@ with `HostFile`; `caddyProviders()` provides the transport, `http://127.0.0.1:20
 PVE and PBS objects over the PVE API, `ProxmoxLxc` for containers, and the provisioning baseline
 every cluster needs first. What it never does to a guest, and why: [docs/proxmox.md](./docs/proxmox.md).
 
+## GitHub — `@homeflare/alchemy/github`
+
+`declareRepoPolicy` declares one repository's merge policy and its default-branch ruleset in a
+single call: squash-only, auto-merge, head branches deleted, no deletion or force pushes, the
+checks you name required. ⛔ Auto-merge with nothing required merges **immediately**, and Alchemy's
+`Ruleset` creates a duplicate rather than adopting one: [docs/repo-policy.md](./docs/repo-policy.md).
+
 ## Adopt verifier — `hf-adopt-verify` / `@homeflare/alchemy/verify`
 
 ⛔ A plan prints `adopted` for a match and for a drift alike. Before a gated deploy run

package/dist/github/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * GitHub helpers for Alchemy — one repository's house policy in one call.
+ *
+ * ⛔ THIS SUBPATH SHIPS NO PROVIDER, AND DELIBERATELY SO. GitHub is first-class in
+ *   Alchemy; everything here composes the vendor's own `Repository` and `Ruleset`.
+ *   Provide `GitHub.providers()` exactly as you would without it.
+ * ★ WHY IT EXISTS ANYWAY. "Open a pull request, let auto-merge land it" is safe only when
+ *   five repository properties and four ruleset rules all agree, and every way of getting
+ *   one of them wrong is silent — an auto-merge that lands on red, a force push that
+ *   rewrites the branch a release tagged, a required context nothing ever reports. One
+ *   call puts the whole policy in one place, and one place is where it gets fixed.
+ *
+ * ⛔ THIS BARREL IS THE PUBLIC API. `repo-policy-form.ts` is reachable by path if you
+ *   genuinely need an internal — a deliberate act rather than an accident of barrelling.
+ */
+export { type RepoPolicy, type RepoPolicyBypassActor, type RepoPolicyOptions, type RepoPolicyRepositorySettings, repoPolicy, } from './repo-policy-form.ts';
+export { type DeclareRepoPolicyOptions, declareRepoPolicy } from './repo-policy.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/github/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/github/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EACL,KAAK,UAAU,EACf,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,4BAA4B,EACjC,UAAU,GACX,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,KAAK,wBAAwB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/github/index.js

@@ -0,0 +1,161 @@
+// src/github/repo-policy-guards.ts
+function requireName(field, value) {
+  const trimmed = value.trim();
+  if (trimmed === "")
+    throw new Error(`repoPolicy: ${field} is required`);
+  return trimmed;
+}
+function normalizeChecks(checks) {
+  const seen = new Set;
+  for (const raw of checks) {
+    const context = raw.trim();
+    if (context === "") {
+      throw new Error("repoPolicy: a required check context is blank — name it exactly as the job reports it");
+    }
+    seen.add(context);
+  }
+  return [...seen].sort();
+}
+function normalizeRefs(field, patterns) {
+  const seen = new Set;
+  for (const raw of patterns) {
+    const pattern = raw.trim();
+    if (pattern === "") {
+      throw new Error(`repoPolicy: a ${field} ref pattern is blank — a ruleset that matches no ref enforces nothing.`);
+    }
+    seen.add(pattern);
+  }
+  return [...seen].sort();
+}
+function normalizeInclude(include, fallback) {
+  if (include === undefined)
+    return [...fallback];
+  if (include.length === 0) {
+    throw new Error("repoPolicy: include is empty — a ruleset that matches no ref enforces nothing. Omit it for the default branch.");
+  }
+  return normalizeRefs("include", include);
+}
+function normalizeExclude(exclude, include) {
+  const patterns = exclude === undefined ? [] : normalizeRefs("exclude", exclude);
+  if (patterns.length === 0)
+    return patterns;
+  const excluded = new Set(patterns);
+  if (include.every((pattern) => excluded.has(pattern))) {
+    throw new Error([
+      "repoPolicy: exclude cancels every include pattern, so the ruleset matches no ref and enforces nothing.",
+      `include ${JSON.stringify(include)} is fully covered by exclude ${JSON.stringify(patterns)}.`
+    ].join(" "));
+  }
+  return patterns;
+}
+function resolveApprovals(requested) {
+  if (requested === undefined)
+    return;
+  if (!Number.isInteger(requested) || requested < 1) {
+    throw new Error([
+      "repoPolicy: requiredApprovals must be a whole number of 1 or more.",
+      "Omit it to declare no pull_request rule.",
+      "0 is not that: it needs require_extra_approval_for_unattributed_changes: false,",
+      "which alchemy@2.0.0-beta.79 cannot send and GitHub defaults to true."
+    ].join(" "));
+  }
+  return requested;
+}
+function assertAutoMergeWaits(input) {
+  if (!input.autoMerge)
+    return;
+  if (input.enforcement !== "active") {
+    throw new Error([
+      `repoPolicy: autoMerge with enforcement '${input.enforcement}' merges every pull request immediately.`,
+      "A ruleset that is not active enforces none of its rules, so auto-merge has nothing to wait for.",
+      "Pass autoMerge: false while the ruleset is being evaluated."
+    ].join(" "));
+  }
+  if (input.checkCount === 0 && input.approvals === undefined) {
+    throw new Error([
+      "repoPolicy: autoMerge with nothing required merges every pull request immediately.",
+      "Name at least one always-reporting check context, or ask for requiredApprovals,",
+      "or pass autoMerge: false for a repository that has no green run to require yet."
+    ].join(" "));
+  }
+}
+
+// src/github/repo-policy-form.ts
+var DEFAULT_RULESET_NAME = "main";
+var DEFAULT_INCLUDE = ["~DEFAULT_BRANCH"];
+function repoPolicy(options) {
+  const owner = requireName("owner", options.owner);
+  const repository = requireName("repository", options.repository);
+  const checks = normalizeChecks(options.checks);
+  const include = normalizeInclude(options.include, DEFAULT_INCLUDE);
+  const exclude = normalizeExclude(options.exclude, include);
+  const autoMerge = options.autoMerge ?? true;
+  const enforcement = options.enforcement ?? "active";
+  const approvals = resolveApprovals(options.requiredApprovals);
+  assertAutoMergeWaits({ approvals, autoMerge, checkCount: checks.length, enforcement });
+  const host = options.baseUrl === undefined ? {} : { baseUrl: options.baseUrl };
+  return {
+    repository: {
+      ...options.settings,
+      ...host,
+      allowAutoMerge: autoMerge,
+      allowMergeCommit: false,
+      allowRebaseMerge: false,
+      allowSquashMerge: true,
+      deleteBranchOnMerge: true,
+      name: repository,
+      owner
+    },
+    ruleset: {
+      ...host,
+      bypassActors: [...options.bypassActors ?? []],
+      conditions: { exclude, include },
+      enforcement,
+      name: options.rulesetName ?? DEFAULT_RULESET_NAME,
+      owner,
+      repository,
+      rules: {
+        deletion: true,
+        nonFastForward: true,
+        ...approvals === undefined ? {} : {
+          pullRequest: {
+            dismissStaleReviewsOnPush: true,
+            requiredApprovingReviewCount: approvals
+          }
+        },
+        ...checks.length === 0 ? {} : {
+          requiredStatusChecks: {
+            checks: checks.map((context) => ({ context })),
+            strictRequiredStatusChecksPolicy: false
+          }
+        }
+      },
+      target: "branch"
+    }
+  };
+}
+// src/github/repo-policy.ts
+import { adopt } from "alchemy/AdoptPolicy";
+import * as GitHub from "alchemy/GitHub";
+import * as RemovalPolicy from "alchemy/RemovalPolicy";
+import * as Effect from "effect/Effect";
+var declareRepoPolicy = (id, options) => Effect.gen(function* () {
+  const policy = yield* Effect.try({
+    catch: (cause) => cause instanceof Error ? cause : new Error(String(cause)),
+    try: () => repoPolicy(options)
+  });
+  const owned = (resource) => {
+    const kept = resource.pipe(RemovalPolicy.retain());
+    return options.adopt === undefined ? kept : kept.pipe(adopt(options.adopt));
+  };
+  const repository = yield* owned(GitHub.Repository(id, policy.repository));
+  const ruleset = yield* owned(GitHub.Ruleset(`${id}-ruleset`, policy.ruleset));
+  return { policy, repository, ruleset };
+});
+export {
+  declareRepoPolicy,
+  repoPolicy
+};
+
+//# debugId=1A73506791DB202C64756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/github/index.js.map

@@ -0,0 +1,12 @@
+{
+  "version": 3,
+  "sources": ["../src/github/repo-policy-guards.ts", "../src/github/repo-policy-form.ts", "../src/github/repo-policy.ts"],
+  "sourcesContent": [
+    "/**\n * Everything `repoPolicy` refuses, and why. Extracted from repo-policy-form.ts so the\n * shape stays readable and the reasoning stays whole.\n *\n * ⛔ FIVE DIFFERENT DOORS LEAD TO THE SAME FAILURE — auto-merge with nothing to wait for.\n *   `gh pr merge --auto` is a queue only while something is outstanding; with nothing\n *   outstanding GitHub merges the pull request on the spot. An empty `checks` is the\n *   obvious door. `enforcement: 'disabled'` or `'evaluate'` is the quiet one: the ruleset\n *   exists, the required checks are listed on it, and none of them block anything. Then\n *   three ways to end up with a ruleset that matches NO REF — which enforces on no ref\n *   while the GitHub UI still shows it as `active`: an empty `include`, a blank ref\n *   pattern, and an `exclude` that cancels every `include`. All five are refused.\n *\n * ★ THE REF DOORS WERE FOUND BY ADVERSARIAL REVIEW, NOT BY DESIGN. The first cut of this\n *   module guarded `include.length === 0` and spread `exclude` raw, so\n *   `include: ['~DEFAULT_BRANCH'], exclude: ['~DEFAULT_BRANCH']` and `include: ['   ']`\n *   both sailed through with `allowAutoMerge: true` — the exact end state the empty-array\n *   guard exists to prevent, reached by a door beside it. Checked by execution, not by\n *   reading: see the `matches no ref` tests in repo-policy-form.test.ts.\n */\n\n/** A non-empty, trimmed identifier, or an error naming the field. */\nexport function requireName(field: string, value: string): string {\n  const trimmed = value.trim();\n  if (trimmed === '') throw new Error(`repoPolicy: ${field} is required`);\n  return trimmed;\n}\n\n/**\n * Trim, de-duplicate, sort. ★ The sort is what makes a second deploy a no-op: GitHub\n * stores the contexts in the order they were sent, so an unsorted list would diff against\n * itself the first time a caller wrote the same contexts in a different order.\n */\nexport function normalizeChecks(checks: readonly string[]): string[] {\n  const seen = new Set<string>();\n  for (const raw of checks) {\n    const context = raw.trim();\n    // ⚠️ A blank context is a typo that reads as coverage: GitHub happily stores it and\n    //   no job ever reports it, so every pull request waits on a check that cannot come.\n    if (context === '') {\n      throw new Error(\n        'repoPolicy: a required check context is blank — name it exactly as the job reports it',\n      );\n    }\n    seen.add(context);\n  }\n  return [...seen].sort();\n}\n\n/**\n * Trim, de-duplicate, sort one list of ref patterns, refusing a blank one.\n *\n * ⚠️ A BLANK PATTERN IS NOT AN EMPTY LIST, AND THAT IS THE WHOLE TRAP. `['   ']` has\n *   length 1, so a guard that counts the array waves it through; GitHub then stores a ref\n *   condition that matches nothing. Same end state as `[]`, reached past the guard.\n * ★ Sorted for the same reason `normalizeChecks` is: GitHub echoes the patterns back in\n *   the order they were sent, so an unsorted list diffs against itself the first time a\n *   caller writes the same patterns in a different order.\n */\nfunction normalizeRefs(field: string, patterns: readonly string[]): string[] {\n  const seen = new Set<string>();\n  for (const raw of patterns) {\n    const pattern = raw.trim();\n    if (pattern === '') {\n      throw new Error(\n        `repoPolicy: a ${field} ref pattern is blank — a ruleset that matches no ref enforces nothing.`,\n      );\n    }\n    seen.add(pattern);\n  }\n  return [...seen].sort();\n}\n\n/**\n * ⛔ AN EMPTY `include` IS REFUSED. Alchemy defaults `conditions.include` to `['~ALL']`\n *   when it is absent, but an explicitly empty array is sent as an empty array, and a\n *   ruleset that matches no ref protects nothing while still reading as `active` in the\n *   GitHub UI — the worst possible combination, because it looks like it worked.\n */\nexport function normalizeInclude(\n  include: readonly string[] | undefined,\n  fallback: readonly string[],\n): string[] {\n  if (include === undefined) return [...fallback];\n  if (include.length === 0) {\n    throw new Error(\n      'repoPolicy: include is empty — a ruleset that matches no ref enforces nothing. Omit it for the default branch.',\n    );\n  }\n  return normalizeRefs('include', include);\n}\n\n/**\n * ⛔ AN `exclude` THAT CANCELS EVERY `include` IS REFUSED. In a GitHub ruleset the\n *   exclusions win, so `include: ['~DEFAULT_BRANCH'], exclude: ['~DEFAULT_BRANCH']` is a\n *   ruleset over nothing — and it reads as a narrowing, which is what makes it worse than\n *   the empty array: the caller believes they scoped the policy, not switched it off.\n *\n * ⚠️ EXACT CANCELLATION ONLY, DELIBERATELY. GitHub's patterns are globs, so deciding in\n *   general whether some exclude swallows some include means implementing GitHub's\n *   matcher and being wrong about it quietly. This refuses the case that is decidable —\n *   every include pattern also appears verbatim in `exclude` — and leaves\n *   `exclude: ['refs/heads/*']` against `include: ['~DEFAULT_BRANCH']` to the operator.\n *   A narrower guard that is always right beats a broad one that false-refuses.\n */\nexport function normalizeExclude(\n  exclude: readonly string[] | undefined,\n  include: readonly string[],\n): string[] {\n  const patterns = exclude === undefined ? [] : normalizeRefs('exclude', exclude);\n  if (patterns.length === 0) return patterns;\n  const excluded = new Set(patterns);\n  if (include.every((pattern) => excluded.has(pattern))) {\n    throw new Error(\n      [\n        'repoPolicy: exclude cancels every include pattern, so the ruleset matches no ref and enforces nothing.',\n        `include ${JSON.stringify(include)} is fully covered by exclude ${JSON.stringify(patterns)}.`,\n      ].join(' '),\n    );\n  }\n  return patterns;\n}\n\n/**\n * ⛔ `0` IS REFUSED, NOT TREATED AS \"NO REVIEWS\". A `pull_request` rule with zero\n *   approvals is the solo-maintainer shape — every change through a PR, no second person\n *   — and it only works with `require_extra_approval_for_unattributed_changes: false`.\n *   alchemy@2.0.0-beta.79's `Ruleset` cannot express that field, and GitHub defaults it\n *   to `true` when it is omitted (measured 2026-09-17), which blocks the very PRs the\n *   zero was meant to let through. Omitting `requiredApprovals` declares no rule at all,\n *   which is a different and honest thing.\n */\nexport function resolveApprovals(requested: number | undefined): number | undefined {\n  if (requested === undefined) return undefined;\n  if (!Number.isInteger(requested) || requested < 1) {\n    throw new Error(\n      [\n        'repoPolicy: requiredApprovals must be a whole number of 1 or more.',\n        'Omit it to declare no pull_request rule.',\n        '0 is not that: it needs require_extra_approval_for_unattributed_changes: false,',\n        'which alchemy@2.0.0-beta.79 cannot send and GitHub defaults to true.',\n      ].join(' '),\n    );\n  }\n  return requested;\n}\n\n/**\n * ⚠️ THE TEST IS \"SOMETHING OUTSTANDING\", NOT \"SOME CHECKS\". A required review holds a\n *   pull request open just as a required check does, so `requiredApprovals` with an empty\n *   `checks` is a legitimate policy. What is refused is auto-merge over a ruleset that\n *   will not hold anything back.\n */\nexport function assertAutoMergeWaits(input: {\n  readonly autoMerge: boolean;\n  readonly checkCount: number;\n  readonly approvals: number | undefined;\n  readonly enforcement: 'active' | 'disabled' | 'evaluate';\n}): void {\n  if (!input.autoMerge) return;\n  if (input.enforcement !== 'active') {\n    throw new Error(\n      [\n        `repoPolicy: autoMerge with enforcement '${input.enforcement}' merges every pull request immediately.`,\n        'A ruleset that is not active enforces none of its rules, so auto-merge has nothing to wait for.',\n        'Pass autoMerge: false while the ruleset is being evaluated.',\n      ].join(' '),\n    );\n  }\n  if (input.checkCount === 0 && input.approvals === undefined) {\n    throw new Error(\n      [\n        'repoPolicy: autoMerge with nothing required merges every pull request immediately.',\n        'Name at least one always-reporting check context, or ask for requiredApprovals,',\n        'or pass autoMerge: false for a repository that has no green run to require yet.',\n      ].join(' '),\n    );\n  }\n}\n",
+    "/**\n * `repoPolicy` — one repository's house merge policy, as plain Alchemy props.\n *\n * ★ PURE ON PURPOSE, AND TYPE-ONLY IMPORTS. The exact shape a stack will deploy can be\n *   asserted in a unit test with no credentials, no network and no Effect runtime.\n *   `repo-policy.ts` is the thin half that turns these props into resources, and\n *   `repo-policy-guards.ts` holds everything this refuses and why.\n *\n * ⛔ AUTO-MERGE WITH NOTHING TO WAIT FOR MERGES IMMEDIATELY. `gh pr merge --auto` is a\n *   queue only while something is outstanding. Five different inputs produce \"nothing\n *   outstanding\" — no `checks` and no `requiredApprovals`, an `enforcement` that is not\n *   `active`, and three ways to land a ruleset that matches no ref (an empty `include`, a\n *   blank ref pattern, an `exclude` that cancels every `include`). All five are refused.\n *   See the guards module.\n *\n * ⛔ EVERY CONTEXT IN `checks` MUST ALWAYS REPORT. A required context that never reports\n *   is not \"passed\", it is \"pending\", and the pull request waits on it forever —\n *   auto-merge included. Point this at an aggregate job that runs `if: always()` and\n *   fails when any upstream job did, never at a job behind a `paths:` filter, a matrix\n *   leg, or anything a skipped workflow can silence.\n */\nimport type { RepositoryProps, RulesetProps } from 'alchemy/GitHub';\nimport {\n  assertAutoMergeWaits,\n  normalizeChecks,\n  normalizeExclude,\n  normalizeInclude,\n  requireName,\n  resolveApprovals,\n} from './repo-policy-guards.ts';\n\n/** Alchemy's own bypass-actor shape, re-exported so a caller imports one module, not two. */\nexport type RepoPolicyBypassActor = NonNullable<RulesetProps['bypassActors']>[number];\n\n/**\n * Repository fields the policy does NOT own — description, topics, visibility, …\n * ⛔ Merged UNDERNEATH the policy, so a caller can describe their repo but cannot quietly\n *   re-enable merge commits through this door. The omitted keys are the policy itself.\n * ⛔ `baseUrl` IS OMITTED TOO, and is a top-level option instead. Setting it on only one\n *   of the two resources would point the repository at a GitHub Enterprise host and its\n *   ruleset at github.com — two halves of one policy on two different instances.\n */\nexport type RepoPolicyRepositorySettings = Omit<\n  RepositoryProps,\n  | 'allowAutoMerge'\n  | 'allowMergeCommit'\n  | 'allowRebaseMerge'\n  | 'allowSquashMerge'\n  | 'baseUrl'\n  | 'deleteBranchOnMerge'\n  | 'name'\n  | 'owner'\n>;\n\nexport interface RepoPolicyOptions {\n  /** Repository owner — a user or organization login. */\n  readonly owner: string;\n  /** Repository name. */\n  readonly repository: string;\n  /**\n   * Status-check contexts a pull request must pass, named exactly as the job reports\n   * them. Trimmed, de-duplicated and sorted, so re-ordering the list is not a diff.\n   */\n  readonly checks: readonly string[];\n  /** @default true — with nothing required it is refused, not quietly downgraded. */\n  readonly autoMerge?: boolean;\n  /** @default 'main' */\n  readonly rulesetName?: string;\n  /** Ref patterns the ruleset covers. @default ['~DEFAULT_BRANCH'] */\n  readonly include?: readonly string[];\n  /**\n   * Ref patterns exempted from it. @default []\n   * ⛔ Exclusions win over inclusions, so one that cancels every `include` is refused —\n   *   it reads as a narrowing and acts as an off switch.\n   */\n  readonly exclude?: readonly string[];\n  /** Who may bypass the ruleset. @default [] — nobody, administrators included. */\n  readonly bypassActors?: readonly RepoPolicyBypassActor[];\n  /**\n   * Approving reviews a pull request needs. Omit for none — `0` is refused rather than\n   * read as \"no reviews\"; `resolveApprovals` in the guards module says why.\n   */\n  readonly requiredApprovals?: number;\n  /** @default 'active' — anything else is refused alongside `autoMerge`. */\n  readonly enforcement?: 'active' | 'disabled' | 'evaluate';\n  /** GitHub Enterprise host, applied to BOTH resources or to neither. */\n  readonly baseUrl?: string;\n  /** Everything about the repository that is not merge policy. */\n  readonly settings?: RepoPolicyRepositorySettings;\n}\n\nexport interface RepoPolicy {\n  readonly repository: RepositoryProps;\n  readonly ruleset: RulesetProps;\n}\n\nconst DEFAULT_RULESET_NAME = 'main';\n/**\n * ★ `~DEFAULT_BRANCH`, NOT `refs/heads/main`. GitHub resolves it per repository, so one\n *   policy covers a repo whose default branch is `master` or `trunk`, and renaming the\n *   default branch later does not silently leave the ruleset pointing at nothing.\n */\nconst DEFAULT_INCLUDE: readonly string[] = ['~DEFAULT_BRANCH'];\n\n/**\n * The house policy for one repository: squash-only merges, auto-merge on, head branches\n * deleted, and a ruleset over the default branch that blocks deletion and force pushes\n * and requires `checks`.\n *\n * ★ `strictRequiredStatusChecksPolicy` IS ALWAYS FALSE, AND NOT A PARAMETER. \"Require\n *   branches to be up to date\" means every merge to the default branch invalidates every\n *   other open pull request, which with auto-merge on is a re-run storm that converges\n *   only when the queue empties. The checks still have to pass; they just do not have to\n *   have passed against the very tip.\n */\nexport function repoPolicy(options: RepoPolicyOptions): RepoPolicy {\n  const owner = requireName('owner', options.owner);\n  const repository = requireName('repository', options.repository);\n  const checks = normalizeChecks(options.checks);\n  const include = normalizeInclude(options.include, DEFAULT_INCLUDE);\n  const exclude = normalizeExclude(options.exclude, include);\n  const autoMerge = options.autoMerge ?? true;\n  const enforcement = options.enforcement ?? 'active';\n  const approvals = resolveApprovals(options.requiredApprovals);\n  assertAutoMergeWaits({ approvals, autoMerge, checkCount: checks.length, enforcement });\n  const host = options.baseUrl === undefined ? {} : { baseUrl: options.baseUrl };\n\n  return {\n    repository: {\n      ...options.settings,\n      ...host,\n      // ⛔ Squash only. The ruleset's own `allowed_merge_methods` is not reachable through\n      //   Alchemy's `pullRequest` rule, so the repository is the only place this holds.\n      allowAutoMerge: autoMerge,\n      allowMergeCommit: false,\n      allowRebaseMerge: false,\n      allowSquashMerge: true,\n      deleteBranchOnMerge: true,\n      name: repository,\n      owner,\n    },\n    ruleset: {\n      ...host,\n      bypassActors: [...(options.bypassActors ?? [])],\n      conditions: { exclude, include },\n      enforcement,\n      name: options.rulesetName ?? DEFAULT_RULESET_NAME,\n      owner,\n      repository,\n      rules: {\n        deletion: true,\n        nonFastForward: true,\n        ...(approvals === undefined\n          ? {}\n          : {\n              pullRequest: {\n                dismissStaleReviewsOnPush: true,\n                requiredApprovingReviewCount: approvals,\n              },\n            }),\n        ...(checks.length === 0\n          ? {}\n          : {\n              requiredStatusChecks: {\n                checks: checks.map((context) => ({ context })),\n                strictRequiredStatusChecksPolicy: false,\n              },\n            }),\n      },\n      target: 'branch',\n    },\n  };\n}\n",
+    "/**\n * `declareRepoPolicy` — the policy from repo-policy-form.ts, as resources.\n *\n *     const policy = yield* declareRepoPolicy('api', {\n *       owner: 'my-org',\n *       repository: 'api',\n *       checks: ['ci', 'secret scan'],\n *     });\n *\n * Provide `GitHub.providers()`; this subpath adds no provider of its own.\n *\n * ⛔ THE RULESET CANNOT BE ADOPTED, AND A FIRST DEPLOY ONTO A REPO THAT ALREADY HAS ONE\n *   MAKES A SECOND. Read out of alchemy@2.0.0-beta.79's own source on 2026-09-22\n *   (`node_modules/alchemy/lib/github/Ruleset.js`): `read` returns `undefined` whenever\n *   there is no prior output, and `reconcile` looks the live ruleset up only BY THE ID IN\n *   THAT OUTPUT — with none, it calls `createRepoRuleset` unconditionally. GitHub permits\n *   several rulesets with the same name on one repository, so nothing errors; the repo\n *   quietly ends up with two, both enforcing.\n *   ★ SO, BEFORE THE FIRST DEPLOY: `gh api repos/<owner>/<repo>/rulesets` and delete a\n *     hand-made ruleset of the same name, or give this one a `rulesetName` of its own.\n *     Afterwards the state carries the id and every later deploy converges that one.\n *   ⚠️ `GitHub.Repository` does NOT share the problem — its `reconcile` probes by name\n *     and converges onto whatever is live — so only half of this helper is adopt-safe,\n *     and the halves fail differently. See docs/repo-policy.md.\n *\n * ⛔ BOTH RESOURCES RETAIN. `retain` is already the vendor default for each of them; it\n *   is piped anyway so that a vendor change cannot quietly turn \"drop this call from the\n *   stack\" into \"delete the repository\" or \"unprotect the default branch\".\n */\nimport { adopt } from 'alchemy/AdoptPolicy';\nimport * as GitHub from 'alchemy/GitHub';\nimport * as RemovalPolicy from 'alchemy/RemovalPolicy';\nimport * as Effect from 'effect/Effect';\nimport { type RepoPolicyOptions, repoPolicy } from './repo-policy-form.ts';\n\nexport interface DeclareRepoPolicyOptions extends RepoPolicyOptions {\n  /**\n   * `true`/`false` pipe `adopt(…)` onto both resources; omitted, the deploy's own policy\n   * decides. ⚠️ It changes nothing about the ruleset hazard above: adoption routes on\n   * what a provider's `read` reports, and this one reports nothing without prior state.\n   */\n  readonly adopt?: boolean;\n}\n\n/**\n * Declares the repository and its ruleset under `<id>` and `<id>-ruleset`. Fails, before\n * declaring either, on any policy the form refuses.\n */\nexport const declareRepoPolicy = (id: string, options: DeclareRepoPolicyOptions) =>\n  Effect.gen(function* () {\n    const policy = yield* Effect.try({\n      catch: (cause) => (cause instanceof Error ? cause : new Error(String(cause))),\n      try: () => repoPolicy(options),\n    });\n    // ⚠️ `never` in the error channel, not a generic `E`: `AdoptPolicy.adopt` is typed\n    //   `Effect<A, never, R> => Effect<A, never, R>`, so a wider error type fails to\n    //   compile here rather than at the call site. Alchemy's resources declare `never`.\n    const owned = <A, R>(resource: Effect.Effect<A, never, R>) => {\n      const kept = resource.pipe(RemovalPolicy.retain());\n      return options.adopt === undefined ? kept : kept.pipe(adopt(options.adopt));\n    };\n    const repository = yield* owned(GitHub.Repository(id, policy.repository));\n    const ruleset = yield* owned(GitHub.Ruleset(`${id}-ruleset`, policy.ruleset));\n    return { policy, repository, ruleset };\n  });\n"
+  ],
+  "mappings": "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",
+  "debugId": "1A73506791DB202C64756E2164756E21",
+  "names": []
+}

package/dist/github/repo-policy-form.d.ts

@@ -0,0 +1,86 @@
+/**
+ * `repoPolicy` — one repository's house merge policy, as plain Alchemy props.
+ *
+ * ★ PURE ON PURPOSE, AND TYPE-ONLY IMPORTS. The exact shape a stack will deploy can be
+ *   asserted in a unit test with no credentials, no network and no Effect runtime.
+ *   `repo-policy.ts` is the thin half that turns these props into resources, and
+ *   `repo-policy-guards.ts` holds everything this refuses and why.
+ *
+ * ⛔ AUTO-MERGE WITH NOTHING TO WAIT FOR MERGES IMMEDIATELY. `gh pr merge --auto` is a
+ *   queue only while something is outstanding. Five different inputs produce "nothing
+ *   outstanding" — no `checks` and no `requiredApprovals`, an `enforcement` that is not
+ *   `active`, and three ways to land a ruleset that matches no ref (an empty `include`, a
+ *   blank ref pattern, an `exclude` that cancels every `include`). All five are refused.
+ *   See the guards module.
+ *
+ * ⛔ EVERY CONTEXT IN `checks` MUST ALWAYS REPORT. A required context that never reports
+ *   is not "passed", it is "pending", and the pull request waits on it forever —
+ *   auto-merge included. Point this at an aggregate job that runs `if: always()` and
+ *   fails when any upstream job did, never at a job behind a `paths:` filter, a matrix
+ *   leg, or anything a skipped workflow can silence.
+ */
+import type { RepositoryProps, RulesetProps } from 'alchemy/GitHub';
+/** Alchemy's own bypass-actor shape, re-exported so a caller imports one module, not two. */
+export type RepoPolicyBypassActor = NonNullable<RulesetProps['bypassActors']>[number];
+/**
+ * Repository fields the policy does NOT own — description, topics, visibility, …
+ * ⛔ Merged UNDERNEATH the policy, so a caller can describe their repo but cannot quietly
+ *   re-enable merge commits through this door. The omitted keys are the policy itself.
+ * ⛔ `baseUrl` IS OMITTED TOO, and is a top-level option instead. Setting it on only one
+ *   of the two resources would point the repository at a GitHub Enterprise host and its
+ *   ruleset at github.com — two halves of one policy on two different instances.
+ */
+export type RepoPolicyRepositorySettings = Omit<RepositoryProps, 'allowAutoMerge' | 'allowMergeCommit' | 'allowRebaseMerge' | 'allowSquashMerge' | 'baseUrl' | 'deleteBranchOnMerge' | 'name' | 'owner'>;
+export interface RepoPolicyOptions {
+    /** Repository owner — a user or organization login. */
+    readonly owner: string;
+    /** Repository name. */
+    readonly repository: string;
+    /**
+     * Status-check contexts a pull request must pass, named exactly as the job reports
+     * them. Trimmed, de-duplicated and sorted, so re-ordering the list is not a diff.
+     */
+    readonly checks: readonly string[];
+    /** @default true — with nothing required it is refused, not quietly downgraded. */
+    readonly autoMerge?: boolean;
+    /** @default 'main' */
+    readonly rulesetName?: string;
+    /** Ref patterns the ruleset covers. @default ['~DEFAULT_BRANCH'] */
+    readonly include?: readonly string[];
+    /**
+     * Ref patterns exempted from it. @default []
+     * ⛔ Exclusions win over inclusions, so one that cancels every `include` is refused —
+     *   it reads as a narrowing and acts as an off switch.
+     */
+    readonly exclude?: readonly string[];
+    /** Who may bypass the ruleset. @default [] — nobody, administrators included. */
+    readonly bypassActors?: readonly RepoPolicyBypassActor[];
+    /**
+     * Approving reviews a pull request needs. Omit for none — `0` is refused rather than
+     * read as "no reviews"; `resolveApprovals` in the guards module says why.
+     */
+    readonly requiredApprovals?: number;
+    /** @default 'active' — anything else is refused alongside `autoMerge`. */
+    readonly enforcement?: 'active' | 'disabled' | 'evaluate';
+    /** GitHub Enterprise host, applied to BOTH resources or to neither. */
+    readonly baseUrl?: string;
+    /** Everything about the repository that is not merge policy. */
+    readonly settings?: RepoPolicyRepositorySettings;
+}
+export interface RepoPolicy {
+    readonly repository: RepositoryProps;
+    readonly ruleset: RulesetProps;
+}
+/**
+ * The house policy for one repository: squash-only merges, auto-merge on, head branches
+ * deleted, and a ruleset over the default branch that blocks deletion and force pushes
+ * and requires `checks`.
+ *
+ * ★ `strictRequiredStatusChecksPolicy` IS ALWAYS FALSE, AND NOT A PARAMETER. "Require
+ *   branches to be up to date" means every merge to the default branch invalidates every
+ *   other open pull request, which with auto-merge on is a re-run storm that converges
+ *   only when the queue empties. The checks still have to pass; they just do not have to
+ *   have passed against the very tip.
+ */
+export declare function repoPolicy(options: RepoPolicyOptions): RepoPolicy;
+//# sourceMappingURL=repo-policy-form.d.ts.map

package/dist/github/repo-policy-form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-policy-form.d.ts","sourceRoot":"","sources":["../../src/github/repo-policy-form.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAUpE,6FAA6F;AAC7F,MAAM,MAAM,qBAAqB,GAAG,WAAW,CAAC,YAAY,CAAC,cAAc,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtF;;;;;;;GAOG;AACH,MAAM,MAAM,4BAA4B,GAAG,IAAI,CAC7C,eAAe,EACb,gBAAgB,GAChB,kBAAkB,GAClB,kBAAkB,GAClB,kBAAkB,GAClB,SAAS,GACT,qBAAqB,GACrB,MAAM,GACN,OAAO,CACV,CAAC;AAEF,MAAM,WAAW,iBAAiB;IAChC,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uBAAuB;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,mFAAmF;IACnF,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,sBAAsB;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,oEAAoE;IACpE,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,iFAAiF;IACjF,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACzD;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAC;IAC1D,uEAAuE;IACvE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,CAAC,EAAE,4BAA4B,CAAC;CAClD;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;CAChC;AAUD;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,UAAU,CAyDjE"}

package/dist/github/repo-policy-guards.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Everything `repoPolicy` refuses, and why. Extracted from repo-policy-form.ts so the
+ * shape stays readable and the reasoning stays whole.
+ *
+ * ⛔ FIVE DIFFERENT DOORS LEAD TO THE SAME FAILURE — auto-merge with nothing to wait for.
+ *   `gh pr merge --auto` is a queue only while something is outstanding; with nothing
+ *   outstanding GitHub merges the pull request on the spot. An empty `checks` is the
+ *   obvious door. `enforcement: 'disabled'` or `'evaluate'` is the quiet one: the ruleset
+ *   exists, the required checks are listed on it, and none of them block anything. Then
+ *   three ways to end up with a ruleset that matches NO REF — which enforces on no ref
+ *   while the GitHub UI still shows it as `active`: an empty `include`, a blank ref
+ *   pattern, and an `exclude` that cancels every `include`. All five are refused.
+ *
+ * ★ THE REF DOORS WERE FOUND BY ADVERSARIAL REVIEW, NOT BY DESIGN. The first cut of this
+ *   module guarded `include.length === 0` and spread `exclude` raw, so
+ *   `include: ['~DEFAULT_BRANCH'], exclude: ['~DEFAULT_BRANCH']` and `include: ['   ']`
+ *   both sailed through with `allowAutoMerge: true` — the exact end state the empty-array
+ *   guard exists to prevent, reached by a door beside it. Checked by execution, not by
+ *   reading: see the `matches no ref` tests in repo-policy-form.test.ts.
+ */
+/** A non-empty, trimmed identifier, or an error naming the field. */
+export declare function requireName(field: string, value: string): string;
+/**
+ * Trim, de-duplicate, sort. ★ The sort is what makes a second deploy a no-op: GitHub
+ * stores the contexts in the order they were sent, so an unsorted list would diff against
+ * itself the first time a caller wrote the same contexts in a different order.
+ */
+export declare function normalizeChecks(checks: readonly string[]): string[];
+/**
+ * ⛔ AN EMPTY `include` IS REFUSED. Alchemy defaults `conditions.include` to `['~ALL']`
+ *   when it is absent, but an explicitly empty array is sent as an empty array, and a
+ *   ruleset that matches no ref protects nothing while still reading as `active` in the
+ *   GitHub UI — the worst possible combination, because it looks like it worked.
+ */
+export declare function normalizeInclude(include: readonly string[] | undefined, fallback: readonly string[]): string[];
+/**
+ * ⛔ AN `exclude` THAT CANCELS EVERY `include` IS REFUSED. In a GitHub ruleset the
+ *   exclusions win, so `include: ['~DEFAULT_BRANCH'], exclude: ['~DEFAULT_BRANCH']` is a
+ *   ruleset over nothing — and it reads as a narrowing, which is what makes it worse than
+ *   the empty array: the caller believes they scoped the policy, not switched it off.
+ *
+ * ⚠️ EXACT CANCELLATION ONLY, DELIBERATELY. GitHub's patterns are globs, so deciding in
+ *   general whether some exclude swallows some include means implementing GitHub's
+ *   matcher and being wrong about it quietly. This refuses the case that is decidable —
+ *   every include pattern also appears verbatim in `exclude` — and leaves
+ *   `exclude: ['refs/heads/*']` against `include: ['~DEFAULT_BRANCH']` to the operator.
+ *   A narrower guard that is always right beats a broad one that false-refuses.
+ */
+export declare function normalizeExclude(exclude: readonly string[] | undefined, include: readonly string[]): string[];
+/**
+ * ⛔ `0` IS REFUSED, NOT TREATED AS "NO REVIEWS". A `pull_request` rule with zero
+ *   approvals is the solo-maintainer shape — every change through a PR, no second person
+ *   — and it only works with `require_extra_approval_for_unattributed_changes: false`.
+ *   alchemy@2.0.0-beta.79's `Ruleset` cannot express that field, and GitHub defaults it
+ *   to `true` when it is omitted (measured 2026-09-17), which blocks the very PRs the
+ *   zero was meant to let through. Omitting `requiredApprovals` declares no rule at all,
+ *   which is a different and honest thing.
+ */
+export declare function resolveApprovals(requested: number | undefined): number | undefined;
+/**
+ * ⚠️ THE TEST IS "SOMETHING OUTSTANDING", NOT "SOME CHECKS". A required review holds a
+ *   pull request open just as a required check does, so `requiredApprovals` with an empty
+ *   `checks` is a legitimate policy. What is refused is auto-merge over a ruleset that
+ *   will not hold anything back.
+ */
+export declare function assertAutoMergeWaits(input: {
+    readonly autoMerge: boolean;
+    readonly checkCount: number;
+    readonly approvals: number | undefined;
+    readonly enforcement: 'active' | 'disabled' | 'evaluate';
+}): void;
+//# sourceMappingURL=repo-policy-guards.d.ts.map

package/dist/github/repo-policy-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-policy-guards.d.ts","sourceRoot":"","sources":["../../src/github/repo-policy-guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,qEAAqE;AACrE,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAIhE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAcnE;AA0BD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACtC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,MAAM,EAAE,CAQV;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACtC,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB,MAAM,EAAE,CAaV;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAalF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC1C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,WAAW,EAAE,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAC;CAC1D,GAAG,IAAI,CAoBP"}

package/dist/github/repo-policy.d.ts

@@ -0,0 +1,21 @@
+import * as GitHub from 'alchemy/GitHub';
+import * as Effect from 'effect/Effect';
+import { type RepoPolicyOptions } from './repo-policy-form.ts';
+export interface DeclareRepoPolicyOptions extends RepoPolicyOptions {
+    /**
+     * `true`/`false` pipe `adopt(…)` onto both resources; omitted, the deploy's own policy
+     * decides. ⚠️ It changes nothing about the ruleset hazard above: adoption routes on
+     * what a provider's `read` reports, and this one reports nothing without prior state.
+     */
+    readonly adopt?: boolean;
+}
+/**
+ * Declares the repository and its ruleset under `<id>` and `<id>-ruleset`. Fails, before
+ * declaring either, on any policy the form refuses.
+ */
+export declare const declareRepoPolicy: (id: string, options: DeclareRepoPolicyOptions) => Effect.Effect<{
+    policy: import("./repo-policy-form.ts").RepoPolicy;
+    repository: GitHub.Repository;
+    ruleset: GitHub.Ruleset;
+}, Error, GitHub.Providers>;
+//# sourceMappingURL=repo-policy.d.ts.map

package/dist/github/repo-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-policy.d.ts","sourceRoot":"","sources":["../../src/github/repo-policy.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,MAAM,MAAM,gBAAgB,CAAC;AAEzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,KAAK,iBAAiB,EAAc,MAAM,uBAAuB,CAAC;AAE3E,MAAM,WAAW,wBAAyB,SAAQ,iBAAiB;IACjE;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,OAAQ,MAAM,WAAW,wBAAwB;;;;2BAgB3E,CAAC"}

package/dist/index.d.ts

@@ -6,6 +6,7 @@
  *
  *     import { R2BucketLock } from '@homeflare/alchemy/cloudflare';
  *     import { BranchProtection } from '@homeflare/alchemy/forgejo';
+ *     import { declareRepoPolicy } from '@homeflare/alchemy/github';
  *     import { BaoMount } from '@homeflare/alchemy/openbao';
  *     import { TalosCluster } from '@homeflare/alchemy/talos';
  *     import { ProxmoxAcl } from '@homeflare/alchemy/proxmox';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,CAAC"}

package/docs/repo-policy-ruleset-hazards.md

@@ -0,0 +1,65 @@
+# `declareRepoPolicy` — the ruleset half's hazards
+
+Everything here is about `GitHub.Ruleset` in `alchemy@2.0.0-beta.79`, not about the
+policy this kit declares. It is extracted from [repo-policy.md](./repo-policy.md) so the
+reasoning stays whole rather than being shaved to fit a line cap.
+
+⚠️ **`GitHub.Repository` shares none of it.** Its `reconcile` probes by name, converges
+onto whatever is live, and `PATCH`es only the fields it holds. The two halves of the
+helper fail differently, which is the whole reason this file exists.
+
+## ⛔ The ruleset cannot be adopted — it duplicates
+
+Read out of `alchemy@2.0.0-beta.79`'s own source on 2026-09-22
+(`node_modules/alchemy/lib/github/Ruleset.js`):
+
+- `read` returns `undefined` whenever there is no prior `output`. Alchemy's adoption
+  routes on what `read` reports, so with no state the engine plans a **create**.
+- `reconcile` looks the live ruleset up **only by the id in that output**. With none, it
+  calls `createRepoRuleset` unconditionally — it never searches by name.
+
+GitHub permits several rulesets with the same name on one repository, so nothing errors.
+The repository quietly ends up with **two `main` rulesets, both enforcing**, and the
+second one is the only one Alchemy will ever converge.
+
+**Before the first deploy onto a repository that already has a ruleset:**
+
+```sh
+gh api repos/<owner>/<repo>/rulesets --jq '.[] | select(.target=="branch") | "\(.id) \(.name)"'
+```
+
+Delete the hand-made ruleset of the same name, or give this one a `rulesetName` of its
+own. After the first deploy the state carries the id and every later deploy converges
+that one ruleset.
+
+★ **Or take the repository half only.** `repoPolicy` returns the two prop objects
+separately, so a stack whose ruleset is already owned by something else can declare the
+settings that adopt cleanly and leave the ruleset alone:
+
+```ts
+yield * GitHub.Repository('api', repoPolicy({ owner, repository, checks }).repository);
+```
+
+⚠️ **`GitHub.Repository` does not share the problem.** Its `reconcile` probes by name and
+converges onto whatever is live, so the repository half adopts cleanly on the first
+deploy even though the plan prints `create`. The two halves of this helper fail
+differently, which is exactly why it is worth writing down.
+
+⛔ **The ruleset half never plans a no-op — measured, not inferred.** Alchemy `deepEqual`s
+the live ruleset against the parameters **it** builds, and it builds a strict subset of
+what GitHub stores. Read live on 2026-09-22 from this repo's own ruleset, GitHub returns
+`required_status_checks.parameters.do_not_enforce_on_create: false` and, on a
+`pull_request` rule, `required_reviewers`, `allowed_merge_methods` and
+`require_extra_approval_for_unattributed_changes` — none of which Alchemy sends. The
+comparison is therefore unequal **forever**, and every deploy issues an idempotent
+`updateRepoRuleset`. It is convergence noise, not drift: the write is the same payload
+each time. But do not expect a clean plan, and do not read the write as a change.
+
+⛔ **The ruleset's `rules` and `bypass_actors` are replaced wholesale, not merged.**
+Alchemy sends the full desired list. Any rule type this helper does not express —
+`creation`, `update`, `required_linear_history`, `required_signatures`,
+`required_deployments`, tag and file-path rules — is **dropped** from a ruleset Alchemy
+owns, as is any bypass actor added by hand. Because the ruleset cannot be adopted this
+cannot wipe a pre-existing one on a first deploy; it bites on a ruleset Alchemy created
+that someone later edited in the GitHub UI. The repository half does not behave this way:
+Alchemy `PATCH`es only the fields it holds, so settings outside `settings` are untouched.