@homeflare/alchemy 0.53.1 → 0.55.0

package/src/ceph/ceph-config-options.test.ts

@@ -1,19 +1,32 @@
 /**
  * Structural guard on the named config-option list itself (mon-transport doc acceptance test #3):
- * the list contains none of the lockout classes, and it starts empty (D-C1).
+ * the list contains none of the lockout classes, and each entry is one reviewed line (D-C1).
  */
 import { describe, expect, test } from 'bun:test';
-import { NAMED_CONFIG_OPTIONS, isLockoutConfigOption } from './ceph-config-options.ts';
+import {
+  NAMED_CONFIG_OPTIONS,
+  allowedWhoFor,
+  isLockoutConfigOption,
+} from './ceph-config-options.ts';
 
 describe('NAMED_CONFIG_OPTIONS', () => {
-  test('starts empty', () => {
-    expect(NAMED_CONFIG_OPTIONS.size).toBe(0);
+  test('the first reviewed entry is the mgr prometheus perf-counter switch, for mgr only', () => {
+    expect(NAMED_CONFIG_OPTIONS.get('mgr/prometheus/exclude_perf_counters')).toEqual(['mgr']);
+    expect(allowedWhoFor('mgr/prometheus/exclude_perf_counters')).toEqual(['mgr']);
+    expect(allowedWhoFor('mon_allow_pool_delete')).toEqual([]);
   });
 
   test('contains none of the lockout classes, whatever gets added later', () => {
-    const bad = [...NAMED_CONFIG_OPTIONS].filter((name) => isLockoutConfigOption(name));
+    const bad = [...NAMED_CONFIG_OPTIONS.keys()].filter((name) => isLockoutConfigOption(name));
     expect(bad).toEqual([]);
   });
+
+  test('every entry names at least one bounded <who>', () => {
+    for (const [name, whos] of NAMED_CONFIG_OPTIONS) {
+      expect([name, whos.length > 0]).toEqual([name, true]);
+      for (const who of whos) expect(who).toMatch(/^(global|mon|osd|mgr|mds|client)(\.[\w-]+)?$/);
+    }
+  });
 });
 
 describe('isLockoutConfigOption', () => {
@@ -31,14 +44,18 @@ describe('isLockoutConfigOption', () => {
     'keyring_path',
     'key',
     'mon_data_key',
+    'mgr/dashboard/key',
+    'mgr/restful/keyring',
   ])('flags %s', (name) => {
     expect(isLockoutConfigOption(name)).toBe(true);
   });
 
-  test.each(['mon_allow_pool_delete', 'osd_pool_default_size', 'mon_max_pg_per_osd'])(
-    'does not flag an ordinary tuning option like %s',
-    (name) => {
-      expect(isLockoutConfigOption(name)).toBe(false);
-    },
-  );
+  test.each([
+    'mgr/prometheus/exclude_perf_counters',
+    'mon_allow_pool_delete',
+    'osd_pool_default_size',
+    'mon_max_pg_per_osd',
+  ])('does not flag an ordinary tuning option like %s', (name) => {
+    expect(isLockoutConfigOption(name)).toBe(false);
+  });
 });

package/src/ceph/ceph-config-options.ts

@@ -3,10 +3,14 @@
  * through the mon-command transport (ceph-argv.ts's `configProblem`). Design:
  * docs/plans/2026-09-26-ceph-config-options.md, D-C1.
  *
- * ⛔ THE LIST STARTS EMPTY, AND EACH ADDITION IS ITS OWN REVIEWED PR LINE. Nothing in K-A4 adds to
- *   it — `CephConfigOption` (K-D) is a separate, later family; this file exists now only so the
- *   transport's allowlist has something to bound `config` against from day one, per the accepted
- *   design ("config get/set for the named option list which starts EMPTY").
+ * ⛔ THE LIST STARTED EMPTY, AND EACH ADDITION IS ITS OWN REVIEWED PR LINE. `Ceph.ConfigOption`
+ *   (K-D, config-option.ts) is the only declarer; it refuses any `{who, name}` this map does not
+ *   carry before planning, and the transport's allowlist (ceph-argv-config.ts) refuses it again
+ *   before anything dials. One entry per line, each with a comment saying what it does and why it
+ *   is managed — never a batch.
+ * ★ EACH ENTRY ALSO NAMES THE `<who>` IT MAY BE SET FOR. This is the config-options design's
+ *   acceptance test #1 ("`<who>` bounded to the declared daemons"): an option listed for `mgr`
+ *   can never be written to `global`, `client.admin` or any other section through this transport.
  * ⛔ NEVER ADD ONE OF THE LOCKOUT CLASSES BELOW. `mon_host`, `public_network`, `cluster_network`,
  *   `public_addr`, `cluster_addr`, every `auth_*_required` and every `key`/`keyring`-bearing
  *   option re-address the mons or de-authenticate the whole cluster — cutting every VM disk — and
@@ -17,8 +21,22 @@
  *   never a `ceph config set` argv, which lands in the runner's log and the node's sudo journal.
  */
 
-/** Starts empty. Add one reviewed option name per PR line, never a batch. */
-export const NAMED_CONFIG_OPTIONS: ReadonlySet<string> = new Set([]);
+/**
+ * option name -> the `<who>` sections it may be set for. Add one reviewed line per PR, never a
+ * batch; the structural test (ceph-config-options.test.ts) runs the lockout guard over every key.
+ */
+export const NAMED_CONFIG_OPTIONS: ReadonlyMap<string, readonly string[]> = new Map<
+  string,
+  readonly string[]
+>([
+  // mgr prometheus module: `false` makes it export per-daemon perf counters (ceph_osd_op_*,
+  // ceph_rgw_* …) instead of omitting them. Set live 2026-10, codified here so plan reconciles it.
+  ['mgr/prometheus/exclude_perf_counters', ['mgr']],
+]);
+
+/** The `<who>` sections `name` may be set for — empty when the option is not on the list. */
+export const allowedWhoFor = (name: string): readonly string[] =>
+  NAMED_CONFIG_OPTIONS.get(name) ?? [];
 
 const LOCKOUT_EXACT: ReadonlySet<string> = new Set([
   'mon_host',
@@ -28,8 +46,11 @@ const LOCKOUT_EXACT: ReadonlySet<string> = new Set([
   'cluster_addr',
 ]);
 
-/** `auth_*_required` (cephx enforcement) and anything key/keyring-shaped, either side of `_`. */
-const LOCKOUT_PATTERN = /^auth_\w*_required$|(^|_)key(ring)?($|_)/;
+/**
+ * `auth_*_required` (cephx enforcement) and anything key/keyring-shaped, bounded by `_` or by the
+ * `/` that separates an mgr module option (`mgr/<module>/<option>`) — so `mgr/x/key` is caught too.
+ */
+const LOCKOUT_PATTERN = /^auth_\w*_required$|(^|[_/])key(ring)?($|[_/])/;
 
 /** Whether `name` is a class this transport must never read a value for, adopt, or write. */
 export const isLockoutConfigOption = (name: string): boolean =>

package/src/ceph/config-option.ts

@@ -0,0 +1,112 @@
+/**
+ * `Ceph.ConfigOption` (K-D) — one `{who, name} = value` row of the Ceph mon config db, declared.
+ * Design: docs/plans/2026-09-26-ceph-config-options.md. Pure helpers: ceph-config-option-form.ts;
+ * the loop: ceph-config-option-reconcile.ts; the allowlist: ceph-argv-config.ts.
+ *
+ * ★ ONE RESOURCE PER OPTION, AND ONLY OPTIONS ON THE NAMED LIST. `NAMED_CONFIG_OPTIONS`
+ *   (ceph-config-options.ts) is the gate: each entry is its own reviewed PR line and names the
+ *   `<who>` it may be set for. Anything else is refused at `diff` (so the plan fails loudly) and
+ *   again by the transport before anything dials.
+ * ★ PLAN READS OVER THE PVE API, NEVER SSH. `read`/`diff` call `GET /nodes/{node}/ceph/cfg/db`
+ *   (read lease only — "a plan never elevates"). Only `reconcile`/`delete` reach ssh, through
+ *   ceph-transport.ts — the existing mon-command transport `Ceph.AuthEntity` uses, not a new one.
+ * ★ ADOPTION OF AN ALREADY-SET OPTION IS A ZERO-WRITE NO-OP. A cold `read` of a live row answers
+ *   `Unowned(attrs)` (the house rule for a marker-less API, H1), so a live option needs
+ *   `adopt(true)` on its row; `reconcile` then observes the matching value and writes nothing.
+ *   ⛔ Fix-live-then-codify is fine for this family exactly because of that: the plan proves it.
+ * ⚠️ PRECONDITION BEFORE DECLARING THE WHOLE CONFIG DB: the dead `public_addr` entries
+ *   (homeflare-proxmox docs/completeness-tb4-sdn-ceph.md, T3) must be removed by hand with
+ *   `ceph config rm` first, so fossils are never adopted. `public_addr` is a lockout class and can
+ *   never be declared here; a single named option (like the first one) is not blocked by it.
+ * ⚠️ THE COMPARED VALUE IS THE MON DB's, not the effective one: a ceph.conf override or a compiled
+ *   default is out of scope (CephConf is its own family).
+ * ⚠️ `defaultRemovalPolicy: 'retain'`: removing a row stops managing it; `config rm` runs only when
+ *   a removal policy of `destroy` is chosen deliberately for that row.
+ */
+import * as nodes from '@distilled.cloud/proxmox/nodes';
+import { Resource } from 'alchemy';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { isResolved } from 'alchemy/Diff';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { mintTier } from '../proxmox/credentials.ts';
+import { runPve } from '../proxmox/distilled-pve.ts';
+import type { PveRequirements } from '../proxmox/resource-spec.ts';
+import { UNREADABLE, readOrUnreadable, unreadableWarning } from '../proxmox/unreadable-read.ts';
+import {
+  type CephConfigOptionAttributes,
+  type CephConfigOptionProps,
+  configOptionProblem,
+  findLive,
+  matches,
+} from './ceph-config-option-form.ts';
+import {
+  deleteCephConfigOption,
+  reconcileCephConfigOption,
+} from './ceph-config-option-reconcile.ts';
+
+export type {
+  CephConfigOptionAttributes,
+  CephConfigOptionProps,
+} from './ceph-config-option-form.ts';
+
+export interface CephConfigOption extends Resource<
+  'Ceph.ConfigOption',
+  CephConfigOptionProps,
+  CephConfigOptionAttributes,
+  never,
+  PveRequirements
+> {}
+
+export const CephConfigOption = Resource<CephConfigOption>('Ceph.ConfigOption', {
+  defaultRemovalPolicy: 'retain',
+});
+
+/** The whole mon config db, over the PVE API, on a read lease. */
+const readRows = (props: Pick<CephConfigOptionProps, 'target' | 'node'>) =>
+  runPve(props.target, 'read', false, nodes.listNodeCephCfgDb({ node: props.node }));
+
+const refuse = (props: CephConfigOptionProps) => {
+  const problem = configOptionProblem(props);
+  return problem === undefined ? Effect.void : Effect.fail(new Error(problem));
+};
+
+export const CephConfigOptionProvider = () =>
+  Provider.effect(
+    CephConfigOption,
+    Effect.succeed(
+      CephConfigOption.Provider.of({
+        list: () => Effect.succeed([]),
+
+        read: Effect.fn(function* ({ olds, output }) {
+          const live = findLive(yield* readRows(olds), olds.who, olds.name);
+          if (live === undefined) return undefined;
+          return output !== undefined ? live : Unowned(live);
+        }),
+
+        diff: Effect.fn(function* ({ news, output }) {
+          if (!isResolved(news)) return undefined;
+          yield* refuse(news);
+          if (output === undefined) return undefined;
+          if (output.who !== news.who || output.name !== news.name)
+            return { action: 'replace' } as const;
+          const rows = yield* readOrUnreadable(readRows(news));
+          if (rows === UNREADABLE) {
+            yield* unreadableWarning(
+              'Ceph.ConfigOption',
+              `${news.who}/${news.name}`,
+              news.target.mount,
+              mintTier(news.target, 'read'),
+            );
+            return { action: 'noop' } as const;
+          }
+          const live = findLive(rows, news.who, news.name);
+          return { action: matches(live, news) ? 'noop' : 'update' } as const;
+        }),
+
+        reconcile: ({ news }) => reconcileCephConfigOption(news, readRows(news), {}),
+
+        delete: ({ olds }) => deleteCephConfigOption(olds, readRows(olds), {}),
+      }),
+    ),
+  );

package/src/ceph/index.ts

@@ -1,12 +1,16 @@
 /**
- * Ceph providers for Alchemy — the mon-command transport and `Ceph.AuthEntity` (K-A4).
+ * Ceph providers for Alchemy — the mon-command transport, `Ceph.AuthEntity` (K-A4) and
+ * `Ceph.ConfigOption` (K-D).
  *
  * ⛔ THIS BARREL IS THE PUBLIC API, DELIBERATELY SMALLER THAN THE DIRECTORY — see
  *   `../openbao/index.ts`'s header for why. The allowlist internals (ceph-argv.ts), the parsing
- *   (ceph-auth-parse.ts) and the reconcile loop (ceph-auth-reconcile.ts) are exported by path for
- *   a future `CephConfigOption` (K-D) or a test to reach directly, not published here.
+ *   (ceph-auth-parse.ts) and the reconcile loops (ceph-auth-reconcile.ts,
+ *   ceph-config-option-reconcile.ts) are reached by path from tests, not published here.
  */
 export type { CephAuthEntityAttributes, CephAuthEntityProps, CephCaps } from './auth-entity.ts';
 export { CephAuthEntity, CephAuthEntityProvider } from './auth-entity.ts';
 export type { CephDial, CephExecResult, CephTransportOptions } from './ceph-transport.ts';
 export { assertFreshQuorum, runCephCommand, sshCephDial } from './ceph-transport.ts';
+export type { CephConfigOptionAttributes, CephConfigOptionProps } from './config-option.ts';
+export { CephConfigOption, CephConfigOptionProvider } from './config-option.ts';
+export { NAMED_CONFIG_OPTIONS } from './ceph-config-options.ts';

package/src/github/fork-pr-approval.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import {
+  type ForkPrApprovalClient,
+  type ForkPrApprovalPolicy,
+  ForkPrApprovalReadbackMismatch,
+  forkPrApprovalHandlers,
+} from './fork-pr-approval.ts';
+
+const fake = (initial: string, store = true) => {
+  const state = { policy: initial, puts: [] as string[] };
+  const client: ForkPrApprovalClient = {
+    get: () => Effect.succeed(state.policy),
+    put: (_o, _r, policy: ForkPrApprovalPolicy) =>
+      Effect.sync(() => {
+        state.puts.push(policy);
+        if (store) state.policy = policy;
+      }),
+  };
+  return { state, handlers: forkPrApprovalHandlers(() => client) };
+};
+
+const props = {
+  owner: 'taslabs-net',
+  repository: 'homeflare-kit',
+  approvalPolicy: 'all_external_contributors',
+} as const;
+// oxlint-disable-next-line typescript/no-explicit-any
+const run = <A>(e: Effect.Effect<A, unknown, any>) => Effect.runPromise(e as Effect.Effect<A>);
+// oxlint-disable-next-line typescript/no-explicit-any
+const h = (x: ReturnType<typeof fake>) => x.handlers as any;
+
+describe('GitHub.ForkPrApproval', () => {
+  test('reconcile PUTs a looser live policy up to the declared one and reads it back', async () => {
+    const f = fake('first_time_contributors');
+    const out = await run(h(f).reconcile({ news: props, output: undefined }));
+    expect(f.state.puts).toEqual(['all_external_contributors']);
+    expect(out).toEqual({ ...props, approvalPolicy: 'all_external_contributors' });
+  });
+
+  test('reconcile writes nothing when live already matches', async () => {
+    const f = fake('all_external_contributors');
+    await run(h(f).reconcile({ news: props, output: undefined }));
+    expect(f.state.puts).toEqual([]);
+  });
+
+  test('a PUT GitHub does not store fails the reconcile', async () => {
+    const f = fake('first_time_contributors', false);
+    const err = await run(h(f).reconcile({ news: props, output: undefined })).catch(
+      (e: unknown) => e,
+    );
+    expect(String(err)).toContain('read back first_time_contributors');
+    expect(ForkPrApprovalReadbackMismatch.name).toBe('ForkPrApprovalReadbackMismatch');
+  });
+
+  test('an unknown policy is refused before any write', async () => {
+    const f = fake('first_time_contributors');
+    const bad = { ...props, approvalPolicy: 'nobody' };
+    await expect(run(h(f).reconcile({ news: bad, output: undefined }))).rejects.toThrow('unknown');
+    expect(f.state.puts).toEqual([]);
+  });
+
+  test('delete never touches the live setting', async () => {
+    const f = fake('all_external_contributors');
+    await run(h(f).delete({ olds: props, output: props }));
+    expect(f.state.puts).toEqual([]);
+  });
+
+  test('read with no state reports the live value as unowned (adopt on purpose)', async () => {
+    const f = fake('first_time_contributors');
+    const r = await run(h(f).read({ olds: props, output: undefined }));
+    expect(JSON.stringify(r)).toContain('first_time_contributors');
+  });
+});

package/src/github/fork-pr-approval.ts

@@ -0,0 +1,174 @@
+/**
+ * `GitHub.ForkPrApproval` — a repository's "approval for running fork pull request workflows
+ * from contributors" setting, as a declared resource.
+ *
+ * ★ WHY IT EXISTS (Tim, 2026-10-14 01:28 ET). `PUBLIC_ONLY_UNDECLARABLE` (repo-baseline-data.ts)
+ *   listed this setting as something no resource could express. homeflare-kit moved onto the
+ *   self-hosted pve pool, and homeflare-mini's ci-runner serves a public repo only while this
+ *   setting is `all_external_contributors` (its `PUBLIC_RUNNER_REPOS`, fail-closed) — a fork's
+ *   code must not reach the LAN runner without a maintainer's click. So the setting is now code.
+ *
+ * ⚠️ ONE ENDPOINT PAIR, NOTHING ELSE. `GET`/`PUT /repos/{owner}/{repo}/actions/permissions/
+ *   fork-pr-contributor-approval`. The setting always exists, so there is no create and no delete:
+ *   `reconcile` PUTs the declared policy and reads it back; `delete` leaves the live setting as it
+ *   is (the default removal policy is `retain`, and dropping a declaration must never loosen it).
+ * ⛔ ADOPT, NEVER CLAIM SILENTLY. With no prior state `read` returns the live value as `Unowned`,
+ *   so a stack has to `adopt(true)` it on purpose — the same convention as `RepositoryRuleset`.
+ * ⛔ READ BACK. A PUT that GitHub accepts but does not store is reported, not trusted: the
+ *   reconcile re-reads and fails on a mismatch.
+ */
+import { Resource } from 'alchemy';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { isResolved } from 'alchemy/Diff';
+import { GitHubCredentials } from 'alchemy/GitHub';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+
+/** GitHub's three values, most to least permissive. */
+export const FORK_PR_APPROVAL_POLICIES = [
+  'first_time_contributors_new_to_github',
+  'first_time_contributors',
+  'all_external_contributors',
+] as const;
+
+export type ForkPrApprovalPolicy = (typeof FORK_PR_APPROVAL_POLICIES)[number];
+
+export interface ForkPrApprovalProps {
+  readonly owner: string;
+  readonly repository: string;
+  readonly approvalPolicy: ForkPrApprovalPolicy;
+  /** GitHub Enterprise API base; omit for github.com. */
+  readonly baseUrl?: string;
+}
+
+export interface ForkPrApprovalAttributes {
+  readonly owner: string;
+  readonly repository: string;
+  readonly approvalPolicy: string;
+}
+
+export interface ForkPrApproval extends Resource<
+  'GitHub.ForkPrApproval',
+  ForkPrApprovalProps,
+  ForkPrApprovalAttributes,
+  never
+> {}
+
+export const ForkPrApproval = Resource<ForkPrApproval>('GitHub.ForkPrApproval', {
+  defaultRemovalPolicy: 'retain',
+});
+
+/** The two calls this resource makes, so tests can hand it a fake. */
+export interface ForkPrApprovalClient<R = never> {
+  readonly get: (owner: string, repo: string) => Effect.Effect<string, Error, R>;
+  readonly put: (
+    owner: string,
+    repo: string,
+    policy: ForkPrApprovalPolicy,
+  ) => Effect.Effect<void, Error, R>;
+}
+
+/** A PUT GitHub accepted but did not store. */
+export class ForkPrApprovalReadbackMismatch extends Error {
+  readonly _tag = 'ForkPrApprovalReadbackMismatch';
+}
+
+const asError = (e: unknown): Error => (e instanceof Error ? e : new Error(String(e)));
+const PATH = 'actions/permissions/fork-pr-contributor-approval';
+
+export const octokitForkPrApprovalClient = (
+  baseUrl: string | undefined,
+): ForkPrApprovalClient<GitHubCredentials> => {
+  const octokit = Effect.gen(function* () {
+    const creds = yield* yield* GitHubCredentials;
+    return baseUrl === undefined ? creds.octokit() : creds.octokit({ baseUrl });
+  }).pipe(Effect.mapError(asError));
+  return {
+    get: (owner, repo) =>
+      Effect.gen(function* () {
+        const o = yield* octokit;
+        const res = yield* Effect.tryPromise({
+          try: () => o.request(`GET /repos/{owner}/{repo}/${PATH}`, { owner, repo }),
+          catch: asError,
+        });
+        return String((res.data as { approval_policy?: unknown }).approval_policy);
+      }),
+    put: (owner, repo, policy) =>
+      Effect.gen(function* () {
+        const o = yield* octokit;
+        yield* Effect.tryPromise({
+          try: () =>
+            o.request(`PUT /repos/{owner}/{repo}/${PATH}`, {
+              owner,
+              repo,
+              approval_policy: policy,
+            }),
+          catch: asError,
+        });
+      }),
+  };
+};
+
+const attrs = (
+  owner: string,
+  repository: string,
+  approvalPolicy: string,
+): ForkPrApprovalAttributes => ({
+  owner,
+  repository,
+  approvalPolicy,
+});
+
+/** The provider's handlers over any client — the real one below, a fake in tests. */
+export const forkPrApprovalHandlers = <R>(
+  clientFor: (baseUrl: string | undefined) => ForkPrApprovalClient<R>,
+) =>
+  ForkPrApproval.Provider.of({
+    list: () => Effect.succeed([]),
+    nuke: { skip: true },
+
+    read: ({ output, olds }) =>
+      Effect.gen(function* () {
+        const live = yield* clientFor(olds.baseUrl).get(olds.owner, olds.repository);
+        const found = attrs(olds.owner, olds.repository, live);
+        return output === undefined ? Unowned(found) : found;
+      }),
+
+    diff: ({ news, olds }) =>
+      Effect.succeed(
+        isResolved(news) &&
+          olds !== undefined &&
+          (news.owner !== olds.owner || news.repository !== olds.repository)
+          ? ({ action: 'replace' } as const)
+          : undefined,
+      ),
+
+    reconcile: ({ news }) =>
+      Effect.gen(function* () {
+        if (!(FORK_PR_APPROVAL_POLICIES as readonly string[]).includes(news.approvalPolicy)) {
+          return yield* Effect.fail(
+            new Error(`unknown fork-PR approval policy: ${String(news.approvalPolicy)}`),
+          );
+        }
+        const client = clientFor(news.baseUrl);
+        const before = yield* client.get(news.owner, news.repository);
+        if (before !== news.approvalPolicy) {
+          yield* client.put(news.owner, news.repository, news.approvalPolicy);
+        }
+        const after = yield* client.get(news.owner, news.repository);
+        if (after !== news.approvalPolicy) {
+          return yield* Effect.fail(
+            new ForkPrApprovalReadbackMismatch(
+              `${news.owner}/${news.repository}: PUT ${news.approvalPolicy}, read back ${after}`,
+            ),
+          );
+        }
+        return attrs(news.owner, news.repository, after);
+      }),
+
+    // ⛔ Retain: removing the declaration never loosens the live setting.
+    delete: () => Effect.void,
+  });
+
+export const ForkPrApprovalProvider = () =>
+  Provider.succeed(ForkPrApproval, forkPrApprovalHandlers(octokitForkPrApprovalClient));

package/src/github/index.ts

@@ -45,6 +45,15 @@ export {
   type RepositoryRulesetRules,
   type RepositoryRulesetStatusChecksRule,
 } from './repository-ruleset.ts';
+export {
+  FORK_PR_APPROVAL_POLICIES,
+  ForkPrApproval,
+  type ForkPrApprovalAttributes,
+  type ForkPrApprovalPolicy,
+  type ForkPrApprovalProps,
+  ForkPrApprovalProvider,
+  ForkPrApprovalReadbackMismatch,
+} from './fork-pr-approval.ts';
 export { repoPolicyProviders } from './repository-ruleset-providers.ts';
 export { RULE_TYPE_COVERAGE, type RepositoryRuleType } from './repository-ruleset-constraints.ts';
 export {

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

@@ -86,10 +86,10 @@ export function repoBaselineRuleset(input: RepoBaselineInput) {
 /** 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. */
+ * the gap. Fork-PR approval left this list on 2026-10-14: `ForkPrApproval` (fork-pr-approval.ts)
+ * declares it. */
 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/repository-ruleset-providers.ts

@@ -38,9 +38,14 @@
  */
 import * as GitHub from 'alchemy/GitHub';
 import * as Layer from 'effect/Layer';
+import { ForkPrApprovalProvider } from './fork-pr-approval.ts';
 import { RepositoryRulesetProvider } from './repository-ruleset.ts';
 
 export const repoPolicyProviders = (options?: GitHub.ProvidersOptions) => {
   const github = GitHub.providers(options);
-  return Layer.mergeAll(github, RepositoryRulesetProvider().pipe(Layer.provideMerge(github)));
+  return Layer.mergeAll(
+    github,
+    RepositoryRulesetProvider().pipe(Layer.provideMerge(github)),
+    ForkPrApprovalProvider().pipe(Layer.provideMerge(github)),
+  );
 };

package/src/linux/sudo-runner-privileged-read.test.ts

@@ -0,0 +1,92 @@
+/**
+ * sshSudoRunner `privilegedReads`: an exact-path, root-owned-regular-file-only sudo read, so a
+ * plan can diff a declared 0600 file without a general root-read primitive.
+ */
+import { describe, expect, test } from 'bun:test';
+import type { FileStat, HostRunner } from '../launchd/runner.ts';
+import { SUDO } from './sudo-allowlist.ts';
+import {
+  BASE64,
+  SudoRefusedError,
+  checkPrivilegedReads,
+  makeSshSudoRunner,
+} from './sudo-runner.ts';
+
+const SECRETISH = '/opt/app/config.yaml';
+const file = (uid: number, kind: FileStat['kind'] = 'file'): FileStat =>
+  ({ kind, mode: 0o600, uid, gid: 0, size: 5 }) as unknown as FileStat;
+
+const host = (stat: FileStat | undefined, exitCode = 0) => {
+  const execs: string[][] = [];
+  const operatorReads: string[] = [];
+  const base = {
+    platform: 'linux',
+    privileged: false,
+    effectiveUid: () => 1001,
+    stat: async () => stat,
+    readFile: async (path: string) => {
+      operatorReads.push(path);
+      return new TextEncoder().encode('operator');
+    },
+    exec: async (argv: string[]) => {
+      execs.push(argv);
+      return {
+        exitCode,
+        stdout: `${Buffer.from('hello').toString('base64')}\n`,
+        stderr: exitCode === 0 ? '' : 'boom',
+      };
+    },
+  } as unknown as HostRunner;
+  const runner = makeSshSudoRunner(['/opt/app/data'], {
+    base,
+    log: () => undefined,
+    stage: async () => {
+      throw new Error('unused');
+    },
+    privilegedReads: [SECRETISH],
+  });
+  return { execs, operatorReads, runner };
+};
+
+describe('privilegedReads', () => {
+  test('a listed root-owned file is read with exactly sudo -n -- base64 -- <path>', async () => {
+    const { execs, runner } = host(file(0));
+    expect(new TextDecoder().decode(await runner.readFile(SECRETISH))).toBe('hello');
+    expect(execs).toEqual([[SUDO, '-n', '--', BASE64, '--', SECRETISH]]);
+  });
+
+  test('an unlisted path is read as the operator, never elevated', async () => {
+    const { execs, operatorReads, runner } = host(file(0));
+    await runner.readFile('/etc/caddy/cf-token.env');
+    await runner.readFile(`${SECRETISH}.bak`);
+    await runner.readFile('/opt/app');
+    expect(execs).toEqual([]);
+    expect(operatorReads).toEqual(['/etc/caddy/cf-token.env', `${SECRETISH}.bak`, '/opt/app']);
+  });
+
+  test('a symlink, a directory or a non-root file at the listed path is refused', async () => {
+    for (const stat of [file(0, 'symlink'), file(0, 'directory'), file(1001)]) {
+      const { execs, runner } = host(stat);
+      await expect(runner.readFile(SECRETISH)).rejects.toBeInstanceOf(SudoRefusedError);
+      expect(execs).toEqual([]);
+    }
+  });
+
+  test('an absent listed file reads as absent', async () => {
+    const { execs, runner } = host(undefined);
+    expect(await runner.readFile(SECRETISH)).toBeUndefined();
+    expect(execs).toEqual([]);
+  });
+
+  test('a failed sudo read throws', async () => {
+    const { runner } = host(file(0), 1);
+    await expect(runner.readFile(SECRETISH)).rejects.toThrow('-> 1');
+  });
+
+  test('only normalized absolute paths may be listed', () => {
+    for (const bad of ['relative', '/opt/../etc/shadow', '/opt//x', '/opt/x/', '/opt/./x', '/']) {
+      expect(() => checkPrivilegedReads([bad])).toThrow(SudoRefusedError);
+    }
+    expect(checkPrivilegedReads([SECRETISH]).has(SECRETISH)).toBe(true);
+  });
+});