@effected/github 0.1.0

package/index.d.ts

@@ -0,0 +1,2427 @@
+import { Config, Context, Duration, Effect, Layer, Option, Redacted, Result, Schedule, Schema, SchemaError, Scope, Stream } from "effect";
+import { PaginatingEndpoints } from "@octokit/plugin-paginate-rest";
+import { Endpoints, RequestHeaders } from "@octokit/types";
+import { SemVer } from "@effected/semver";
+//#region src/GitHubError.d.ts
+/**
+ * Why a GitHub call failed, as a value you can branch on.
+ *
+ * @remarks
+ * This discriminant is what replaces string-matching an error message. The
+ * package this replaces carried a free-form `reason` string and nothing else
+ * structural, so consumers grepped it: one repo lowercased a GraphQL message and
+ * tested `includes("already") || includes("exists")`, and another re-issued an
+ * existence check after every failed branch creation because it could not tell
+ * "someone else created it" from "that failed".
+ *
+ * @public
+ */
+declare const GitHubErrorKind: Schema.Literals<readonly ["notFound", "alreadyExists", "rejected", "unauthorized", "rateLimited", "transport", "decode"]>;
+declare const GitHubError_base: Schema.Class<GitHubError, Schema.TaggedStruct<"GitHubError", {
+  /** Structural routing. Branch on this, never on the rendered message. */
+  readonly kind: Schema.Literals<readonly ["notFound", "alreadyExists", "rejected", "unauthorized", "rateLimited", "transport", "decode"]>;
+  /** What was attempted: a resource method (`"GitBranch.upsert"`) or a raw route. */
+  readonly operation: Schema.String;
+  /** Human-readable cause, for logs and messages. Never a routing surface. */
+  readonly reason: Schema.String;
+  /** GitHub's HTTP status, when the request reached GitHub at all. */
+  readonly status: Schema.optionalKey<Schema.Int>;
+  /**
+   * A server-advised delay before retrying, in milliseconds.
+   *
+   * @remarks
+   * Written by the client from `retry-after` or the rate-limit reset, and read
+   * by exactly one thing: the retry `Schedule`. It is a policy input, not
+   * information for a caller — which is why it is optional and why the
+   * `retryable` boolean it used to travel with is now a derived getter.
+   */
+  readonly retryAfterMillis: Schema.optionalKey<Schema.Int>;
+  /** The underlying throwable, when one exists. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Every REST failure this package produces, from every resource.
+ *
+ * @remarks
+ * One error class, not one per resource. Across the six repos surveyed for this
+ * port, consumers read `reason` about forty times, `status` twice, `operation`
+ * twice, and matched a resource-specific `_tag` exactly **once** — at a call
+ * site that disappears entirely now that `GitBranch.upsert` exists. Eighteen
+ * near-identical error classes and thirteen near-identical mapper closures
+ * bought that one match.
+ *
+ * What replaces them is {@link GitHubErrorKind} for routing and `operation` for
+ * identification. This mirrors `@effected/git`, where the rule is that no
+ * consumer ever string-matches stderr because classification happens once.
+ *
+ * @public
+ */
+declare class GitHubError extends GitHubError_base {
+  /** `"GitBranch.upsert failed (422): Reference already exists"`. */
+  get message(): string;
+  /**
+   * Whether retrying could plausibly succeed.
+   *
+   * @remarks
+   * Derived from `kind` rather than stored. A 404 or a
+   * validation rejection will fail identically on every attempt; only a
+   * transport failure or a rate limit can change its mind.
+   */
+  get retryable(): boolean;
+  /** The requested thing is not there. */
+  static notFound(operation: string, subject: string): GitHubError;
+  /** The thing you asked to create is already there. */
+  static alreadyExists(operation: string, subject: string): GitHubError;
+  /** GitHub understood the request and refused it. */
+  static rejected(operation: string, status: number, reason: string): GitHubError;
+  /** A response did not match the schema it was decoded against. */
+  static decode(operation: string, reason: string, cause?: unknown): GitHubError;
+  /**
+   * Classify anything octokit threw.
+   *
+   * @remarks
+   * The single classification step for the whole package — every resource
+   * method's failures come through here, so the taxonomy cannot drift between
+   * resources the way thirteen hand-written mapper closures did.
+   *
+   * `nowMillis` is passed in rather than read from the wall clock so the
+   * function stays pure and total: the rate-limit reset header is an absolute
+   * epoch second, and turning it into a delay needs a "now" the caller controls.
+   * The client supplies `Clock.currentTimeMillis`, which is the `TestClock`
+   * under test.
+   */
+  static fromOctokit(operation: string, error: unknown, nowMillis: number): GitHubError;
+  /**
+   * A predicate over one or more kinds, for `Effect.catchIf`.
+   *
+   * @example
+   * ```ts
+   * import { GitHubError } from "@effected/github";
+   * import { Effect } from "effect";
+   *
+   * declare const read: Effect.Effect<string, GitHubError>;
+   *
+   * const orDefault = read.pipe(
+   *   Effect.catchIf(GitHubError.hasKind("notFound"), () => Effect.succeed("")),
+   * );
+   * ```
+   */
+  static hasKind(...kinds: ReadonlyArray<(typeof GitHubErrorKind.literals)[number]>): (error: GitHubError) => boolean;
+}
+//#endregion
+//#region src/GraphQL.d.ts
+declare const GraphQLErrorEntry_base: Schema.Class<GraphQLErrorEntry, Schema.Struct<{
+  /** GitHub's prose. */
+  readonly message: Schema.String;
+  /** GitHub's own classification, e.g. `"NOT_FOUND"` or `"FORBIDDEN"`. */
+  readonly type: Schema.optionalKey<Schema.String>;
+}>, {}>;
+/**
+ * One entry from a GraphQL response's `errors` array.
+ *
+ * @public
+ */
+declare class GraphQLErrorEntry extends GraphQLErrorEntry_base {}
+declare const GitHubGraphQLError_base: Schema.Class<GitHubGraphQLError, Schema.TaggedStruct<"GitHubGraphQLError", {
+  /**
+   * Structural routing, mirroring `GitHubError`'s.
+   *
+   * @remarks
+   * `"alreadyExists"` exists here for the same reason it exists on the REST
+   * error: without it a consumer lowercases the message and greps it for
+   * `"already"` and `"exists"`, which is exactly what one surveyed repo did to
+   * make project creation idempotent.
+   */
+  readonly kind: Schema.Literals<readonly ["alreadyExists", "notFound", "rejected", "unauthorized", "rateLimited", "transport", "decode"]>;
+  /** The document's name, e.g. `"linkedIssues"` — never the literal `"graphql"`. */
+  readonly operation: Schema.String;
+  /** Human-readable cause, for logs. */
+  readonly reason: Schema.String;
+  /** Everything GitHub reported, in order. */
+  readonly errors: Schema.$Array<typeof GraphQLErrorEntry>;
+  /** A server-advised delay in milliseconds, read only by the retry schedule. */
+  readonly retryAfterMillis: Schema.optionalKey<Schema.Int>;
+  /** The underlying throwable, when one exists. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A GraphQL call failed.
+ *
+ * @remarks
+ * Separate from `GitHubError` because GraphQL genuinely answers differently:
+ * a 200 response can still carry failures, and it carries a **list** of them.
+ * `errors` is the one structured field a surveyed consumer actually read.
+ *
+ * @public
+ */
+declare class GitHubGraphQLError extends GitHubGraphQLError_base {
+  get message(): string;
+  /** Whether retrying could plausibly succeed. Derived, like the REST error's. */
+  get retryable(): boolean;
+  /** A response arrived but did not match the document's declared schema. */
+  static decode(operation: string, reason: string, cause?: unknown): GitHubGraphQLError;
+  /**
+   * Classify anything the GraphQL transport threw.
+   *
+   * @remarks
+   * octokit surfaces two different failures here: a `GraphqlResponseError`,
+   * which is an HTTP 200 whose body carries `errors`, and an ordinary HTTP
+   * failure with a `status`. Both arrive as throwables and both are read
+   * structurally, for the same reason the REST classifier does it — the error
+   * classes live in packages this one does not declare.
+   */
+  static fromThrowable(operation: string, error: unknown, nowMillis: number): GitHubGraphQLError;
+}
+/**
+ * A named GraphQL document, its variables, and how to read its answer.
+ *
+ * @remarks
+ * This is the mechanism that makes `client.graphql` return a **domain value**
+ * rather than an `unknown` the caller casts. The package this replaces took a
+ * query string and a caller-chosen type parameter with nothing connecting them,
+ * so every consumer wrote its own response interface and hoped.
+ *
+ * The kit owns the documents its resources need; a consumer with a domain of
+ * its own — silk-sync-action's ProjectV2 work, for instance — builds its own
+ * `GraphQLDocument` and gets the same typing and the same error taxonomy
+ * without this package having to know about its schema.
+ *
+ * @example
+ * ```ts
+ * import { GraphQLDocument } from "@effected/github";
+ * import { Schema } from "effect";
+ *
+ * const ViewerLogin = GraphQLDocument.make({
+ *   name: "viewerLogin",
+ *   document: `query { viewer { login } }`,
+ *   response: Schema.Struct({ viewer: Schema.Struct({ login: Schema.String }) }),
+ * })<{ readonly login: string }>();
+ * ```
+ *
+ * @public
+ */
+declare class GraphQLDocument<A, V extends Record<string, unknown>> {
+  /** Names the span and the error's `operation`. */
+  readonly name: string;
+  /** The document text sent to GitHub. */
+  readonly document: string;
+  /** Decodes the raw `data` payload into the domain value. */
+  readonly decode: (raw: unknown) => Effect.Effect<A, SchemaError.SchemaError>;
+  /**
+   * Turns the caller's variables into the wire object.
+   *
+   * @remarks
+   * Identity by default. It exists so `V` is genuinely load-bearing: without
+   * a member mentioning it, TypeScript's structural typing would make
+   * documents with different variable shapes interchangeable and the
+   * call-site checking would be decorative.
+   */
+  readonly encodeVariables: (variables: V) => Record<string, unknown>;
+  private constructor();
+  /**
+   * Build a document from a response schema.
+   *
+   * @remarks
+   * Curried, because `A` is inferred from `response` while `V` is stated:
+   * TypeScript takes explicit type arguments all-or-nothing, so a single call
+   * would force the caller to spell out the decoded type as well.
+   */
+  static make<A, I>(options: {
+    readonly name: string;
+    readonly document: string;
+    readonly response: Schema.Codec<A, I>;
+  }): <V extends Record<string, unknown>>(encodeVariables?: (variables: V) => Record<string, unknown>) => GraphQLDocument<A, V>;
+}
+//#endregion
+//#region src/Resilience.d.ts
+declare const RateLimitSnapshot_base: Schema.Class<RateLimitSnapshot, Schema.Struct<{
+  /** Requests left in the current window. */
+  readonly remaining: Schema.Int;
+  /** The window's ceiling. */
+  readonly limit: Schema.Int;
+  /** When the window resets, as epoch **seconds** — GitHub's own unit. */
+  readonly resetEpochSeconds: Schema.Int;
+}>, {}>;
+/**
+ * What GitHub's rate-limit headers said on the most recent REST response.
+ *
+ * @remarks
+ * Every REST response carries `x-ratelimit-remaining`, `x-ratelimit-limit` and
+ * `x-ratelimit-reset`; the client parses them into this and keeps the latest
+ * one. Read it through the client's `rateLimit` member when you want to pace
+ * yourself — **nothing in this package throttles on your behalf.**
+ *
+ * The package this replaces coupled the writer and the reader through an
+ * optional shared `Ref` service that both resolved with `Effect.serviceOption`,
+ * so an application that forgot to provide it got two private cells and a
+ * silently dead feature. Here the cell lives inside the client layer that writes
+ * it, and this is the only way to read it.
+ *
+ * @public
+ */
+declare class RateLimitSnapshot extends RateLimitSnapshot_base {
+  /** Milliseconds until the window resets, relative to `nowMillis`, floored at zero. */
+  millisUntilReset(nowMillis: number): number;
+  /** True when the budget is spent. */
+  get isExhausted(): boolean;
+}
+/**
+ * The shape {@link RetryPolicy} needs from a failure to decide anything.
+ *
+ * @remarks
+ * Declared structurally so this module imports no error class. That keeps the
+ * policy usable for both the REST and the GraphQL error without either of them
+ * importing the other, and it makes every policy decision testable against a
+ * two-field literal instead of a constructed error.
+ *
+ * @public
+ */
+interface RetryableFailure {
+  /** Whether retrying could plausibly succeed. */
+  readonly retryable: boolean;
+  /** A server-advised delay in milliseconds, when GitHub sent one. */
+  readonly retryAfterMillis?: number | undefined;
+}
+declare const RetryPolicy_base: Schema.Class<RetryPolicy, Schema.Struct<{
+  /** Retries after the first attempt. `0` disables retrying. */
+  readonly maxRetries: Schema.Int;
+  /** The first backoff step; doubles per attempt. */
+  readonly baseDelay: Schema.DurationFromMillis;
+  /** The computed backoff never exceeds this. */
+  readonly maxDelay: Schema.DurationFromMillis;
+  /** Prefer GitHub's `retry-after` / rate-limit reset over the computed backoff. */
+  readonly respectRetryAfter: Schema.Boolean;
+  /**
+   * Refuse to wait longer than this for a server-advised delay.
+   *
+   * @remarks
+   * A primary rate-limit window can be three quarters of an hour out. Sleeping
+   * through it converts a failure into a hang, so past this ceiling the error
+   * is re-failed immediately and the caller decides what to do.
+   */
+  readonly maxServerAdvisedDelay: Schema.DurationFromMillis;
+}>, {}>;
+/**
+ * How the client retries a failed request.
+ *
+ * @remarks
+ * There is exactly **one** retry policy in this package, and it is wired into
+ * the client so every resource inherits it and no resource carries its own. The
+ * package this replaces shipped four mutually inconsistent policies — a
+ * hand-rolled recursive loop, a second exported `Schedule` that ignored
+ * server-advised delays, a per-operation branch retry layered on top of the
+ * client's, and a rate-limiter retry with no predicate at all, which cheerfully
+ * retried permission denials — and consumers added two more on top.
+ *
+ * Only failures that report `retryable` are retried, which for `GitHubError` means a transport failure or a rate limit. A 404, a
+ * validation rejection and an authorization failure fail on the first attempt.
+ *
+ * @public
+ */
+declare class RetryPolicy extends RetryPolicy_base {
+  /** Four retries, 1s base, 30s cap, honoring server-advised delays up to a minute. */
+  static readonly default: RetryPolicy;
+  /** Retries nothing; every failure surfaces on the first attempt. */
+  static readonly none: RetryPolicy;
+  /**
+   * Whether this policy would retry `failure` at all, ignoring attempt counts.
+   *
+   * @remarks
+   * Pure and total, so the classification is testable without a clock, a
+   * runtime or a schedule.
+   */
+  retries(failure: RetryableFailure): boolean;
+  /**
+   * The delay before the given attempt, for a failure and a `[0, 1)` draw.
+   *
+   * @remarks
+   * A server-advised delay wins outright when `respectRetryAfter`
+   * is set: GitHub knows when its window reopens and a computed backoff can only
+   * guess. Otherwise this is **full jitter** — a uniform draw from
+   * `[0, min(baseDelay * 2^(attempt-1), maxDelay)]` — which spreads a fleet of
+   * retrying callers rather than synchronizing them into a second herd.
+   *
+   * `random` is a parameter so the arithmetic is checkable without stubbing a
+   * generator.
+   */
+  delayFor(failure: RetryableFailure, attempt: number, random: number): Duration.Duration;
+  /** The server-advised delay, when there is one and this policy honors it. */
+  private advisedMillis;
+  /**
+   * The `Schedule` this policy compiles to, for `Effect.retry`.
+   *
+   * @remarks
+   * Built on `Schedule.modifyDelay`, whose callback receives the schedule's
+   * `Metadata` — including the **input that failed**. That is what makes a
+   * header-driven policy expressible as a `Schedule` at all: the delay is a
+   * function of the error, not only of the attempt number. Not knowing this was
+   * available is why the package this replaces hand-rolled a recursive retry
+   * loop instead of using `Effect.retry`.
+   */
+  schedule<E extends RetryableFailure>(): Schedule.Schedule<number, E>;
+}
+//#endregion
+//#region src/Rest.d.ts
+/**
+ * Every REST route GitHub documents, as a `"<METHOD> <path>"` literal — for
+ * example `"GET /repos/{owner}/{repo}"`.
+ *
+ * @remarks
+ * This is the key the whole typed surface turns on. `@octokit/types` generates
+ * the `Endpoints` map from GitHub's own OpenAPI description, so a route literal
+ * carries both its parameter shape and its response shape with it, and neither
+ * a caller nor an implementation ever has to name a payload type by hand.
+ *
+ * The generated map is **types only** — `@octokit/types` ships no JavaScript at
+ * all — so leaning on it costs zero runtime bytes.
+ *
+ * @public
+ */
+type Route = keyof Endpoints;
+/**
+ * Transport knobs octokit accepts on any route, narrowed to the three this
+ * package allows.
+ *
+ * @remarks
+ * octokit's own `RequestParameters` carries an `[parameter: string]: unknown`
+ * index signature, so intersecting it would silently accept every misspelled
+ * parameter. These three are the ones the surveyed call sites genuinely need:
+ * `headers` for a release asset's `content-type` and the attestations API
+ * version pin, `mediaType.format` for raw content reads, and `baseUrl` for the
+ * `uploads.github.com` host that release-asset uploads go to. Everything else a
+ * caller might reach for is a real endpoint parameter and is already typed.
+ *
+ * @public
+ */
+interface RequestExtras {
+  /** Extra request headers. Keys must be lowercase. */
+  readonly headers?: RequestHeaders;
+  /** Media-type negotiation, e.g. `{ format: "raw" }`. */
+  readonly mediaType?: {
+    readonly format?: string;
+  };
+  /** Overrides the API host for this one request. */
+  readonly baseUrl?: string;
+}
+/**
+ * The parameters `Route` accepts — path, query and body parameters from
+ * GitHub's OpenAPI description, plus the extras below.
+ *
+ * @public
+ */
+type Params<R extends Route> = Endpoints[R]["parameters"] & RequestExtras;
+/**
+ * The full response `Route` returns, including `status`, `headers` and `data`.
+ *
+ * @public
+ */
+type Response<R extends Route> = Endpoints[R]["response"];
+/**
+ * The `data` payload `Route` returns.
+ *
+ * @public
+ */
+type Data<R extends Route> = Endpoints[R]["response"]["data"];
+/**
+ * The subset of routes that paginate.
+ *
+ * @remarks
+ * Handing a non-paginating route to a paginating call is a **compile** error,
+ * which the string-keyed surface this package replaces could not express.
+ *
+ * @public
+ */
+type PaginatingRoute = keyof PaginatingEndpoints;
+/**
+ * One element of a paginating route's collection.
+ *
+ * @remarks
+ * Derived here rather than imported: `@octokit/plugin-paginate-rest` computes
+ * the same thing internally as `GetResultsType`, but does not export it. The
+ * second branch covers the search-shaped endpoints whose payload is
+ * `{ total_count, items }` rather than a bare array — octokit normalizes those
+ * to the inner array at runtime, and this mirrors that at the type level.
+ *
+ * @public
+ */
+type Item<R extends PaginatingRoute> = PaginatingEndpoints[R]["response"]["data"] extends ReadonlyArray<infer T> ? T : PaginatingEndpoints[R]["response"]["data"] extends {
+  readonly items: ReadonlyArray<infer T>;
+} ? T : never;
+declare const PageOptions_base: Schema.Class<PageOptions, Schema.Struct<{
+  /** Items requested per page. GitHub's ceiling is 100. */
+  readonly perPage: Schema.optionalKey<Schema.Int>;
+  /** Stop after this many pages. Absent means "until GitHub stops". */
+  readonly maxPages: Schema.optionalKey<Schema.Int>;
+}>, {}>;
+/**
+ * How far a paginated read should go.
+ *
+ * @remarks
+ * Both fields are honored by every paginating method in this package. The
+ * package it replaces accepted them on the client and then passed `{}` at six
+ * of its eight call sites, so callers silently got 100-item pages and an
+ * unbounded walk with no way to say otherwise.
+ *
+ * `perPage` is **validated, not clamped**: GitHub caps a page at 100 and
+ * silently ignores anything larger, so a caller asking for 250 has a bug whose
+ * arithmetic is already wrong. Failing at the boundary is cheaper than
+ * discovering it in production.
+ *
+ * @public
+ */
+declare class PageOptions extends PageOptions_base {
+  /** Reads every page, 100 at a time — GitHub's maximum page size. */
+  static readonly all: PageOptions;
+  /**
+   * Reads at most one page of `perPage` items.
+   *
+   * @remarks
+   * The shape a "is there any?" or "give me the newest few" read wants, where
+   * walking every page is waste.
+   */
+  static first(perPage: number): PageOptions;
+}
+//#endregion
+//#region src/GitHubClient.d.ts
+/**
+ * The typed GitHub transport: one request, one paginated read, one GraphQL
+ * document, and whatever the rate-limit headers last said.
+ *
+ * @remarks
+ * 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.
+ *
+ * @public
+ */
+interface GitHubClientShape {
+  /**
+   * One request. The route types both the parameters and the returned `data`.
+   *
+   * @example
+   * ```ts
+   * import { GitHubClient } from "@effected/github";
+   * import { Effect } from "effect";
+   *
+   * const defaultBranch = Effect.gen(function* () {
+   *   const client = yield* GitHubClient;
+   *   const repo = yield* client.request("GET /repos/{owner}/{repo}", { owner: "o", repo: "r" });
+   *   return repo.default_branch; // string — no cast, no hand-written interface
+   * });
+   * ```
+   */
+  readonly request: <R extends Route>(route: R, params: Params<R>) => Effect.Effect<Data<R>, GitHubError>;
+  /**
+   * A route GitHub does not describe in its OpenAPI schema, or one whose live
+   * shape differs from it.
+   *
+   * @remarks
+   * The `schema` is **mandatory**. This is an escape hatch from the route
+   * table, never from typing: the payload still arrives decoded, and a shape
+   * mismatch fails as `kind: "decode"` rather than surfacing as a value nobody
+   * checked. The attestations read uses it, because pinning
+   * `X-GitHub-Api-Version` puts the response on a contract the generated types
+   * do not describe.
+   */
+  readonly requestDecoded: <A, I>(route: string, params: Record<string, unknown> & RequestExtras, schema: Schema.Codec<A, I>) => Effect.Effect<A, GitHubError>;
+  /**
+   * Collect every page of a paginating route, honoring {@link PageOptions}.
+   *
+   * @remarks
+   * Handing this a non-paginating route is a compile error.
+   */
+  readonly paginate: <R extends PaginatingRoute>(route: R, params: Params<R>, options?: PageOptions) => Effect.Effect<ReadonlyArray<Item<R>>, GitHubError>;
+  /**
+   * The same traversal as a `Stream`, for when the caller decides where to stop.
+   *
+   * @remarks
+   * Lazy in requests: a downstream `Stream.take` stops the walk rather than
+   * filtering pages that were already fetched.
+   */
+  readonly paginateStream: <R extends PaginatingRoute>(route: R, params: Params<R>, options?: PageOptions) => Stream.Stream<Item<R>, GitHubError>;
+  /** Run an owned GraphQL document and decode its answer. */
+  readonly graphql: <A, V extends Record<string, unknown>>(document: GraphQLDocument<A, V>, variables: V) => Effect.Effect<A, GitHubGraphQLError>;
+  /**
+   * What GitHub's rate-limit headers said on the most recent response.
+   *
+   * @remarks
+   * Observation, not policy: **nothing here throttles on your behalf.** The
+   * client retries a rate-limited failure with GitHub's own advised delay, and
+   * a caller that wants to pace itself proactively reads this.
+   */
+  readonly rateLimit: Effect.Effect<Option.Option<RateLimitSnapshot>>;
+}
+/**
+ * How a client layer is built.
+ *
+ * @public
+ */
+interface GitHubClientOptions {
+  /** The token every request authenticates with. */
+  readonly token: Redacted.Redacted<string>;
+  /** Retry behavior. Defaults to {@link RetryPolicy.default}; `"off"` disables it. */
+  readonly retry?: RetryPolicy | "off" | undefined;
+  /** A GitHub Enterprise API root, e.g. `https://github.acme.com/api/v3`. */
+  readonly baseUrl?: string | undefined;
+  /** Appended to octokit's own user agent. */
+  readonly userAgent?: string | undefined;
+  /**
+   * A replacement for the global `fetch`.
+   *
+   * @remarks
+   * octokit's own documented hook. It is the seam a test drives the **real**
+   * request path through — classification, header capture, retry and
+   * pagination all exercised against canned HTTP responses instead of against
+   * a hand-written double of this service.
+   */
+  readonly fetch?: typeof globalThis.fetch | undefined;
+}
+/**
+ * A recorded response table for {@link GitHubClient.layerFixture}.
+ *
+ * @public
+ */
+interface GitHubFixtures {
+  /** Keyed by route; the value is the `data` payload a request answers with. */
+  readonly request?: Readonly<Record<string, unknown>> | undefined;
+  /** Keyed by route; the value is the whole collection, paged on demand. */
+  readonly paginate?: Readonly<Record<string, ReadonlyArray<unknown>>> | undefined;
+  /** Keyed by document name; the value is the raw payload to decode. */
+  readonly graphql?: Readonly<Record<string, unknown>> | undefined;
+  /** What `rateLimit` answers. */
+  readonly rateLimit?: RateLimitSnapshot | undefined;
+  /**
+   * Every route a paginated read requested, in order, with the page size asked
+   * for. Populated by the fixture as the test runs.
+   */
+  readonly requested?: Array<{
+    readonly route: string;
+    readonly perPage: number;
+  }> | undefined;
+}
+declare const GitHubClient_base: Context.ServiceClass<GitHubClient, "@effected/github/GitHubClient", GitHubClientShape>;
+/**
+ * The typed GitHub API client.
+ *
+ * @remarks
+ * The route is the key. `@octokit/types` generates a map from GitHub's OpenAPI
+ * description that carries every endpoint's parameter and response shapes, and
+ * `@octokit/core`'s `request` already consumes it — so a caller writes a route
+ * literal and gets both sides typed, with no callback, no type parameter to
+ * invent, and no cast.
+ *
+ * That is the whole point of this package. The surface it replaces was
+ * `rest<T>(operation: string, fn: (octokit: any) => Promise<{ data: T }>)`,
+ * where `T` was whatever the caller wrote and nothing connected it to the
+ * endpoint. Four consumer repos paid for that with sixteen cast sites and three
+ * hand-written octokit interfaces, one of which gave up and typed its methods as
+ * `Record<string, (p: unknown) => Promise<{ data: unknown }>>`.
+ *
+ * @public
+ */
+declare class GitHubClient extends GitHubClient_base {
+  /**
+   * A client authenticated with a token you already hold.
+   *
+   * @remarks
+   * This module imports `@octokit/core` and nothing heavier. A consumer that
+   * only ever authenticates with a token never links the GitHub App JWT signer,
+   * because the App-authenticated layer lives in `GitHubApp` — a different
+   * module — rather than as a third static here.
+   */
+  static readonly layerFromToken: (options: GitHubClientOptions) => Layer.Layer<GitHubClient>;
+  /**
+   * A client authenticated from configuration, `GITHUB_TOKEN` by default.
+   *
+   * @remarks
+   * Reads through the ambient `ConfigProvider`, not `process.env`, so a test
+   * provides a provider instead of mutating the environment and a non-Actions
+   * consumer can source the token however it likes.
+   *
+   * Construction fails with core's `ConfigError` — an honest "no token is
+   * configured". The layer this replaces failed with a **wire-failure** error
+   * type instead, which is why one consumer wrapped it in `Layer.orDie` under a
+   * five-line comment explaining that the error did not mean what it said.
+   */
+  static readonly layerFromConfig: (options?: Omit<GitHubClientOptions, "token"> & {
+    readonly name?: string | undefined;
+  }) => Layer.Layer<GitHubClient, Config.ConfigError>;
+  /**
+   * An in-memory double: stub the members a test exercises, and every other
+   * member **dies** naming itself.
+   *
+   * @remarks
+   * No 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.
+   *
+   * For recorded responses that page for real, use
+   * {@link GitHubClient.layerFixture}.
+   */
+  static readonly makeTest: (overrides?: Partial<GitHubClientShape>) => GitHubClientShape;
+  /** {@link GitHubClient.makeTest} behind a `Layer`. */
+  static readonly layerTest: (overrides?: Partial<GitHubClientShape>) => Layer.Layer<GitHubClient>;
+  /**
+   * A double over recorded responses that **pages them for real**.
+   *
+   * @remarks
+   * The one recorded-response double in this package, and the single narrow
+   * exception to the no-behavior-reimplementing-doubles rule — safe precisely
+   * because it reimplements nothing: it builds a `PageSource` over the recorded
+   * array and hands it to the same `paginate` engine the live client uses, so
+   * `perPage` and `maxPages` cannot behave differently here than in production.
+   *
+   * The double it replaces named its pagination parameters `_options` and
+   * ignored them, returning every recorded page regardless of what the caller
+   * asked for — which made every truncation path in every consumer
+   * structurally untestable.
+   *
+   * `fixtures.requested` is appended to as the test runs, so a suite can assert
+   * which routes were walked and at what page size.
+   */
+  static readonly layerFixture: (fixtures: GitHubFixtures) => Layer.Layer<GitHubClient>;
+}
+//#endregion
+//#region src/ArtifactMetadata.d.ts
+declare const StorageRecordInput_base: Schema.Class<StorageRecordInput, Schema.Struct<{
+  /** The artifact's package URL (purl). */
+  readonly name: Schema.NonEmptyString;
+  /** Its content digest, as `algorithm:hex`. */
+  readonly digest: Schema.NonEmptyString;
+  /** The registry's base URL. */
+  readonly registryUrl: Schema.NonEmptyString;
+  /** The repository name **within the registry**. */
+  readonly repository: Schema.NonEmptyString;
+  /** Where the artifact is stored, when there is a direct URL. */
+  readonly artifactUrl: Schema.optionalKey<Schema.String>;
+  /** The artifact's path within the registry, when there is one. */
+  readonly path: Schema.optionalKey<Schema.String>;
+}>, {}>;
+/**
+ * What to record about a published artifact.
+ *
+ * @remarks
+ * These are the fields the endpoint actually accepts. The version this replaces
+ * declared a `version` field the endpoint has no notion of — a fabricated key
+ * that a `Record<string, unknown>` body accepted silently and the generated
+ * types reject outright.
+ *
+ * @public
+ */
+declare class StorageRecordInput extends StorageRecordInput_base {}
+/**
+ * Organization-level artifact metadata.
+ *
+ * @remarks
+ * Org-scoped rather than repository-scoped, so it takes the organization as an
+ * argument and does **not** read {@link Repo}.
+ *
+ * @public
+ */
+interface ArtifactMetadataShape {
+  /** Record where a published artifact lives; returns the ids GitHub stored. */
+  readonly createStorageRecord: (org: string, input: StorageRecordInput) => Effect.Effect<ReadonlyArray<number>, GitHubError>;
+}
+declare const ArtifactMetadata_base: Context.ServiceClass<ArtifactMetadata, "@effected/github/ArtifactMetadata", ArtifactMetadataShape>;
+/**
+ * Artifact metadata.
+ *
+ * @public
+ */
+declare class ArtifactMetadata extends ArtifactMetadata_base {
+  static readonly layer: Layer.Layer<ArtifactMetadata, never, GitHubClient>;
+  /** An in-memory double; unstubbed members die naming themselves. */
+  static readonly makeTest: (overrides?: Partial<ArtifactMetadataShape>) => ArtifactMetadataShape;
+  /** {@link ArtifactMetadata.makeTest} behind a `Layer`. */
+  static readonly layerTest: (overrides?: Partial<ArtifactMetadataShape>) => Layer.Layer<ArtifactMetadata>;
+}
+//#endregion
+//#region src/Repo.d.ts
+declare const InvalidRepoRefError_base: Schema.Class<InvalidRepoRefError, Schema.TaggedStruct<"InvalidRepoRefError", {
+  /** What was handed in. */
+  readonly input: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A repository slug was not `owner/repo`.
+ *
+ * @public
+ */
+declare class InvalidRepoRefError extends InvalidRepoRefError_base {
+  get message(): string;
+}
+declare const RepoRef_base: Schema.Class<RepoRef, Schema.Struct<{
+  /** The user or organization. */
+  readonly owner: Schema.NonEmptyString;
+  /** The repository name, without the owner. */
+  readonly repo: Schema.NonEmptyString;
+}>, {}>;
+/**
+ * Which repository an operation acts on.
+ *
+ * @public
+ */
+declare class RepoRef extends RepoRef_base {
+  /**
+   * Parse `"owner/repo"`, synchronously.
+   *
+   * @remarks
+   * The sync `Result` primitive; {@link RepoRef.parse} is the `Effect` form over
+   * it. `make` is reserved by the class factory for the validated field
+   * constructor, which is why string parsing is named rather than overloaded.
+   */
+  static parseResult(slug: string): Result.Result<RepoRef, InvalidRepoRefError>;
+  /** Parse `"owner/repo"`. */
+  static readonly parse: (slug: string) => Effect.Effect<RepoRef, InvalidRepoRefError, never>;
+  /** `"owner/repo"`. */
+  get slug(): string;
+}
+declare const Repo_base: Context.ServiceClass<Repo, "@effected/github/Repo", RepoRef>;
+/**
+ * The repository the surrounding program acts on.
+ *
+ * @remarks
+ * Every resource service takes this in its `R` and **no method takes an
+ * `{ owner, repo }` argument**, which is what makes a read like
+ * `GitHubRepository.defaultBranch` a single expression instead of a preamble.
+ *
+ * The package this replaces read `process.env.GITHUB_REPOSITORY` in three
+ * places — inside the client, inside the App layer, and transitively in every
+ * caller of `client.repo` — which is most of what coupled a GitHub API client to
+ * the GitHub Actions runtime. Here the coordinate is a value, the env-driven way
+ * to get one is a layer variant **named for being env-driven**, and a program
+ * that acts on several repositories uses {@link Repo.provide}:
+ *
+ * @example
+ * ```ts
+ * import { Repo } from "@effected/github";
+ * import { Effect } from "effect";
+ *
+ * declare const syncOne: Effect.Effect<void, never, Repo>;
+ * declare const targets: ReadonlyArray<Repo["Service"]>;
+ *
+ * const syncAll = Effect.forEach(targets, (target) => syncOne.pipe(Repo.provide(target)), {
+ *   concurrency: 4,
+ * });
+ * ```
+ *
+ * **A deliberate exception to "no non-effectful members on a service shape."**
+ * This shape is entirely one immutable value: there is nothing to leave
+ * unimplemented, so `Layer.mock` has nothing to degrade and `Layer.succeed` is
+ * the correct double. The rule exists to stop a sync member from quietly
+ * degrading a *mixed* shape's partial mock. The boundary to hold: the moment a
+ * method appears here, this is a service again and the rule applies.
+ *
+ * @public
+ */
+declare class Repo extends Repo_base {
+  /** The repository, as a value you already have. */
+  static readonly layer: (ref: RepoRef) => Layer.Layer<Repo>;
+  /** The repository, from an `"owner/repo"` slug. */
+  static readonly layerFromSlug: (slug: string) => Layer.Layer<Repo, InvalidRepoRefError>;
+  /**
+   * The repository from configuration, `GITHUB_REPOSITORY` by default.
+   *
+   * @remarks
+   * The one env-driven variant, read through the ambient `ConfigProvider` rather
+   * than `process.env` — so a test provides a provider instead of mutating the
+   * environment, and a consumer outside Actions can source it however it likes.
+   */
+  static readonly layerFromConfig: (options?: {
+    readonly name?: string | undefined;
+  }) => Layer.Layer<Repo, Config.ConfigError | InvalidRepoRefError>;
+  /** Run `effect` against a different repository. */
+  static readonly provide: (ref: RepoRef) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Repo>>;
+}
+//#endregion
+//#region src/Attestation.d.ts
+declare const AttestationRecord_base: Schema.Class<AttestationRecord, Schema.Struct<{
+  /** GitHub's id for it, when the response carried one. */
+  readonly id: Schema.optionalKey<Schema.Int>;
+  /** Where a human can look at it. */
+  readonly url: Schema.String;
+}>, {}>;
+/**
+ * A stored attestation.
+ *
+ * @public
+ */
+declare class AttestationRecord extends AttestationRecord_base {}
+declare const AttestationListEntry_base: Schema.Class<AttestationListEntry, Schema.Struct<{
+  /** Where the bundle lives. */
+  readonly url: Schema.String;
+  /** The in-toto predicate type, when the listing reported one. */
+  readonly predicateType: Schema.optionalKey<Schema.String>;
+}>, {}>;
+/**
+ * One entry from an attestation listing.
+ *
+ * @public
+ */
+declare class AttestationListEntry extends AttestationListEntry_base {}
+/**
+ * The attestation REST surface.
+ *
+ * @remarks
+ * Upload and listing only. Building a statement, signing it and producing the
+ * bundle belong to `@effected/sbom`; assembling those into a pipeline belongs to
+ * the consumer. That split is what dissolves the five-service knot the previous
+ * package needed a mega-layer to test.
+ *
+ * @public
+ */
+interface AttestationShape {
+  /** Store a signed bundle against the repository. */
+  readonly upload: (bundle: unknown) => Effect.Effect<AttestationRecord, GitHubError, Repo>;
+  /**
+   * Everything attested about a subject digest.
+   *
+   * @remarks
+   * **404 and 422 both mean "none"**, not "broken" — GitHub answers a digest it
+   * has never seen either way depending on the path, and a caller asking "is
+   * this attested?" wants an empty list for both.
+   */
+  readonly listForSubject: (sha256: string, options?: {
+    readonly predicateType?: string | undefined;
+  }) => Effect.Effect<ReadonlyArray<AttestationListEntry>, GitHubError, Repo>;
+}
+declare const Attestation_base: Context.ServiceClass<Attestation, "@effected/github/Attestation", AttestationShape>;
+/**
+ * Attestations.
+ *
+ * @public
+ */
+declare class Attestation extends Attestation_base {
+  static readonly layer: Layer.Layer<Attestation, never, GitHubClient>;
+  /** An in-memory double; unstubbed members die naming themselves. */
+  static readonly makeTest: (overrides?: Partial<AttestationShape>) => AttestationShape;
+  /** {@link Attestation.makeTest} behind a `Layer`. */
+  static readonly layerTest: (overrides?: Partial<AttestationShape>) => Layer.Layer<Attestation>;
+}
+//#endregion
+//#region src/CheckRun.d.ts
+/** How a check run finished. @public */
+declare const CheckConclusion: Schema.Literals<readonly ["success", "failure", "neutral", "cancelled", "timed_out", "action_required", "skipped"]>;
+/** How serious an annotation is. @public */
+declare const AnnotationLevel: Schema.Literals<readonly ["notice", "warning", "failure"]>;
+declare const Annotation_base: Schema.Class<Annotation, Schema.Struct<{
+  /** Repository-relative path. */
+  readonly path: Schema.String;
+  /** First line of the range, 1-based. */
+  readonly startLine: Schema.Int;
+  /** Last line of the range, 1-based. */
+  readonly endLine: Schema.Int;
+  readonly level: Schema.Literals<readonly ["notice", "warning", "failure"]>;
+  readonly message: Schema.String;
+  readonly title: Schema.optionalKey<Schema.String>;
+}>, {}>;
+/**
+ * One annotation on a check run.
+ *
+ * @public
+ */
+declare class Annotation extends Annotation_base {}
+declare const CheckRunOutput_base: Schema.Class<CheckRunOutput, Schema.Struct<{
+  readonly title: Schema.String;
+  /** Markdown shown under the title. Capped at 65535 **bytes**. */
+  readonly summary: Schema.String;
+  /** Longer markdown. Capped at 65535 **bytes**. */
+  readonly text: Schema.optionalKey<Schema.String>;
+  /** At most 50 per request; the rest are dropped by {@link CheckRunOutput.truncated}. */
+  readonly annotations: Schema.optionalKey<Schema.$Array<typeof Annotation>>;
+}>, {}>;
+/**
+ * A check run's rendered output.
+ *
+ * @remarks
+ * GitHub's limits are **byte** limits, and that distinction is the whole reason
+ * this class exists rather than a struct: `✅`, `❌`, `🦋` and `│` cost several
+ * bytes each, so a character-count check passes while the request comes back
+ * 422 saying *"summary exceeds a maximum bytesize of 65535"*. One consumer hit
+ * exactly that and wrote the truncation by hand.
+ *
+ * @public
+ */
+declare class CheckRunOutput extends CheckRunOutput_base {
+  /** GitHub's cap on `summary` and `text`, in UTF-8 bytes. */
+  static readonly LIMIT_BYTES = 65535;
+  /** GitHub's cap on annotations per request. */
+  static readonly MAX_ANNOTATIONS = 50;
+  /** Appended when a field had to be cut. */
+  static readonly NOTICE = "\n\n_…truncated (exceeded GitHub's 65535-byte check limit)._";
+  /**
+   * This output, cut to fit GitHub's limits.
+   *
+   * @remarks
+   * Pure, so the byte arithmetic is testable with no client, no layer and no
+   * network — which is what lets a property test hammer it with arbitrary
+   * multi-byte input.
+   */
+  truncated(): CheckRunOutput;
+}
+declare const CheckRunRef_base: Schema.Class<CheckRunRef, Schema.Struct<{
+  readonly id: Schema.Int;
+  readonly name: Schema.String;
+  /** The web URL. */
+  readonly url: Schema.String;
+  readonly status: Schema.String;
+}>, {}>;
+/**
+ * A check run as GitHub reports it.
+ *
+ * @public
+ */
+declare class CheckRunRef extends CheckRunRef_base {}
+/**
+ * Conclude the surrounding {@link CheckRunShape.withCheckRun} explicitly.
+ *
+ * @remarks
+ * **Recording, not sending.** The call stores the verdict; the bracket's
+ * finalizer writes it exactly once, on whichever path `use` leaves by. That is
+ * what makes an explicit conclusion survive a later failure or an interrupt,
+ * and what keeps the completion a single request no matter how many times this
+ * is called. Calling it twice keeps the **last** verdict.
+ *
+ * Its error channel is `never` because the finalizer owns the reporting: a
+ * caller that could observe a failed `complete` here would have to decide what
+ * to do about it while already on the way out.
+ *
+ * Omit `output` to conclude without touching the run's rendered output —
+ * whatever the last {@link CheckRunShape.update} wrote stays.
+ *
+ * @public
+ */
+type ConcludeCheckRun = (conclusion: (typeof CheckConclusion.literals)[number], output?: CheckRunOutput) => Effect.Effect<void>;
+/**
+ * Check runs.
+ *
+ * @public
+ */
+interface CheckRunShape {
+  /** Start an in-progress check run against a commit. */
+  readonly create: (name: string, headSha: string) => Effect.Effect<CheckRunRef, GitHubError, Repo>;
+  readonly get: (id: number) => Effect.Effect<CheckRunRef, GitHubError, Repo>;
+  /** Update an in-flight run's output. */
+  readonly update: (id: number, output: CheckRunOutput) => Effect.Effect<void, GitHubError, Repo>;
+  /** Finish a run. */
+  readonly complete: (id: number, conclusion: (typeof CheckConclusion.literals)[number], output?: CheckRunOutput) => Effect.Effect<void, GitHubError, Repo>;
+  /**
+   * Run `use` inside a check run, concluding it however `use` exits.
+   *
+   * @remarks
+   * **Every exit reaches a terminal state.** Left to itself the bracket
+   * concludes `"success"` on success, `"failure"` on a typed failure or a
+   * defect, and `"cancelled"` on an interrupt. A run left `in_progress` is
+   * never reaped by GitHub and blocks branch protection until someone deletes
+   * it by hand, so the finalizer is exit-aware rather than a `tap`/`tapError`
+   * pair — which fires on the first two only.
+   *
+   * **`use` can override that verdict**, which is how the other four
+   * conclusions are reachable. `conclude` records one; a recorded verdict
+   * **wins on every exit path**, including failure and interruption, because
+   * how a check ran and how the surrounding program ended are different
+   * questions. A findings-derived `"neutral"` is the motivating case: the work
+   * ran fine and the result is advisory.
+   *
+   * Only the success path can fail the effect on the conclusion's behalf.
+   * Neither an interrupt nor an existing failure is replaced by whatever went
+   * wrong while reporting it.
+   *
+   * `use` keeps its own `R` and its own `A`, unlike the version this replaces,
+   * whose callback was `R`-less and so forced consumers to build
+   * self-contained layers just to use the bracket.
+   *
+   * @example
+   * ```ts
+   * check.withCheckRun("lint", sha, (id, conclude) =>
+   *   Effect.gen(function* () {
+   *     const findings = yield* lint();
+   *     yield* conclude(deriveConclusion(findings), report(findings));
+   *     return findings;
+   *   }),
+   * );
+   * ```
+   */
+  readonly withCheckRun: <A, E, R>(name: string, headSha: string, use: (id: number, conclude: ConcludeCheckRun) => Effect.Effect<A, E, R>) => Effect.Effect<A, E | GitHubError, R | Repo>;
+}
+declare const CheckRun_base: Context.ServiceClass<CheckRun, "@effected/github/CheckRun", CheckRunShape>;
+/**
+ * Check runs.
+ *
+ * @public
+ */
+declare class CheckRun extends CheckRun_base {
+  static readonly layer: Layer.Layer<CheckRun, never, GitHubClient>;
+  /** An in-memory double; unstubbed members die naming themselves. */
+  static readonly makeTest: (overrides?: Partial<CheckRunShape>) => CheckRunShape;
+  /** {@link CheckRun.makeTest} behind a `Layer`. */
+  static readonly layerTest: (overrides?: Partial<CheckRunShape>) => Layer.Layer<CheckRun>;
+}
+//#endregion
+//#region src/GitBranch.d.ts
+/**
+ * What {@link GitBranchShape.upsert} did.
+ *
+ * @public
+ */
+type BranchOutcome = "created" | "reset";
+/**
+ * Branch refs in GitHub's Git Database API.
+ *
+ * @remarks
+ * **Not local git.** Despite the name this is `POST /repos/…/git/refs` and
+ * friends — no subprocess, no working tree, no checkout. `@effected/git` is the
+ * package that runs git.
+ *
+ * @public
+ */
+interface GitBranchShape {
+  /** Create a branch at `sha`. Fails `alreadyExists` when it is already there. */
+  readonly create: (name: string, sha: string) => Effect.Effect<void, GitHubError, Repo>;
+  /**
+   * Point `name` at `sha`, creating it if needed.
+   *
+   * @remarks
+   * **One call, one intent.** Creating a branch that may already exist is the
+   * single most-repeated dance in the surveyed consumers: the marketplace
+   * manager spent a seven-line comment and a nine-line workaround on it, doing
+   * `getSha` → `exists` → `create` → on failure `exists` again → `reset`, up to
+   * four round trips, because the error it caught carried no structured
+   * "already exists". silk-release-action wrote the mirror image of the same
+   * dance a few files away.
+   *
+   * This is one round trip in the common case and two in the raced one, and the
+   * recovery **resets** rather than inheriting a branch a concurrent creator
+   * rooted somewhere else — which is the semantics that comment was defending.
+   */
+  readonly upsert: (name: string, sha: string) => Effect.Effect<BranchOutcome, GitHubError, Repo>;
+  /** Is the branch there? A 404 is `false`, not an error. */
+  readonly exists: (name: string) => Effect.Effect<boolean, GitHubError, Repo>;
+  /** The commit the branch points at. Fails `notFound` when it does not exist. */
+  readonly sha: (name: string) => Effect.Effect<string, GitHubError, Repo>;
+  /** As {@link GitBranchShape.sha}, with absence as `Option.none`. */
+  readonly shaOption: (name: string) => Effect.Effect<Option.Option<string>, GitHubError, Repo>;
+  /** Force the branch to `sha`. Fails `notFound` when it does not exist. */
+  readonly reset: (name: string, sha: string) => Effect.Effect<void, GitHubError, Repo>;
+  /** Delete the branch. */
+  readonly delete: (name: string) => Effect.Effect<void, GitHubError, Repo>;
+  /**
+   * Create a branch **linked to an issue**, as the GitHub UI's "create a branch"
+   * button does.
+   *
+   * @remarks
+   * The one operation in this package with **no REST equivalent** — GitHub
+   * exposes `createLinkedBranch` only through GraphQL, which is why the document
+   * is owned here rather than left in a consumer. A linked branch shows up on the
+   * issue and closes it when the branch's pull request merges; a branch created
+   * with {@link GitBranchShape.create} does neither.
+   */
+  readonly createLinked: (input: {
+    readonly issueNodeId: string;
+    readonly repositoryNodeId: string;
+    readonly name: string;
+    readonly sha: string;
+  }) => Effect.Effect<void, GitHubGraphQLError, Repo>;
+}
+declare const GitBranch_base: Context.ServiceClass<GitBranch, "@effected/github/GitBranch", GitBranchShape>;
+/**
+ * Branches, as refs.
+ *
+ * @public
+ */
+declare class GitBranch extends GitBranch_base {
+  /**
+   * @remarks
+   * The callback is written `(client) => make(client)` rather than passed as
+   * `make` directly, and that is load-bearing: a static initializer runs while
+   * the module body is still evaluating, so naming a `const` declared further
+   * down throws `Cannot access 'make' before initialization` **at import time**,
+   * with a clean typecheck. Wrapping it in an arrow defers the read to when the
+   * layer is built.
+   */
+  static readonly layer: Layer.Layer<GitBranch, never, GitHubClient>;
+  /** An in-memory double; unstubbed members die naming themselves. */
+  static readonly makeTest: (overrides?: Partial<GitBranchShape>) => GitBranchShape;
+  /** {@link GitBranch.makeTest} behind a `Layer`. */
+  static readonly layerTest: (overrides?: Partial<GitBranchShape>) => Layer.Layer<GitBranch>;
+}
+//#endregion
+//#region src/GitCommit.d.ts
+/**
+ * A blob's file mode, as the Git Database API spells it.
+ *
+ * @public
+ */
+declare const FileMode: Schema.Literals<readonly ["100644", "100755", "120000"]>;
+declare const FileContent_base: Schema.Class<FileContent, Schema.TaggedStruct<"FileContent", {
+  /** Repository-relative path. */
+  readonly path: Schema.NonEmptyString;
+  /** The file's new contents. */
+  readonly content: Schema.String;
+  /** Defaults to a regular file. */
+  readonly mode: Schema.optionalKey<Schema.Literals<readonly ["100644", "100755", "120000"]>>;
+}>, {}>;
+/**
+ * A file to write in a commit.
+ *
+ * @public
+ */
+declare class FileContent extends FileContent_base {}
+declare const FileDeletion_base: Schema.Class<FileDeletion, Schema.TaggedStruct<"FileDeletion", {
+  /** Repository-relative path. */
+  readonly path: Schema.NonEmptyString;
+}>, {}>;
+/**
+ * A file to remove in a commit.
+ *
+ * @public
+ */
+declare class FileDeletion extends FileDeletion_base {}
+/**
+ * One change in a commit.
+ *
+ * @public
+ */
+declare const FileChange: Schema.Union<readonly [typeof FileContent, typeof FileDeletion]>;
+/** One change in a commit. @public */
+type FileChange = FileContent | FileDeletion;
+declare const CommitRef_base: Schema.Class<CommitRef, Schema.Struct<{
+  /** The commit's own sha. */
+  readonly sha: Schema.String;
+  /** The tree the commit points at — what `baseTree` wants. */
+  readonly treeSha: Schema.String;
+  /** Parent commit shas, in order. */
+  readonly parents: Schema.$Array<Schema.String>;
+}>, {}>;
+/**
+ * A commit, projected to the three fields callers actually use.
+ *
+ * @remarks
+ * `treeSha` is here because two surveyed call sites dropped to a raw octokit
+ * cast for it alone, both with the comment *"the Git Data API's `base_tree`
+ * wants a tree SHA, not a commit SHA"* — the same eight lines written twice, in
+ * two files, for one string.
+ *
+ * @public
+ */
+declare class CommitRef extends CommitRef_base {}
+/**
+ * Commits and trees in GitHub's Git Database API.
+ *
+ * @public
+ */
+interface GitCommitShape {
+  /** Read a commit's sha, tree and parents. */
+  readonly get: (sha: string) => Effect.Effect<CommitRef, GitHubError, Repo>;
+  /** Build a tree, optionally on top of an existing one. */
+  readonly createTree: (options: {
+    readonly changes: ReadonlyArray<FileChange>;
+    readonly baseTree?: string | undefined;
+  }) => Effect.Effect<string, GitHubError, Repo>;
+  /** Create a commit object. */
+  readonly createCommit: (options: {
+    readonly message: string;
+    readonly tree: string;
+    readonly parents: ReadonlyArray<string>;
+  }) => Effect.Effect<string, GitHubError, Repo>;
+  /**
+   * Write `changes` onto `branch` as one commit, returning its sha.
+   *
+   * @remarks
+   * The four-call sequence — read the branch, build a tree on its commit's
+   * tree, create the commit, move the ref — as one operation. The ref update is
+   * **not** forced: a branch that moved underneath you is a conflict worth
+   * hearing about, not one to overwrite.
+   */
+  readonly commitFiles: (options: {
+    readonly branch: string;
+    readonly message: string;
+    readonly changes: ReadonlyArray<FileChange>;
+  }) => Effect.Effect<string, GitHubError, Repo>;
+}
+declare const GitCommit_base: Context.ServiceClass<GitCommit, "@effected/github/GitCommit", GitCommitShape>;
+/**
+ * Commits, trees and blobs.
+ *
+ * @public
+ */
+declare class GitCommit extends GitCommit_base {
+  static readonly layer: Layer.Layer<GitCommit, never, GitHubClient>;
+  /** An in-memory double; unstubbed members die naming themselves. */
+  static readonly makeTest: (overrides?: Partial<GitCommitShape>) => GitCommitShape;
+  /** {@link GitCommit.makeTest} behind a `Layer`. */
+  static readonly layerTest: (overrides?: Partial<GitCommitShape>) => Layer.Layer<GitCommit>;
+}
+//#endregion
+//#region src/GitHubApp.d.ts
+declare const GitHubAppError_base: Schema.Class<GitHubAppError, Schema.TaggedStruct<"GitHubAppError", {
+  /** Which step failed. */
+  readonly kind: Schema.Literals<readonly ["jwt", "token", "revoke", "identity", "installation"]>;
+  /** Human-readable cause. */
+  readonly reason: Schema.String;
+  /** The underlying failure, when there is one. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A GitHub App call failed.
+ *
+ * @remarks
+ * Distinct from `GitHubError` because "I could not obtain credentials" and "the
+ * API call failed" are different problems with different fixes: the first is a
+ * misconfigured app, a wrong private key or a missing installation; the second
+ * is the request that used the credentials.
+ *
+ * @public
+ */
+declare class GitHubAppError extends GitHubAppError_base {
+  get message(): string;
+  /** @internal */
+  static of(kind: GitHubAppError["kind"], reason: string, cause?: unknown): GitHubAppError;
+}
+/**
+ * The credentials that identify a GitHub App.
+ *
+ * @remarks
+ * `appId` accepts either the numeric app id or the newer client id — GitHub
+ * accepts both as the JWT issuer, and this package does not care which you use.
+ *
+ * @public
+ */
+interface AppCredentials {
+  /** The app id or client id. */
+  readonly appId: string;
+  /**
+   * The app's private key, in PEM.
+   *
+   * @remarks
+   * PKCS#1 (`-----BEGIN RSA PRIVATE KEY-----`, which is what github.com hands
+   * you) is converted to PKCS#8 automatically **on Node**. On a runtime without
+   * `node:crypto` a PKCS#1 key fails with an explicit `kind: "jwt"` error, and
+   * the fix is to convert the key once with
+   * `openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt`. This constraint is
+   * inherited from the JWT signer and is identical to `@octokit/auth-app`'s.
+   */
+  readonly privateKey: Redacted.Redacted<string>;
+}
+/**
+ * What to mint an installation token for.
+ *
+ * @public
+ */
+interface TokenRequest extends AppCredentials {
+  /** The installation. Discovered from `owner` when omitted. */
+  readonly installationId?: number | undefined;
+  /**
+   * The account whose installation to use, when `installationId` is omitted.
+   *
+   * @remarks
+   * Discovery costs a JWT mint plus a paginated walk of `GET /app/installations`,
+   * so supplying `installationId` is strictly cheaper. When both are omitted and
+   * the app has exactly one installation, that one is used; with several, the
+   * failure names them.
+   */
+  readonly owner?: string | undefined;
+}
+declare const InstallationToken_base: Schema.Class<InstallationToken, Schema.Struct<{
+  /** The token. Decodes to `Redacted`, encodes back to the raw string. */
+  readonly token: Schema.RedactedFromValue<Schema.String>;
+  /** When GitHub will stop accepting it — about an hour out. */
+  readonly expiresAt: Schema.DateTimeUtcFromString;
+  /** The installation it is scoped to. */
+  readonly installationId: Schema.Int;
+  /** The permissions GitHub actually granted, which may be narrower than requested. */
+  readonly permissions: Schema.$Record<Schema.String, Schema.String>;
+  /** The app's slug, when identity was resolved. */
+  readonly appSlug: Schema.optionalKey<Schema.String>;
+  /** The app's bot user id, when identity was resolved. */
+  readonly appUserId: Schema.optionalKey<Schema.Int>;
+  /** The app's display name, when identity was resolved. */
+  readonly appName: Schema.optionalKey<Schema.String>;
+}>, {}>;
+/**
+ * An installation access token and what GitHub said about it.
+ *
+ * @remarks
+ * Encodable on purpose. `@effected/github-actions` persists one across the
+ * `pre`/`main`/`post` process boundary through `GITHUB_STATE`, and
+ * `Schema.encodeUnknownEffect` produces JSON with the token as a plain string
+ * and `expiresAt` as an ISO instant. A `Redacted` cannot survive serialization
+ * by design, so masking the encoded value is the caller's job — Actions calls
+ * `::add-mask::`.
+ *
+ * @public
+ */
+declare class InstallationToken extends InstallationToken_base {
+  /**
+   * Whether this token is spent, `skew` before its stated expiry.
+   *
+   * @remarks
+   * Modelled **and enforced**. The package this replaces persisted `expiresAt`
+   * and read it nowhere, so a long `main` phase that outlived the hour simply
+   * started answering 401 with no explanation.
+   */
+  isExpired(nowMillis: number, skew?: Duration.Duration): boolean;
+  /** The committer identity a commit made with this token should carry. */
+  botIdentity(): BotIdentity;
+}
+declare const BotIdentity_base: Schema.Class<BotIdentity, Schema.Struct<{
+  /** The git author/committer name, e.g. `"my-app[bot]"`. */
+  readonly name: Schema.String;
+  /** The no-reply address GitHub attributes to that account. */
+  readonly email: Schema.String;
+}>, {}>;
+/**
+ * Who a bot commits as.
+ *
+ * @remarks
+ * A **pure class**, not a service member. The package this replaces put
+ * `botIdentity(source?)` on the `GitHubApp` service shape as a plain synchronous
+ * method, which makes it required in every `Layer.mock` and silently degrades
+ * every partial double to a full implementation.
+ *
+ * @public
+ */
+declare class BotIdentity extends BotIdentity_base {
+  /** The identity for an app, given whatever of its identity is known. */
+  static forApp(source: {
+    readonly appSlug: string;
+    readonly appUserId?: number | undefined;
+  }): BotIdentity;
+  /** The well-known identity of the `github-actions` bot. */
+  static readonly githubActions: BotIdentity;
+}
+declare const AppIdentity_base: Schema.Class<AppIdentity, Schema.Struct<{
+  /** The URL slug, e.g. `"my-app"`. */
+  readonly slug: Schema.String;
+  /** The display name. */
+  readonly name: Schema.String;
+  /** The bot user's numeric id, when it could be resolved. */
+  readonly userId: Schema.optionalKey<Schema.Int>;
+}>, {}>;
+/**
+ * What GitHub knows about the app itself.
+ *
+ * @public
+ */
+declare class AppIdentity extends AppIdentity_base {
+  /** The committer identity for this app. */
+  botIdentity(): BotIdentity;
+}
+declare const Installation_base: Schema.Class<Installation, Schema.Struct<{
+  /** The installation id, which is what a token is minted against. */
+  readonly id: Schema.Int;
+  /** The account the app is installed on, when GitHub reported one. */
+  readonly account: Schema.optionalKey<Schema.String>;
+}>, {}>;
+/**
+ * One installation of the app.
+ *
+ * @public
+ */
+declare class Installation extends Installation_base {}
+/**
+ * Transport settings for the app's own API calls.
+ *
+ * @public
+ */
+interface GitHubAppOptions {
+  /** A GitHub Enterprise API root. */
+  readonly baseUrl?: string | undefined;
+  /** Appended to octokit's user agent. */
+  readonly userAgent?: string | undefined;
+  /** Retry behavior for the app's own calls. */
+  readonly retry?: RetryPolicy | "off" | undefined;
+  /** A replacement `fetch`, for tests and proxies. */
+  readonly fetch?: typeof globalThis.fetch | undefined;
+}
+declare const GitHubApp_base: Context.ServiceClass<GitHubApp, "@effected/github/GitHubApp", GitHubAppShape>;
+/**
+ * GitHub App authentication: mint, revoke and identify.
+ *
+ * @remarks
+ * **This is the only module in the package that imports a JWT signer**, which is
+ * what makes the tree-shaking invariant structural rather than aspirational: a
+ * consumer that authenticates with a token it already holds imports
+ * `GitHubClient` and never reaches this module or its dependency.
+ *
+ * That constraint is also why the App-authenticated **client** layer lives here
+ * as {@link GitHubApp.clientLayer} rather than as a third static on
+ * `GitHubClient`: statics on one class share one module, and putting it there
+ * would make every token-only consumer link the signer. The kit has this shape
+ * already — `@effected/workspaces` ships `localExecLayer`, which builds
+ * `@effected/commands`' service, for the same reason.
+ *
+ * The JWT signer is `universal-github-app-jwt` — zero dependencies, and
+ * `@octokit/auth-app`'s own JWT dependency. Taking it directly rather than
+ * taking `auth-app` leaves behind roughly half a megabyte of OAuth app, user and
+ * device-flow machinery that this package never calls.
+ *
+ * @public
+ */
+declare class GitHubApp extends GitHubApp_base {
+  /** The default transport. Bind it once; layers are memoized by reference. */
+  static readonly layer: Layer.Layer<GitHubApp>;
+  /**
+   * A transport with custom settings.
+   *
+   * @remarks
+   * Parameterized, so **bind the result to a `const`** and reuse it. Calling
+   * this at two provide sites builds two instances, because layers are
+   * memoized by reference.
+   */
+  static readonly layerWith: (options: GitHubAppOptions) => Layer.Layer<GitHubApp>;
+  /**
+   * A {@link GitHubClient} authenticated as an app installation.
+   *
+   * @remarks
+   * The token's lifetime is the layer's scope: it is minted on build and
+   * **revoked on release**, best-effort, so a workflow does not leave live
+   * credentials behind. It is also **re-minted automatically** a minute before
+   * it expires, which the package this replaces did not do — it persisted
+   * `expiresAt` and read it nowhere, so a `main` phase outliving the hour
+   * started answering 401 with nothing explaining why.
+   *
+   * A failure to obtain credentials surfaces to the caller as a
+   * `GitHubError { kind: "unauthorized" }` carrying the `GitHubAppError` as its
+   * cause: from a request's point of view, "could not authenticate" is an
+   * authorization failure, and widening every method's error channel to say so
+   * would tax every caller for a case only this layer can produce.
+   */
+  static readonly clientLayer: (request: TokenRequest, options?: GitHubAppOptions) => Layer.Layer<GitHubClient, GitHubAppError>;
+  /** An in-memory double; unstubbed members die naming themselves. */
+  static readonly makeTest: (overrides?: Partial<GitHubAppShape>) => GitHubAppShape;
+  /** {@link GitHubApp.makeTest} behind a `Layer`. */
+  static readonly layerTest: (overrides?: Partial<GitHubAppShape>) => Layer.Layer<GitHubApp>;
+}
+/**
+ * The app-authentication surface.
+ *
+ * @remarks
+ * Every member is a function returning an `Effect`, so a partial double stays
+ * partial. `installations` takes credentials rather than being an
+ * `Effect`-valued property because the credentials are per-call, not per-layer.
+ *
+ * @public
+ */
+interface GitHubAppShape {
+  /**
+   * Mint an installation token.
+   *
+   * @remarks
+   * Used by `@effected/github-actions`' token bridge in a workflow's `pre`
+   * phase. Touches: nothing else on this shape.
+   */
+  readonly token: (request: TokenRequest) => Effect.Effect<InstallationToken, GitHubAppError>;
+  /**
+   * Mint a token that is revoked when the scope closes.
+   *
+   * @remarks
+   * Touches: `token`, `revoke`.
+   */
+  readonly scopedToken: (request: TokenRequest) => Effect.Effect<InstallationToken, GitHubAppError, Scope.Scope>;
+  /**
+   * Revoke a token now.
+   *
+   * @remarks
+   * Used by the token bridge's `post` phase. Touches: nothing else.
+   */
+  readonly revoke: (token: Redacted.Redacted<string>) => Effect.Effect<void, GitHubAppError>;
+  /**
+   * Resolve the app's slug, name and bot user id.
+   *
+   * @remarks
+   * Supply `installationToken` when you have one: `GET /users/{slug}[bot]`
+   * rejects an app JWT, so without it the lookup runs unauthenticated at
+   * GitHub's 60-requests-per-hour-per-IP limit. Touches: nothing else.
+   */
+  readonly identity: (request: AppCredentials & {
+    readonly installationToken?: Redacted.Redacted<string> | undefined;
+  }) => Effect.Effect<AppIdentity, GitHubAppError>;
+  /**
+   * Every installation of the app.
+   *
+   * @remarks
+   * Touches: nothing else.
+   */
+  readonly installations: (credentials: AppCredentials) => Effect.Effect<ReadonlyArray<Installation>, GitHubAppError>;
+}
+//#endregion
+//#region src/GitHubCommit.d.ts
+declare const CommitSummary_base: Schema.Class<CommitSummary, Schema.Struct<{
+  /** The commit sha. */
+  readonly sha: Schema.String;
+  /** The full commit message, untrimmed — this package does not decide what "the message" means. */
+  readonly message: Schema.String;
+  /** The author's name as git recorded it, or `"Unknown"` when GitHub reports none. */
+  readonly author: Schema.String;
+  /** The GitHub login of the authoring account, when GitHub could attribute one. */
+  readonly authorLogin: Schema.optionalKey<Schema.String>;
+  /** The web URL for the commit. */
+  readonly url: Schema.String;
+}>, {}>;
+/**
+ * A commit, projected to what callers read.
+ *
+ * @public
+ */
+declare class CommitSummary extends CommitSummary_base {
+  /** The message's first line. */
+  get subject(): string;
+}
+/**
+ * How a file changed in a commit or a comparison.
+ *
+ * @public
+ */
+declare const FileStatus: Schema.Literals<readonly ["added", "removed", "modified", "renamed", "copied", "changed", "unchanged"]>;
+declare const CommitFile_base: Schema.Class<CommitFile, Schema.Struct<{
+  /** Repository-relative path, after any rename. */
+  readonly path: Schema.String;
+  /** What happened to it. */
+  readonly status: Schema.Literals<readonly ["added", "removed", "modified", "renamed", "copied", "changed", "unchanged"]>;
+  /** Lines added. */
+  readonly additions: Schema.Int;
+  /** Lines removed. */
+  readonly deletions: Schema.Int;
+  /** The path before a rename or copy. */
+  readonly previousPath: Schema.optionalKey<Schema.String>;
+}>, {}>;
+/**
+ * One changed file.
+ *
+ * @public
+ */
+declare class CommitFile extends CommitFile_base {}
+declare const CommitComparison_base: Schema.Class<CommitComparison, Schema.Struct<{
+  /** How head relates to base. */
+  readonly status: Schema.Literals<readonly ["diverged", "ahead", "behind", "identical"]>;
+  /** Commits head has that base does not. */
+  readonly aheadBy: Schema.Int;
+  /** Commits base has that head does not. */
+  readonly behindBy: Schema.Int;
+  /** The commits in the range. */
+  readonly commits: Schema.$Array<typeof CommitSummary>;
+  /** The files that differ, subject to GitHub's own 300-file cap on this endpoint. */
+  readonly files: Schema.$Array<typeof CommitFile>;
+}>, {}>;
+/**
+ * The result of comparing two refs.
+ *
+ * @public
+ */
+declare class CommitComparison extends CommitComparison_base {}
+/**
+ * Reading commits.
+ *
+ * @public
+ */
+interface GitHubCommitShape {
+  /** One commit. */
+  readonly get: (ref: string) => Effect.Effect<CommitSummary, GitHubError, Repo>;
+  /** Commits on a ref, newest first. */
+  readonly list: (options?: {
+    readonly ref?: string | undefined;
+    readonly path?: string | undefined;
+    readonly page?: PageOptions | undefined;
+  }) => Effect.Effect<ReadonlyArray<CommitSummary>, GitHubError, Repo>;
+  /**
+   * Compare two refs.
+   *
+   * @remarks
+   * GitHub paginates this **by commit**, while the single-commit read paginates
+   * **by file** at 300 per page — so a one-commit comparison is permanently
+   * truncated at 300 files no matter what you pass. That is GitHub's constraint,
+   * recorded here rather than discovered later.
+   */
+  readonly compare: (base: string, head: string) => Effect.Effect<CommitComparison, GitHubError, Repo>;
+  /** The files one commit touched, paginated by file. */
+  readonly changedFiles: (ref: string, options?: {
+    readonly page?: PageOptions | undefined;
+  }) => Effect.Effect<ReadonlyArray<CommitFile>, GitHubError, Repo>;
+}
+declare const GitHubCommit_base: Context.ServiceClass<GitHubCommit, "@effected/github/GitHubCommit", GitHubCommitShape>;
+/**
+ * Commits, as GitHub reports them.
+ *
+ * @public
+ */
+declare class GitHubCommit extends GitHubCommit_base {
+  static readonly layer: Layer.Layer<GitHubCommit, never, GitHubClient>;
+  /** An in-memory double; unstubbed members die naming themselves. */
+  static readonly makeTest: (overrides?: Partial<GitHubCommitShape>) => GitHubCommitShape;
+  /** {@link GitHubCommit.makeTest} behind a `Layer`. */
+  static readonly layerTest: (overrides?: Partial<GitHubCommitShape>) => Layer.Layer<GitHubCommit>;
+}
+//#endregion
+//#region src/GitHubContent.d.ts
+/**
+ * Reading a file out of a repository.
+ *
+ * @public
+ */
+interface GitHubContentShape {
+  /**
+   * A text file's contents at `ref`, or the default branch when `ref` is
+   * omitted.
+   */
+  readonly getFile: (path: string, options?: {
+    readonly ref?: string | undefined;
+  }) => Effect.Effect<string, GitHubError, Repo>;
+  /** As {@link GitHubContentShape.getFile}, with absence as `Option.none`. */
+  readonly getFileOption: (path: string, options?: {
+    readonly ref?: string | undefined;
+  }) => Effect.Effect<Option.Option<string>, GitHubError, Repo>;
+}
+declare const GitHubContent_base: Context.ServiceClass<GitHubContent, "@effected/github/GitHubContent", GitHubContentShape>;
+/**
+ * Repository file contents.
+ *
+ * @public
+ */
+declare class GitHubContent extends GitHubContent_base {
+  static readonly layer: Layer.Layer<GitHubContent, never, GitHubClient>;
+  /** An in-memory double; unstubbed members die naming themselves. */
+  static readonly makeTest: (overrides?: Partial<GitHubContentShape>) => GitHubContentShape;
+  /** {@link GitHubContent.makeTest} behind a `Layer`. */
+  static readonly layerTest: (overrides?: Partial<GitHubContentShape>) => Layer.Layer<GitHubContent>;
+}
+//#endregion
+//#region src/GitHubIssue.d.ts
+declare const IssueInfo_base: Schema.Class<IssueInfo, Schema.Struct<{
+  readonly number: Schema.Int;
+  readonly title: Schema.String;
+  readonly state: Schema.Literals<readonly ["open", "closed"]>;
+  /** Label names, normalized from GitHub's `string | { name }` union. */
+  readonly labels: Schema.$Array<Schema.String>;
+  readonly url: Schema.String;
+  /** The GraphQL node id. */
+  readonly nodeId: Schema.String;
+}>, {}>;
+/**
+ * An issue, projected to what callers read.
+ *
+ * @public
+ */
+declare class IssueInfo extends IssueInfo_base {}
+declare const LinkedIssue_base: Schema.Class<LinkedIssue, Schema.Struct<{
+  readonly number: Schema.Int;
+  readonly title: Schema.String;
+  readonly state: Schema.String;
+  readonly url: Schema.String;
+  readonly nodeId: Schema.String;
+  /**
+   * Whether a human wrote the link, rather than GitHub inferring it from the
+   * branch or commit messages.
+   *
+   * @remarks
+   * This is the field the whole document exists for. The version this replaces
+   * could not express `userLinkedOnly`, so one consumer re-declared the query
+   * with the field aliased twice to get it — the single largest duplicated
+   * document in the survey.
+   */
+  readonly userLinked: Schema.Boolean;
+}>, {}>;
+/**
+ * An issue a pull request closes.
+ *
+ * @public
+ */
+declare class LinkedIssue extends LinkedIssue_base {}
+/**
+ * Issues.
+ *
+ * @public
+ */
+interface GitHubIssueShape {
+  readonly get: (number: number) => Effect.Effect<IssueInfo, GitHubError, Repo>;
+  readonly list: (options?: {
+    readonly state?: "open" | "closed" | "all" | undefined;
+    readonly labels?: ReadonlyArray<string> | undefined;
+    readonly page?: PageOptions | undefined;
+  }) => Effect.Effect<ReadonlyArray<IssueInfo>, GitHubError, Repo>;
+  readonly close: (number: number, reason?: "completed" | "not_planned") => Effect.Effect<void, GitHubError, Repo>;
+  /** Post a comment. */
+  readonly comment: (number: number, body: string) => Effect.Effect<number, GitHubError, Repo>;
+  /** The issues a pull request closes, with `userLinked` telling you who linked them. */
+  readonly linkedIssues: (prNumber: number) => Effect.Effect<ReadonlyArray<LinkedIssue>, GitHubGraphQLError, Repo>;
+  /**
+   * Has `prNumber` already been cross-referenced on this issue?
+   *
+   * @remarks
+   * The idempotence guard one consumer wrote a bespoke timeline query for,
+   * so that re-running a workflow does not comment twice.
+   */
+  readonly isCrossReferencedBy: (issueNumber: number, prNumber: number) => Effect.Effect<boolean, GitHubGraphQLError, Repo>;
+}
+declare const GitHubIssue_base: Context.ServiceClass<GitHubIssue, "@effected/github/GitHubIssue", GitHubIssueShape>;
+/**
+ * Issues.
+ *
+ * @public
+ */
+declare class GitHubIssue extends GitHubIssue_base {
+  static readonly layer: Layer.Layer<GitHubIssue, never, GitHubClient>;
+  /** An in-memory double; unstubbed members die naming themselves. */
+  static readonly makeTest: (overrides?: Partial<GitHubIssueShape>) => GitHubIssueShape;
+  /** {@link GitHubIssue.makeTest} behind a `Layer`. */
+  static readonly layerTest: (overrides?: Partial<GitHubIssueShape>) => Layer.Layer<GitHubIssue>;
+}
+//#endregion
+//#region src/GitHubRelease.d.ts
+declare const ReleaseInfo_base: Schema.Class<ReleaseInfo, Schema.Struct<{
+  readonly id: Schema.Int;
+  readonly tag: Schema.String;
+  readonly name: Schema.String;
+  readonly body: Schema.String;
+  readonly draft: Schema.Boolean;
+  readonly prerelease: Schema.Boolean;
+  /** The web URL. */
+  readonly url: Schema.String;
+  /** The templated upload endpoint GitHub hands back for assets. */
+  readonly uploadUrl: Schema.String;
+}>, {}>;
+/**
+ * A release.
+ *
+ * @public
+ */
+declare class ReleaseInfo extends ReleaseInfo_base {}
+declare const ReleaseAsset_base: Schema.Class<ReleaseAsset, Schema.Struct<{
+  readonly id: Schema.Int;
+  readonly name: Schema.String;
+  /** The browser download URL. */
+  readonly url: Schema.String;
+  /** Size in bytes. */
+  readonly size: Schema.Int;
+}>, {}>;
+/**
+ * A file attached to a release.
+ *
+ * @public
+ */
+declare class ReleaseAsset extends ReleaseAsset_base {}
+/**
+ * Releases and their assets.
+ *
+ * @public
+ */
+interface GitHubReleaseShape {
+  readonly create: (input: {
+    readonly tag: string;
+    readonly name?: string | undefined;
+    readonly body?: string | undefined;
+    readonly draft?: boolean | undefined;
+    readonly prerelease?: boolean | undefined;
+    readonly generateReleaseNotes?: boolean | undefined;
+  }) => Effect.Effect<ReleaseInfo, GitHubError, Repo>;
+  readonly getByTag: (tag: string) => Effect.Effect<ReleaseInfo, GitHubError, Repo>;
+  /** As {@link GitHubReleaseShape.getByTag}, with absence as `Option.none`. */
+  readonly getByTagOption: (tag: string) => Effect.Effect<Option.Option<ReleaseInfo>, GitHubError, Repo>;
+  readonly list: (options?: {
+    readonly page?: PageOptions | undefined;
+  }) => Effect.Effect<ReadonlyArray<ReleaseInfo>, GitHubError, Repo>;
+  readonly update: (id: number, patch: {
+    readonly name?: string | undefined;
+    readonly body?: string | undefined;
+    readonly draft?: boolean | undefined;
+    readonly prerelease?: boolean | undefined;
+  }) => Effect.Effect<ReleaseInfo, GitHubError, Repo>;
+  /**
+   * Attach a file to a release.
+   *
+   * @remarks
+   * The one route in this package that is **not** in GitHub's generated
+   * endpoint map: asset upload goes to `uploads.github.com` with a raw binary
+   * body, and the map omits it. So it goes through `requestDecoded` with an
+   * owned schema — the escape hatch is from the route table, never from typing.
+   */
+  readonly uploadAsset: (release: ReleaseInfo, asset: {
+    readonly name: string;
+    readonly data: Uint8Array | string;
+    readonly contentType: string;
+  }) => Effect.Effect<ReleaseAsset, GitHubError, Repo>;
+  readonly listAssets: (id: number, options?: {
+    readonly page?: PageOptions | undefined;
+  }) => Effect.Effect<ReadonlyArray<ReleaseAsset>, GitHubError, Repo>;
+}
+declare const GitHubRelease_base: Context.ServiceClass<GitHubRelease, "@effected/github/GitHubRelease", GitHubReleaseShape>;
+/**
+ * Releases.
+ *
+ * @public
+ */
+declare class GitHubRelease extends GitHubRelease_base {
+  static readonly layer: Layer.Layer<GitHubRelease, never, GitHubClient>;
+  /** An in-memory double; unstubbed members die naming themselves. */
+  static readonly makeTest: (overrides?: Partial<GitHubReleaseShape>) => GitHubReleaseShape;
+  /** {@link GitHubRelease.makeTest} behind a `Layer`. */
+  static readonly layerTest: (overrides?: Partial<GitHubReleaseShape>) => Layer.Layer<GitHubRelease>;
+}
+//#endregion
+//#region src/GitHubRepository.d.ts
+/**
+ * Everything GitHub reports about a repository.
+ *
+ * @remarks
+ * The **generated** response type, not a hand-written projection. One surveyed
+ * consumer declared a sixteen-field interface for this endpoint and round-tripped
+ * those fields back through `PATCH` — and every one of the sixteen already
+ * existed, verbatim, in the OpenAPI types the package now leans on. Re-declaring
+ * them would have been the same mistake with our name on it.
+ *
+ * @public
+ */
+type RepositorySettings = Data<"GET /repos/{owner}/{repo}">;
+/**
+ * The fields `PATCH /repos/{owner}/{repo}` accepts, minus the coordinate.
+ *
+ * @public
+ */
+type RepositoryPatch = Omit<Params<"PATCH /repos/{owner}/{repo}">, "owner" | "repo">;
+/**
+ * The repository itself.
+ *
+ * @public
+ */
+interface GitHubRepositoryShape {
+  /** The full, faithfully typed repository payload. */
+  readonly settings: Effect.Effect<RepositorySettings, GitHubError, Repo>;
+  /** Apply a settings patch and return what GitHub then reports. */
+  readonly updateSettings: (patch: RepositoryPatch) => Effect.Effect<RepositorySettings, GitHubError, Repo>;
+  /**
+   * The default branch's name.
+   *
+   * @remarks
+   * One surveyed consumer spent eight lines of hand-written octokit interface
+   * plus eleven lines of code to read this one string.
+   */
+  readonly defaultBranch: Effect.Effect<string, GitHubError, Repo>;
+  /**
+   * The repository's GraphQL node id.
+   *
+   * @remarks
+   * Needed as `repositoryId` by the `createLinkedBranch` and `createPullRequest`
+   * mutations, which is why a second consumer cast `repos.get` for it alone.
+   */
+  readonly nodeId: Effect.Effect<string, GitHubError, Repo>;
+}
+declare const GitHubRepository_base: Context.ServiceClass<GitHubRepository, "@effected/github/GitHubRepository", GitHubRepositoryShape>;
+/**
+ * Repository settings and coordinates.
+ *
+ * @public
+ */
+declare class GitHubRepository extends GitHubRepository_base {
+  static readonly layer: Layer.Layer<GitHubRepository, never, GitHubClient>;
+  /** An in-memory double; unstubbed members die naming themselves. */
+  static readonly makeTest: (overrides?: Partial<GitHubRepositoryShape>) => GitHubRepositoryShape;
+  /** {@link GitHubRepository.makeTest} behind a `Layer`. */
+  static readonly layerTest: (overrides?: Partial<GitHubRepositoryShape>) => Layer.Layer<GitHubRepository>;
+}
+//#endregion
+//#region src/GitTag.d.ts
+declare const TagRef_base: Schema.Class<TagRef, Schema.Struct<{
+  /** The tag name, without `refs/tags/`. */
+  readonly tag: Schema.NonEmptyString;
+  /** The **commit** sha, with annotated tags already dereferenced. */
+  readonly sha: Schema.String;
+}>, {}>;
+/**
+ * A tag and the commit it ultimately points at.
+ *
+ * @public
+ */
+declare class TagRef extends TagRef_base {}
+declare const SemverTag_base: Schema.Class<SemverTag, Schema.Struct<{
+  /** The tag name as GitHub has it. */
+  readonly tag: Schema.NonEmptyString;
+  /** The commit sha. */
+  readonly sha: Schema.String;
+  /** The version read out of the name. */
+  readonly version: typeof SemVer;
+}>, {}>;
+/**
+ * A tag whose name carries a version.
+ *
+ * @public
+ */
+declare class SemverTag extends SemverTag_base {}
+/**
+ * Read a version out of a tag name.
+ *
+ * @remarks
+ * The default covers the three shapes `@effected/workspaces`' `ReleaseTag`
+ * produces and the surveyed repos actually cut: `v1.2.3`, `pkg@v1.2.3` and
+ * `@scope/pkg@1.2.3`. Taking the substring after the **last** `@` is what makes
+ * the scoped form work, since the scope itself contains one.
+ *
+ * @public
+ */
+type VersionFromTag = (tag: string) => Option.Option<string>;
+/** The default {@link VersionFromTag}. @public */
+declare const versionFromTag: VersionFromTag;
+/**
+ * How to pick the newest version-shaped tag.
+ *
+ * @public
+ */
+interface LatestSemverOptions {
+  /** Only consider tags starting with this. */
+  readonly prefix?: string | undefined;
+  /** Consider prereleases too. Off by default: `1.0.0-rc.1` is not the latest release. */
+  readonly includePrerelease?: boolean | undefined;
+  /** Override the tag-name → version convention. */
+  readonly extract?: VersionFromTag | undefined;
+  /** How far to walk. */
+  readonly page?: PageOptions | undefined;
+}
+/**
+ * Tag refs in GitHub's Git Database API.
+ *
+ * @public
+ */
+interface GitTagShape {
+  /** Create a tag ref at `sha`. Fails `alreadyExists` when it is already there. */
+  readonly create: (tag: string, sha: string) => Effect.Effect<void, GitHubError, Repo>;
+  /** Point `tag` at `sha`, creating it if needed. */
+  readonly upsert: (tag: string, sha: string) => Effect.Effect<void, GitHubError, Repo>;
+  /** Delete the tag ref. */
+  readonly delete: (tag: string) => Effect.Effect<void, GitHubError, Repo>;
+  /** Every tag, newest GitHub-order first. `prefix` filters client-side. */
+  readonly list: (options?: {
+    readonly prefix?: string | undefined;
+    readonly page?: PageOptions | undefined;
+  }) => Effect.Effect<ReadonlyArray<TagRef>, GitHubError, Repo>;
+  /**
+   * The commit a tag points at, dereferencing annotated tags.
+   *
+   * @remarks
+   * Fails typed past five levels of nesting rather than looping.
+   */
+  readonly resolve: (tag: string) => Effect.Effect<string, GitHubError, Repo>;
+  /**
+   * The newest version-shaped tag.
+   *
+   * @remarks
+   * Replaces thirty-five lines at one surveyed call site that ran **one
+   * `Effect.result` per parse and another per comparison** to answer this. Both
+   * are synchronous in `@effected/semver` (`parseResult`, `compare`), so this is
+   * a single pass over the page stream with no round trips at all.
+   */
+  readonly latestSemver: (options?: LatestSemverOptions) => Effect.Effect<Option.Option<SemverTag>, GitHubError, Repo>;
+}
+declare const GitTag_base: Context.ServiceClass<GitTag, "@effected/github/GitTag", GitTagShape>;
+/**
+ * Tags.
+ *
+ * @public
+ */
+declare class GitTag extends GitTag_base {
+  static readonly layer: Layer.Layer<GitTag, never, GitHubClient>;
+  /** An in-memory double; unstubbed members die naming themselves. */
+  static readonly makeTest: (overrides?: Partial<GitTagShape>) => GitTagShape;
+  /** {@link GitTag.makeTest} behind a `Layer`. */
+  static readonly layerTest: (overrides?: Partial<GitTagShape>) => Layer.Layer<GitTag>;
+}
+//#endregion
+//#region src/PullRequest.d.ts
+/** How a pull request is merged. @public */
+declare const MergeMethod: Schema.Literals<readonly ["merge", "squash", "rebase"]>;
+declare const PullRequestInfo_base: Schema.Class<PullRequestInfo, Schema.Struct<{
+  /** The number in `#123`. */
+  readonly number: Schema.Int;
+  /** The GraphQL node id, which the auto-merge mutations need. */
+  readonly nodeId: Schema.String;
+  /** The web URL. */
+  readonly url: Schema.String;
+  readonly title: Schema.String;
+  readonly state: Schema.Literals<readonly ["open", "closed"]>;
+  /** The source branch name. */
+  readonly head: Schema.String;
+  /** The target branch name. */
+  readonly base: Schema.String;
+  readonly draft: Schema.Boolean;
+  readonly merged: Schema.Boolean;
+  /**
+   * When it merged, if it did.
+   *
+   * @remarks
+   * An `Option`, not an optional field. Whether a pull request has merged is a
+   * fact GitHub always reports, so modelling it as "maybe absent" would be
+   * modelling a gap in our fixtures rather than a gap in the domain.
+   */
+  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. */
+  readonly mergeCommitSha: Schema.optionalKey<Schema.String>;
+}>, {}>;
+/**
+ * A pull request, projected to what callers read.
+ *
+ * @public
+ */
+declare class PullRequestInfo extends PullRequestInfo_base {}
+/** What {@link PullRequestShape.upsert} did. @public */
+interface UpsertedPullRequest {
+  readonly pullRequest: PullRequestInfo;
+  readonly created: boolean;
+}
+/**
+ * Pull requests.
+ *
+ * @public
+ */
+interface PullRequestShape {
+  readonly get: (number: number) => Effect.Effect<PullRequestInfo, GitHubError, Repo>;
+  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>;
+  /** The files a pull request changes. */
+  readonly listFiles: (number: number, options?: {
+    readonly page?: PageOptions | undefined;
+  }) => Effect.Effect<ReadonlyArray<string>, GitHubError, Repo>;
+  /**
+   * The pull requests associated with a commit.
+   *
+   * @remarks
+   * Named for the question it answers, because the previous surface had this
+   * method and one consumer never found it — dropping to a raw octokit callback
+   * with the only `noExplicitAny` suppression in the entire survey. It also
+   * paginates now, which the previous one did not.
+   */
+  readonly listAssociatedWithCommit: (sha: string, options?: {
+    readonly page?: PageOptions | undefined;
+  }) => Effect.Effect<ReadonlyArray<PullRequestInfo>, GitHubError, Repo>;
+  readonly create: (input: {
+    readonly title: string;
+    readonly head: string;
+    readonly base: string;
+    readonly body?: string | undefined;
+    readonly draft?: boolean | undefined;
+  }) => Effect.Effect<PullRequestInfo, GitHubError, Repo>;
+  readonly update: (number: number, patch: {
+    readonly title?: string | undefined;
+    readonly body?: string | undefined;
+    readonly state?: "open" | "closed" | undefined;
+    readonly base?: string | undefined;
+  }) => Effect.Effect<PullRequestInfo, GitHubError, Repo>;
+  /** Update the open pull request for `head`→`base`, or open one. */
+  readonly upsert: (input: {
+    readonly title: string;
+    readonly head: string;
+    readonly base: string;
+    readonly body?: string | undefined;
+    readonly draft?: boolean | undefined;
+  }) => Effect.Effect<UpsertedPullRequest, GitHubError, Repo>;
+  readonly merge: (number: number, options?: {
+    readonly method?: "merge" | "squash" | "rebase" | undefined;
+    readonly commitTitle?: string | undefined;
+    readonly commitMessage?: string | undefined;
+  }) => Effect.Effect<string, GitHubError, Repo>;
+  readonly addLabels: (number: number, labels: ReadonlyArray<string>) => Effect.Effect<void, GitHubError, Repo>;
+  readonly requestReviewers: (number: number, reviewers: {
+    readonly users?: ReadonlyArray<string> | undefined;
+    readonly teams?: ReadonlyArray<string> | undefined;
+  }) => Effect.Effect<void, GitHubError, Repo>;
+  /**
+   * Turn auto-merge on or off.
+   *
+   * @remarks
+   * An explicit call, not an option on `create`/`update`. The previous surface
+   * fired these mutations from an `Effect.tap` **after** the create succeeded,
+   * so a create that worked could still surface an auto-merge failure as if the
+   * create had failed.
+   */
+  readonly setAutoMerge: (pullRequest: PullRequestInfo, method: "merge" | "squash" | "rebase" | "off") => Effect.Effect<void, GitHubGraphQLError, Repo>;
+}
+declare const PullRequest_base: Context.ServiceClass<PullRequest, "@effected/github/PullRequest", PullRequestShape>;
+/**
+ * Pull requests.
+ *
+ * @public
+ */
+declare class PullRequest extends PullRequest_base {
+  static readonly layer: Layer.Layer<PullRequest, never, GitHubClient>;
+  /** An in-memory double; unstubbed members die naming themselves. */
+  static readonly makeTest: (overrides?: Partial<PullRequestShape>) => PullRequestShape;
+  /** {@link PullRequest.makeTest} behind a `Layer`. */
+  static readonly layerTest: (overrides?: Partial<PullRequestShape>) => Layer.Layer<PullRequest>;
+}
+//#endregion
+//#region src/PullRequestComment.d.ts
+declare const CommentMarker_base: Schema.Class<CommentMarker, Schema.Struct<{
+  /** Whose comments these are, e.g. your action's name. */
+  readonly namespace: Schema.NonEmptyString;
+  /** Which comment, within that namespace. */
+  readonly key: Schema.NonEmptyString;
+}>, {}>;
+/**
+ * The hidden marker that makes a comment findable again.
+ *
+ * @remarks
+ * A pure class, not a hardcoded string. The surface this replaces baked
+ * `<!-- savvy-web:${key} -->` into the library — one vendor's name, inside a
+ * package meant to be general. Here the namespace is the caller's, the marker is
+ * testable without a client, and the library has no opinion about whose comments
+ * these are.
+ *
+ * @public
+ */
+declare class CommentMarker extends CommentMarker_base {
+  /** The HTML comment appended to a body so the comment can be found again. */
+  get html(): string;
+  /** Does this body carry the marker? */
+  matches(body: string): boolean;
+}
+declare const CommentRecord_base: Schema.Class<CommentRecord, Schema.Struct<{
+  readonly id: Schema.Int;
+  readonly body: Schema.String;
+  readonly url: Schema.String;
+}>, {}>;
+/**
+ * A comment this package wrote or found.
+ *
+ * @public
+ */
+declare class CommentRecord extends CommentRecord_base {}
+/**
+ * Sticky comments on a pull request or issue.
+ *
+ * @public
+ */
+interface PullRequestCommentShape {
+  /** Post a new comment. */
+  readonly create: (issueNumber: number, body: string) => Effect.Effect<CommentRecord, GitHubError, Repo>;
+  /**
+   * Update the marked comment if there is one, or post it.
+   *
+   * @remarks
+   * The marker is appended to the body, so a comment written by `upsert` is
+   * always findable by the same marker afterwards.
+   */
+  readonly upsert: (issueNumber: number, marker: CommentMarker, body: string) => Effect.Effect<CommentRecord, GitHubError, Repo>;
+  /**
+   * Find the marked comment.
+   *
+   * @remarks
+   * **Paginates.** The version this replaces requested a single page of 100 and
+   * stopped, so on a busy pull request the marker silently vanished and every
+   * update posted a new comment instead.
+   */
+  readonly find: (issueNumber: number, marker: CommentMarker, options?: {
+    readonly page?: PageOptions | undefined;
+  }) => Effect.Effect<Option.Option<CommentRecord>, GitHubError, Repo>;
+  readonly delete: (commentId: number) => Effect.Effect<void, GitHubError, Repo>;
+}
+declare const PullRequestComment_base: Context.ServiceClass<PullRequestComment, "@effected/github/PullRequestComment", PullRequestCommentShape>;
+/**
+ * Sticky comments.
+ *
+ * @public
+ */
+declare class PullRequestComment extends PullRequestComment_base {
+  static readonly layer: Layer.Layer<PullRequestComment, never, GitHubClient>;
+  /** An in-memory double; unstubbed members die naming themselves. */
+  static readonly makeTest: (overrides?: Partial<PullRequestCommentShape>) => PullRequestCommentShape;
+  /** {@link PullRequestComment.makeTest} behind a `Layer`. */
+  static readonly layerTest: (overrides?: Partial<PullRequestCommentShape>) => Layer.Layer<PullRequestComment>;
+}
+//#endregion
+//#region src/TokenPermissions.d.ts
+/**
+ * How much access a permission grants.
+ *
+ * @public
+ */
+declare const PermissionLevel: Schema.Literals<readonly ["read", "write", "admin"]>;
+/** How much access a permission grants. @public */
+type PermissionLevel = (typeof PermissionLevel.literals)[number];
+declare const PermissionGap_base: Schema.Class<PermissionGap, Schema.Struct<{
+  /** The permission's name, e.g. `"contents"`. */
+  readonly permission: Schema.String;
+  /** What was asked for. */
+  readonly required: Schema.Literals<readonly ["read", "write", "admin"]>;
+  /** What the token has, when it has any at all. */
+  readonly granted: Schema.optionalKey<Schema.Literals<readonly ["read", "write", "admin"]>>;
+}>, {}>;
+/**
+ * A permission the token does not have enough of.
+ *
+ * @public
+ */
+declare class PermissionGap extends PermissionGap_base {}
+declare const ExtraPermission_base: Schema.Class<ExtraPermission, Schema.Struct<{
+  readonly permission: Schema.String;
+  readonly granted: Schema.Literals<readonly ["read", "write", "admin"]>;
+  /** What was asked for, when anything was. */
+  readonly required: Schema.optionalKey<Schema.Literals<readonly ["read", "write", "admin"]>>;
+}>, {}>;
+/**
+ * A permission the token has and did not need.
+ *
+ * @public
+ */
+declare class ExtraPermission extends ExtraPermission_base {}
+declare const PermissionResult_base: Schema.Class<PermissionResult, Schema.Struct<{
+  /** Permissions that are missing or too weak. */
+  readonly missing: Schema.$Array<typeof PermissionGap>;
+  /** Permissions granted beyond what was asked for. */
+  readonly extra: Schema.$Array<typeof ExtraPermission>;
+}>, {}>;
+/**
+ * What comparing a token's permissions against a requirement found.
+ *
+ * @public
+ */
+declare class PermissionResult extends PermissionResult_base {
+  /** Nothing missing. */
+  get satisfied(): boolean;
+  /** Nothing missing and nothing spare. */
+  get exact(): boolean;
+}
+declare const TokenPermissionError_base: Schema.Class<TokenPermissionError, Schema.TaggedStruct<"TokenPermissionError", {
+  /** Which assertion failed. */
+  readonly kind: Schema.Literals<readonly ["insufficient", "excess"]>;
+  /** The comparison that produced it. */
+  readonly result: typeof PermissionResult;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A token asked for access it does not have, or has access it did not ask for.
+ *
+ * @public
+ */
+declare class TokenPermissionError extends TokenPermissionError_base {
+  get message(): string;
+}
+declare const TokenPermissions_base: Schema.Class<TokenPermissions, Schema.Struct<{
+  /** Permission name to level. */
+  readonly granted: Schema.$Record<Schema.String, Schema.Literals<readonly ["read", "write", "admin"]>>;
+}>, {}>;
+/**
+ * The permissions a token was granted, and what they satisfy.
+ *
+ * @remarks
+ * **A pure class, not a service.** The version this replaces was a
+ * `Context.Service` whose live layer was a `Layer.succeed` with zero octokit
+ * calls and an empty `R` — a `read < write < admin` comparator behind a service
+ * boundary that bought nothing. It cost something, though: its test double
+ * reimplemented the entire ranking and every assertion branch, making it the
+ * heaviest of the thirty-eight doubles in the package.
+ *
+ * Here there is no service, no layer and no double: a caller holds the
+ * permissions GitHub already gave it (`InstallationToken.permissions`) and
+ * compares them. The only `Effect`s are the two assertions, and they exist only
+ * because failing typed is more useful than returning a boolean.
+ *
+ * @example
+ * ```ts
+ * import { TokenPermissions } from "@effected/github";
+ * import { Effect } from "effect";
+ *
+ * declare const permissions: Record<string, string>;
+ *
+ * const check = Effect.gen(function* () {
+ *   const granted = TokenPermissions.fromGitHub(permissions);
+ *   yield* granted.assertSufficient({ contents: "write", pull_requests: "write" });
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class TokenPermissions extends TokenPermissions_base {
+  /**
+   * Read GitHub's permission map, ignoring anything unrecognized.
+   *
+   * @remarks
+   * GitHub adds permission levels over time; a token carrying one this package
+   * does not know about is not a reason to fail a comparison about a different
+   * permission entirely.
+   */
+  static fromGitHub(permissions: Readonly<Record<string, string>>): TokenPermissions;
+  /** Compare against a requirement. Pure and total. */
+  compare(required: Readonly<Record<string, PermissionLevel>>): PermissionResult;
+  /** Fail unless every required permission is held at least at the level asked for. */
+  assertSufficient(required: Readonly<Record<string, PermissionLevel>>): Effect.Effect<void, TokenPermissionError>;
+  /**
+   * Fail unless the token holds exactly what was asked for.
+   *
+   * @remarks
+   * For the workflow that wants a least-privilege token and treats a broader
+   * one as a misconfiguration worth stopping for.
+   */
+  assertExact(required: Readonly<Record<string, PermissionLevel>>): Effect.Effect<void, TokenPermissionError>;
+}
+//#endregion
+//#region src/WorkflowDispatch.d.ts
+declare const WorkflowRunStatus_base: Schema.Class<WorkflowRunStatus, Schema.Struct<{
+  readonly id: Schema.Int;
+  /** `queued`, `in_progress`, `completed`, … */
+  readonly status: Schema.String;
+  /** Set once `status` is `completed`. */
+  readonly conclusion: Schema.optionalKey<Schema.String>;
+  readonly url: Schema.String;
+}>, {}>;
+/**
+ * Where a workflow run has got to.
+ *
+ * @public
+ */
+declare class WorkflowRunStatus extends WorkflowRunStatus_base {
+  /** Has the run finished, whatever the outcome? */
+  get isDone(): boolean;
+}
+/**
+ * How long to wait for a dispatched run.
+ *
+ * @public
+ */
+interface PollOptions {
+  /** How often to check. Defaults to ten seconds. */
+  readonly interval?: Duration.Duration | undefined;
+  /** How long to keep checking. Defaults to five minutes. */
+  readonly timeout?: Duration.Duration | undefined;
+}
+/**
+ * Triggering workflows.
+ *
+ * @public
+ */
+interface WorkflowDispatchShape {
+  /** Fire a `workflow_dispatch` event. GitHub answers 204 with no run id. */
+  readonly dispatch: (workflow: string, ref: string, inputs?: Record<string, string>) => Effect.Effect<void, GitHubError, Repo>;
+  readonly runStatus: (runId: number) => Effect.Effect<WorkflowRunStatus, GitHubError, Repo>;
+  /**
+   * Dispatch, find the run it created, and wait for it to finish.
+   *
+   * @remarks
+   * The wait is `Effect.repeat` with a predicate over the **success** value.
+   * The version this replaces encoded "not finished yet" as a sentinel *error*
+   * baked into a user-visible error union — control flow in the error channel,
+   * which every consumer then had to know not to treat as a failure.
+   */
+  readonly dispatchAndWait: (workflow: string, ref: string, options?: {
+    readonly inputs?: Record<string, string> | undefined;
+    readonly poll?: PollOptions | undefined;
+  }) => Effect.Effect<WorkflowRunStatus, GitHubError, Repo>;
+}
+declare const WorkflowDispatch_base: Context.ServiceClass<WorkflowDispatch, "@effected/github/WorkflowDispatch", WorkflowDispatchShape>;
+/**
+ * Workflow dispatch.
+ *
+ * @public
+ */
+declare class WorkflowDispatch extends WorkflowDispatch_base {
+  static readonly layer: Layer.Layer<WorkflowDispatch, never, GitHubClient>;
+  /** An in-memory double; unstubbed members die naming themselves. */
+  static readonly makeTest: (overrides?: Partial<WorkflowDispatchShape>) => WorkflowDispatchShape;
+  /** {@link WorkflowDispatch.makeTest} behind a `Layer`. */
+  static readonly layerTest: (overrides?: Partial<WorkflowDispatchShape>) => Layer.Layer<WorkflowDispatch>;
+}
+//#endregion
+export { Annotation, AnnotationLevel, type AppCredentials, AppIdentity, ArtifactMetadata, type ArtifactMetadataShape, Attestation, AttestationListEntry, AttestationRecord, type AttestationShape, BotIdentity, type BranchOutcome, CheckConclusion, CheckRun, CheckRunOutput, CheckRunRef, type CheckRunShape, CommentMarker, CommentRecord, CommitComparison, CommitFile, CommitRef, CommitSummary, type ConcludeCheckRun, ExtraPermission, FileChange, FileContent, FileDeletion, FileMode, FileStatus, GitBranch, type GitBranchShape, GitCommit, type GitCommitShape, GitHubApp, GitHubAppError, type GitHubAppOptions, type GitHubAppShape, GitHubClient, type GitHubClientOptions, type GitHubClientShape, GitHubCommit, type GitHubCommitShape, GitHubContent, type GitHubContentShape, GitHubError, GitHubErrorKind, type GitHubFixtures, GitHubGraphQLError, GitHubIssue, type GitHubIssueShape, GitHubRelease, type GitHubReleaseShape, GitHubRepository, type GitHubRepositoryShape, GitTag, type GitTagShape, GraphQLDocument, GraphQLErrorEntry, Installation, InstallationToken, InvalidRepoRefError, IssueInfo, type LatestSemverOptions, LinkedIssue, MergeMethod, PageOptions, PermissionGap, PermissionLevel, PermissionResult, type PollOptions, PullRequest, PullRequestComment, type PullRequestCommentShape, PullRequestInfo, type PullRequestShape, RateLimitSnapshot, ReleaseAsset, ReleaseInfo, Repo, RepoRef, type RepositoryPatch, type RepositorySettings, type Data as RestData, type RequestExtras as RestExtras, type Item as RestItem, type PaginatingRoute as RestPaginatingRoute, type Params as RestParams, type Response as RestResponse, type Route as RestRoute, RetryPolicy, type RetryableFailure, SemverTag, StorageRecordInput, TagRef, TokenPermissionError, TokenPermissions, type TokenRequest, type UpsertedPullRequest, type VersionFromTag, WorkflowDispatch, type WorkflowDispatchShape, WorkflowRunStatus, versionFromTag };
+//# sourceMappingURL=index.d.ts.map