@effected/github 0.23.1 → 0.25.0

package/ActionsOidc.js

@@ -191,10 +191,23 @@ const testClaims = (overrides = {}) => ({
 *
 * @public
 */
-const ActionsOidc = {
-	issuer: ISSUER,
-	verify,
-	testClaims
+var ActionsOidc = class {
+	constructor() {}
+	/** The Actions OIDC issuer, `https://token.actions.githubusercontent.com`. */
+	static issuer = ISSUER;
+	/** Verify a runner-issued OIDC token: signature against GitHub's JWKS, iss, aud, exp/nbf, then typed claims. */
+	static verify = verify;
+	/**
+	* A valid claims payload for tests, overridable field by field.
+	*
+	* @remarks
+	* Wire-shaped (snake_case keys, string ids) and complete except for the
+	* time claims `iat` and `exp`, which depend on the clock: a signer stamps
+	* them, as `TestIssuer.sign` from `@effected/jwt/testing` does. `iss` is
+	* {@link ActionsOidc.issuer}; `aud` is a placeholder to override with the
+	* audience under test.
+	*/
+	static testClaims = testClaims;
 };
 
 export { ActionsOidc, ActionsOidcClaims, ActionsOidcClaimsFromWire };

package/ArtifactMetadata.js

@@ -1,3 +1,4 @@
+import { unstubbed } from "./internal/unstubbed.js";
 import { GitHubClient } from "./GitHubClient.js";
 import { Repo } from "./Repo.js";
 import { Context, Effect, Layer, Schema } from "effect";
@@ -37,14 +38,12 @@ var StorageRecordInput = class extends Schema.Class("StorageRecordInput")({
 var ArtifactMetadata = class ArtifactMetadata extends Context.Service()("@effected/github/ArtifactMetadata") {
 	/** The live service, built over a `GitHubClient`. */
 	static layer = Layer.effect(this, Effect.map(GitHubClient, (client) => make(client)));
-	/** An in-memory double; unstubbed members die naming themselves. */
-	static makeTest = (overrides = {}) => ({ createStorageRecord: overrides.createStorageRecord ?? (() => unstubbed("createStorageRecord")) });
+	/** An in-memory double; an unstubbed member dies when run, naming itself. */
+	static makeTest = (overrides = {}) => ({ createStorageRecord: overrides.createStorageRecord ?? (() => dies("createStorageRecord")) });
 	/** {@link ArtifactMetadata.makeTest} behind a `Layer`. */
 	static layerTest = (overrides = {}) => Layer.succeed(ArtifactMetadata, ArtifactMetadata.makeTest(overrides));
 };
-const unstubbed = (member) => {
-	throw new Error(`ArtifactMetadata.makeTest: ${member}() was called but not stubbed — pass an override.`);
-};
+const dies = unstubbed("ArtifactMetadata.makeTest");
 const make = (client) => ({ createStorageRecord: Effect.fn("ArtifactMetadata.createStorageRecord")(function* (input) {
 	const { owner } = yield* Repo;
 	yield* Effect.annotateCurrentSpan({

package/Attestation.js

@@ -1,3 +1,4 @@
+import { unstubbed } from "./internal/unstubbed.js";
 import { GitHubClient } from "./GitHubClient.js";
 import { Repo } from "./Repo.js";
 import { Context, Effect, Layer, Schema } from "effect";
@@ -11,6 +12,10 @@ import { Context, Effect, Layer, Schema } from "effect";
 * with a stated sunset. Pinning the version means the response is on a contract
 * the generated types do not describe — which is why this module is the one that
 * uses `requestDecoded` with owned schemas rather than the route table.
+*
+* Sent as a per-call header, which wins over the client's own
+* `apiVersion`, so these reads stay on this contract even when a consumer
+* pins the client to another version.
 */
 const API_VERSION = "2026-03-10";
 /**
@@ -54,17 +59,15 @@ const ListResponse = Schema.Struct({ attestations: Schema.optionalKey(Schema.Arr
 var Attestation = class Attestation extends Context.Service()("@effected/github/Attestation") {
 	/** The live service, built over a `GitHubClient`. */
 	static layer = Layer.effect(this, Effect.map(GitHubClient, (client) => make(client)));
-	/** An in-memory double; unstubbed members die naming themselves. */
+	/** An in-memory double; an unstubbed member dies when run, naming itself. */
 	static makeTest = (overrides = {}) => ({
-		upload: overrides.upload ?? (() => unstubbed("upload")),
-		listForSubject: overrides.listForSubject ?? (() => unstubbed("listForSubject"))
+		upload: overrides.upload ?? (() => dies("upload")),
+		listForSubject: overrides.listForSubject ?? (() => dies("listForSubject"))
 	});
 	/** {@link Attestation.makeTest} behind a `Layer`. */
 	static layerTest = (overrides = {}) => Layer.succeed(Attestation, Attestation.makeTest(overrides));
 };
-const unstubbed = (member) => {
-	throw new Error(`Attestation.makeTest: ${member}() was called but not stubbed — pass an override.`);
-};
+const dies = unstubbed("Attestation.makeTest");
 const make = (client) => ({
 	upload: Effect.fn("Attestation.upload")(function* (bundle) {
 		const { owner, repo } = yield* Repo;

package/AuthenticatedApp.js

@@ -1,4 +1,5 @@
 import { GitHubError } from "./GitHubError.js";
+import { unstubbed } from "./internal/unstubbed.js";
 import { GitHubClient } from "./GitHubClient.js";
 import { numericId } from "./internal/ids.js";
 import { Context, Effect, Layer, Schema, Stream } from "effect";
@@ -118,20 +119,18 @@ var DeliveryAttempt = class extends Schema.Class("DeliveryAttempt")({
 var AuthenticatedApp = class AuthenticatedApp extends Context.Service()("@effected/github/AuthenticatedApp") {
 	/** The live service, built over an App-JWT `GitHubClient`. */
 	static layer = Layer.effect(this, Effect.map(GitHubClient, (client) => make(client)));
-	/** An in-memory double; unstubbed members die naming themselves. */
+	/** An in-memory double; an unstubbed member dies when run, naming itself. */
 	static makeTest = (overrides = {}) => ({
-		get: overrides.get ?? (() => unstubbed("get")),
-		deliveries: overrides.deliveries ?? (() => unstubbed("deliveries")),
-		delivery: overrides.delivery ?? (() => unstubbed("delivery")),
-		redeliver: overrides.redeliver ?? (() => unstubbed("redeliver")),
-		uninstall: overrides.uninstall ?? (() => unstubbed("uninstall"))
+		get: overrides.get ?? (() => dies("get")),
+		deliveries: overrides.deliveries ?? (() => Stream.fromEffect(dies("deliveries"))),
+		delivery: overrides.delivery ?? (() => dies("delivery")),
+		redeliver: overrides.redeliver ?? (() => dies("redeliver")),
+		uninstall: overrides.uninstall ?? (() => dies("uninstall"))
 	});
 	/** {@link AuthenticatedApp.makeTest} behind a `Layer`. */
 	static layerTest = (overrides = {}) => Layer.succeed(AuthenticatedApp, AuthenticatedApp.makeTest(overrides));
 };
-const unstubbed = (member) => {
-	throw new Error(`AuthenticatedApp.makeTest: ${member}() was called but not stubbed — pass an override.`);
-};
+const dies = unstubbed("AuthenticatedApp.makeTest");
 const decodeDelivery = Schema.decodeUnknownEffect(DeliveryAttempt);
 const decodeApp = Schema.decodeUnknownEffect(AppInfo);
 /** A nullable int64 id, narrowed like every other id. */

package/CheckRun.js

@@ -1,4 +1,5 @@
 import { GitHubError } from "./GitHubError.js";
+import { unstubbed } from "./internal/unstubbed.js";
 import { GitHubClient } from "./GitHubClient.js";
 import { Repo } from "./Repo.js";
 import { numericId } from "./internal/ids.js";
@@ -239,24 +240,22 @@ var CheckRunRef = class extends Schema.Class("CheckRunRef")({
 var CheckRun = class CheckRun extends Context.Service()("@effected/github/CheckRun") {
 	/** The live service, built over a `GitHubClient`. */
 	static layer = Layer.effect(this, Effect.map(GitHubClient, (client) => make(client)));
-	/** An in-memory double; unstubbed members die naming themselves. */
+	/** An in-memory double; an unstubbed member dies when run, naming itself. */
 	static makeTest = (overrides = {}) => ({
-		create: overrides.create ?? (() => unstubbed("create")),
-		get: overrides.get ?? (() => unstubbed("get")),
-		update: overrides.update ?? (() => unstubbed("update")),
-		updateRef: overrides.updateRef ?? (() => unstubbed("updateRef")),
-		list: overrides.list ?? (() => unstubbed("list")),
-		findByExternalId: overrides.findByExternalId ?? (() => unstubbed("findByExternalId")),
-		complete: overrides.complete ?? (() => unstubbed("complete")),
-		completeRef: overrides.completeRef ?? (() => unstubbed("completeRef")),
-		withCheckRun: overrides.withCheckRun ?? (() => unstubbed("withCheckRun"))
+		create: overrides.create ?? (() => dies("create")),
+		get: overrides.get ?? (() => dies("get")),
+		update: overrides.update ?? (() => dies("update")),
+		updateRef: overrides.updateRef ?? (() => dies("updateRef")),
+		list: overrides.list ?? (() => dies("list")),
+		findByExternalId: overrides.findByExternalId ?? (() => dies("findByExternalId")),
+		complete: overrides.complete ?? (() => dies("complete")),
+		completeRef: overrides.completeRef ?? (() => dies("completeRef")),
+		withCheckRun: overrides.withCheckRun ?? (() => dies("withCheckRun"))
 	});
 	/** {@link CheckRun.makeTest} behind a `Layer`. */
 	static layerTest = (overrides = {}) => Layer.succeed(CheckRun, CheckRun.makeTest(overrides));
 };
-const unstubbed = (member) => {
-	throw new Error(`CheckRun.makeTest: ${member}() was called but not stubbed — pass an override.`);
-};
+const dies = unstubbed("CheckRun.makeTest");
 const wireOutput = (output) => {
 	const capped = output.truncated();
 	return {

package/CodeScanning.js

@@ -1,3 +1,4 @@
+import { unstubbed } from "./internal/unstubbed.js";
 import { GitHubClient } from "./GitHubClient.js";
 import { Repo } from "./Repo.js";
 import { Context, Effect, Layer } from "effect";
@@ -25,17 +26,15 @@ var CodeScanning = class CodeScanning extends Context.Service()("@effected/githu
 	* with a clean typecheck.
 	*/
 	static layer = Layer.effect(this, Effect.map(GitHubClient, (client) => make(client)));
-	/** An in-memory double; unstubbed members die naming themselves. */
+	/** An in-memory double; an unstubbed member dies when run, naming itself. */
 	static makeTest = (overrides = {}) => ({
-		configure: overrides.configure ?? (() => unstubbed("configure")),
-		languages: overrides.languages ?? (() => unstubbed("languages"))
+		configure: overrides.configure ?? (() => dies("configure")),
+		languages: overrides.languages ?? (() => dies("languages"))
 	});
 	/** {@link CodeScanning.makeTest} behind a `Layer`. */
 	static layerTest = (overrides = {}) => Layer.succeed(CodeScanning, CodeScanning.makeTest(overrides));
 };
-const unstubbed = (member) => {
-	throw new Error(`CodeScanning.makeTest: ${member}() was called but not stubbed — pass an override.`);
-};
+const dies = unstubbed("CodeScanning.makeTest");
 const SETUP_KEYS = [
 	"state",
 	"languages",

package/DeploymentEnvironment.js

@@ -1,3 +1,4 @@
+import { unstubbed } from "./internal/unstubbed.js";
 import { GitHubClient } from "./GitHubClient.js";
 import { Repo } from "./Repo.js";
 import { Context, Effect, Layer } from "effect";
@@ -34,18 +35,16 @@ var DeploymentEnvironment = class DeploymentEnvironment extends Context.Service(
 	* further down throws at import time with a clean typecheck.
 	*/
 	static layer = Layer.effect(this, Effect.map(GitHubClient, (client) => make(client)));
-	/** An in-memory double; unstubbed members die naming themselves. */
+	/** An in-memory double; an unstubbed member dies when run, naming itself. */
 	static makeTest = (overrides = {}) => ({
-		upsert: overrides.upsert ?? (() => unstubbed("upsert")),
-		list: overrides.list ?? (() => unstubbed("list")),
-		delete: overrides.delete ?? (() => unstubbed("delete"))
+		upsert: overrides.upsert ?? (() => dies("upsert")),
+		list: overrides.list ?? (() => dies("list")),
+		delete: overrides.delete ?? (() => dies("delete"))
 	});
 	/** {@link DeploymentEnvironment.makeTest} behind a `Layer`. */
 	static layerTest = (overrides = {}) => Layer.succeed(DeploymentEnvironment, DeploymentEnvironment.makeTest(overrides));
 };
-const unstubbed = (member) => {
-	throw new Error(`DeploymentEnvironment.makeTest: ${member}() was called but not stubbed — pass an override.`);
-};
+const dies = unstubbed("DeploymentEnvironment.makeTest");
 const make = (client) => {
 	return {
 		upsert: Effect.fn("DeploymentEnvironment.upsert")(function* (name, config = {}) {

package/GitBranch.js

@@ -1,5 +1,6 @@
 import { GitHubError } from "./GitHubError.js";
 import { GraphQLDocument } from "./GraphQL.js";
+import { unstubbed } from "./internal/unstubbed.js";
 import { GitHubClient } from "./GitHubClient.js";
 import { Repo } from "./Repo.js";
 import { Context, Effect, Layer, Option, Schema } from "effect";
@@ -50,23 +51,21 @@ var GitBranch = class GitBranch extends Context.Service()("@effected/github/GitB
 	* layer is built.
 	*/
 	static layer = Layer.effect(this, Effect.map(GitHubClient, (client) => make(client)));
-	/** An in-memory double; unstubbed members die naming themselves. */
+	/** An in-memory double; an unstubbed member dies when run, naming itself. */
 	static makeTest = (overrides = {}) => ({
-		create: overrides.create ?? (() => unstubbed("create")),
-		upsert: overrides.upsert ?? (() => unstubbed("upsert")),
-		exists: overrides.exists ?? (() => unstubbed("exists")),
-		sha: overrides.sha ?? (() => unstubbed("sha")),
-		shaOption: overrides.shaOption ?? (() => unstubbed("shaOption")),
-		reset: overrides.reset ?? (() => unstubbed("reset")),
-		delete: overrides.delete ?? (() => unstubbed("delete")),
-		createLinked: overrides.createLinked ?? (() => unstubbed("createLinked"))
+		create: overrides.create ?? (() => dies("create")),
+		upsert: overrides.upsert ?? (() => dies("upsert")),
+		exists: overrides.exists ?? (() => dies("exists")),
+		sha: overrides.sha ?? (() => dies("sha")),
+		shaOption: overrides.shaOption ?? (() => dies("shaOption")),
+		reset: overrides.reset ?? (() => dies("reset")),
+		delete: overrides.delete ?? (() => dies("delete")),
+		createLinked: overrides.createLinked ?? (() => dies("createLinked"))
 	});
 	/** {@link GitBranch.makeTest} behind a `Layer`. */
 	static layerTest = (overrides = {}) => Layer.succeed(GitBranch, GitBranch.makeTest(overrides));
 };
-const unstubbed = (member) => {
-	throw new Error(`GitBranch.makeTest: ${member}() was called but not stubbed — pass an override.`);
-};
+const dies = unstubbed("GitBranch.makeTest");
 /**
 * `main`, `refs/heads/main` and `heads/main` all name the same branch.
 *

package/GitCommit.js

@@ -1,3 +1,4 @@
+import { unstubbed } from "./internal/unstubbed.js";
 import { GitHubClient } from "./GitHubClient.js";
 import { Repo } from "./Repo.js";
 import { Context, Effect, Layer, Schema } from "effect";
@@ -86,19 +87,17 @@ var CommitRef = class extends Schema.Class("CommitRef")({
 var GitCommit = class GitCommit extends Context.Service()("@effected/github/GitCommit") {
 	/** The live service, built over a `GitHubClient`. */
 	static layer = Layer.effect(this, Effect.map(GitHubClient, (client) => make(client)));
-	/** An in-memory double; unstubbed members die naming themselves. */
+	/** An in-memory double; an unstubbed member dies when run, naming itself. */
 	static makeTest = (overrides = {}) => ({
-		get: overrides.get ?? (() => unstubbed("get")),
-		createTree: overrides.createTree ?? (() => unstubbed("createTree")),
-		createCommit: overrides.createCommit ?? (() => unstubbed("createCommit")),
-		commitFiles: overrides.commitFiles ?? (() => unstubbed("commitFiles"))
+		get: overrides.get ?? (() => dies("get")),
+		createTree: overrides.createTree ?? (() => dies("createTree")),
+		createCommit: overrides.createCommit ?? (() => dies("createCommit")),
+		commitFiles: overrides.commitFiles ?? (() => dies("commitFiles"))
 	});
 	/** {@link GitCommit.makeTest} behind a `Layer`. */
 	static layerTest = (overrides = {}) => Layer.succeed(GitCommit, GitCommit.makeTest(overrides));
 };
-const unstubbed = (member) => {
-	throw new Error(`GitCommit.makeTest: ${member}() was called but not stubbed — pass an override.`);
-};
+const dies = unstubbed("GitCommit.makeTest");
 /** The Git Database tree entry for one change. */
 const treeEntry = (change) => change._tag === "FileContent" ? {
 	path: change.path,

package/GitHubApp.js

@@ -1,6 +1,7 @@
 import { GitHubError } from "./GitHubError.js";
 import { GitHubGraphQLError } from "./GraphQL.js";
-import { GitHubClient, makeClientShape } from "./GitHubClient.js";
+import { unstubbed } from "./internal/unstubbed.js";
+import { GitHubClient, makeClientShape, resolveApiVersion } from "./GitHubClient.js";
 import { numericId } from "./internal/ids.js";
 import { InstallationTokenStore } from "./InstallationTokenStore.js";
 import { Cause, Clock, Context, DateTime, Deferred, Duration, Effect, Layer, Option, Redacted, Ref, Schema, Semaphore, Stream } from "effect";
@@ -435,16 +436,16 @@ var GitHubApp = class GitHubApp extends Context.Service()("@effected/github/GitH
 		...options,
 		token: cached.token.token
 	})));
-	/** An in-memory double; unstubbed members die naming themselves. */
+	/** An in-memory double; an unstubbed member dies when run, naming itself. */
 	static makeTest = (overrides = {}) => {
-		const token = overrides.token ?? (() => unstubbed("token"));
+		const token = overrides.token ?? (() => dies("token"));
 		return {
 			token,
-			scopedToken: overrides.scopedToken ?? (() => unstubbed("scopedToken")),
-			revoke: overrides.revoke ?? (() => unstubbed("revoke")),
-			identity: overrides.identity ?? (() => unstubbed("identity")),
-			botUser: overrides.botUser ?? (() => unstubbed("botUser")),
-			installations: overrides.installations ?? (() => unstubbed("installations")),
+			scopedToken: overrides.scopedToken ?? (() => dies("scopedToken")),
+			revoke: overrides.revoke ?? (() => dies("revoke")),
+			identity: overrides.identity ?? (() => dies("identity")),
+			botUser: overrides.botUser ?? (() => dies("botUser")),
+			installations: overrides.installations ?? (() => dies("installations")),
 			cachedToken: overrides.cachedToken ?? makeCachedToken(token)
 		};
 	};
@@ -515,9 +516,7 @@ const makeCachedToken = (token) => {
 		};
 	});
 };
-const unstubbed = (member) => {
-	throw new Error(`GitHubApp.makeTest: ${member}() was called but not stubbed — pass an override.`);
-};
+const dies = unstubbed("GitHubApp.makeTest");
 /** Mint an app JWT: iat 60 s in the past (clock drift), exp 9 minutes after now (GitHub caps at 10). */
 const mintJwt = (credentials) => Effect.gen(function* () {
 	const key = yield* JwtKey.fromPkcs8Pem(credentials.privateKey, { alg: "RS256" });
@@ -545,7 +544,7 @@ const asBearer = (token, options) => makeClientShape({
 });
 const appFailure = (kind) => (error) => Effect.fail(GitHubAppError.of(kind, error.reason, error));
 function makeApp(options) {
-	return Effect.sync(() => {
+	return Effect.map(resolveApiVersion(options.apiVersion), () => {
 		const installations = Effect.fn("GitHubApp.installations")(function* (credentials) {
 			return (yield* (yield* asApp(credentials, options)).paginate("GET /app/installations", {}).pipe(Effect.catch(appFailure("installation")))).map((entry) => {
 				const account = entry.account ?? void 0;
@@ -635,6 +634,7 @@ const normalizePermissions = (raw) => {
 * release.
 */
 const makeRotatingClient = (mint, release, options, operation) => Effect.gen(function* () {
+	const apiVersion = yield* resolveApiVersion(options.apiVersion);
 	const held = yield* Ref.make(Option.none());
 	const revokeHeld = Effect.flatMap(Ref.get(held), (current) => Option.isSome(current) ? Effect.ignore(release(current.value.credential.token)) : Effect.void);
 	const rotate = Effect.gen(function* () {
@@ -679,7 +679,8 @@ const makeRotatingClient = (mint, release, options, operation) => Effect.gen(fun
 		paginate: (route, params, pageOptions) => Effect.flatMap(current, (client) => client.paginate(route, params, pageOptions)),
 		paginateStream: (route, params, pageOptions) => Stream.unwrap(Effect.map(current, (client) => client.paginateStream(route, params, pageOptions))),
 		graphql: (document, variables) => Effect.flatMap(currentForGraphQL, (client) => client.graphql(document, variables)),
-		rateLimit: Effect.flatMap(Ref.get(held), (state) => Option.isSome(state) ? state.value.client.rateLimit : Effect.succeed(Option.none()))
+		rateLimit: Effect.flatMap(Ref.get(held), (state) => Option.isSome(state) ? state.value.client.rateLimit : Effect.succeed(Option.none())),
+		apiVersion
 	};
 });
 

package/GitHubClient.js

@@ -1,8 +1,9 @@
 import { GitHubError } from "./GitHubError.js";
 import { GitHubGraphQLError } from "./GraphQL.js";
 import { RetryPolicy } from "./Resilience.js";
-import { makeTransport } from "./internal/octokit.js";
+import { DEFAULT_API_VERSION, makeTransport } from "./internal/octokit.js";
 import { fromArray, paginate } from "./internal/paginate.js";
+import { unstubbed } from "./internal/unstubbed.js";
 import { Clock, Config, Context, Effect, Layer, Option, Schema, Stream } from "effect";
 
 // src/GitHubClient.ts
@@ -10,7 +11,7 @@ import { Clock, Config, Context, Effect, Layer, Option, Schema, Stream } from "e
 const DEFAULT_PER_PAGE = 100;
 /**
 * A raw HTTP failure recorded for {@link GitHubClient.layerFixture}, made by
-* {@link (GitHubFixtures:variable).failure}.
+* {@link (GitHubFixtures:class).failure}.
 *
 * @remarks
 * Branded, so a fixture's data payload that happens to have a `status` and a
@@ -45,12 +46,42 @@ const isRawFailure = (value) => typeof value === "object" && value !== null && v
 *
 * @public
 */
-const GitHubFixtures = { failure: (response) => new RawFailure(response) };
+var GitHubFixtures = class {
+	constructor() {}
+	/**
+	* A raw failure: what GitHub answered, classified at call time by the same
+	* classifier the live client uses.
+	*
+	* @remarks
+	* Record it wherever a fixture accepts a `GitHubError` (`request`, and so
+	* `requestDecoded`, and `paginate`). Each call fails with
+	* `GitHubError.fromResponse(route, response, now)`, `now` read from `Clock`,
+	* so a rate-limit reset header is measured against the `TestClock`. Prefer it
+	* to a hand-built `GitHubError` when the test is about GitHub's actual
+	* response: the classification is then the package's, not the test's.
+	*
+	* @example
+	* ```ts
+	* import { GitHubClient, GitHubFixtures } from "@effected/github";
+	*
+	* const layer = GitHubClient.layerFixture({
+	*   request: {
+	*     "POST /repos/{owner}/{repo}/releases": GitHubFixtures.failure({
+	*       status: 422,
+	*       body: {
+	*         message: "Validation Failed",
+	*         errors: [{ resource: "Release", code: "already_exists", field: "tag_name" }],
+	*       },
+	*     }),
+	*   },
+	* });
+	* ```
+	*/
+	static failure = (response) => new RawFailure(response);
+};
 const resolvePolicy = (retry) => retry === void 0 ? RetryPolicy.default : retry === "off" ? RetryPolicy.none : retry;
 const perPageOf = (options) => options?.perPage ?? DEFAULT_PER_PAGE;
-const unstubbed = (member) => {
-	throw new Error(`GitHubClient.makeTest: ${member}() was called but not stubbed — pass an override, or use GitHubClient.layerFixture for recorded responses.`);
-};
+const dies = unstubbed("GitHubClient.makeTest", "pass an override, or use GitHubClient.layerFixture for recorded responses.");
 /**
 * The typed GitHub API client.
 *
@@ -118,21 +149,25 @@ var GitHubClient = class GitHubClient extends Context.Service()("@effected/githu
 	* member **dies** naming itself.
 	*
 	* @remarks
-	* No member has an honest default. A fabricated response — an empty list, a
+	* No request member has an honest default. A fabricated response — an empty list, a
 	* made-up sha — would leak into the code under test as fact, so the double
 	* fails loudly instead, which also makes it proof that a test touches nothing
 	* but what it stubbed.
 	*
+	* `rateLimit` answers `Option.none()` and `apiVersion` the live default,
+	* because a real client legitimately answers both without a request.
+	*
 	* For recorded responses that page for real, use
 	* {@link GitHubClient.layerFixture}.
 	*/
 	static makeTest = (overrides = {}) => ({
-		request: overrides.request ?? (() => unstubbed("request")),
-		requestDecoded: overrides.requestDecoded ?? (() => unstubbed("requestDecoded")),
-		paginate: overrides.paginate ?? (() => unstubbed("paginate")),
-		paginateStream: overrides.paginateStream ?? (() => unstubbed("paginateStream")),
-		graphql: overrides.graphql ?? (() => unstubbed("graphql")),
-		rateLimit: overrides.rateLimit ?? Effect.succeed(Option.none())
+		request: overrides.request ?? (() => dies("request")),
+		requestDecoded: overrides.requestDecoded ?? (() => dies("requestDecoded")),
+		paginate: overrides.paginate ?? (() => dies("paginate")),
+		paginateStream: overrides.paginateStream ?? (() => Stream.fromEffect(dies("paginateStream"))),
+		graphql: overrides.graphql ?? (() => dies("graphql")),
+		rateLimit: overrides.rateLimit ?? Effect.succeed(Option.none()),
+		apiVersion: overrides.apiVersion ?? "2026-03-10"
 	});
 	/** {@link GitHubClient.makeTest} behind a `Layer`. */
 	static layerTest = (overrides = {}) => Layer.succeed(GitHubClient, GitHubClient.makeTest(overrides));
@@ -150,13 +185,28 @@ var GitHubClient = class GitHubClient extends Context.Service()("@effected/githu
 	*
 	* **It records every call it serves, including one that fails.** A call
 	* answered by a recorded `GitHubError` or a
-	* {@link (GitHubFixtures:variable).failure} is recorded before it fails, so
+	* {@link (GitHubFixtures:class).failure} is recorded before it fails, so
 	* one fixture both records the calls and classifies a raw failure the way
 	* the live client would; there is no need to classify by hand inside a
 	* {@link GitHubClient.layerTest} handler.
 	*/
 	static layerFixture = (fixtures) => Layer.succeed(GitHubClient, makeFixture(fixtures));
 };
+/** A calendar api-version: `YYYY-MM-DD`. */
+const API_VERSION_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+/**
+* The api-version a client pins: the option when it is a calendar version,
+* the default when it is absent, and a defect naming the option otherwise.
+*
+* @remarks
+* A defect, not a typed failure: a malformed version is a wiring mistake no
+* caller recovers from, and every layer that builds a client would otherwise
+* widen its error channel for it. Exported for `GitHubApp`, which validates
+* eagerly at its own layer construction. Not part of the public surface.
+*
+* @internal
+*/
+const resolveApiVersion = (option) => option === void 0 ? Effect.succeed(DEFAULT_API_VERSION) : API_VERSION_PATTERN.test(option) ? Effect.succeed(option) : Effect.die(/* @__PURE__ */ new Error(`GitHubClient: the apiVersion option must be a calendar version like "${DEFAULT_API_VERSION}" (YYYY-MM-DD), got ${JSON.stringify(option)}`));
 /**
 * Builds the live shape over a constructed transport.
 *
@@ -168,12 +218,14 @@ var GitHubClient = class GitHubClient extends Context.Service()("@effected/githu
 * @internal
 */
 const makeClientShape = (options) => Effect.gen(function* () {
+	const apiVersion = yield* resolveApiVersion(options.apiVersion);
 	const transport = yield* makeTransport({
 		token: options.token,
 		retry: resolvePolicy(options.retry),
 		baseUrl: options.baseUrl,
 		userAgent: options.userAgent,
-		fetch: options.fetch
+		fetch: options.fetch,
+		apiVersion
 	});
 	const request = Effect.fn("GitHubClient.request")(function* (route, params) {
 		yield* Effect.annotateCurrentSpan({ route });
@@ -205,7 +257,8 @@ const makeClientShape = (options) => Effect.gen(function* () {
 			const raw = yield* transport.graphql(document.name, document.document, document.encodeVariables(variables));
 			return yield* document.decode(raw).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(GitHubGraphQLError.decode(document.name, "response did not match its schema", error))));
 		}),
-		rateLimit: transport.rateLimit
+		rateLimit: transport.rateLimit,
+		apiVersion
 	};
 });
 const makeFixture = (fixtures) => {
@@ -272,8 +325,9 @@ const makeFixture = (fixtures) => {
 			const raw = fixtures.graphql?.[document.name];
 			return raw === void 0 ? Effect.die(/* @__PURE__ */ new Error(`GitHubClient.layerFixture: no graphql fixture for ${document.name}`)) : document.decode(raw).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(GitHubGraphQLError.decode(document.name, "fixture did not match its schema", error))));
 		},
-		rateLimit: Effect.succeed(Option.fromUndefinedOr(fixtures.rateLimit))
+		rateLimit: Effect.succeed(Option.fromUndefinedOr(fixtures.rateLimit)),
+		apiVersion: fixtures.apiVersion ?? "2026-03-10"
 	};
 };
 
-export { GitHubClient, GitHubFixtures, RawFailure, makeClientShape };
+export { GitHubClient, GitHubFixtures, RawFailure, makeClientShape, resolveApiVersion };

package/GitHubCommit.js

@@ -1,4 +1,5 @@
 import { paginate } from "./internal/paginate.js";
+import { unstubbed } from "./internal/unstubbed.js";
 import { GitHubClient } from "./GitHubClient.js";
 import { Repo } from "./Repo.js";
 import { Context, Effect, Layer, Option, Schema, Stream } from "effect";
@@ -114,19 +115,17 @@ var CommitComparison = class extends Schema.Class("CommitComparison")({
 var GitHubCommit = class GitHubCommit extends Context.Service()("@effected/github/GitHubCommit") {
 	/** The live service, built over a `GitHubClient`. */
 	static layer = Layer.effect(this, Effect.map(GitHubClient, (client) => make(client)));
-	/** An in-memory double; unstubbed members die naming themselves. */
+	/** An in-memory double; an unstubbed member dies when run, naming itself. */
 	static makeTest = (overrides = {}) => ({
-		get: overrides.get ?? (() => unstubbed("get")),
-		list: overrides.list ?? (() => unstubbed("list")),
-		compare: overrides.compare ?? (() => unstubbed("compare")),
-		changedFiles: overrides.changedFiles ?? (() => unstubbed("changedFiles"))
+		get: overrides.get ?? (() => dies("get")),
+		list: overrides.list ?? (() => dies("list")),
+		compare: overrides.compare ?? (() => dies("compare")),
+		changedFiles: overrides.changedFiles ?? (() => dies("changedFiles"))
 	});
 	/** {@link GitHubCommit.makeTest} behind a `Layer`. */
 	static layerTest = (overrides = {}) => Layer.succeed(GitHubCommit, GitHubCommit.makeTest(overrides));
 };
-const unstubbed = (member) => {
-	throw new Error(`GitHubCommit.makeTest: ${member}() was called but not stubbed — pass an override.`);
-};
+const dies = unstubbed("GitHubCommit.makeTest");
 const summarize = (raw) => CommitSummary.make({
 	sha: raw.sha,
 	message: raw.commit.message,

package/GitHubContent.js

@@ -1,4 +1,5 @@
 import { GitHubError } from "./GitHubError.js";
+import { unstubbed } from "./internal/unstubbed.js";
 import { GitHubClient } from "./GitHubClient.js";
 import { Repo } from "./Repo.js";
 import { Context, Effect, Layer, Option, Result } from "effect";
@@ -35,17 +36,15 @@ const utf8 = new TextDecoder("utf-8", { ignoreBOM: true });
 var GitHubContent = class GitHubContent extends Context.Service()("@effected/github/GitHubContent") {
 	/** The live service, built over a `GitHubClient`. */
 	static layer = Layer.effect(this, Effect.map(GitHubClient, (client) => make(client)));
-	/** An in-memory double; unstubbed members die naming themselves. */
+	/** An in-memory double; an unstubbed member dies when run, naming itself. */
 	static makeTest = (overrides = {}) => ({
-		getFile: overrides.getFile ?? (() => unstubbed("getFile")),
-		getFileOption: overrides.getFileOption ?? (() => unstubbed("getFileOption"))
+		getFile: overrides.getFile ?? (() => dies("getFile")),
+		getFileOption: overrides.getFileOption ?? (() => dies("getFileOption"))
 	});
 	/** {@link GitHubContent.makeTest} behind a `Layer`. */
 	static layerTest = (overrides = {}) => Layer.succeed(GitHubContent, GitHubContent.makeTest(overrides));
 };
-const unstubbed = (member) => {
-	throw new Error(`GitHubContent.makeTest: ${member}() was called but not stubbed — pass an override.`);
-};
+const dies = unstubbed("GitHubContent.makeTest");
 const make = (client) => {
 	const getFile = Effect.fn("GitHubContent.getFile")(function* (path, options) {
 		const { owner, repo } = yield* Repo;