@joshuafolkken/kit 1.2114.0 → 1.3000.0

package/scripts/gh/git-gh-etag-read.ts

@@ -0,0 +1,107 @@
+import { parse_json_array_or_undefined } from '#scripts/git/parse-json-array'
+import { shared_cache, type CacheSlot } from '#scripts/josh/shared-cache'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { z } from 'zod'
+import { git_gh_conditional, type ConditionalRead } from './git-gh-conditional'
+import { git_gh_exec } from './git-gh-exec'
+
+// A `gh api` GET sent with the ETag of the answer the previous josh process read, kept on disk
+// (joshuafolkken/kit#6560). `backlog:next` and `issue:scout` each run as a fresh process a minute or
+// a filing apart, so an in-process memo never sees its own second read; a `304 Not Modified` costs
+// nothing against the rate limit, so a listing or a body that has not changed since is free.
+//
+// **One record per path.** A `shared_cache` slot holds one key, so each path gets its own slot,
+// named by the path's digest because the path itself is no file name.
+
+const SLOT_PREFIX = 'josh-gh-etag-'
+const PATH_DIGEST_LENGTH = 16
+const HOURS_KEPT = 24
+const MS_PER_HOUR = 3_600_000
+const UNREADABLE_MESSAGE = 'gh api could not read'
+
+const kept_schema = z.object({ etag: z.string(), body: z.string() })
+
+type KeptAnswer = z.infer<typeof kept_schema>
+
+interface SettledAnswer {
+	body: string
+	kept?: KeptAnswer
+}
+
+// A body read with the ETag of a previous answer, saying whether it is that previous one — the shape
+// both the disk read here and the merge gate's in-process read answer (joshuafolkken/kit#7226).
+interface ReadDetail {
+	body: string
+	is_unchanged: boolean
+}
+
+// The body an answer stands for — the previous one where GitHub says it has not changed — and what to
+// keep for the next read. `undefined` is an answer with no body to give.
+function settle(
+	previous: KeptAnswer | undefined,
+	answer: ConditionalRead,
+): SettledAnswer | undefined {
+	if (previous !== undefined && answer.kind === 'unchanged') return { body: previous.body }
+	if (answer.kind !== 'changed') return undefined
+	if (answer.etag === undefined) return { body: answer.body }
+
+	return { body: answer.body, kept: { etag: answer.etag, body: answer.body } }
+}
+
+function slot_of(path: string): CacheSlot {
+	const name = stamp_file.digest(path).slice(0, PATH_DIGEST_LENGTH)
+
+	return { prefix: `${SLOT_PREFIX}${name}-`, ttl_ms: HOURS_KEPT * MS_PER_HOUR }
+}
+
+// gh's own failure is what is thrown, so a caller classifying it by status reads the same error the
+// unconditional read threw.
+function unreadable(path: string, answer: ConditionalRead): unknown {
+	const cause = answer.kind === 'unreadable' ? answer.cause : undefined
+
+	return cause ?? new Error(`${UNREADABLE_MESSAGE}: ${path}`)
+}
+
+// The answer for `path`, or the previous process's where GitHub says it has not changed, saying which.
+// A failure throws, the contract `exec_gh_api` has. `timeout_ms` bounds the request as
+// `exec_gh_api`'s does.
+async function read_detail(path: string, timeout_ms?: number): Promise<ReadDetail> {
+	const slot = slot_of(path)
+	const previous = shared_cache.read(slot, path, kept_schema, Date.now())
+	const answer = await git_gh_conditional.read_conditional(path, previous?.etag, timeout_ms)
+	const settled = settle(previous, answer)
+
+	if (settled === undefined) throw unreadable(path, answer)
+	if (settled.kept !== undefined) shared_cache.write(slot, path, settled.kept, Date.now())
+
+	return { body: settled.body, is_unchanged: answer.kind === 'unchanged' }
+}
+
+// `read_detail`'s body alone.
+async function read(path: string, timeout_ms?: number): Promise<string> {
+	const { body } = await read_detail(path, timeout_ms)
+
+	return body
+}
+
+// A listing whose first page holds `per_page` rows (joshuafolkken/kit#6699). The ETag covers one page
+// only, so a full first page — more may follow — is read unconditionally with `--paginate` instead;
+// an answer that is no array is handed back for the caller's own parser to reject. `read_page` reads
+// the first page: the merge gate passes its in-process read (joshuafolkken/kit#6756).
+async function read_listing(
+	path: string,
+	per_page: number,
+	read_page: (page_path: string) => Promise<string> = read,
+): Promise<string> {
+	const first = await read_page(path)
+	const rows = parse_json_array_or_undefined(first, z.unknown())
+
+	if (rows === undefined || rows.length < per_page) return first
+
+	return await git_gh_exec.exec_gh_api({ path, should_paginate: true })
+}
+
+const git_gh_etag_read = { read, read_detail, read_listing, settle, slot_of }
+
+export type { KeptAnswer, ReadDetail }
+export { git_gh_etag_read }

