@effected/github 0.23.1 → 0.25.0

package/index.d.ts

@@ -174,11 +174,12 @@ interface ActionsOidcVerifyOptions {
  *
  * @public
  */
-export declare const ActionsOidc: {
+export declare class ActionsOidc {
+  private constructor();
   /** The Actions OIDC issuer, `https://token.actions.githubusercontent.com`. */
-  readonly issuer: "https://token.actions.githubusercontent.com";
+  static readonly issuer: "https://token.actions.githubusercontent.com";
   /** Verify a runner-issued OIDC token: signature against GitHub's JWKS, iss, aud, exp/nbf, then typed claims. */
-  readonly verify: (token: string, options: ActionsOidcVerifyOptions) => Effect.Effect<ActionsOidcClaims, JwtError, JwksResolver>;
+  static readonly verify: (token: string, options: ActionsOidcVerifyOptions) => Effect.Effect<ActionsOidcClaims, JwtError, JwksResolver>;
   /**
    * A valid claims payload for tests, overridable field by field.
    *
@@ -189,8 +190,8 @@ export declare const ActionsOidc: {
    * {@link ActionsOidc.issuer}; `aud` is a placeholder to override with the
    * audience under test.
    */
-  readonly testClaims: (overrides?: Readonly<Record<string, unknown>>) => Record<string, unknown>;
-};
+  static readonly testClaims: (overrides?: Readonly<Record<string, unknown>>) => Record<string, unknown>;
+}
 /**
  * Why a GitHub call failed, as a value you can branch on.
  *
@@ -760,7 +761,8 @@ export declare class PageOptions extends PageOptions_base {
  * Every member is an `Effect`, a `Stream`, or a function returning one — the
  * rule that keeps `Layer.mock` and `layerTest(Partial<Shape>)` useful. That
  * includes `rateLimit`, which is an `Effect`-valued property rather than a
- * getter for exactly this reason.
+ * getter for exactly this reason. The one plain value is `apiVersion`, a
+ * string fixed at construction that no double needs to stub.
  *
  * @public
  */
@@ -820,6 +822,20 @@ interface GitHubClientShape {
    * a caller that wants to pace itself proactively reads this.
    */
   readonly rateLimit: Effect.Effect<Option.Option<RateLimitSnapshot>>;
+  /**
+   * The REST api-version this client pins, as sent in `x-github-api-version`.
+   *
+   * @remarks
+   * A plain value, not an `Effect`: it is fixed when the client is built and
+   * reading it does no work. Resource services read it to shape a request for
+   * the version it goes out under — a body field one version requires and a
+   * later one removed, say. Calendar versions are `YYYY-MM-DD`, so two of them
+   * compare correctly as strings: `client.apiVersion < "2026-03-10"`.
+   *
+   * A call that sets its own `x-github-api-version` header goes out under that
+   * version instead; this is the version of every other call.
+   */
+  readonly apiVersion: string;
 }
 /**
  * How a client layer is built.
@@ -845,6 +861,25 @@ interface GitHubClientOptions {
    * a hand-written double of this service.
    */
   readonly fetch?: typeof globalThis.fetch | undefined;
+  /**
+   * The REST api-version every request pins, sent as `x-github-api-version`.
+   * Defaults to `"2026-03-10"`.
+   *
+   * @remarks
+   * Without the header GitHub serves its oldest supported version, which it
+   * deprecates and then sunsets, so the client always sends one. A call that
+   * sets its own `x-github-api-version` header keeps it: the per-call header
+   * wins over this option.
+   *
+   * A GitHub Enterprise Server release that predates the default version
+   * rejects the header, so a client pointed at one through `baseUrl` sets the
+   * newest version that server supports here.
+   *
+   * Must be a calendar version, `YYYY-MM-DD`. Anything else is a wiring
+   * mistake and kills the fiber building the client, with a defect naming
+   * this option, rather than reaching GitHub as a header it rejects.
+   */
+  readonly apiVersion?: string | undefined;
 }
 /**
  * One call served by {@link GitHubClient.layerFixture}, as recorded in
@@ -864,7 +899,7 @@ interface RecordedCall {
 }
 /**
  * A raw HTTP failure recorded for {@link GitHubClient.layerFixture}, made by
- * {@link (GitHubFixtures:variable).failure}.
+ * {@link (GitHubFixtures:class).failure}.
  *
  * @remarks
  * Branded, so a fixture's data payload that happens to have a `status` and a
@@ -894,7 +929,8 @@ export declare class RawFailure {
  *
  * @public
  */
