@joshuafolkken/kit 1.872.0

package/scripts/epic/epic-relation-recheck.ts

@@ -0,0 +1,108 @@
+import { git_epic_parse } from '#scripts/git/git-epic-parse'
+import { epic_graph, type EpicChild, type IssueReference } from './epic-graph'
+
+// joshuafolkken/kit#1113: a second look at the relations, taken only where the first one is about to
+// become a verdict.
+//
+// `read_blocked_by` answers from the issue's own `issue_dependencies_summary` when that summary says
+// zero, which is what keeps a pass over the whole backlog to one request per issue that declares a
+// blocker (joshuafolkken/kit#1024). The summary is GitHub's count, and it can disagree with the
+// listing it counts: measured on joshuafolkken/kit#1111, whose summary read `total_blocked_by: 0`
+// while `dependencies/blocked_by` returned `#1106`, and where re-POSTing that relation was refused
+// with `Target issue has already been taken` — so the relation was real and only the counter was
+// wrong. `epic:next` read the epic as self-contradictory, printed `declared but not recorded:
+// #1106 -> #1111`, and exited 1. An unattended run stops there, on a graph with nothing to fix.
+//
+// It corrects nothing else. A relation that is genuinely absent still comes back absent, and the
+// mismatch is still reported — the point is that the report is now about the relations rather than
+// about a counter.
+
+// A body may legitimately be ahead of its relations — an epic written before `josh` recorded them,
+// or one whose recording failed — and `missing_relations` calls that case a mismatch too. There the
+// declaration can name every child, so an uncapped recheck fans out one request per child of a
+// 200-child epic, concurrently, to confirm what the body already implies. Past this many suspects
+// the mismatch is not a stale counter and is reported unchecked: a stale counter is one relation
+// GitHub miscounted, not the whole graph.
+const RECHECK_LIMIT = 20
+
+// How the caller reads one child's blockers without consulting the summary. Injected so the
+// decision above can be tested without a network, and so this module needs no opinion about how a
+// child in another repository is addressed.
+type BlockersReader = (child: EpicChild) => Promise<Array<IssueReference>>
+
+// The children a declared-but-unrecorded link points at. `link.blocked` is the child whose
+// `blocked_by` would have to carry the blocker, so it is the only side worth reading again.
+//
+// Restricted to `declared_repo` because a declared link is written as a bare number, which names an
+// issue in the epic's own repository — `epic_graph` matches those by number alone. An epic tracking
+// both `#40` and `owner/other#40` would otherwise have the second child re-read on the first one's
+// account, and its relations replaced with a different issue's (joshuafolkken/kit#1014).
+function suspect_children(
+	children: ReadonlyArray<EpicChild>,
+	body: string | undefined,
+	declared_repo: string,
+): Set<number> {
+	const links = git_epic_parse.parse_dependency_links(body)
+	const local = children.filter((child) => child.repo === declared_repo)
+
+	return new Set(
+		epic_graph.missing_relations(links, local, declared_repo).map((link) => link.blocked),
+	)
+}
+
+// A read that fails leaves the child exactly as the first read found it, and says so. The mismatch
+// is then reported as it was before — the honest answer, since nothing was learned — but a run that
+// exits 1 on it should not have to guess whether the correction was even attempted.
+async function reread_child(child: EpicChild, read_blockers: BlockersReader): Promise<EpicChild> {
+	try {
+		return { ...child, blocked_by: await read_blockers(child) }
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error)
+
+		console.warn(
+			`⚠ could not re-read the blockers of #${String(child.number)}: ${reason}\n` +
+				'  a mismatch reported below may be this read failing rather than a missing relation',
+		)
+
+		return child
+	}
+}
+
+// Said out loud for the same reason the failed read is: `epic:next` exits 1 on the mismatch that
+// follows, and an operator reading that message should not have to guess whether the correction was
+// even attempted.
+function skipped_over_limit(
+	children: ReadonlyArray<EpicChild>,
+	suspect_count: number,
+): ReadonlyArray<EpicChild> {
+	console.warn(
+		`⚠ ${String(suspect_count)} declared links are unrecorded, past the ${String(RECHECK_LIMIT)} this re-reads\n` +
+			'  the mismatch below is reported from the first read; the body is likely ahead of the relations',
+	)
+
+	return children
+}
+
+async function recheck_missing_relations(
+	children: ReadonlyArray<EpicChild>,
+	body: string | undefined,
+	declared_repo: string,
+	read_blockers: BlockersReader,
+): Promise<ReadonlyArray<EpicChild>> {
+	const suspects = suspect_children(children, body, declared_repo)
+	if (suspects.size === 0) return children
+	if (suspects.size > RECHECK_LIMIT) return skipped_over_limit(children, suspects.size)
+
+	return await Promise.all(
+		children.map(async (child) =>
+			suspects.has(child.number) && child.repo === declared_repo
+				? await reread_child(child, read_blockers)
+				: child,
+		),
+	)
+}
+
+const epic_relation_recheck = { recheck_missing_relations, suspect_children, RECHECK_LIMIT }
+
+export type { BlockersReader }
+export { epic_relation_recheck }

