@homeflare/alchemy 0.25.1 → 0.27.0

package/docs/repository-ruleset.md

@@ -0,0 +1,114 @@
+# `GitHub.RepositoryRuleset`
+
+A bridge resource for the one thing upstream `GitHub.Ruleset` cannot do: find a ruleset
+that already exists, by name, before creating a second one with the same name. See
+[repository-ruleset.ts](../src/github/repository-ruleset.ts) for the full hazard writeup
+and [repo-policy-ruleset-hazards.md](./repo-policy-ruleset-hazards.md) for the upstream
+behavior this closes.
+
+```ts
+import { RepositoryRuleset, RepositoryRulesetProvider } from '@homeflare/alchemy/github';
+import * as GitHub from 'alchemy/GitHub';
+import * as Effect from 'effect/Effect';
+
+Effect.gen(function* () {
+  yield* RepositoryRuleset('main-ruleset', {
+    owner: 'taslabs-net',
+    repository: 'widgets',
+    name: 'main',
+    rules: {
+      deletion: true,
+      nonFastForward: true,
+      pullRequest: {
+        requiredApprovingReviewCount: 0,
+        allowedMergeMethods: ['squash'],
+        extraApprovalForUnattributedChanges: false,
+      },
+      requiredStatusChecks: { checks: [{ context: 'ci' }, { context: 'secret scan' }] },
+    },
+  });
+});
+```
+
+Provide **both** `GitHub.providers()` (for `GitHub.Repository`, if declared alongside) and
+`RepositoryRulesetProvider()` — this is a separate `Provider`, registered under its own
+type string (`GitHub.RepositoryRuleset`), not inside upstream's `GitHub.Providers`
+collection. The two coexist in one stack without any change to upstream's own code.
+
+## Type string: H14
+
+`GitHub.RepositoryRuleset` sits inside upstream's own `GitHub` namespace — the standard's
+gap H14, recorded rather than avoided. The alternative was `HomeFlare.GitHub.Ruleset`;
+`GitHub.RepositoryRuleset` was chosen because it is GitHub's own term for the object
+(`repository-ruleset` in the OpenAPI schema) and reads naturally beside `GitHub.Ruleset`.
+
+## Client: Octokit, not distilled — H15
+
+`@distilled.cloud/github@1.0.0-rc.12` has `createRepoRuleset`/`updateRepoRuleset`, but its
+request bodies are `effect/Schema` `S.Struct`s with no field for
+`require_extra_approval_for_unattributed_changes` — the flag this whole resource exists
+for (see below). Octokit's request builder was MEASURED
+(`repository-ruleset-wire.test.ts`, a real `@octokit/rest` instance with a fetch shim, no
+network) to forward that untyped key onto the wire unchanged. The client itself is not
+hand-rolled: it is built from `GitHubCredentials`/`creds.octokit()`, upstream's own
+exported credential service.
+
+## What it models beyond upstream `RulesetProps`
+
+| field                                             | upstream `Ruleset` | this resource      |
+| ------------------------------------------------- | ------------------ | ------------------ |
+| `pullRequest.allowedMergeMethods`                 | no                 | yes                |
+| `pullRequest.requiredReviewers`                   | no                 | yes                |
+| `pullRequest.extraApprovalForUnattributedChanges` | no                 | `false` only (H15) |
+| `requiredStatusChecks.doNotEnforceOnCreate`       | no                 | yes                |
+
+`RULE_TYPE_COVERAGE` in `repository-ruleset-constraints.ts` classifies every rule type
+Octokit's own installed types know (21 of them — see the file for the 27.0.0-vs-29.0.1
+version note) as `'modeled'` or `'refused'`; a live rule of a refused type, or a modeled
+`pull_request` the declaration says nothing about, fails the plan by name rather than
+being silently dropped by the wholesale `rules` PUT.
+
+## What it refuses, and never does
+
+- **A second same-named ruleset**: `DuplicateRuleset`, before reading either one.
+- **Widening `bypassActors`**: refused on update; `undefined` means unmanaged (the live
+  value is carried forward unchanged), not "clear it".
+- **A live rule of an unmodeled type**, or a live rule of ANY modeled type the
+  declaration omits by silence rather than by explicitly saying `false`: refused, naming
+  the field. This covers every rule, not only `pull_request`/`requiredStatusChecks` —
+  see `undeclaredLiveRuleRefusal`'s own comment for the concrete scenario (forgetting
+  `deletion: true` would otherwise silently drop branch-deletion protection) that made
+  this the general case rather than a special one.
+- **Adding a required check that has never reported success** on the default branch's
+  current tip (checks + statuses): refused before any write. Documented limitation: this
+  checks the current tip only, not full history (repository-ruleset-octokit.ts).
+- **A readback mismatch**: after any write, an INDEPENDENT `GET` — never the write's own
+  response — is compared against what was sent for the approval count, merge methods and
+  the extension flag. A mismatch fails the plan.
+
+## Never-noop, fixed
+
+Upstream `Ruleset#reconcile` compares its desired object against the live GET with a raw
+`deepEqual` — no normalization. GitHub does not promise to echo `rules`, checks or merge
+methods back in request order, and a live check carries `integration_id: null` where the
+request never sent the key. `canonicalizeWireRuleset` (repository-ruleset-form.ts) sorts
+every list with no meaningful order (recursively, key order included — see its own
+comment for the bug that finding produced) before two wire rulesets are ever compared, so
+a repository whose live ruleset already matches the declaration makes **zero** API calls.
+
+## Removal policy
+
+`retain`, always — deleting a ruleset takes an explicit `RemovalPolicy.destroy()` from the
+caller, the same as upstream `GitHub.Ruleset`.
+
+## Tests
+
+- `repository-ruleset-lifecycle.test.ts` — a GET-only loopback fake serving the 16 live
+  rulesets this family was walked against; the house baseline's real drift against every
+  one, and the canonicalization/mutation checks.
+- `repository-ruleset-write.test.ts` / `-write-refusals.test.ts` — a write-recording fake:
+  what a create sends, zero writes on a noop or a refusal, exactly one update on real
+  drift, and the readback check.
+- `repository-ruleset-wire.test.ts` — the H15 measurement against a real Octokit instance.
+- `repository-ruleset-coverage.test.ts` — the rule-type coverage change detector (the
+  completeness guarantee itself is enforced by `tsc`, not this file — see its header).