-export declare const GitHubFixtures: {
+export declare class GitHubFixtures {
+  private constructor();
   /**
    * A raw failure: what GitHub answered, classified at call time by the same
    * classifier the live client uses.
@@ -924,12 +960,12 @@ export declare const GitHubFixtures: {
    * });
    * ```
    */
-  readonly failure: (response: {
+  static readonly failure: (response: {
     readonly status: number;
     readonly headers?: Readonly<Record<string, string>> | undefined;
     readonly body?: unknown;
   }) => RawFailure;
-};
+}
 /**
  * A recorded response table for {@link GitHubClient.layerFixture}.
  *
@@ -944,7 +980,7 @@ export interface GitHubFixtures {
    * is how a suite stubs a 404 (or a rate-limit, or a 422) deliberately,
    * rather than relying on a route's absence to produce one — absence is a
    * wiring mistake and {@link (GitHubFixtures:interface).unstubbed} treats it as
-   * such. A {@link RawFailure} from {@link (GitHubFixtures:variable).failure}
+   * such. A {@link RawFailure} from {@link (GitHubFixtures:class).failure}
    * fails it too, classified from GitHub's raw response.
    *
    * A value of `undefined` counts as unstubbed, so stub a route that answers
@@ -987,6 +1023,15 @@ export interface GitHubFixtures {
   readonly unstubbed?: "die" | "fail" | "empty" | undefined;
   /** What `rateLimit` answers. */
   readonly rateLimit?: RateLimitSnapshot | undefined;
+  /**
+   * What `apiVersion` answers; defaults to the live client's default,
+   * `"2026-03-10"`.
+   *
+   * @remarks
+   * Set it to drive a resource's version-dependent branch — a request body
+   * an older api-version needs — without a live client.
+   */
+  readonly apiVersion?: string | undefined;
   /**
    * Every call the fixture served, in order. Populated as the test runs.
    *
@@ -1063,11 +1108,14 @@ export declare class GitHubClient extends GitHubClient_base {
    * member **dies** naming itself.
    *
    * @remarks
-   * No member has an honest default. A fabricated response — an empty list, a
+   * No request member has an honest default. A fabricated response — an empty list, a
    * made-up sha — would leak into the code under test as fact, so the double
    * fails loudly instead, which also makes it proof that a test touches nothing
    * but what it stubbed.
    *
+   * `rateLimit` answers `Option.none()` and `apiVersion` the live default,
+   * because a real client legitimately answers both without a request.
+   *
    * For recorded responses that page for real, use
    * {@link GitHubClient.layerFixture}.
    */
@@ -1088,7 +1136,7 @@ export declare class GitHubClient extends GitHubClient_base {
    *
    * **It records every call it serves, including one that fails.** A call
    * answered by a recorded `GitHubError` or a
-   * {@link (GitHubFixtures:variable).failure} is recorded before it fails, so
+   * {@link (GitHubFixtures:class).failure} is recorded before it fails, so
    * one fixture both records the calls and classifies a raw failure the way
    * the live client would; there is no need to classify by hand inside a
    * {@link GitHubClient.layerTest} handler.
@@ -1249,7 +1297,7 @@ declare const ArtifactMetadata_base: Context.ServiceClass<ArtifactMetadata, "@ef
 export declare class ArtifactMetadata extends ArtifactMetadata_base {
   /** The live service, built over a `GitHubClient`. */
   static readonly layer: Layer.Layer<ArtifactMetadata, never, GitHubClient>;
-  /** An in-memory double; unstubbed members die naming themselves. */
+  /** An in-memory double; an unstubbed member dies when run, naming itself. */
   static readonly makeTest: (overrides?: Partial<ArtifactMetadataShape>) => ArtifactMetadataShape;
   /** {@link ArtifactMetadata.makeTest} behind a `Layer`. */
   static readonly layerTest: (overrides?: Partial<ArtifactMetadataShape>) => Layer.Layer<ArtifactMetadata>;
@@ -1317,7 +1365,7 @@ declare const Attestation_base: Context.ServiceClass<Attestation, "@effected/git
 export declare class Attestation extends Attestation_base {
   /** The live service, built over a `GitHubClient`. */
   static readonly layer: Layer.Layer<Attestation, never, GitHubClient>;
-  /** An in-memory double; unstubbed members die naming themselves. */
+  /** An in-memory double; an unstubbed member dies when run, naming itself. */
   static readonly makeTest: (overrides?: Partial<AttestationShape>) => AttestationShape;
   /** {@link Attestation.makeTest} behind a `Layer`. */
   static readonly layerTest: (overrides?: Partial<AttestationShape>) => Layer.Layer<Attestation>;
@@ -1463,7 +1511,8 @@ interface AuthenticatedAppShape {
    *
    * @remarks
    * Irreversible from the app's side: only the account can install it again.
-   * An installation that does not exist (or is already gone) fails with
+   * GitHub answers 202 and removes the installation in the background, so it
+   * may still be listed briefly after this returns. An installation that does not exist (or is already gone) fails with
    * `GitHubError { kind: "notFound" }`.
    */
   readonly uninstall: (installationId: number) => Effect.Effect<void, GitHubError>;
@@ -1510,7 +1559,7 @@ declare const AuthenticatedApp_base: Context.ServiceClass<AuthenticatedApp, "@ef
 export declare class AuthenticatedApp extends AuthenticatedApp_base {
   /** The live service, built over an App-JWT `GitHubClient`. */
   static readonly layer: Layer.Layer<AuthenticatedApp, never, GitHubClient>;
-  /** An in-memory double; unstubbed members die naming themselves. */
+  /** An in-memory double; an unstubbed member dies when run, naming itself. */
   static readonly makeTest: (overrides?: Partial<AuthenticatedAppShape>) => AuthenticatedAppShape;
   /** {@link AuthenticatedApp.makeTest} behind a `Layer`. */
   static readonly layerTest: (overrides?: Partial<AuthenticatedAppShape>) => Layer.Layer<AuthenticatedApp>;
@@ -1915,7 +1964,7 @@ declare const CheckRun_base: Context.ServiceClass<CheckRun, "@effected/github/Ch
 export declare class CheckRun extends CheckRun_base {
   /** The live service, built over a `GitHubClient`. */
   static readonly layer: Layer.Layer<CheckRun, never, GitHubClient>;
-  /** An in-memory double; unstubbed members die naming themselves. */
+  /** An in-memory double; an unstubbed member dies when run, naming itself. */
   static readonly makeTest: (overrides?: Partial<CheckRunShape>) => CheckRunShape;
   /** {@link CheckRun.makeTest} behind a `Layer`. */
   static readonly layerTest: (overrides?: Partial<CheckRunShape>) => Layer.Layer<CheckRun>;
@@ -1934,7 +1983,15 @@ export declare class CheckRun extends CheckRun_base {
 interface CodeScanningSetup {
   /** Whether default setup is `configured` or `not-configured`. */
   readonly state?: "configured" | "not-configured" | undefined;
-  /** The CodeQL languages to analyse. */
+  /**
+   * The CodeQL languages to analyse.
+   *
+   * @remarks
+   * CodeQL's names, not linguist's: JavaScript and TypeScript are the one
+   * combined `javascript-typescript`, and the separate `javascript` and
+   * `typescript` values are no longer accepted under the api-version the
+   * client pins.
+   */
   readonly languages?: ReadonlyArray<string> | undefined;
   /** `default` or `extended`. */
   readonly query_suite?: string | undefined;
@@ -2003,7 +2060,7 @@ export declare class CodeScanning extends CodeScanning_base {
    * with a clean typecheck.
    */
   static readonly layer: Layer.Layer<CodeScanning, never, GitHubClient>;
-  /** An in-memory double; unstubbed members die naming themselves. */
+  /** An in-memory double; an unstubbed member dies when run, naming itself. */
   static readonly makeTest: (overrides?: Partial<CodeScanningShape>) => CodeScanningShape;
   /** {@link CodeScanning.makeTest} behind a `Layer`. */
   static readonly layerTest: (overrides?: Partial<CodeScanningShape>) => Layer.Layer<CodeScanning>;
@@ -2080,7 +2137,7 @@ export declare class DeploymentEnvironment extends DeploymentEnvironment_base {
    * further down throws at import time with a clean typecheck.
    */
   static readonly layer: Layer.Layer<DeploymentEnvironment, never, GitHubClient>;
-  /** An in-memory double; unstubbed members die naming themselves. */
+  /** An in-memory double; an unstubbed member dies when run, naming itself. */
   static readonly makeTest: (overrides?: Partial<DeploymentEnvironmentShape>) => DeploymentEnvironmentShape;
   /** {@link DeploymentEnvironment.makeTest} behind a `Layer`. */
   static readonly layerTest: (overrides?: Partial<DeploymentEnvironmentShape>) => Layer.Layer<DeploymentEnvironment>;
@@ -2192,7 +2249,7 @@ export declare class GitBranch extends GitBranch_base {
    * layer is built.
    */
   static readonly layer: Layer.Layer<GitBranch, never, GitHubClient>;
-  /** An in-memory double; unstubbed members die naming themselves. */
+  /** An in-memory double; an unstubbed member dies when run, naming itself. */
   static readonly makeTest: (overrides?: Partial<GitBranchShape>) => GitBranchShape;
   /** {@link GitBranch.makeTest} behind a `Layer`. */
   static readonly layerTest: (overrides?: Partial<GitBranchShape>) => Layer.Layer<GitBranch>;
@@ -2328,7 +2385,7 @@ declare const GitCommit_base: Context.ServiceClass<GitCommit, "@effected/github/
 export declare class GitCommit extends GitCommit_base {
   /** The live service, built over a `GitHubClient`. */
   static readonly layer: Layer.Layer<GitCommit, never, GitHubClient>;
-  /** An in-memory double; unstubbed members die naming themselves. */
+  /** An in-memory double; an unstubbed member dies when run, naming itself. */
   static readonly makeTest: (overrides?: Partial<GitCommitShape>) => GitCommitShape;
   /** {@link GitCommit.makeTest} behind a `Layer`. */
   static readonly layerTest: (overrides?: Partial<GitCommitShape>) => Layer.Layer<GitCommit>;
@@ -2372,7 +2429,7 @@ declare const InstallationTokenStore_base: Context.ServiceClass<InstallationToke
 export declare class InstallationTokenStore extends InstallationTokenStore_base {
   /** An in-process store over a `Ref`, expiring entries against `Clock`. */
   static readonly layerMemory: Layer.Layer<InstallationTokenStore>;
-  /** An in-memory double; unstubbed members die naming themselves. */
+  /** An in-memory double; an unstubbed member dies when run, naming itself. */
   static readonly makeTest: (overrides?: Partial<InstallationTokenStoreShape>) => InstallationTokenStoreShape;
   /** {@link InstallationTokenStore.makeTest} behind a `Layer`. */
   static readonly layerTest: (overrides?: Partial<InstallationTokenStoreShape>) => Layer.Layer<InstallationTokenStore>;
@@ -2669,6 +2726,15 @@ interface GitHubAppOptions {
   readonly retry?: RetryPolicy | "off" | undefined;
   /** A replacement `fetch`, for tests and proxies. */
   readonly fetch?: typeof globalThis.fetch | undefined;
+  /**
+   * The REST api-version the app's clients pin; defaults to `"2026-03-10"`.
+   *
+   * @remarks
+   * The same option as `GitHubClientOptions.apiVersion`, applied to every
+   * client this module builds: as the app, as an installation, and
+   * unauthenticated.
+   */
+  readonly apiVersion?: string | undefined;
 }
 declare const GitHubApp_base: Context.ServiceClass<GitHubApp, "@effected/github/GitHubApp", GitHubAppShape>;
 /**
@@ -2875,7 +2941,7 @@ export declare class GitHubApp extends GitHubApp_base {
    * ```
    */
   static readonly cachedClientLayer: (request: CachedTokenRequest, options?: GitHubAppOptions) => Layer.Layer<GitHubClient, GitHubAppError, GitHubApp | InstallationTokenStore>;
-  /** An in-memory double; unstubbed members die naming themselves. */
+  /** An in-memory double; an unstubbed member dies when run, naming itself. */
   static readonly makeTest: (overrides?: Partial<GitHubAppShape>) => GitHubAppShape;
   /** {@link GitHubApp.makeTest} behind a `Layer`. */
   static readonly layerTest: (overrides?: Partial<GitHubAppShape>) => Layer.Layer<GitHubApp>;
@@ -3077,7 +3143,7 @@ declare const GitHubCommit_base: Context.ServiceClass<GitHubCommit, "@effected/g
 export declare class GitHubCommit extends GitHubCommit_base {
   /** The live service, built over a `GitHubClient`. */
   static readonly layer: Layer.Layer<GitHubCommit, never, GitHubClient>;
-  /** An in-memory double; unstubbed members die naming themselves. */
+  /** An in-memory double; an unstubbed member dies when run, naming itself. */
   static readonly makeTest: (overrides?: Partial<GitHubCommitShape>) => GitHubCommitShape;
   /** {@link GitHubCommit.makeTest} behind a `Layer`. */
   static readonly layerTest: (overrides?: Partial<GitHubCommitShape>) => Layer.Layer<GitHubCommit>;
@@ -3137,7 +3203,7 @@ declare const GitHubContent_base: Context.ServiceClass<GitHubContent, "@effected
 export declare class GitHubContent extends GitHubContent_base {
   /** The live service, built over a `GitHubClient`. */
   static readonly layer: Layer.Layer<GitHubContent, never, GitHubClient>;
-  /** An in-memory double; unstubbed members die naming themselves. */
+  /** An in-memory double; an unstubbed member dies when run, naming itself. */
   static readonly makeTest: (overrides?: Partial<GitHubContentShape>) => GitHubContentShape;
   /** {@link GitHubContent.makeTest} behind a `Layer`. */
   static readonly layerTest: (overrides?: Partial<GitHubContentShape>) => Layer.Layer<GitHubContent>;
@@ -3233,7 +3299,7 @@ declare const PullRequestComment_base: Context.ServiceClass<PullRequestComment,
 export declare class PullRequestComment extends PullRequestComment_base {
   /** The live service, built over a `GitHubClient`. */
   static readonly layer: Layer.Layer<PullRequestComment, never, GitHubClient>;
-  /** An in-memory double; unstubbed members die naming themselves. */
+  /** An in-memory double; an unstubbed member dies when run, naming itself. */
   static readonly makeTest: (overrides?: Partial<PullRequestCommentShape>) => PullRequestCommentShape;
   /** {@link PullRequestComment.makeTest} behind a `Layer`. */
   static readonly layerTest: (overrides?: Partial<PullRequestCommentShape>) => Layer.Layer<PullRequestComment>;
@@ -3390,7 +3456,7 @@ declare const GitHubIssue_base: Context.ServiceClass<GitHubIssue, "@effected/git
 export declare class GitHubIssue extends GitHubIssue_base {
   /** The live service, built over a `GitHubClient`. */
   static readonly layer: Layer.Layer<GitHubIssue, never, GitHubClient>;
-  /** An in-memory double; unstubbed members die naming themselves. */
+  /** An in-memory double; an unstubbed member dies when run, naming itself. */
   static readonly makeTest: (overrides?: Partial<GitHubIssueShape>) => GitHubIssueShape;
   /** {@link GitHubIssue.makeTest} behind a `Layer`. */
   static readonly layerTest: (overrides?: Partial<GitHubIssueShape>) => Layer.Layer<GitHubIssue>;
@@ -3510,7 +3576,7 @@ declare const GitHubRelease_base: Context.ServiceClass<GitHubRelease, "@effected
 export declare class GitHubRelease extends GitHubRelease_base {
   /** The live service, built over a `GitHubClient`. */
   static readonly layer: Layer.Layer<GitHubRelease, never, GitHubClient>;
-  /** An in-memory double; unstubbed members die naming themselves. */
+  /** An in-memory double; an unstubbed member dies when run, naming itself. */
   static readonly makeTest: (overrides?: Partial<GitHubReleaseShape>) => GitHubReleaseShape;
   /** {@link GitHubRelease.makeTest} behind a `Layer`. */
   static readonly layerTest: (overrides?: Partial<GitHubReleaseShape>) => Layer.Layer<GitHubRelease>;
@@ -3598,17 +3664,21 @@ type OwnerType = "User" | "Organization";
  */
 export declare const SECURITY_ANALYSIS_STATUS_FIELDS: ReadonlySet<string>;
 /**
- * Settings reachable **only** through the GraphQL `updateRepository` mutation,
- * mapped from snake_case keys to camelCase GraphQL input fields.
+ * Settings written through the GraphQL `updateRepository` mutation, mapped
+ * from snake_case keys to camelCase GraphQL input fields.
  *
  * @remarks
- * GitHub never exposed these on the REST repository endpoint — the
- * `PATCH /repos/{owner}/{repo}` route accepts none of them, and
- * `has_discussions` is the treacherous one: the REST **read** returns it, so
- * routing its write to the PATCH looks symmetric, but the PATCH silently
- * ignores unknown body fields and answers 200, so the write would look applied
- * while the repository never changed. Setting any of these forces a second
- * round trip to learn the repository's node id.
+ * `applySettings` checks this map **first**, so a key here always goes
+ * through GraphQL, even when the REST patch also declares it.
+ * `has_sponsorships` and `has_discussions` are GraphQL-only: the
+ * `PATCH /repos/{owner}/{repo}` route accepts neither, and `has_discussions`
+ * is the treacherous one — the REST **read** returns it, so routing its write
+ * to the PATCH looks symmetric, but the PATCH silently ignores unknown body
+ * fields and answers 200, so the write would look applied while the
+ * repository never changed. `has_pull_requests` is in the REST patch's body
+ * too; GraphQL is preferred for it so the three toggles travel together.
+ * Setting any of these forces a second round trip to learn the repository's
+ * node id.
  *
  * @public
  */
@@ -3648,7 +3718,7 @@ export declare const transformSecurityAndAnalysis: (value: unknown) => Record<st
  * agree right up until a field is dropped, which is exactly the case anyone
  * reading a dry run is trying to check.
  *
- * Both lists use the **caller's** key names, not the wire names, because the
+ * Every list uses the **caller's** key names, not the wire names, because the
  * audience for them is a person reading a plan against the config they wrote.
  *
  * @public
@@ -3658,10 +3728,25 @@ interface AppliedSettings {
   readonly rest: ReadonlyArray<string>;
   /** Keys sent through the GraphQL mutation, named as the caller supplied them. */
   readonly graphql: ReadonlyArray<string>;
+  /**
+   * Keys neither API accepts, which were **not sent**.
+   *
+   * @remarks
+   * A key that is not a GraphQL-only setting and not in the REST patch's
+   * declared body — a typo such as `has_discussion`, or a setting GitHub has
+   * not described — lands here, as does a key the client's api-version
+   * removed from the patch (`use_squash_pr_title_as_default` under
+   * `2026-03-10` and later; a client pinned to an older version still sends
+   * it). Sending it would be worse than useless: the
+   * REST `PATCH` ignores unknown fields and answers 200, so the key would be
+   * reported applied while the repository never changed. A caller that wants
+   * an unknown key to fail the run checks this list.
+   */
+  readonly ignored: ReadonlyArray<string>;
 }
 /**
- * Read and update a repository's settings, and look up its default branch, node
- * id and owner type.
+ * Read and update a repository's settings and topics, and look up its default
+ * branch, node id and owner type.
  *
  * @public
  */
@@ -3707,30 +3792,58 @@ interface GitHubRepositoryShape {
    * `updateSettings` is the thin, faithfully-typed PATCH and returns what
    * GitHub then reports. This is the **applicator**: it takes an open map,
    * routes each key to whichever API can actually set it, and returns an
-   * {@link AppliedSettings} naming the keys that were sent through each.
+   * {@link AppliedSettings} naming the keys that were sent through each and
+   * the keys neither accepts.
    *
    * Three settings — `has_sponsorships`, `has_pull_requests` and
-   * `has_discussions` ({@link GRAPHQL_ONLY_SETTINGS}) — are only reachable
-   * through GraphQL's `updateRepository`, which addresses a repository by **node
-   * id**. So a map touching any of them costs an extra read; a map touching none
+   * `has_discussions` ({@link GRAPHQL_ONLY_SETTINGS}) — are written through
+   * GraphQL's `updateRepository`, which addresses a repository by **node id**;
+   * the first and last are reachable no other way, and GraphQL is preferred
+   * for `has_pull_requests`. So a map touching any of them costs an extra read; a map touching none
    * does not, which is the common case.
    *
    * The map is open by design. GitHub's settings surface is large and moving,
-   * and a closed type here would date the package — but it also means a typo is
-   * forwarded rather than rejected, so a caller that owns a schema should
-   * validate before calling.
+   * and a closed type here would date the package. A key that is neither
+   * GraphQL-only nor in the REST patch's declared body — the key list is
+   * generated from GitHub's OpenAPI description — is not sent and is reported
+   * in `ignored`, rather than forwarded to a `PATCH` that would ignore it and
+   * answer 200. It does not fail the call, so additive GitHub API growth never
+   * breaks a run; a caller that owns a schema should still validate first.
    */
   readonly applySettings: (settings: Record<string, unknown>) => Effect.Effect<AppliedSettings, GitHubError | GitHubGraphQLError, Repo>;
+  /**
+   * The repository's topics, as GitHub stores them.
+   *
+   * @remarks
+   * Reads `GET /repos/{owner}/{repo}/topics`, which answers the whole set in
+   * one object, so there is nothing to paginate. GitHub stores every topic
+   * lowercased, so this is the value to compare a desired set against.
+   */
+  readonly topics: Effect.Effect<ReadonlyArray<string>, GitHubError, Repo>;
+  /**
+   * Replace the repository's whole topic set, and return the set GitHub stored.
+   *
+   * @remarks
+   * `PUT /repos/{owner}/{repo}/topics` replaces rather than merges, so `names`
+   * is the complete desired set and an empty array clears every topic.
+   *
+   * **The return value is not `names`.** GitHub lowercases every topic it
+   * stores, so a caller that records what it sent — `Effect`, say — sees drift
+   * on the next read, which answers `effect`. Record the returned array, which
+   * is GitHub's own answer to the write, as the applied state.
+   */
+  readonly setTopics: (names: ReadonlyArray<string>) => Effect.Effect<ReadonlyArray<string>, GitHubError, Repo>;
 }
 declare const GitHubRepository_base: Context.ServiceClass<GitHubRepository, "@effected/github/GitHubRepository", GitHubRepositoryShape>;
 /**
  * Read and update a repository's settings, including settings only GraphQL can
- * write, and look up its default branch, node id and owner type.
+ * write, read and replace its topics, and look up its default branch, node id
+ * and owner type.
  *
  * @remarks
  * Provide it with {@link GitHubRepository.layer}, which needs a `GitHubClient`;
- * every member also needs a `Repo` in `R`. `settings`, `defaultBranch`, `nodeId`
- * and `ownerType` are `Effect` values, not functions.
+ * every member also needs a `Repo` in `R`. `settings`, `defaultBranch`, `nodeId`,
+ * `ownerType` and `topics` are `Effect` values, not functions.
  *
  * @example
  * ```ts
@@ -3741,7 +3854,7 @@ declare const GitHubRepository_base: Context.ServiceClass<GitHubRepository, "@ef
  *   const repository = yield* GitHubRepository;
  *   const branch = yield* repository.defaultBranch;
  *   const applied = yield* repository.applySettings({ has_wiki: false, has_discussions: true });
- *   return { branch, applied }; // applied.rest, applied.graphql
+ *   return { branch, applied }; // applied.rest, applied.graphql, applied.ignored
  * });
  * ```
  *
@@ -3750,7 +3863,7 @@ declare const GitHubRepository_base: Context.ServiceClass<GitHubRepository, "@ef
 export declare class GitHubRepository extends GitHubRepository_base {
   /** The live service, built over a `GitHubClient`. */
   static readonly layer: Layer.Layer<GitHubRepository, never, GitHubClient>;
-  /** An in-memory double; unstubbed members die naming themselves. */
+  /** An in-memory double; an unstubbed member dies when run, naming itself. */
   static readonly makeTest: (overrides?: Partial<GitHubRepositoryShape>) => GitHubRepositoryShape;
   /** {@link GitHubRepository.makeTest} behind a `Layer`. */
   static readonly layerTest: (overrides?: Partial<GitHubRepositoryShape>) => Layer.Layer<GitHubRepository>;
@@ -3880,7 +3993,7 @@ declare const GitTag_base: Context.ServiceClass<GitTag, "@effected/github/GitTag
 export declare class GitTag extends GitTag_base {
   /** The live service, built over a `GitHubClient`. */
   static readonly layer: Layer.Layer<GitTag, never, GitHubClient>;
-  /** An in-memory double; unstubbed members die naming themselves. */
+  /** An in-memory double; an unstubbed member dies when run, naming itself. */
   static readonly makeTest: (overrides?: Partial<GitTagShape>) => GitTagShape;
   /** {@link GitTag.makeTest} behind a `Layer`. */
   static readonly layerTest: (overrides?: Partial<GitTagShape>) => Layer.Layer<GitTag>;
@@ -3917,7 +4030,27 @@ declare const PullRequestInfo_base: Schema.Class<PullRequestInfo, Schema.Struct<
   readonly mergedAt: Schema.Option<Schema.DateTimeUtcFromString>;
   /** The description, when GitHub sent one. */
   readonly body: Schema.optionalKey<Schema.String>;
-  /** The merge commit, once there is one. */
+  /**
+   * The sha of the commit the merge produced; absent until the pull request
+   * has merged.
+   *
+   * @remarks
+   * Read from GraphQL's `PullRequest.mergeCommit.oid`. The REST pull request
+   * object no longer carries `merge_commit_sha` under the api-version this
+   * package pins, so a merged pull request costs one extra GraphQL round trip
+   * per single read (`get`, `update`, `upsert`), and an open or
+   * closed-unmerged one costs nothing. When the REST response does carry the
+   * field (a client pinned to an older api-version), it is used for a merged
+   * pull request and the GraphQL read is skipped.
+   *
+   * **A list read leaves it absent unless asked.** `list` and
+   * `listAssociatedWithCommit` fill it only when called with
+   * `mergeCommits: true`, at one GraphQL call per 100 merged pull requests.
+   *
+   * It is never the speculative test-merge commit GitHub computes for an open
+   * pull request, so `mergeCommitSha === sha` means "this commit is what the
+   * pull request merged as".
+   */
   readonly mergeCommitSha: Schema.optionalKey<Schema.String>;
 }>, {}>;
 /**
@@ -3951,7 +4084,7 @@ interface UpsertedPullRequest {
  */
 interface PullRequestShape {
   /** Read one pull request. Fails `notFound` when it does not exist. */
-  readonly get: (number: number) => Effect.Effect<PullRequestInfo, GitHubError, Repo>;
+  readonly get: (number: number) => Effect.Effect<PullRequestInfo, GitHubError | GitHubGraphQLError, Repo>;
   /**
    * Open, closed or all pull requests, optionally filtered.
    *
@@ -3968,13 +4101,20 @@ interface PullRequestShape {
    * in the wrong account — the filter then matches nothing, silently. When the
    * head may live in a fork, pass a qualified `owner:ref` built from the source
    * owner rather than from anything this projection carries.
+   *
+   * **`mergeCommitSha` is absent on every result unless `mergeCommits` is
+   * `true`.** The REST list no longer carries it, and filling it costs one
+   * GraphQL call per 100 merged pull requests in the result, so it is opt-in.
+   * Only with the option can this fail with `GitHubGraphQLError`.
    */
   readonly list: (options?: {
     readonly head?: string | undefined;
     readonly base?: string | undefined;
     readonly state?: "open" | "closed" | "all" | undefined;
     readonly page?: PageOptions | undefined;
-  }) => Effect.Effect<ReadonlyArray<PullRequestInfo>, GitHubError, Repo>;
+    /** Fill `mergeCommitSha` on merged results from GraphQL. Defaults to `false`. */
+    readonly mergeCommits?: boolean | undefined;
+  }) => Effect.Effect<ReadonlyArray<PullRequestInfo>, GitHubError | GitHubGraphQLError, Repo>;
   /**
    * The files a pull request changes.
    *
@@ -3992,10 +4132,17 @@ interface PullRequestShape {
    *
    * @remarks
    * Paginated: pass `page` to bound the walk.
+   *
+   * **`mergeCommitSha` is absent on every result unless `mergeCommits` is
+   * `true`**, at one GraphQL call per 100 merged pull requests — so a caller
+   * matching `sha` against the merge commit passes it. Only with the option
+   * can this fail with `GitHubGraphQLError`.
    */
   readonly listAssociatedWithCommit: (sha: string, options?: {
     readonly page?: PageOptions | undefined;
-  }) => Effect.Effect<ReadonlyArray<PullRequestInfo>, GitHubError, Repo>;
+    /** Fill `mergeCommitSha` on merged results from GraphQL. Defaults to `false`. */
+    readonly mergeCommits?: boolean | undefined;
+  }) => Effect.Effect<ReadonlyArray<PullRequestInfo>, GitHubError | GitHubGraphQLError, Repo>;
   /** Open a pull request from `head` into `base`. */
   readonly create: (input: {
     readonly title: string;
@@ -4010,7 +4157,7 @@ interface PullRequestShape {
     readonly body?: string | undefined;
     readonly state?: "open" | "closed" | undefined;
     readonly base?: string | undefined;
-  }) => Effect.Effect<PullRequestInfo, GitHubError, Repo>;
+  }) => Effect.Effect<PullRequestInfo, GitHubError | GitHubGraphQLError, Repo>;
   /**
    * Update the open pull request for `head`→`base`, or open one.
    *
@@ -4024,7 +4171,7 @@ interface PullRequestShape {
     readonly base: string;
     readonly body?: string | undefined;
     readonly draft?: boolean | undefined;
-  }) => Effect.Effect<UpsertedPullRequest, GitHubError, Repo>;
+  }) => Effect.Effect<UpsertedPullRequest, GitHubError | GitHubGraphQLError, Repo>;
   /** Merge a pull request and return the merge commit sha. `method` defaults to GitHub's choice. */
   readonly merge: (number: number, options?: {
     readonly method?: "merge" | "squash" | "rebase" | undefined;
@@ -4079,7 +4226,7 @@ declare const PullRequest_base: Context.ServiceClass<PullRequest, "@effected/git
 export declare class PullRequest extends PullRequest_base {
   /** The live service, built over a `GitHubClient`. */
   static readonly layer: Layer.Layer<PullRequest, never, GitHubClient>;
-  /** An in-memory double; unstubbed members die naming themselves. */
+  /** An in-memory double; an unstubbed member dies when run, naming itself. */
   static readonly makeTest: (overrides?: Partial<PullRequestShape>) => PullRequestShape;
   /** {@link PullRequest.makeTest} behind a `Layer`. */
   static readonly layerTest: (overrides?: Partial<PullRequestShape>) => Layer.Layer<PullRequest>;
@@ -4175,7 +4322,7 @@ export declare class RepositorySecret extends RepositorySecret_base {
    * further down throws at import time with a clean typecheck.
    */
   static readonly layer: Layer.Layer<RepositorySecret, never, GitHubClient>;
-  /** An in-memory double; unstubbed members die naming themselves. */
+  /** An in-memory double; an unstubbed member dies when run, naming itself. */
   static readonly makeTest: (overrides?: Partial<RepositorySecretShape>) => RepositorySecretShape;
   /** {@link RepositorySecret.makeTest} behind a `Layer`. */
   static readonly layerTest: (overrides?: Partial<RepositorySecretShape>) => Layer.Layer<RepositorySecret>;
@@ -4255,7 +4402,7 @@ export declare class RepositorySecurity extends RepositorySecurity_base {
    * further down throws at import time with a clean typecheck.
    */
   static readonly layer: Layer.Layer<RepositorySecurity, never, GitHubClient>;
-  /** An in-memory double; unstubbed members die naming themselves. */
+  /** An in-memory double; an unstubbed member dies when run, naming itself. */
   static readonly makeTest: (overrides?: Partial<RepositorySecurityShape>) => RepositorySecurityShape;
   /** {@link RepositorySecurity.makeTest} behind a `Layer`. */
   static readonly layerTest: (overrides?: Partial<RepositorySecurityShape>) => Layer.Layer<RepositorySecurity>;
@@ -4360,7 +4507,7 @@ export declare class RepositoryVariable extends RepositoryVariable_base {
    * further down throws at import time with a clean typecheck.
    */
   static readonly layer: Layer.Layer<RepositoryVariable, never, GitHubClient>;
-  /** An in-memory double; unstubbed members die naming themselves. */
+  /** An in-memory double; an unstubbed member dies when run, naming itself. */
   static readonly makeTest: (overrides?: Partial<RepositoryVariableShape>) => RepositoryVariableShape;
   /** {@link RepositoryVariable.makeTest} behind a `Layer`. */
   static readonly layerTest: (overrides?: Partial<RepositoryVariableShape>) => Layer.Layer<RepositoryVariable>;
@@ -4490,7 +4637,7 @@ export declare class Ruleset extends Ruleset_base {
    * further down throws at import time with a clean typecheck.
    */
   static readonly layer: Layer.Layer<Ruleset, never, GitHubClient>;
-  /** An in-memory double; unstubbed members die naming themselves. */
+  /** An in-memory double; an unstubbed member dies when run, naming itself. */
   static readonly makeTest: (overrides?: Partial<RulesetShape>) => RulesetShape;
   /** {@link Ruleset.makeTest} behind a `Layer`. */
   static readonly layerTest: (overrides?: Partial<RulesetShape>) => Layer.Layer<Ruleset>;
@@ -4702,15 +4849,21 @@ interface WorkflowDispatchShape {
    * Fire a `workflow_dispatch` event and report the run it created.
    *
    * @remarks
-   * Sends the same request as {@link WorkflowDispatchShape.dispatch} with
-   * `return_run_details: true`. GitHub then answers 200 with the run's id and
-   * URLs, which arrive as `Option.some` of a {@link DispatchedRun}; a 200 body
-   * that does not have that shape fails with a `decode` `GitHubError`.
-   *
-   * A 204 with no body is `Option.none()`. That is what a GitHub Enterprise
-   * Server predating the field answers — it ignores `return_run_details` and
-   * still dispatches — so it is **not a failure**: the workflow was dispatched,
-   * the server just did not say which run it created.
+   * Sends the same request as {@link WorkflowDispatchShape.dispatch}. Under
+   * the api-version the client pins by default, GitHub answers every dispatch
+   * with 200 and the run's id and URLs, which arrive as `Option.some` of a
+   * {@link DispatchedRun}; a 200 body that does not have that shape fails with
+   * a `decode` `GitHubError`.
+   *
+   * A 204 with no body is `Option.none()`. That is what an older api-version
+   * answers when it does not report the run — a GitHub Enterprise Server that
+   * predates the field, say — and it is **not a failure**: the workflow was
+   * dispatched, the server just did not say which run it created.
+   *
+   * Older api-versions report the run only when asked, so a client pinned
+   * before `2026-03-10` (`GitHubClientShape.apiVersion`) sends
+   * `return_run_details: true`; from `2026-03-10` on the flag is removed from
+   * the request and is not sent.
    *
    * Under `GitHubClient.layerFixture`, stub the 204 the way every other
    * no-body route is stubbed: answer the dispatch route with `null`. `""`
@@ -4760,8 +4913,8 @@ interface WorkflowDispatchShape {
    *
    * The run is identified by {@link WorkflowDispatchShape.dispatchWithRun}:
    * when GitHub reports the run it created, exactly that run is polled, so
-   * concurrent dispatches cannot be confused. When it does not (a 204 from a
-   * GitHub Enterprise Server predating `return_run_details`), the run is found
+   * concurrent dispatches cannot be confused. When it does not (a 204 from an
+   * older api-version), the run is found
    * instead by branch, creation time and workflow path — and on that fallback
    * alone, concurrent dispatches of the same workflow on the same ref can be
    * confused.
@@ -4801,7 +4954,7 @@ declare const WorkflowDispatch_base: Context.ServiceClass<WorkflowDispatch, "@ef
 export declare class WorkflowDispatch extends WorkflowDispatch_base {
   /** The live service, built over a `GitHubClient`. */
   static readonly layer: Layer.Layer<WorkflowDispatch, never, GitHubClient>;
-  /** An in-memory double; unstubbed members die naming themselves. */
+  /** An in-memory double; an unstubbed member dies when run, naming itself. */
   static readonly makeTest: (overrides?: Partial<WorkflowDispatchShape>) => WorkflowDispatchShape;
   /** {@link WorkflowDispatch.makeTest} behind a `Layer`. */
   static readonly layerTest: (overrides?: Partial<WorkflowDispatchShape>) => Layer.Layer<WorkflowDispatch>;