package/scripts/epic/epic-report.ts

@@ -0,0 +1,200 @@
+import type { Classification } from './epic-classify'
+import { epic_graph, type EpicChild, type GraphAnomaly } from './epic-graph'
+
+// Turning a classification into the answer a caller acts on.
+//
+// The verdict is what `epicrun` (joshuafolkken/kit#861) branches on, so the three "nothing to run"
+// cases are kept apart: waiting, stopping, and being finished are different instructions
+// (joshuafolkken/kit#860).
+
+// What the caller should do next.
+type EpicVerdict = 'run' | 'wait' | 'stop' | 'complete' | 'error'
+
+interface RepoCandidates {
+	repo: string
+	children: ReadonlyArray<EpicChild>
+	// The local checkout a runner would work in, from joshuafolkken/kit#869's map. Absent when the
+	// repository is not checked out here — reported rather than cloned, since creating a working tree
+	// nobody asked for is not a step this command takes (joshuafolkken/kit#864).
+	path?: string
+}
+
+interface EpicNextResult {
+	verdict: EpicVerdict
+	// Runnable children bundled per repository. How many of one bundle may start at once is the
+	// repository's free-lane count, which `epic-lane-offer.ts` decides and this report does not know
+	// (joshuafolkken/kit#1491).
+	candidates: ReadonlyArray<RepoCandidates>
+	waiting: ReadonlyArray<EpicChild>
+	blocked_on_people: ReadonlyArray<EpicChild>
+	anomalies: ReadonlyArray<GraphAnomaly>
+}
+
+// Bundle by repository, repositories in name order, so a run is reproducible rather than dependent
+// on the order GitHub happened to list the repositories in. **The children are not re-ordered at
+// all** since joshuafolkken/kit#1583 — they keep the order the epic's task list gave them, which is
+// how an epic says which of its runnable children goes first; the reasoning is at `bundle_by_repo`
+// below.
+// The discovery map is keyed lowercase — GitHub resolves owner and repository names
+// case-insensitively — so the lookup lowercases too. Without it any capital in a repository name
+// printed "no local checkout" for a repository that is checked out (joshuafolkken/kit#864).
+//
+// `exactOptionalPropertyTypes` rejects `{ path: undefined }`, so the key is added only when there
+// is a path to put in it.
+function to_path_field(path: string | undefined): { path?: string } {
+	return path === undefined ? {} : { path }
+}
+
+function bundle_by_repo(
+	children: ReadonlyArray<EpicChild>,
+	paths: ReadonlyMap<string, string> = new Map(),
+): Array<RepoCandidates> {
+	const grouped = new Map<string, Array<EpicChild>>()
+
+	for (const child of children) {
+		const bucket = grouped.get(child.repo) ?? []
+
+		bucket.push(child)
+		grouped.set(child.repo, bucket)
+	}
+
+	const repos: Array<string> = []
+
+	for (const [repo] of grouped) repos.push(repo)
+
+	// **The children keep the order they arrived in, which is the order the epic's task list names
+	// them** (joshuafolkken/kit#1583). They used to be re-sorted by issue number here, on the premise
+	// that number order is split order — true only of an epic whose children were all filed in one
+	// split, and false of every epic that grows as work is found: there the number order is *filing*
+	// order, and an epic had no way at all to say which of its runnable children should go first.
+	//
+	// Nothing else had to change to make the body order authoritative: `epic-fetch.ts` →
+	// `fetch_children` already reads the task list in body order and `epic-classify.ts` fills
+	// `runnable` in that order, so this sort was the one step discarding it.
+	//
+	// **The repositories are still sorted by name**, which is a different question — that is grouping,
+	// not the order work is offered in.
+	return repos
+		.toSorted((left, right) => left.localeCompare(right))
+		.map((repo) => ({
+			repo,
+			children: grouped.get(repo) ?? [],
+			...to_path_field(paths.get(repo.toLowerCase())),
+		}))
+}
+
+// The verdict, in the order the decision has to be made. Waiting is checked before stopping for the
+// reason the categories exist: a run that stops while something is still resolving on its own gives
+// up on an epic that was going to finish.
+function decide_verdict(classification: Classification, anomalies: number): EpicVerdict {
+	if (anomalies > 0) return 'error'
+	if (classification.runnable.length > 0) return 'run'
+	if (classification.time.length > 0) return 'wait'
+	if (classification.human.length > 0) return 'stop'
+
+	return 'complete'
+}
+
+// An unusable graph offers nothing. Emptied here rather than left to each caller to check the
+// verdict first: a candidate list that is populated while the verdict says `error` is work somebody
+// will eventually start, and the anomaly exists to say that nothing may start.
+function build_result(
+	classification: Classification,
+	anomalies: ReadonlyArray<GraphAnomaly>,
+	paths: ReadonlyMap<string, string> = new Map(),
+): EpicNextResult {
+	const verdict = decide_verdict(classification, anomalies.length)
+
+	return {
+		verdict,
+		candidates: verdict === 'error' ? [] : bundle_by_repo(classification.runnable, paths),
+		waiting: classification.time,
+		blocked_on_people: classification.human,
+		anomalies,
+	}
+}
+
+// Every runnable child of one repository, in the order they would be offered — **the order the
+// epic's own task list names them** (joshuafolkken/kit#1583). It was lowest number first until then,
+// on the premise that number order is split order; an epic that gains children as work is found has
+// no such property, and the epic could not express a priority at all.
+//
+// **Priority is not dependency, and this is the difference.** A child high in the list that is stuck
+// never reaches `runnable`, so it is skipped rather than blocking the ones below it — which is what a
+// declared `blocked-by` chain would do instead, and why an order recorded as a chain stops the batch
+// the moment one child needs a person.
+//
+// The whole bundle rather than only its head, because the confirmation walk needs the rest of it: a
+// candidate whose relations listing disagrees with its summary is withheld and the next one is
+// confirmed in its place (joshuafolkken/kit#1121).
+function candidates_for_repo(result: EpicNextResult, repo: string): ReadonlyArray<EpicChild> {
+	return result.candidates.find((bundle) => bundle.repo === repo)?.children ?? []
+}
+
+// The repository, with the checkout a runner would use. A repository with no local checkout says so
+// rather than being omitted: it is still where the work belongs.
+function format_bundle_heading(bundle: RepoCandidates): string {
+	return `  ${bundle.repo}  ${bundle.path ?? '(no local checkout)'}`
+}
+
+// A child in another repository is written `owner/repo#N`, not a bare `#N` — a bare number resolves
+// against the reader's own repository and would linkify to the wrong issue there
+// (joshuafolkken/kit#2329). This reuses the one spelling `epic_graph.format_reference` already gives
+// every other read of a child, rather than a second one here.
+function format_child(child: EpicChild, current_repo: string): string {
+	return `    ${epic_graph.format_reference(child, current_repo)}`
+}
+
+function format_group(
+	label: string,
+	children: ReadonlyArray<EpicChild>,
+	current_repo: string,
+): Array<string> {
+	if (children.length === 0) return []
+
+	return [label, ...children.map((child) => format_child(child, current_repo))]
+}
+
+const VERDICT_LINES: Readonly<Record<EpicVerdict, string>> = {
+	run: 'Runnable children (each takes a free lane in its repository):',
+	wait: 'Nothing is runnable yet, but these resolve on their own — wait and ask again:',
+	stop: 'Nothing will resolve on its own. These need a person:',
+	complete: 'Every child is closed; the epic is complete.',
+	error: 'The dependency graph is unusable:',
+}
+
+// The report. Every open child appears exactly once, so a caller can see that nothing was dropped.
+function format_result(result: EpicNextResult, current_repo: string): string {
+	if (result.verdict === 'error') {
+		return [VERDICT_LINES.error, ...result.anomalies.map((anomaly) => anomaly.message)].join('\n')
+	}
+
+	const lines = [VERDICT_LINES[result.verdict]]
+
+	for (const bundle of result.candidates) {
+		lines.push(
+			format_bundle_heading(bundle),
+			...bundle.children.map((child) => format_child(child, current_repo)),
+		)
+	}
+
+	lines.push(
+		...format_group('  Waiting on time:', result.waiting, current_repo),
+		...format_group('  Waiting on a person:', result.blocked_on_people, current_repo),
+	)
+
+	return lines.join('\n')
+}
+
+const epic_report = {
+	bundle_by_repo,
+	format_bundle_heading,
+	decide_verdict,
+	build_result,
+	candidates_for_repo,
+	format_result,
+	VERDICT_LINES,
+}
+
+export type { EpicNextResult, EpicVerdict, RepoCandidates }
+export { epic_report }