package/docs/upstream-conformance.md

@@ -94,11 +94,22 @@ then tidiness.
 
 ## Conforms
 
+- **`github/RepositoryRuleset`** (added 2026-09-23) closes the hazard the row above names:
+  probes by name (`read`/`reconcile` both), answers `Unowned` on a cold name match (H1),
+  normalizes before comparing so a matching live ruleset is a true noop, and refuses
+  (rather than silently drops) a live rule type it does not model. Two recorded
+  divergences: the type string sits in upstream's own `GitHub` namespace (H14), and the
+  client is Octokit rather than distilled because distilled's `S.Struct` request schemas
+  have no field for `require_extra_approval_for_unattributed_changes` (H15) — see
+  [repository-ruleset.md](./repository-ruleset.md). `declareRepoPolicy` is rewired onto
+  it; the row below is now describing upstream `GitHub.Ruleset` itself, which this family
+  does not touch and remains usable directly.
 - **`github/declareRepoPolicy`** composes upstream `GitHub.Repository` and
   `GitHub.Ruleset`. Its one hazard is upstream's own: `Ruleset.read` returns `undefined`
   without prior output, so a first deploy creates a duplicate
   ([repo-policy.md](./repo-policy.md)). The fix belongs upstream: read by name and answer
-  `Unowned`.
+  `Unowned`. Since 2026-09-23 `declareRepoPolicy` no longer takes this path (see the
+  `RepositoryRuleset` row above); this remains accurate for upstream `Ruleset` on its own.
 - **`cloudflare/website.ts`** sets house defaults over upstream `Website.Astro` and
   `Website.Vite`.
 - **`ownership/*`** is built only on `AdoptPolicy`, `Stack`, `State` and `Artifacts`. Its

package/docs/upstream-pr-ruleset-fixes.md

