@joshuafolkken/kit 1.872.0

package/scripts/epic/epic-bundle-gaps.ts

@@ -0,0 +1,86 @@
+import { cutoff_cause, type ScanCutoff } from '#scripts/git/listing-cutoff'
+
+// What `epic:bundle` could not see, said in the `⚠ … cap` shape joshuafolkken/kit#1033 settled on
+// for `epic:audit`. Split out of `epic-bundle-cli.ts` because the wording carries more explanation
+// than the command it warns from (joshuafolkken/kit#1067).
+//
+// **Two listings, and two cuts each.** The listing decides *what* is hidden — a backlog issue, or
+// the epic that tracks one — and the cut decides *which number to cite*, because a reader who wants
+// the answer widened reaches for a different knob in each case: the caller's `limit`, which this
+// command sets, or the paging's page ceiling, which it does not. The dispatch between the two is
+// `cutoff_cause`, shared with every other caller that reports one.
+
+// The backlog scan's gap: a related issue past the cut is reported as "no existing issue shares a
+// reference" — an assertion about data that was never loaded.
+function backlog_gap(cutoff: ScanCutoff, limit: number): string | undefined {
+	const cause = cutoff_cause(cutoff, `hit its ${String(limit)}-issue cap`)
+	if (cause === undefined) return undefined
+
+	return `⚠ The backlog listing ${cause}; older issues were not considered.`
+}
+
+// Named separately from the backlog's. What this one hides is *which epic tracks a candidate*, so
+// `Nothing to bundle.` under it may mean "the epic was past the cut" rather than "no epic tracks
+// it" — and acting on the second reading creates the duplicate epic (joshuafolkken/kit#950).
+function epic_gap(cutoff: ScanCutoff, limit: number): string | undefined {
+	const cause = cutoff_cause(cutoff, `hit its ${String(limit)}-epic cap`)
+	if (cause === undefined) return undefined
+
+	return `⚠ The epic listing ${cause}; an epic past it was not considered.`
+}
+
+// Whether "this issue belongs to no epic" is a finding or merely an absence.
+//
+// Every verdict that *places* the subject in an epic rests on that negative — `create_epic` asserts
+// it about the candidates too, but `add_to_epic` and `ask` assert it about the subject alone — and
+// the assertion is only as good as the epic listing it was read from: an epic past the cut tracks its
+// children invisibly, so each of them reads as tracked by nothing. Acted on as Tier A, that absence
+// puts a **second** epic over an issue one already tracks — the state `fullrun.md` forbids, because
+// the auto-close then has two task lists to disagree about and `epic:next` answers from two graphs
+// (joshuafolkken/kit#943).
+//
+// A membership that *was* found is untouched, and that is the whole of what survives a cut: `none`
+// reporting `#E already tracks this issue` read the epic it names, and more epics past the cut cannot
+// unseat it.
+//
+// The cut is the whole condition, and deliberately so. An epic the listing answered without a body
+// would hide its children the same way, but it cannot arrive: the listing mapping coerces a REST
+// `null` body to `''` before this module's caller ever parses one (`git-gh-issue-rest.ts`,
+// `to_gh_field_value`), so a gate arm for it would be code no input can reach
+// (joshuafolkken/kit#1697).
+//
+// The cutoff is optional because the fetched backlog carries it that way: a listing nothing capped
+// records no cut at all, which is the same answer as `none`. Defaulted here rather than at each call
+// site, so a caller holding the optional field cannot forget the coercion (joshuafolkken/kit#1703).
+function is_membership_established(cutoff: ScanCutoff = 'none'): boolean {
+	return cutoff === 'none'
+}
+
+// Not a placement, and not `Nothing to bundle.` either: the command has an answer about the
+// candidates and no answer about which epics they and the subject sit in. The headline says which of
+// the two, because a run reads the first line and acts on it.
+const UNCONFIRMED_MEMBERSHIP_LINE =
+	'Could not confirm which epic already tracks these — do not place this issue in one.'
+
+const UNCONFIRMED_MEMBERSHIP_REASON =
+	'the epics were not read in full, so an epic already tracking one of these may never have been seen'
+
+// The whole verdict for that case. The children and the declared order are deliberately absent: they
+// are the recipe for the placement this line says not to make.
+function unconfirmed_membership(related: string): Array<string> {
+	return [
+		UNCONFIRMED_MEMBERSHIP_LINE,
+		`  ${UNCONFIRMED_MEMBERSHIP_REASON}`,
+		`  Related: ${related}`,
+	]
+}
+
+const epic_bundle_gaps = {
+	backlog_gap,
+	epic_gap,
+	is_membership_established,
+	UNCONFIRMED_MEMBERSHIP_LINE,
+	unconfirmed_membership,
+}
+
+export { epic_bundle_gaps }