package/scripts/gate/core-budget.ts

@@ -0,0 +1,292 @@
+import { randomUUID } from 'node:crypto'
+import { readdirSync } from 'node:fs'
+import { availableParallelism } from 'node:os'
+import path from 'node:path'
+import { PLATFORM_TEMP_ROOT } from '#scripts/josh/platform-temporary'
+import { process_identity } from '#scripts/josh/process-identity'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { z } from 'zod'
+
+// A machine-wide weighted core budget with admission control (joshuafolkken/kit#2351).
+//
+// **The gate's CPU budget used to be decided once, at the gate's start, and never revisited.**
+// `announce_gate_plan` counted the unit runs alive the instant it began and sized itself against that
+// one reading — so the common case (nothing else in a gate yet) had every gate conclude it was alone
+// and reserve the whole machine, and only a gate that *started* later deferred. Three overlapping gates
+// therefore demanded thirty cores of an eleven-core machine, which is the "usually fine, occasionally
+// saturates" this module removes.
+//
+// **The fix is admission rather than recomputation.** A heavy step declares the cores it needs, claims
+// a place in a machine-wide ledger, and waits while the ledger is full — so the peak cannot exceed the
+// budget by construction, and the asymmetry ("whoever started first took everything") disappears
+// because a place is claimed in claim order rather than seized at start. Waiting is what replaces the
+// recomputation `unit-worker-share.ts` did: a step that could not fit does not shrink, it defers.
+//
+// **A solo run is bit-for-bit unchanged, and that is arithmetic rather than a branch.** The gate's
+// weights are its `reserved_cores` (the static checks) and its `unit_worker_cap` (the unit suite), and
+// `reserved(2 + 1 + 1) + unit_cap(cores - 4)` is exactly `cores` — so a single gate's four claims sum
+// to the whole budget and every one is admitted the instant it is made, with no poll and no wait. Under
+// concurrency the same weights sum past the budget and the ledger is what holds the machine down.
+//
+// **Liveness is `process_identity`'s, reused rather than re-invented** (joshuafolkken/kit#1245). A run
+// killed outright leaves its marker behind, and a ledger that trusted the file alone would fill forever
+// and admit nothing. The pid-and-start-time pair a marker carries is the same identity the unit-run
+// marker keeps, swept on read the moment its process is gone.
+
+const RESERVED_PREFIX = 'josh-core-reserved-'
+const RESERVED_SUFFIX = '.json'
+// How often a waiting reservation re-reads the ledger: short enough that a freed place is taken up
+// promptly, long enough that the wait itself burns no measurable CPU.
+const POLL_INTERVAL_MS = 50
+// The longest a reservation waits before it is admitted at minimum width regardless — a heavy step must
+// make progress even if the budget never clears, so a leaked or wedged sibling cannot stall the machine
+// for good. Two minutes is well past a unit suite's worst measured time under six-way load.
+const WAIT_CAP_MS = 120_000
+// The head of the ledger is always admitted, so the smallest budget worth planning against is one core.
+const MIN_BUDGET = 1
+
+const reservation_schema = z.object({
+	pid: z.number(),
+	process_start: z.string().optional(),
+	weight: z.number(),
+	claimed_at: z.number(),
+})
+
+type Reservation = z.infer<typeof reservation_schema>
+
+interface LiveReservation {
+	// The marker's filename, which is its identity in the ledger and the tiebreak when two reservations
+	// share a claim time.
+	key: string
+	reservation: Reservation
+}
+
+interface ReserveOptions {
+	budget?: number
+	wait_cap_ms?: number
+	poll_interval_ms?: number
+	directory?: string
+	now?: () => number
+	sleep?: (ms: number) => Promise<void>
+}
+
+interface Handle {
+	target: string
+}
+
+function marker_name(key: string): string {
+	return `${RESERVED_PREFIX}${key}${RESERVED_SUFFIX}`
+}
+
+// **"Cannot tell" counts as live**, the same direction `unit-worker-share.ts` takes: being wrong that
+// way costs a reservation a slower admission, while the other way admits past a run that is still there.
+function is_running(reservation: Reservation): boolean {
+	return process_identity.is_same_process(reservation.pid, reservation.process_start) !== false
+}
+
+function read_reservation(source: string): Reservation | undefined {
+	const raw = stamp_file.read_stamp_text(source)
+
+	if (raw === undefined) return undefined
+
+	try {
+		const parsed = reservation_schema.safeParse(JSON.parse(raw))
+
+		return parsed.success ? parsed.data : undefined
+	} catch {
+		return undefined
+	}
+}
+
+// **A dead marker is removed, not merely skipped** — otherwise a reissued pid turns a leaked place into
+// a phantom that fills the budget for good. The unlink never throws: a marker this account may not
+// remove is left alone, exactly as `unit-worker-share.ts` leaves it.
+function sweep_marker(source: string): void {
+	try {
+		stamp_file.remove_stamp(source)
+	} catch {
+		/* not ours to remove; counting it out is the whole requirement */
+	}
+}
+
+function live_reservation(source: string): Reservation | undefined {
+	const reservation = read_reservation(source)
+
+	if (reservation === undefined) return undefined
+	if (is_running(reservation)) return reservation
+
+	sweep_marker(source)
+
+	return undefined
+}
+
+// An unreadable temp directory answers "no other reservation", the direction that admits rather than
+// stalls a run on a guess.
+function marker_files(directory: string): Array<string> {
+	try {
+		return readdirSync(directory).filter((name) => name.startsWith(RESERVED_PREFIX))
+	} catch {
+		return []
+	}
+}
+
+function live_reservations(directory: string = PLATFORM_TEMP_ROOT): Array<LiveReservation> {
+	return marker_files(directory).flatMap((name) => {
+		const reservation = live_reservation(path.join(directory, name))
+
+		return reservation === undefined ? [] : [{ key: name, reservation }]
+	})
+}
+
+// Claim order, with the filename as the tiebreak so every reader agrees on the same ledger order
+// however the wall clock rounded two near-simultaneous claims.
+function compare_claim(left: LiveReservation, right: LiveReservation): number {
+	const by_time = left.reservation.claimed_at - right.reservation.claimed_at
+
+	return by_time === 0 ? left.key.localeCompare(right.key) : by_time
+}
+
+// **The keys admitted under FIFO.** The head always runs — a single check heavier than the whole
+// machine must not wait for room that will never come — and each later reservation runs while the
+// cumulative weight ahead of it still fits the budget. The first that does not fit stops the walk, so a
+// place is never jumped: admission is in claim order, which is what removes the start-time asymmetry.
+function admitted_keys(reservations: ReadonlyArray<LiveReservation>, budget: number): Set<string> {
+	const admitted = new Set<string>()
+	let cumulative = 0
+
+	for (const [index, entry] of reservations.toSorted(compare_claim).entries()) {
+		cumulative += entry.reservation.weight
+
+		if (index !== 0 && cumulative > budget) break
+
+		admitted.add(entry.key)
+	}
+
+	return admitted
+}
+
+function is_admitted(
+	key: string,
+	reservations: ReadonlyArray<LiveReservation>,
+	budget: number,
+): boolean {
+	return admitted_keys(reservations, budget).has(key)
+}
+
+// The weight actually running at once — what the reproduction test asserts stays within the budget.
+function admitted_load(reservations: ReadonlyArray<LiveReservation>, budget: number): number {
+	const admitted = admitted_keys(reservations, budget)
+
+	return reservations
+		.filter((entry) => admitted.has(entry.key))
+		.reduce((total, entry) => total + entry.reservation.weight, 0)
+}
+
+// `Math.max` propagates `NaN` rather than clamping it, so an unusable budget is caught before it could
+// make every comparison false and admit everything — the hole `gate-plan.ts` closes for the same reason.
+function normalize_budget(budget: number): number {
+	return Number.isFinite(budget) ? Math.max(MIN_BUDGET, Math.floor(budget)) : MIN_BUDGET
+}
+
+async function default_sleep(ms: number): Promise<void> {
+	await new Promise<void>((resolve) => {
+		setTimeout(resolve, ms)
+	})
+}
+
+function write_reservation(target: string, weight: number, claimed_at: number): void {
+	stamp_file.write_stamp(target, { ...process_identity.own_fields(), weight, claimed_at })
+}
+
+// The clock and cadence a wait runs on, resolved apart from the ledger fields so `reserve` stays under
+// the complexity limit — each default is a branch, and six in one function is past it.
+interface TimingConfig {
+	now: () => number
+	sleep: (ms: number) => Promise<void>
+	poll_interval_ms: number
+}
+
+interface WaitContext extends TimingConfig {
+	key: string
+	directory: string
+	budget: number
+	deadline: number
+}
+
+function resolve_timing(options: ReserveOptions): TimingConfig {
+	return {
+		now: options.now ?? Date.now,
+		sleep: options.sleep ?? default_sleep,
+		poll_interval_ms: options.poll_interval_ms ?? POLL_INTERVAL_MS,
+	}
+}
+
+// Poll the ledger until this reservation is admitted, or until the wait cap admits it at minimum width.
+// A solo run is admitted on the first read — its own claim is the ledger's head — so the loop body never
+// runs and the wait costs nothing.
+async function await_admission(context: WaitContext): Promise<void> {
+	while (!is_admitted(context.key, live_reservations(context.directory), context.budget)) {
+		if (context.now() >= context.deadline) return
+
+		await context.sleep(context.poll_interval_ms)
+	}
+}
+
+async function reserve(weight: number, options: ReserveOptions = {}): Promise<Handle> {
+	const timing = resolve_timing(options)
+	const directory = options.directory ?? PLATFORM_TEMP_ROOT
+	const budget = normalize_budget(options.budget ?? availableParallelism())
+	const claimed_at = timing.now()
+	const name = marker_name(randomUUID())
+	const target = path.join(directory, name)
+
+	write_reservation(target, weight, claimed_at)
+	await await_admission({
+		...timing,
+		key: name,
+		directory,
+		budget,
+		deadline: claimed_at + (options.wait_cap_ms ?? WAIT_CAP_MS),
+	})
+
+	return { target }
+}
+
+function release(handle: Handle): void {
+	sweep_marker(handle.target)
+}
+
+// The whole reservation lifetime around a step: claim a place, wait for admission, run, and free the
+// place on any exit. `finally`, so a step that threw still releases its cores.
+async function with_core_reservation<T>(
+	weight: number,
+	run: () => Promise<T>,
+	options: ReserveOptions = {},
+): Promise<T> {
+	const handle = await reserve(weight, options)
+
+	try {
+		return await run()
+	} finally {
+		release(handle)
+	}
+}
+
+const core_budget = {
+	MIN_BUDGET,
+	POLL_INTERVAL_MS,
+	RESERVED_PREFIX,
+	WAIT_CAP_MS,
+	admitted_keys,
+	admitted_load,
+	is_admitted,
+	is_running,
+	live_reservations,
+	read_reservation,
+	release,
+	reserve,
+	with_core_reservation,
+}
+
+export type { LiveReservation, Reservation, ReserveOptions }
+export { core_budget }