@@ -0,0 +1,77 @@
+# Draft: two upstream PRs to `alchemy-run/alchemy`
+
+**Not posted.** Posting either is Tim's decision (alchemy-provider-standard's boundary:
+"posting anything to an upstream repository is Tim's decision. Ask first, with options
+and a recommendation."). This is the recommendation, drafted 2026-09-23 alongside
+`GitHub.RepositoryRuleset`, the house's stopgap for PR 1 below.
+
+## PR 1: `GitHub.Ruleset` — adopt by name, normalize before comparing
+
+**Target**: `packages/alchemy/src/GitHub/Ruleset.ts`, pinned tag `v2.0.0-beta.79`.
+
+**Problem** (measured from the source, see `repository-ruleset.ts`'s header):
+`reconcile`'s `observed` lookup is `output === undefined ? undefined :
+getRuleset(news, output.rulesetId)` — with no prior state it never searches by name, so a
+first deploy onto a repository that already has a same-named ruleset creates a **second**
+one. Separately, the `deepEqual` compare in the same function has no normalization: rule
+order, `allowed_merge_methods` order, check order, and `integration_id: null` vs an
+omitted key all make a matching live ruleset compare unequal, so a converged stack issues
+an idempotent `updateRepoRuleset` on every single plan.
+
+**Proposed fix**, following the shape `RepositoryRuleset` already proves out:
+
+1. `read`, with `output === undefined`: list the repo's rulesets
+   (`octokit.paginate(getRepoRulesets, { includes_parents: false })`), filter by
+   `name`/`target`. Zero matches → `undefined`. One → `GET` by id, wrap `Unowned(attrs)`
+   (H1: identical is not automatically ours). More than one → a typed failure naming
+   every id, before reading any of them — `alchemy`'s `Data.TaggedError` convention.
+2. `reconcile`'s observe step: the same name-probe when `output` is absent.
+3. Normalize both sides of the `deepEqual` (or switch to Alchemy's own `deepEqual` plus a
+   canonicalization pass) before comparing: sort `rules` by `type`, sort
+   `allowed_merge_methods`, sort `required_status_checks` by context, and drop
+   `integration_id: null` before comparing.
+
+**Compatibility**: additive. A caller with no prior state today gets a `create`; after
+the fix, a repository with an existing same-named ruleset gets an adopt instead — a
+behavior change, but the current behavior (silently making a duplicate) is the bug.
+
+**House stopgap**: `GitHub.RepositoryRuleset` in this package, retained until this lands
+and releases, then retired per alchemy-provider-standard's retirement steps (drop the kit
+declaration, declare `GitHub.Ruleset` with `adopt(true)`, the fixed read-by-name adopts
+it).
+
+## PR 2: `GitHub.RulesetProps` — the fields this house needed and upstream lacks
+
+**Target**: same file, same tag.
+
+**Fields to add** to `rules.pullRequest`:
+
+- `allowedMergeMethods?: ('merge' | 'squash' | 'rebase')[]` — GitHub's own schema
+  (`repository-rule-pull-request`, both `@octokit/openapi-types` 27.0.0 and 29.0.1 this
+  checkout has read) already carries `allowed_merge_methods`; Alchemy's props do not.
+- `requiredReviewers?: { filePatterns: string[]; minimumApprovals: number; reviewer: {
+id: number; type: 'Team' } }[]` — same schema, `required_reviewers` (beta per GitHub's
+  own doc comment, but already live and typed).
+
+And to `rules.requiredStatusChecks`:
+
+- `doNotEnforceOnCreate?: boolean` — the schema's `do_not_enforce_on_create`.
+
+**Deliberately NOT proposed**: `require_extra_approval_for_unattributed_changes`. It
+appears in ZERO of the schemas this house has read — not GitHub's own
+`rest-api-description` at commit `4377b4f4845b` (measured 2026-09-23, 0 occurrences), not
+either installed `@octokit/openapi-types` (27.0.0 or 29.0.1). It is real and round-trips
+live (this estate's own rulesets carry it — LIVE SURVEY 2026-09-23), but proposing a
+field GitHub has not documented anywhere upstream can point to is a different, weaker
+kind of PR. `GitHub.RepositoryRuleset` sends it as an untyped extra key on the request
+body (H15, measured in `repository-ruleset-wire.test.ts`) precisely because it has no
+home in a typed prop upstream would accept today.
+
+**Compatibility**: additive, no behavior change for an existing caller.
+
+## Sequencing
+
+PR 2 is safe to post on its own, any time — it adds optional fields nothing currently
+sets. PR 1 is the one worth discussing with a maintainer first: the adopt-by-name
+behavior change, even though it fixes a bug, is a visible difference for anyone who
+relied on (or never noticed) the duplicate-ruleset behavior.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.25.1",
+  "version": "0.27.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",

package/src/github/declare-repo-baseline.ts

@@ -0,0 +1,42 @@
+/**
+ * `declareRepoBaseline` — the house GitHub baseline (repo-baseline-data.ts), as resources.
+ *
+ *     const baseline = yield* declareRepoBaseline('api', {
+ *       owner: 'taslabs-net',
+ *       repository: 'api',
+ *       checks: ['ci', 'secret scan'],
+ *       visibility: 'private',
+ *     });
+ *
+ * Provide `GitHub.providers()` AND `RepositoryRulesetProvider()` — this subpath ships no
+ * provider of its own, the same as `declareRepoPolicy`. Both resources are `retain` and
+ * `adopt(true)` ALWAYS, unlike `declareRepoPolicy`'s optional `adopt` — a baseline this widely
+ * shared is meant for a checkout adopting the estate's existing repository and ruleset by name,
+ * never for creating one out from under a caller who forgot the flag (H1: a name match is not
+ * ours until adopted).
+ *
+ * ⛔ NO IMPORT FROM `@homeflare/config`, either direction — see `renderRepoShape`'s own header
+ *   in `packages/config/src/repo-shape/render.ts`. A caller spreads `renderRepoShape(shape)
+ *   .policy` into these options itself; `checks` only needs to be `readonly string[]`.
+ */
+import { adopt } from 'alchemy/AdoptPolicy';
+import * as GitHub from 'alchemy/GitHub';
+import * as RemovalPolicy from 'alchemy/RemovalPolicy';
+import * as Effect from 'effect/Effect';
+import {
+  type RepoBaselineInput,
+  repoBaselineRuleset,
+  repoBaselineSettings,
+} from './repo-baseline-data.ts';
+import { RepositoryRuleset } from './repository-ruleset.ts';
+
+export interface DeclareRepoBaselineOptions extends RepoBaselineInput {}
+
+export const declareRepoBaseline = (id: string, options: DeclareRepoBaselineOptions) =>
+  Effect.gen(function* () {
+    const owned = <A, R>(resource: Effect.Effect<A, never, R>) =>
+      resource.pipe(RemovalPolicy.retain(), adopt(true));
+    const repository = yield* owned(GitHub.Repository(id, repoBaselineSettings(options)));
+    const ruleset = yield* owned(RepositoryRuleset(`${id}-ruleset`, repoBaselineRuleset(options)));
+    return { repository, ruleset };
+  });

package/src/github/index.ts

@@ -1,17 +1,21 @@
 /**
- * GitHub helpers for Alchemy — one repository's house policy in one call.
+ * GitHub helpers for Alchemy — one repository's house policy in one call, and (2026-09-23) the
+ * one bridge resource this house builds atop upstream GitHub: `GitHub.RepositoryRuleset`.
  *
- * ⛔ 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.
+ * ⚠️ `declareRepoPolicy`/`declareRepoBaseline` COMPOSE UPSTREAM `GitHub.Repository` PLUS THIS
+ *   SUBPATH'S OWN `RepositoryRulesetProvider()` — provide BOTH `GitHub.providers()` and
+ *   `RepositoryRulesetProvider()`. Before 2026-09-23 this subpath shipped no provider at all,
+ *   composing only vendor resources; `RepositoryRuleset` is the one exception, and
+ *   repository-ruleset.ts's header says why upstream's own `Ruleset` cannot fill the gap.
+ * ★ WHY THE POLICY HELPERS EXIST. "Open a pull request, let auto-merge land it" is safe only
+ *   when five repository properties and four ruleset rules all agree, and every way of getting
+ *   one of them wrong is silent — an auto-merge that lands on red, a force push that rewrites
+ *   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.
+ * ⛔ THIS BARREL IS THE PUBLIC API. `repo-policy-form.ts`, `repository-ruleset-form.ts` and the
+ *   rest of the `repository-ruleset-*` internals are reachable by path if you genuinely need
+ *   one — a deliberate act rather than an accident of barrelling.
  */
 export {
   type RepoPolicy,
@@ -21,3 +25,31 @@ export {
   repoPolicy,
 } from './repo-policy-form.ts';
 export { type DeclareRepoPolicyOptions, declareRepoPolicy } from './repo-policy.ts';
+export {
+  type RepoBaselineInput,
+  PUBLIC_ONLY_UNDECLARABLE,
+  repoBaselineRuleset,
+  repoBaselineSettings,
+} from './repo-baseline-data.ts';
+export { type DeclareRepoBaselineOptions, declareRepoBaseline } from './declare-repo-baseline.ts';
+export {
+  RepositoryRuleset,
+  RepositoryRulesetProvider,
+  type RepositoryRulesetAttributes,
+  type RepositoryRulesetProps,
+  type RepositoryRulesetPullRequestRule,
+  type RepositoryRulesetReviewerRule,
+  type RepositoryRulesetRules,
+  type RepositoryRulesetStatusChecksRule,
+} from './repository-ruleset.ts';
+export { RULE_TYPE_COVERAGE, type RepositoryRuleType } from './repository-ruleset-constraints.ts';
+export {
+  BypassActorWidened,
+  DuplicateRuleset,
+  NeverReportedContext,
+  ReadbackMismatch,
+  RequiredChecksOmitted,
+  RulesetConstraintRefused,
+  UndeclaredLiveRule,
+  type RepositoryRulesetError,
+} from './repository-ruleset-errors.ts';

package/src/github/repo-baseline-data.test.ts

@@ -0,0 +1,76 @@
+/**
+ * Pins the house baseline VALUES so a loosening (an extra merge method, a dropped `deletion`
+ * rule, `extraApprovalForUnattributedChanges` flipped) shows up as a reviewed diff in THIS
+ * file, not as a silent change to every repo that adopts `declareRepoBaseline`.
+ */
+import { describe, expect, test } from 'bun:test';
+import { repoBaselineRuleset, repoBaselineSettings } from './repo-baseline-data.ts';
+
+const input = {
+  owner: 'taslabs-net',
+  repository: 'widgets',
+  checks: ['ci', 'secret scan'],
+  visibility: 'private' as const,
+};
+
+describe('repoBaselineSettings', () => {
+  test('squash-only, auto-merge on, wiki off — identical for private and public', () => {
+    expect(repoBaselineSettings(input)).toEqual({
+      owner: 'taslabs-net',
+      name: 'widgets',
+      visibility: 'private',
+      allowSquashMerge: true,
+      allowMergeCommit: false,
+      allowRebaseMerge: false,
+      allowAutoMerge: true,
+      deleteBranchOnMerge: true,
+      hasWiki: false,
+    });
+  });
+
+  test('a public repo gets the same settings, only visibility differs', () => {
+    const publicSettings = repoBaselineSettings({ ...input, visibility: 'public' });
+    const privateSettings = repoBaselineSettings(input);
+    expect({ ...publicSettings, visibility: undefined }).toEqual({
+      ...privateSettings,
+      visibility: undefined,
+    });
+  });
+});
+
+describe('repoBaselineRuleset', () => {
+  test('pins the exact ruleset shape the GitHub-baseline plan specifies', () => {
+    expect(repoBaselineRuleset(input)).toEqual({
+      owner: 'taslabs-net',
+      repository: 'widgets',
+      name: 'main',
+      target: 'branch',
+      enforcement: 'active',
+      bypassActors: [],
+      conditions: { include: ['~DEFAULT_BRANCH'], exclude: [] },
+      rules: {
+        deletion: true,
+        nonFastForward: true,
+        pullRequest: {
+          requiredApprovingReviewCount: 0,
+          dismissStaleReviewsOnPush: true,
+          requireCodeOwnerReview: false,
+          requireLastPushApproval: false,
+          requiredReviewThreadResolution: false,
+          allowedMergeMethods: ['squash'],
+          extraApprovalForUnattributedChanges: false,
+        },
+        requiredStatusChecks: {
+          checks: [{ context: 'ci' }, { context: 'secret scan' }],
+          strictRequiredStatusChecksPolicy: false,
+          doNotEnforceOnCreate: false,
+        },
+      },
+    });
+  });
+
+  test('no checks (homeflare/anyauth/desktop today) omits requiredStatusChecks entirely', () => {
+    const ruleset = repoBaselineRuleset({ ...input, checks: [] });
+    expect(ruleset.rules.requiredStatusChecks).toBeUndefined();
+  });
+});

package/src/github/repo-baseline-data.ts

@@ -0,0 +1,86 @@
+/**
+ * The house GitHub baseline, as plain data — the VALUES section of the GitHub-baseline plan
+ * (2026-09-23), and nothing else. No provider import (S9's "pure core" pattern, the same split
+ * repo-policy-form.ts uses): `declare-repo-baseline.ts` turns this into resources, and
+ * `hf-repo-baseline-check.ts` reads it read-only against a live repo. Both import THIS file so
+ * neither can drift from the other.
+ *
+ * ⚠️ IDENTICAL FOR PRIVATE AND PUBLIC, except the fields this module marks `publicOnly` —
+ *   `security_and_analysis` is `null` on every private repo this estate has (LIVE SURVEY,
+ *   2026-09-23), so secret scanning / push protection / private vulnerability reporting are
+ *   not settable there at all, not merely off.
+ */
+
+export interface RepoBaselineInput {
+  readonly owner: string;
+  readonly repository: string;
+  readonly checks: readonly string[];
+  readonly visibility: 'public' | 'private';
+  readonly description?: string;
+}
+
+/** `GitHub.Repository` fields this baseline owns. Every merge-automation caller across the 17
+ * tray checkouts uses `--squash` (measured 2026-09-23; the only non-squash mentions are
+ * GitLab-era comments in cliff.toml), so squash-only is not a per-repo choice. */
+export function repoBaselineSettings(input: RepoBaselineInput) {
+  return {
+    owner: input.owner,
+    name: input.repository,
+    ...(input.description === undefined ? {} : { description: input.description }),
+    visibility: input.visibility,
+    allowSquashMerge: true,
+    allowMergeCommit: false,
+    allowRebaseMerge: false,
+    allowAutoMerge: true,
+    deleteBranchOnMerge: true,
+    hasWiki: false,
+  };
+}
+
+/** `GitHub.RepositoryRuleset` `main` — target branch, 0-approval solo-maintainer shape, the
+ * named `checks` required, squash-only at the ruleset level too (H15's whole reason to exist:
+ * the repository setting can be re-ticked in the UI; the ruleset is what actually enforces it). */
+export function repoBaselineRuleset(input: RepoBaselineInput) {
+  return {
+    owner: input.owner,
+    repository: input.repository,
+    name: 'main',
+    target: 'branch' as const,
+    enforcement: 'active' as const,
+    bypassActors: [],
+    conditions: { include: ['~DEFAULT_BRANCH'], exclude: [] },
+    rules: {
+      deletion: true,
+      nonFastForward: true,
+      pullRequest: {
+        requiredApprovingReviewCount: 0,
+        dismissStaleReviewsOnPush: true,
+        requireCodeOwnerReview: false,
+        requireLastPushApproval: false,
+        requiredReviewThreadResolution: false,
+        allowedMergeMethods: ['squash' as const],
+        extraApprovalForUnattributedChanges: false as const,
+      },
+      ...(input.checks.length === 0
+        ? {}
+        : {
+            requiredStatusChecks: {
+              checks: input.checks.map((context) => ({ context })),
+              strictRequiredStatusChecksPolicy: false,
+              doNotEnforceOnCreate: false,
+            },
+          }),
+    },
+  };
+}
+
+/** Public-only settings this baseline asserts but cannot express through either resource above
+ * at `alchemy@2.0.0-beta.79` — recorded for the wave-3 handoff artifact (plan section 2), not
+ * declared anywhere. Both already measured ON for `kit` (LIVE SURVEY 2026-09-23); `builds` is
+ * the gap. */
+export const PUBLIC_ONLY_UNDECLARABLE = [
+  'secret_scanning: enabled',
+  'secret_scanning_push_protection: enabled',
+  'private_vulnerability_reporting: enabled',
+  "fork-PR approval: 'first_time_contributors'",
+] as const;

package/src/github/repo-policy.ts

@@ -7,21 +7,19 @@
  *       checks: ['ci', 'secret scan'],
  *     });
  *
- * Provide `GitHub.providers()`; this subpath adds no provider of its own.
+ * Provide `GitHub.providers()` AND `RepositoryRulesetProvider()`; this subpath adds no GitHub
+ * provider of its own.
  *
- * ⛔ THE RULESET CANNOT BE ADOPTED, AND A FIRST DEPLOY ONTO A REPO THAT ALREADY HAS ONE
- *   MAKES A SECOND. 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, and `reconcile` looks the live ruleset up only BY THE ID IN
- *   THAT OUTPUT — with none, it calls `createRepoRuleset` unconditionally. GitHub permits
- *   several rulesets with the same name on one repository, so nothing errors; the repo
- *   quietly ends up with two, both enforcing.
- *   ★ SO, BEFORE THE FIRST DEPLOY: `gh api repos/<owner>/<repo>/rulesets` and delete a
- *     hand-made ruleset of the same name, or give this one a `rulesetName` of its own.
- *     Afterwards the state carries the id and every later deploy converges that one.
- *   ⚠️ `GitHub.Repository` does NOT share the problem — its `reconcile` probes by name
- *     and converges onto whatever is live — so only half of this helper is adopt-safe,
- *     and the halves fail differently. See docs/repo-policy.md.
+ * ★ REWIRED 2026-09-23 onto `GitHub.RepositoryRuleset`, not upstream `GitHub.Ruleset` — the
+ *   ADOPT-SAFE bridge documented in repository-ruleset.ts. Only `builds` calls this, and its
+ *   ruleset has NEVER been created (LIVE SURVEY 2026-09-23: 0 rulesets live on `builds`), so
+ *   the swap changes no live resource's identity; a cold first deploy is the only deploy this
+ *   call has ever had. `homeflare/docs/repo-policy-ruleset-hazards.md`'s "before the first
+ *   deploy, check by hand" workaround is now enforced by the resource itself (the name-probe in
+ *   repository-ruleset-probe.ts) rather than left to the operator — see that doc for the
+ *   history, kept rather than deleted so the hazard `builds` almost hit stays legible.
+ * ⚠️ `GitHub.Repository` keeps its OWN upstream behavior unchanged — it already probed by name
+ *   and converged, so only the ruleset half of this helper needed the swap.
  *
  * ⛔ BOTH RESOURCES RETAIN. `retain` is already the vendor default for each of them; it
  *   is piped anyway so that a vendor change cannot quietly turn "drop this call from the
@@ -32,12 +30,12 @@ import * as GitHub from 'alchemy/GitHub';
 import * as RemovalPolicy from 'alchemy/RemovalPolicy';
 import * as Effect from 'effect/Effect';
 import { type RepoPolicyOptions, repoPolicy } from './repo-policy-form.ts';
+import { RepositoryRuleset } from './repository-ruleset.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.
+   * decides.
    */
   readonly adopt?: boolean;
 }
@@ -60,6 +58,8 @@ export const declareRepoPolicy = (id: string, options: DeclareRepoPolicyOptions)
       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));
+    // `policy.ruleset` is a plain `RulesetProps` — every field `RepositoryRulesetProps` adds
+    // over it is optional, so it needs no translation to satisfy the bridge's props.
+    const ruleset = yield* owned(RepositoryRuleset(`${id}-ruleset`, policy.ruleset));
     return { policy, repository, ruleset };
   });