package/scripts/epic/epic-bundle-referenced.ts

@@ -0,0 +1,195 @@
+import { git_gh_command } from '#scripts/git/git-gh-command'
+import { bounded_pool } from '#scripts/lib/bounded-pool'
+import { epic_audit_logic } from './epic-audit'
+import type { BacklogIssue } from './epic-bundle'
+import { epic_issue, type EpicIssue } from './epic-issue'
+
+// Candidates the open backlog cannot show, read from the subject's own prose.
+//
+// `epic:bundle` searched open issues only, which left a window of minutes in which it could answer
+// correctly: a follow-up issue names its parent, and the parent's pull request merges right after —
+// on joshuafolkken/kit#943 the gap between filing and the parent closing was about three minutes.
+// Past it the command reported `Nothing to bundle.` with exit 0, asserting there was no relation
+// rather than that it had not looked (joshuafolkken/kit#947).
+//
+// The numbers a body names are information the command already holds; the open listing was never
+// what supplied them. Only the *reading* of those issues needs a request, and this module decides
+// which ones are worth one and which of the answers count.
+
+// One read each, so the count is what bounds the cost. Chosen an order of magnitude above the
+// references a real issue body carries — kit#946's body names five — so the cap is a runaway guard
+// rather than something an ordinary issue reaches. A body naming more than this is prose about the
+// backlog, not an issue with twenty prerequisites.
+//
+// Since joshuafolkken/kit#1024 a read is `gh api`, and one reference costs one REST request in the
+// common case. Three cases cost two. The `dependencies/blocked_by` endpoint is asked unless the
+// issue's own dependency summary reports exactly zero blockers, so an issue that declares one pays
+// for it. So does a pull request, which the issue endpoint serves as readily as an issue and which
+// carries no dependency summary at all — an absent summary is not a zero, so the skip that settles
+// the common case cannot apply to one. That second request is a read rather than a failure: the
+// endpoint answers a pull request with an empty array (measured against a merged one), so the
+// reference is read normally and then dropped by the `/pull/` check below. And a read that failed
+// pays for the status probe `issue_view_json_classified` spends telling a number that resolves to
+// nothing from a read that could not be made.
+const REFERENCED_LOOKUP_LIMIT = 20
+
+// The numbers the subject's body names that the open listing did not already provide.
+//
+// Deliberately one-way: the reverse — a closed issue whose body names the subject — would mean
+// scanning every closed issue in the repository. It is not needed, because a follow-up issue naming
+// its parent is what the filing procedure itself requires (`prompts/review.md` → "Review round cap").
+interface ReferencedLookups {
+	numbers: Array<number>
+	// The references the cap left unread. Named rather than dropped: silently truncating puts the
+	// command back to asserting there was no relation when it had merely stopped looking — the same
+	// failure the whole module removes, reintroduced by its own guard.
+	dropped: Array<number>
+}
+
+function referenced_lookups(subject: BacklogIssue, known: ReadonlySet<number>): ReferencedLookups {
+	const candidates = epic_audit_logic
+		.parse_references(subject.body, subject.repo)
+		.filter((number) => number !== subject.number && !known.has(number))
+
+	return {
+		numbers: candidates.slice(0, REFERENCED_LOOKUP_LIMIT),
+		dropped: candidates.slice(REFERENCED_LOOKUP_LIMIT),
+	}
+}
+
+interface ReferencedContext {
+	repo: string
+	// Which epic tracks each issue, from the open epics' task lists.
+	epics: ReadonlyMap<number, number>
+	// The open epics themselves, so an epic never enters its own children's candidate pool.
+	epic_numbers: ReadonlySet<number>
+}
+
+function to_backlog_issue(issue: EpicIssue, context: ReferencedContext): BacklogIssue {
+	const epic = context.epics.get(issue.number)
+
+	return {
+		number: issue.number,
+		repo: context.repo,
+		body: issue.body,
+		blocked_by: epic_issue.blocker_references_of(issue, context.repo),
+		is_epic: context.epic_numbers.has(issue.number),
+		...(epic !== undefined && { epic }),
+	}
+}
+
+// Whether a referenced issue read this way belongs in the candidate pool.
+//
+// An open one always does — it may simply have been past the listing's cap. A closed one counts only
+// when an open epic already tracks it, and that restriction is the point of the whole read: the
+// answer worth recovering is `add_to_epic <that epic>`. `create_epic` over a closed issue would
+// build an epic whose other child is already finished — nothing for a run to execute, and an epic
+// that reads as half-done from the moment it is created.
+function is_usable_candidate(issue: BacklogIssue, read: EpicIssue): boolean {
+	// The issue endpoint answers for a pull request too, and a body citing "the fix landed in #952"
+	// is ordinary prose. Without this, a merged PR reads as an open issue in no epic and the command
+	// proposes creating an epic with a pull request among its children (joshuafolkken/kit#947).
+	if (issue.is_epic === true || epic_issue.is_pull_request(read)) return false
+
+	return epic_issue.is_open(read.state) || issue.epic !== undefined
+}
+
+// How one referenced number came back. `missing` is GitHub resolving it to nothing — a typo, or a
+// number belonging to another repository quoted in prose — which is an answer, not a gap: there is
+// no candidate and nothing was lost. `unreadable` is the gap, and it is the only one reported
+// (joshuafolkken/kit#957).
+interface ReferencedRead {
+	number: number
+	result: EpicIssue | 'missing' | 'unreadable'
+}
+
+function is_failed_read(result: ReferencedRead['result']): result is 'missing' | 'unreadable' {
+	return typeof result === 'string'
+}
+
+interface ReferencedResult {
+	// The ones that qualify, shaped like any other backlog issue so the decision logic is unchanged.
+	issues: Array<BacklogIssue>
+	// The ones whose read failed, and the ones the cap never reached. Both are gaps rather than
+	// answers: folded into "no relation found" they become the confident wrong verdict this whole
+	// module exists to remove. A number that resolves to nothing is **not** here — reporting it as a
+	// gap stops an unattended run over a reference that never existed (joshuafolkken/kit#957).
+	unreadable: Array<number>
+}
+
+function usable_candidates(
+	reads: ReadonlyArray<ReferencedRead>,
+	context: ReferencedContext,
+): Array<BacklogIssue> {
+	return reads.flatMap((read) => {
+		if (is_failed_read(read.result)) return []
+		const candidate = to_backlog_issue(read.result, context)
+
+		return is_usable_candidate(candidate, read.result) ? [candidate] : []
+	})
+}
+
+function collect_referenced(
+	reads: ReadonlyArray<ReferencedRead>,
+	context: ReferencedContext,
+): ReferencedResult {
+	return {
+		issues: usable_candidates(reads, context),
+		unreadable: reads.filter((read) => read.result === 'unreadable').map((read) => read.number),
+	}
+}
+
+// One `gh api` read per reference, a few at a time. Bounded for the same reason the relation reads
+// are: spawning every request at once is what turns a rate limit into a wrong answer, because a
+// refused read arrives as an absence rather than as an error.
+const LOOKUP_CONCURRENCY = 8
+
+// A read that came back shaped wrong counts as unreadable, not as missing: the number resolved to
+// something, so the gap is in what arrived rather than in whether there was anything to arrive.
+async function read_one(number: number): Promise<ReferencedRead> {
+	const read = await git_gh_command.issue_get_plan_fields_classified(String(number))
+
+	if (read.kind !== 'read') return { number, result: read.kind }
+
+	return { number, result: epic_issue.parse_epic_issue(read.json) ?? 'unreadable' }
+}
+
+// The pool is shared with the eval suite rather than spelled out again here: this was written as
+// waves — slice, `Promise.all`, next slice — which holds every finished read's slot until the whole
+// slice returns (joshuafolkken/kit#1144).
+async function fetch_referenced(numbers: ReadonlyArray<number>): Promise<Array<ReferencedRead>> {
+	return await bounded_pool.bounded_map(
+		numbers,
+		LOOKUP_CONCURRENCY,
+		async (number) => await read_one(number),
+	)
+}
+
+// What the subject's body names, read and filtered. `undefined` when there was nothing new to read,
+// which lets the caller keep the backlog it already has rather than rebuilding an identical one.
+async function referenced_candidates(
+	subject: BacklogIssue,
+	known: ReadonlySet<number>,
+	context: ReferencedContext,
+): Promise<ReferencedResult | undefined> {
+	const { numbers, dropped } = referenced_lookups(subject, known)
+	if (numbers.length === 0 && dropped.length === 0) return undefined
+	const found = collect_referenced(await fetch_referenced(numbers), context)
+
+	return { ...found, unreadable: [...found.unreadable, ...dropped] }
+}
+
+const epic_bundle_referenced = {
+	REFERENCED_LOOKUP_LIMIT,
+	LOOKUP_CONCURRENCY,
+	referenced_lookups,
+	is_failed_read,
+	to_backlog_issue,
+	is_usable_candidate,
+	collect_referenced,
+	fetch_referenced,
+	referenced_candidates,
+}
+
+export type { ReferencedContext, ReferencedLookups, ReferencedRead, ReferencedResult }
+export { epic_bundle_referenced }