package/scripts/gh/git-gh-exec.ts

@@ -1,11 +1,15 @@
 import { has_timed_out } from '#scripts/git/git-execa-error'
 import { agent_session_environment } from '#scripts/josh/agent-session-environment'
+import { bounded_pool } from '#scripts/lib/bounded-pool'
 import { error_text } from '#scripts/lib/error-message'
 import { token_shape } from '#scripts/lib/token-shape'
 import { execa, execaSync } from 'execa'
+import { gh_call_kind } from './gh-call-kind'
+import { gh_request_tally } from './gh-request-tally'
 import { check_gh_installed } from './git-gh-check'
-import { gh_failure } from './git-gh-failure'
+import { gh_failure, has_stdout_field } from './git-gh-failure'
 import { gh_retry } from './git-gh-retry'
+import { GH_SPAWN_CONCURRENCY } from './git-gh-spawn-width'
 
 const BODY_FROM_STDIN = '-'
 
@@ -14,23 +18,23 @@ const BODY_FROM_STDIN = '-'
 // `gh` would hold the caller open with no upper bound — most visibly in `josh propagate`, whose
 // runner is single-threaded and would process no further consumer at all.
 //
-// **It is a request's budget, not a step's.** `STEP_TIMEOUT_MS` (30 minutes, `propagate-steps.ts`)
-// covers a consumer's whole unit suite and a `pnpm add`; one REST call has no business borrowing
-// that number. The value is read off what the callers actually do instead:
+// **It is a request's budget, not a step's.** `STEP_TIMEOUT_MS` in `propagate-steps.ts` covers a
+// consumer's whole unit suite and a `pnpm add`; one REST call must not borrow that budget.
+// The value is read off what the callers actually do instead:
 //
-// - `CHECK_WAIT_INTERVAL_MS` is 10 seconds — the merge gate's poll cadence. A request still in
-//   flight six polls later is not slow, it is stuck.
-// - `PR_CHECKS_WATCH_TIMEOUT_MS` is 120 seconds: `followup`'s look-ahead, which bounds its own
+// - `CHECK_WAIT_INTERVAL_MS` defines the merge gate's poll cadence. A request still in
+//   flight across repeated polls must not block the loop indefinitely.
+// - `PR_CHECKS_WATCH_TIMEOUT_MS` bounds `followup`'s look-ahead and its own
 //   *sleeps* rather than the wall clock, so each poll's requests sit on top of it. A request allowed
 //   to outlast that whole window would make the budget meaningless; half of it keeps one request
 //   from dominating the look-ahead.
-// - the readers that override it ask for 5 seconds (`repo-setting.ts`) and 20
-//   (`propagate-publish.ts`, `epic-cross-repo.ts`). Sixty is deliberately the most generous of them,
+// - the readers that override it (`repo-setting.ts`, `propagate-publish.ts`, `epic-cross-repo.ts`)
+//   use tighter budgets. This default is deliberately more generous,
 //   because this entry also serves `--paginate` requests — several HTTP round trips inside one