package/scripts/epic/epic-bundle.ts

@@ -0,0 +1,309 @@
+import type { DependencyLink } from '#scripts/git/git-epic-parse'
+import type { IssueReference } from '#scripts/git/git-epic-reference'
+import { epic_audit_logic } from './epic-audit'
+import { epic_graph } from './epic-graph'
+
+// Bundling a newly filed issue with the ones it turns out to be related to.
+//
+// "Two or more always means an epic" already holds when one request is split on the spot. It does
+// not reach the other way in: two issues filed days apart that turn out to be the front and back of
+// one job are executed separately, in whatever order, with the reasoning recorded nowhere
+// (joshuafolkken/kit#873).
+//
+// The candidate search reads issue references out of prose — the same reading joshuafolkken/kit#870
+// does inside one epic. That analysis is imported rather than written a second time; the only
+// difference is what it is pointed at.
+
+// An open issue as the search sees it.
+interface BacklogIssue {
+	number: number
+	repo: string
+	body: string
+	// Optional because nothing in this module reads it: the strong signals below are references and
+	// recorded dependencies, and a title resemblance is deliberately not one of them. It rides on the
+	// same listing for `issue:scout`, whose duplicate search is the one thing that does compare titles
+	// (joshuafolkken/kit#1252), and is absent on an issue read one at a time by reference.
+	title?: string
+	// The epic tracking it, when one does. An issue belongs to at most one epic, because that is what
+	// a task list can express.
+	epic?: number
+	// Whether this issue *is* an epic. An epic is a container, not a sibling: every child names it as
+	// its parent, so without this every child would find its own epic as a candidate and be told to
+	// bundle with it (joshuafolkken/kit#873, found by running the command on a real backlog).
+	is_epic?: boolean
+	// Repository-qualified, not bare numbers (joshuafolkken/kit#1130). Issue numbers are unique per
+	// repository, so a blocker read as `40` alone matched any candidate numbered 40 — including one in
+	// a different repository entirely. That produced a bundle nobody's data supported, and, through
+	// `bundle_dependency_links`, a `blocked-by` relation recorded onto the wrong issue: a write, not
+	// only a misreading.
+	blocked_by: ReadonlyArray<IssueReference>
+}
+
+// What to do with the candidates found. Bundling is reversible — an epic is editable and a child can
+// be removed — so it needs no confirmation. Merging epics is not, so it does.
+type BundleAction = 'add_to_epic' | 'create_epic' | 'ask' | 'none'
+
+interface BundleDecision {
+	action: BundleAction
+	// The epic to add to, for `add_to_epic`.
+	epic?: number
+	// The epics the candidates are spread across, for `ask`.
+	epics: ReadonlyArray<number>
+	candidates: ReadonlyArray<number>
+	reason: string
+}
+
+// Whether `from`'s body names `to`. One direction of the citation test, because which direction it
+// was is what `epic-bundle-evidence.ts` reports — and the read is single-sourced here rather than
+// written a second time there, so the candidate search and the evidence beside it cannot drift apart
+// (joshuafolkken/kit#1737).
+function names_in_body(from: BacklogIssue, to: BacklogIssue): boolean {
+	return epic_audit_logic.parse_references(from.body, from.repo).includes(to.number)
+}
+
+// Whether two issues cite each other, in either direction. A one-way citation is enough: the point
+// is that somebody wrote one issue while thinking about the other.
+function has_mutual_reference(subject: BacklogIssue, other: BacklogIssue): boolean {
+	return names_in_body(subject, other) || names_in_body(other, subject)
+}
+
+// Whether `blocked` names `blocker` in its recorded relations. Compared by identity — repository and
+// number — through the same key the epic graph uses, rather than a second spelling of the comparison.
+function names_as_blocker(blocked: BacklogIssue, blocker: BacklogIssue): boolean {
+	const wanted = epic_graph.key_of(blocker)
+
+	return blocked.blocked_by.some((recorded) => epic_graph.key_of(recorded) === wanted)
+}
+
+// Whether a dependency is already recorded between the two, in either direction.
+function has_recorded_dependency(subject: BacklogIssue, other: BacklogIssue): boolean {
+	return names_as_blocker(subject, other) || names_as_blocker(other, subject)
+}
+
+// A strong signal, and only a strong signal.
+//
+// Similar titles are deliberately not one. "Related" expands without limit, and a threshold is what
+// keeps an unrelated issue out of the bundle; a wording resemblance may inform the reader's
+// judgement, but it may not be what decides.
+function is_strong_signal(subject: BacklogIssue, other: BacklogIssue): boolean {
+	// Neither side. Asked about an epic, the one-sided check found every one of its children through
+	// their own `parent: #N` line and proposed bundling a container with its contents.
+	if (subject.number === other.number || subject.is_epic === true || other.is_epic === true) {
+		return false
+	}
+
+	return has_mutual_reference(subject, other) || has_recorded_dependency(subject, other)
+}
+
+function find_candidates(
+	subject: BacklogIssue,
+	backlog: ReadonlyArray<BacklogIssue>,
+): Array<BacklogIssue> {
+	return backlog.filter((other) => is_strong_signal(subject, other))
+}
+
+// The distinct epics the candidates already belong to.
+function candidate_epics(candidates: ReadonlyArray<BacklogIssue>): Array<number> {
+	const epics = new Set<number>()
+
+	for (const candidate of candidates) {
+		if (candidate.epic !== undefined) epics.add(candidate.epic)
+	}
+
+	return [...epics].toSorted((left, right) => left - right)
+}
+
+const NO_SIGNAL_REASON = 'no existing issue shares a reference or a dependency with this one'
+
+// Names the epic, rather than only reporting that one exists. The number is what the caller does
+// something with: the prerequisite procedure inserts into that epic instead of creating a second one,
+// and an issue tracked by two epics gives the auto-close two task lists to disagree about
+// (joshuafolkken/kit#943). The decision already carried the number; only this sentence dropped it.
+function already_tracked_reason(epic: number): string {
+	return `#${String(epic)} already tracks this issue`
+}
+
+const SPREAD_REASON =
+	'the related issues already belong to different epics; pick the one this issue belongs in and record why'
+
+function to_numbers(candidates: ReadonlyArray<BacklogIssue>): Array<number> {
+	return candidates.map((candidate) => candidate.number)
+}
+
+function create_decision(subject: BacklogIssue, numbers: ReadonlyArray<number>): BundleDecision {
+	const count = String(numbers.length)
+	const reason = `#${String(subject.number)} and ${count} related issue(s) belong to no epic`
+
+	return { action: 'create_epic', epics: [], candidates: numbers, reason }
+}
+
+// Which epic each issue is itself tracked by. An epic is a row of the backlog like any other, so a
+// nested one carries its own parent here and no second read is needed (joshuafolkken/kit#1079).
+// The repository filter is defensive: every caller stamps one repository onto the whole listing
+// today, and the filter is what keeps a bare epic number naming the subject's repository if one ever
+// assembles two.
+function epic_parents(
+	backlog: ReadonlyArray<BacklogIssue>,
+	repo: string,
+): ReadonlyMap<number, number> {
+	const parents = new Map<number, number>()
+
+	for (const issue of backlog) {
+		if (issue.repo === repo && issue.epic !== undefined) parents.set(issue.number, issue.epic)
+	}
+
+	return parents
+}
+
+// Every epic above this one. `seen` bounds the walk, so a body declaring a cycle cannot loop here —
+// and an epic that lies on one ends up in its own set, which is how `is_cyclic` finds it.
+function ancestors_of(epic: number, parents: ReadonlyMap<number, number>): Set<number> {
+	const seen = new Set<number>()
+	let current = parents.get(epic)
+
+	while (current !== undefined && !seen.has(current)) {
+		seen.add(current)
+		current = parents.get(current)
+	}
+
+	return seen
+}
+
+// An epic reachable from itself sits on a cycle, and a cycle has no innermost member. Narrowing one
+// would drop whichever epic the walk happened to cover: two epics naming each other cover each
+// other, so a third unrelated epic beside them would be left as the sole survivor and the issue
+// placed there with nothing asked.
+function is_cyclic(
+	epics: ReadonlyArray<number>,
+	above: ReadonlyArray<ReadonlySet<number>>,
+): boolean {
+	return epics.some((epic, index) => above[index]?.has(epic) === true)
+}
+
+// Nested epics are not two peers to choose between: the parent already contains the child, so an
+// issue related to both belongs in the child and no merge is on the table. Asking anyway is the
+// false positive joshuafolkken/kit#1079 recorded three times, one of which stopped a whole batch.
+function narrow_to_innermost(
+	epics: ReadonlyArray<number>,
+	parents: ReadonlyMap<number, number>,
+): Array<number> {
+	const above = epics.map((epic) => ancestors_of(epic, parents))
+	// Report the spread unchanged and let a person decide, rather than pick one arbitrarily.
+	if (is_cyclic(epics, above)) return [...epics]
+	const covered = new Set(above.flatMap((ancestors) => [...ancestors]))
+
+	return epics.filter((epic) => !covered.has(epic))
+}
+
+// Says which epics were dropped as parents, so a placement that skipped an epic the candidates name
+// is legible without re-deriving the nesting. The count is enough to decide the wording: a cycle is
+// reported without narrowing above, so a lone survivor of two or more means the graph was acyclic,
+// and there every dropped epic is a transitive parent of the one left.
+function tracks_reason(epic: number, involved: ReadonlyArray<number>): string {
+	const tracks = `#${String(epic)} already tracks a related issue`
+	if (involved.length === 1) return tracks
+
+	return `${tracks}; the other epics the candidates sit in are its own parents`
+}
+
+// Which of the three the candidates call for, once there is at least one.
+function decide_with_candidates(
+	subject: BacklogIssue,
+	candidates: ReadonlyArray<BacklogIssue>,
+	parents: ReadonlyMap<number, number>,
+): BundleDecision {
+	const numbers = to_numbers(candidates)
+	const involved = candidate_epics(candidates)
+	const epics = narrow_to_innermost(involved, parents)
+	if (epics.length > 1) return { action: 'ask', epics, candidates: numbers, reason: SPREAD_REASON }
+	const [epic] = epics
+	if (epic === undefined) return create_decision(subject, numbers)
+
+	return {
+		action: 'add_to_epic',
+		epic,
+		epics: [epic],
+		candidates: numbers,
+		reason: tracks_reason(epic, involved),
+	}
+}
+
+// What to do about the candidates. An epic is created only when the subject plus at least one
+// unbundled candidate make two — an epic tracking one child is not a batch.
+function decide_bundle(
+	subject: BacklogIssue,
+	backlog: ReadonlyArray<BacklogIssue>,
+): BundleDecision {
+	// An issue an epic already tracks has nothing to bundle: it belongs to at most one, and moving it
+	// between epics is not what this rule is for.
+	if (subject.epic !== undefined) {
+		return {
+			action: 'none',
+			epics: [subject.epic],
+			candidates: [],
+			reason: already_tracked_reason(subject.epic),
+		}
+	}
+
+	const candidates = find_candidates(subject, backlog)
+
+	if (candidates.length === 0) {
+		return { action: 'none', epics: [], candidates: [], reason: NO_SIGNAL_REASON }
+	}
+
+	return decide_with_candidates(subject, candidates, epic_parents(backlog, subject.repo))
+}
+
+// The dependency links a bundle should record, from what the candidates already declare. Bundling
+// without the order records the batch and loses the reason it is a batch — an issue that must follow
+// another is exactly the case this exists to catch (joshuafolkken/kit#873).
+//
+// Only relations already declared are carried over; an order nobody stated is not invented here.
+function bundle_dependency_links(
+	subject: BacklogIssue,
+	candidates: ReadonlyArray<BacklogIssue>,
+): Array<DependencyLink> {
+	const members = [subject, ...candidates]
+	const keys = new Set(members.map((member) => epic_graph.key_of(member)))
+	// The bundle's own repository, which is what a bare declared number names. Taken from the subject
+	// rather than from each member: comparing a blocker against its *own* member's repository would
+	// let two members elsewhere emit a link between them, and the epic body would then resolve those
+	// bare numbers against this repository — a different pair of issues. `epic_graph.child_links`
+	// guards the identical case the identical way (joshuafolkken/kit#1130).
+	const declared_repo = subject.repo
+
+	return members
+		.filter((member) => member.repo === declared_repo)
+		.flatMap((member) =>
+			member.blocked_by
+				.filter((blocker) => blocker.repo === declared_repo && keys.has(epic_graph.key_of(blocker)))
+				.map((blocker) => ({ blocker: blocker.number, blocked: member.number })),
+		)
+}
+
+// The children a new epic would track, in number order so the batch reads the way it was filed.
+function bundle_children(
+	subject: BacklogIssue,
+	candidates: ReadonlyArray<BacklogIssue>,
+): Array<number> {
+	return [subject.number, ...to_numbers(candidates)].toSorted((left, right) => left - right)
+}
+
+const epic_bundle = {
+	names_as_blocker,
+	names_in_body,
+	NO_SIGNAL_REASON,
+	already_tracked_reason,
+	SPREAD_REASON,
+	has_mutual_reference,
+	has_recorded_dependency,
+	is_strong_signal,
+	find_candidates,
+	candidate_epics,
+	decide_bundle,
+	bundle_dependency_links,
+	bundle_children,
+}
+
+export type { BacklogIssue, BundleAction, BundleDecision }
+export { epic_bundle }