-//   spawn — which a 5-second budget would break.
+//   spawn — which the tightest override would break.
 //
-// The aggregate is not what this bounds and must not be read as one: `followup` makes roughly 573
-// requests across a 32-minute wait, and what caps that wait is its own attempt count. All this
+// The aggregate is not what this bounds and must not be read as one: `followup` makes repeated
+// requests while waiting, and what caps that wait is its own attempt count. All this
 // guarantees is that no single request holds it forever.
 //
 // **What a timed-out read costs its caller is decided by that caller, and two are worth naming.**
@@ -64,7 +68,7 @@ function to_timeout_option(timeout_ms?: number): { timeout: number } {
 // **`gh` dials GitHub directly, never through a proxy this machine stood up on loopback**.
 // A package-manager wrapper writes one into the environment of everything
 // its invocation spawns, and it exists to inspect package downloads — api.github.com crosses it
-// without inspection, so the hop buys nothing and can fail on its own: one 30-second stall makes the
+// without inspection, so the hop buys nothing and can fail on its own: one stalled request makes the
 // wrapper refuse every later GitHub connection of that `followup`, and the retries in the poll loop
 // can then only ever fail. The loopback test and
 // the list of spellings are the agent-session launcher's, shared rather than
@@ -115,12 +119,6 @@ function has_stderr_field(error: unknown): error is Error & { stderr: string } {
 	return error instanceof Error && 'stderr' in error && typeof error.stderr === 'string'
 }
 
-// execa attaches the captured output to the error it throws, which is where the status line lands
-// when `gh api` exits non-zero — the case the whole probe exists for.
-function has_stdout_field(error: unknown): error is Error & { stdout: string } {
-	return error instanceof Error && 'stdout' in error && typeof error.stdout === 'string'
-}
-
 // `has_timed_out` is shared with the push transport rather than restated here: execa marks a spawn
 // it killed the same way whichever binary was spawned, and `git push` has a budget of its own.
 function to_timeout_prefix(error: unknown): string {
@@ -152,7 +150,10 @@ function to_gh_error(error: unknown): Error {
 	)
 }
 
-async function exec_gh_command(
+// Held around the spawn only: `with_retry`'s backoff waits outside a slot.
+const gh_slots = bounded_pool.limiter(GH_SPAWN_CONCURRENCY)
+
+async function spawn_gh_command(
 	arguments_: Array<string>,
 	timeout_ms?: number,
 	cwd?: string,
@@ -160,6 +161,8 @@ async function exec_gh_command(
 	await check_gh_installed()
 	const options = to_spawn_options(timeout_ms, cwd)
 
+	gh_request_tally.count_call(gh_call_kind.of(arguments_))
+
 	try {
 		const { stdout } = await execa('gh', arguments_, options) // NOSONAR S8705: execa array args (no shell), trusted dev CLI tooling
 
@@ -169,20 +172,32 @@ async function exec_gh_command(
 	}
 }
 
-async function exec_gh_command_with_stdin(input: {
+async function exec_gh_command(
+	arguments_: Array<string>,
+	timeout_ms?: number,
+	cwd?: string,
+): Promise<string> {
+	return await gh_slots.run(async () => await spawn_gh_command(arguments_, timeout_ms, cwd))
+}
+
+interface StdinCommand {
 	args: Array<string>
 	stdin_body: string
 	// `number | undefined` rather than plain optional: `exec_gh_api` forwards its own optional field,
 	// which `exactOptionalPropertyTypes` will not narrow for it.
 	timeout_ms?: number | undefined
 	cwd?: string | undefined
-}): Promise<string> {
+}
+
+async function spawn_gh_command_with_stdin(input: StdinCommand): Promise<string> {
 	await check_gh_installed()
 
 	// Built ahead of the call so the spawn itself stays on one line: `// NOSONAR` suppresses the rule
 	// only on the line it sits on, and a wrapped call moves that line away from the reported one.
 	const options = { input: input.stdin_body, ...to_spawn_options(input.timeout_ms, input.cwd) }
 
+	gh_request_tally.count_call(gh_call_kind.of(input.args))
+
 	try {
 		const { stdout } = await execa('gh', input.args, options) // NOSONAR S8705: execa array args (no shell), trusted dev CLI tooling
 
@@ -192,6 +207,10 @@ async function exec_gh_command_with_stdin(input: {
 	}
 }
 
+async function exec_gh_command_with_stdin(input: StdinCommand): Promise<string> {
+	return await gh_slots.run(async () => await spawn_gh_command_with_stdin(input))
+}
+
 // The status line `gh api --include` prints before the headers, e.g. `HTTP/2.0 404 Not Found`.
 const STATUS_LINE_PATTERN = /^HTTP\/[\d.]+ (?<status>\d{3})\b/u
 
@@ -220,7 +239,7 @@ function status_of_failure(error: unknown): number | undefined {
 // spawn beside four bounded ones would be an inconsistency in the same file. A timeout reaches the
 // `catch` and answers `undefined`, which already means "no status was reached", which its one
 // caller already reads as a failed read rather than as a 404.
-async function exec_gh_api_status(path: string, timeout_ms?: number): Promise<number | undefined> {
+async function spawn_gh_api_status(path: string, timeout_ms?: number): Promise<number | undefined> {
 	// Hoisted so the spawn below fits on one line, which `// NOSONAR` requires — it suppresses only
 	// the line it sits on. The **argument list** stays an inline literal for the opposite reason:
 	// `gh-subcommand-guard.ts` resolves the subcommand from it, and hoisting that into a `const`
@@ -230,6 +249,7 @@ async function exec_gh_api_status(path: string, timeout_ms?: number): Promise<nu
 
 	try {
 		await check_gh_installed()
+		gh_request_tally.count_call(gh_call_kind.of_api(path))
 		const { stdout } = await execa('gh', ['api', '--include', '--silent', path], options) // NOSONAR S8705: execa array args (no shell), trusted dev CLI tooling
 
 		return parse_status_line(stdout)
@@ -238,6 +258,10 @@ async function exec_gh_api_status(path: string, timeout_ms?: number): Promise<nu
 	}
 }
 
+async function exec_gh_api_status(path: string, timeout_ms?: number): Promise<number | undefined> {
+	return await gh_slots.run(async () => await spawn_gh_api_status(path, timeout_ms))
+}
+
 // The synchronous twin of `exec_gh_api_status`, for `epic-cross-repo.ts`, whose resolver is
 // synchronous all the way up to `epic_classify`. Same request, same
 // answer: the status line, or `undefined` when no status was reached. It cannot run
@@ -246,6 +270,8 @@ async function exec_gh_api_status(path: string, timeout_ms?: number): Promise<nu
 function exec_gh_api_status_sync(path: string, timeout_ms?: number): number | undefined {
 	const options = to_spawn_options(timeout_ms)
 
+	gh_request_tally.count_call(gh_call_kind.of_api(path))
+
 	try {
 		const { stdout } = execaSync('gh', ['api', '--include', '--silent', path], options) // NOSONAR S8705: execa array args (no shell), trusted dev CLI tooling
 
@@ -365,6 +391,21 @@ async function exec_gh_api(request: GhApiRequest): Promise<string> {
 	return await gh_retry.with_retry(async () => await send_gh_api(request))
 }
 
+// `exec_gh_api` without the count, for the request tally's own core allowance reading
+// (`gh-request-tally.ts`): `GET /rate_limit` costs no quota and is the measurement, not a measured
+// call. It takes no slot and no retry, so the reading never waits behind the calls it measures.
+async function exec_gh_api_uncounted(request: GhApiRequest): Promise<string> {
+	const options = to_spawn_options(request.timeout_ms, request.cwd)
+
+	try {
+		const { stdout } = await execa('gh', to_gh_api_args(request), options) // NOSONAR S8705: execa array args (no shell), trusted dev CLI tooling
+
+		return stdout.trimEnd()
+	} catch (error) {
+		throw to_gh_error(error)
+	}
+}
+
 // The synchronous twin of `exec_gh_api`, for a caller that cannot await. `josh propagate` runs each
 // consumer's steps as a sequential chain of `execaSync` spawns with inherited stdio, and that shape
 // reaches from `open_issue` up through `RunStep`, `run_target` and `run_targets` — so the issue it
@@ -389,9 +430,12 @@ function exec_gh_api_sync(request: GhApiRequest): string {
 	refuse_credential_body(request)
 	const body_option = request.body === undefined ? {} : { input: request.body }
 	const options = { ...body_option, ...to_spawn_options(request.timeout_ms, request.cwd) }
+	const gh_arguments = to_gh_api_args(request)
+
+	gh_request_tally.count_call(gh_call_kind.of(gh_arguments))
 
 	try {
-		const { stdout } = execaSync('gh', to_gh_api_args(request), options) // NOSONAR S8705: execa array args (no shell), trusted dev CLI tooling
+		const { stdout } = execaSync('gh', gh_arguments, options) // NOSONAR S8705: execa array args (no shell), trusted dev CLI tooling
 
 		return stdout.trimEnd()
 	} catch (error) {
@@ -416,6 +460,7 @@ const git_gh_exec = {
 	exec_gh_command,
 	exec_gh_command_with_stdin,
 	exec_gh_api,
+	exec_gh_api_uncounted,
 	exec_gh_api_sync,
 	read_gh_api_sync,
 	exec_gh_api_status,
@@ -424,5 +469,9 @@ const git_gh_exec = {
 }
 
 export type { GhApiRequest }
-export { git_gh_exec, has_stderr_field, has_stdout_field }
+export { git_gh_exec, has_stderr_field }
 export { BODY_FROM_STDIN, GH_REQUEST_TIMEOUT_MESSAGE, GH_REQUEST_TIMEOUT_MS }
+
+export { GH_SPAWN_CONCURRENCY } from './git-gh-spawn-width'
+
+export { has_stdout_field } from './git-gh-failure'

package/scripts/gh/git-gh-failure.ts

@@ -48,6 +48,12 @@ interface GhFailure {
 // `Error` distinguished by a field, and one subclass among them would be a second convention.
 const GH_FAILURE_FIELD = 'gh_failure'
 
+// execa attaches the captured output to the error it throws, which is where the status line lands
+// when `gh api` exits non-zero — the case the whole probe exists for.
+function has_stdout_field(error: unknown): error is Error & { stdout: string } {
+	return error instanceof Error && 'stdout' in error && typeof error.stdout === 'string'
+}
+
 function has_gh_failure(error: unknown): error is Error & { gh_failure: GhFailure } {
 	return error instanceof Error && Object.hasOwn(error, GH_FAILURE_FIELD)
 }
@@ -94,7 +100,15 @@ function failure_of(error: unknown): GhFailure | undefined {
 	return has_gh_failure(error) ? error.gh_failure : undefined
 }
 
-const gh_failure = { attach, classify_stdout, failure_of, parse_response_status }
+// The response body a failed `gh api` request wrote, kept on the execa error `git-gh-exec.ts` wraps:
+// `gh` exits non-zero on a GraphQL document that carries `errors`, even beside answered `data`.
+function body_of(error: unknown): string | undefined {
+	const cause = error instanceof Error ? error.cause : undefined
+
+	return has_stdout_field(cause) ? cause.stdout : undefined
+}
+
+const gh_failure = { attach, body_of, classify_stdout, failure_of, parse_response_status }
 
 export type { GhFailure }
-export { gh_failure, GH_FAILURE_FIELD }
+export { gh_failure, GH_FAILURE_FIELD, has_stdout_field }

package/scripts/gh/git-gh-helpers.ts

@@ -1,11 +1,7 @@
 import { has_stderr_field } from './git-gh-exec'
 
-// One optional string answer from `gh`. Every caller asks with `--jq`, which unwraps the JSON
-// string itself, so the value arrives raw and there is nothing to unquote — this used to strip a
-// leading and trailing `"` anyway, which ate real characters from any answer that legitimately
-// carried them. A title of `"queue" should stop at the first failure` reached Telegram as
-// `queue" should stop at the first failure`. Trimming and the empty answer
-// are the whole contract.
+// `--jq` already unwraps JSON strings, so only surrounding whitespace and empty answers need
+// normalization. Quotes in the raw answer belong to the user's text and must survive.
 function parse_pr_state_string(result: string): string | undefined {
 	const trimmed = result.trim()
 

package/scripts/gh/git-gh-issue-alias-graphql.ts

@@ -0,0 +1,113 @@
+import { json_value } from '#scripts/lib/json-value'
+import { z } from 'zod'
+import { git_gh_blocked_by_graphql } from './git-gh-blocked-by-graphql'
+import { git_gh_issue_graphql, type RepositoryVariables } from './git-gh-issue-graphql'
+import { git_gh_transport } from './git-gh-transport'
+
+// Any fields of many issues in one GraphQL query per hundred (joshuafolkken/kit#6791), each issue an
+// aliased `issue(number:)` field of its repository, since a caller holds numbers rather than the
+// `node_id`s `nodes(ids:)` needs. The caller names the fields and the schema one issue answers in.
+//
+// **A number missing from the answer is the caller's to read through REST**: a session on REST
+// (`git-gh-transport.ts`), a failed query — one number that is a pull request or nothing fails the
+// whole document — or a repository the checkout cannot name.
+
+const ALIAS_PREFIX = 'issue'
+
+const rate_limit_schema = z.object({ cost: z.number(), remaining: z.number() })
+
+// What GraphQL answered, keyed by number, and what the queries cost: `cost` sums the points every
+// answered query spent, `remaining` is the GraphQL budget the last one left.
+interface AliasRead<T> {
+	answers: Map<number, T>
+	cost: number
+	remaining: number | undefined
+}
+
+interface ChunkData<T> {
+	rateLimit: z.infer<typeof rate_limit_schema>
+	repository: Record<string, T | null>
+}
+
+function alias_of(issue_number: number): string {
+	return `${ALIAS_PREFIX}${String(issue_number)}`
+}
+
+function query_of(issue_numbers: ReadonlyArray<number>, fields: string): string {
+	const aliases = issue_numbers.map(
+		(issue_number) =>
+			`${alias_of(issue_number)}: issue(number: ${String(issue_number)}) { ${fields} }`,
+	)
+
+	return `query($owner: String!, $name: String!) {
+	rateLimit { cost remaining }
+	repository(owner: $owner, name: $name) { ${aliases.join('\n')} }
+}`
+}
+
+function response_schema_of<T>(issue_schema: z.ZodType<T>): z.ZodType<{ data: ChunkData<T> }> {
+	const repository_schema = z.record(z.string(), issue_schema.nullable())
+	const data_schema = z.looseObject({ rateLimit: rate_limit_schema, repository: repository_schema })
+
+	return z.looseObject({ data: data_schema })
+}
+
+async function query_chunk<T>(
+	issue_numbers: ReadonlyArray<number>,
+	fields: string,
+	issue_schema: z.ZodType<T>,
+	variables: RepositoryVariables,
+): Promise<ChunkData<T> | undefined> {
+	const json = await git_gh_transport.query({ query: query_of(issue_numbers, fields), variables })
+	if (json === undefined) return undefined
+
+	return json_value.parse_with(json, response_schema_of(issue_schema))?.data
+}
+
+function with_chunk<T>(
+	read: AliasRead<T>,
+	issue_numbers: ReadonlyArray<number>,
+	data: ChunkData<T> | undefined,
+): AliasRead<T> {
+	if (data === undefined) return read
+
+	const answered = issue_numbers.flatMap((issue_number): Array<[number, T]> => {
+		const issue = data.repository[alias_of(issue_number)]
+
+		return issue === undefined || issue === null ? [] : [[issue_number, issue]]
+	})
+
+	return {
+		answers: new Map([...read.answers, ...answered]),
+		cost: read.cost + data.rateLimit.cost,
+		remaining: data.rateLimit.remaining,
+	}
+}
+
+// The issues of one repository (`repo` as `--repo` names it; the checkout's own when absent), each
+// answering `fields` in `issue_schema`.
+async function read_aliased<T>(
+	issue_numbers: ReadonlyArray<number>,
+	fields: string,
+	issue_schema: z.ZodType<T>,
+	repo?: string,
+): Promise<AliasRead<T>> {
+	const variables =
+		issue_numbers.length === 0 ? undefined : git_gh_issue_graphql.repository_variables_of(repo)
+	let read: AliasRead<T> = { answers: new Map(), cost: 0, remaining: undefined }
+	if (variables === undefined) return read
+
+	const chunks = git_gh_blocked_by_graphql.chunks_of([...new Set(issue_numbers)])
+
+	for (const chunk of chunks) {
+		// eslint-disable-next-line no-await-in-loop -- one query at a time keeps the burst to one request
+		read = with_chunk(read, chunk, await query_chunk(chunk, fields, issue_schema, variables))
+	}
+
+	return read
+}
+
+const git_gh_issue_alias_graphql = { read_aliased }
+
+export type { AliasRead }
+export { git_gh_issue_alias_graphql }

package/scripts/gh/git-gh-issue-batch-graphql.ts

@@ -0,0 +1,155 @@
+import { json_value } from '#scripts/lib/json-value'
+import { z } from 'zod'
+import { git_gh_blocked_by_graphql } from './git-gh-blocked-by-graphql'
+import {
+	git_gh_issue_graphql,
+	ISSUE_FIELDS,
+	issue_fields_schema,
+	type GraphqlIssueFields,
+	type RepositoryVariables,
+} from './git-gh-issue-graphql'
+import { STATE_AND_RELATIONS_FIELDS, type IssueRead } from './git-gh-issue-read'
+import { git_gh_issue_rest } from './git-gh-issue-rest'
+import { git_gh_transport } from './git-gh-transport'
+
+// An epic's children — state, labels, blocker relations, body and author — in one GraphQL query per
+// hundred (joshuafolkken/kit#6792). REST reads them one issue at a time, one or two core requests
+// each, so a 200-child epic spent hundreds of the 5,000-per-hour core budget on every `epic:next`.
+// The children are addressed as aliased `issue(number:)` fields of their repository, since a task
+// list carries numbers rather than the `node_id`s `nodes(ids:)` needs.
+//
+// Each answer is mapped into the read `issue_get_state_and_relations_classified` produces, through
+// the same REST mapping (`git-gh-issue-graphql.ts`), so nothing downstream changes.
+//
+// **A number missing from the answer is the caller's to read through REST**: a session on REST
+// (`git-gh-transport.ts`), a failed query, a repository the checkout cannot name, a pull request
+// (below), or a number that resolves to nothing — its alias answers `null` beside an `errors` entry,
+// and `gh` exits non-zero while the other aliases still answer (`query_partial`,
+// joshuafolkken/kit#6964).
+// REST keeps telling a missing number from a failed read, which a GraphQL error document does not.
+//
+// Each alias asks `issueOrPullRequest` for the issue fields only, so a pull request answers an empty
+// object that leaves its own number to REST — REST tells it apart by its URL — instead of failing
+// the chunk it shares with up to ninety-nine issues (joshuafolkken/kit#6869).
+
+const ALIAS_PREFIX = 'issue'
+
+const rate_limit_schema = z.object({ cost: z.number(), remaining: z.number() })
+
+// Each alias is checked on its own: `null` for nothing at that number, `{}` for a pull request.
+const repository_schema = z.record(z.string(), z.unknown())
+
+const data_schema = z.looseObject({ rateLimit: rate_limit_schema, repository: repository_schema })
+
+const response_schema = z.looseObject({ data: data_schema })
+
+type ChunkData = z.infer<typeof data_schema>
+
+// The reads GraphQL answered, keyed by number, and what the queries cost: `cost` sums the points
+// every answered query spent, `remaining` is the GraphQL budget the last one left.
+interface BatchRead {
+	reads: Map<number, IssueRead>
+	cost: number
+	remaining: number | undefined
+}
+
+function alias_of(issue_number: number): string {
+	return `${ALIAS_PREFIX}${String(issue_number)}`
+}
+
+function query_of(issue_numbers: ReadonlyArray<number>): string {
+	const aliases = issue_numbers.map(
+		(issue_number) =>
+			`${alias_of(issue_number)}: issueOrPullRequest(number: ${String(issue_number)}) { ... on Issue { ${ISSUE_FIELDS} } }`,
+	)
+
+	return `query($owner: String!, $name: String!) {
+	rateLimit { cost remaining }
+	repository(owner: $owner, name: $name) { ${aliases.join('\n')} }
+}`
+}
+
+function answered(json: string): IssueRead {
+	return { kind: 'read', json }
+}
+
+// `fields` is the `--json` list of the REST read the answer stands in for.
+function to_read(issue: GraphqlIssueFields, fields: string): IssueRead {
+	const issue_json = git_gh_issue_rest.to_gh_issue(
+		git_gh_issue_graphql.to_rest_issue(issue),
+		git_gh_issue_rest.split_fields(fields),
+		git_gh_issue_graphql.to_blocked_by(issue),
+	)
+
+	return answered(JSON.stringify(issue_json))
+}
+
+async function query_chunk(
+	issue_numbers: ReadonlyArray<number>,
+	variables: RepositoryVariables,
+): Promise<ChunkData | undefined> {
+	const json = await git_gh_transport.query_partial({ query: query_of(issue_numbers), variables })
+	if (json === undefined) return undefined
+
+	return json_value.parse_with(json, response_schema)?.data
+}
+
+// One chunk's numbers and the fields their reads carry.
+interface ChunkRequest {
+	issue_numbers: ReadonlyArray<number>
+	fields: string
+}
+
+function answered_reads(request: ChunkRequest, data: ChunkData): Array<[number, IssueRead]> {
+	return request.issue_numbers.flatMap((issue_number): Array<[number, IssueRead]> => {
+		const issue = issue_fields_schema.safeParse(data.repository[alias_of(issue_number)])
+
+		return issue.success ? [[issue_number, to_read(issue.data, request.fields)]] : []
+	})
+}
+
+function with_chunk(
+	batch: BatchRead,
+	request: ChunkRequest,
+	data: ChunkData | undefined,
+): BatchRead {
+	if (data === undefined) return batch
+
+	return {
+		reads: new Map([...batch.reads, ...answered_reads(request, data)]),
+		cost: batch.cost + data.rateLimit.cost,
+		remaining: data.rateLimit.remaining,
+	}
+}
+
+function empty_batch(): BatchRead {
+	return { reads: new Map(), cost: 0, remaining: undefined }
+}
+
+// The children of one repository (`repo` as `--repo` names it; the checkout's own when absent).
+async function read_many(
+	issue_numbers: ReadonlyArray<number>,
+	repo?: string,
+	fields: string = STATE_AND_RELATIONS_FIELDS,
+): Promise<BatchRead> {
+	const variables =
+		issue_numbers.length === 0 ? undefined : git_gh_issue_graphql.repository_variables_of(repo)
+	let batch = empty_batch()
+	if (variables === undefined) return batch
+
+	const chunks = git_gh_blocked_by_graphql.chunks_of([...new Set(issue_numbers)])
+
+	for (const chunk of chunks) {
+		const request = { issue_numbers: chunk, fields }
+
+		// eslint-disable-next-line no-await-in-loop -- one query at a time keeps the burst to one request
+		batch = with_chunk(batch, request, await query_chunk(chunk, variables))
+	}
+
+	return batch
+}
+
+const git_gh_issue_batch_graphql = { answered, empty_batch, read_many }
+
+export type { BatchRead }
+export { git_gh_issue_batch_graphql }