@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/lane/lane-state.ts

@@ -0,0 +1,302 @@
+import { readdirSync } from 'node:fs'
+import path from 'node:path'
+import { repository_lock } from '#scripts/git/repository-lock'
+import { session_cite } from '#scripts/issue/session-cite'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { figure_format } from '#scripts/lib/figure-format'
+import { json_value } from '#scripts/lib/json-value'
+import { run_carry } from '#scripts/run/carry/run-carry'
+import { z } from 'zod'
+
+// One record per lane of where it is in its life — opened, running, paused, ended — written only by
+// the lane commands (joshuafolkken/kit#4268), so a reader asks the record rather than guessing from
+// the `.env` mtime, the event stream or the `ps` state.
+//
+// **It is a `stamp_path` keyed on the common git directory**, beside the carry record and the event
+// stream and outside every work tree, so it is the same file from the main checkout and from inside
+// the lane, it outlives `lane:close`'s removal of the lane, and `JOSH_TEMP_ROOT` moves it with every
+// other record the run keeps.
+//
+// **The write is `stamp_file.replace_stamp`'s** — a temporary file beside the target, renamed over it —
+// so two commands writing the same lane at once leave one whole record, never a torn one. **The read,
+// the transition check and that write are one step under a per-record lock**, as the event stream's
+// append is: unlocked, a pause that read `running` could rename its `paused` over a merge's `ended`.
+//
+// **A transition the lifecycle does not have is not written** (an `ended` lane is not paused); it is
+// warned about and the command carries on, as it does when the record cannot be written at all — the
+// record never fails the command that keeps it.
+
+const STATE_PREFIX = 'josh-lane-state-'
+const STATE_SUFFIX = '.json'
+const LOCK_SUFFIX = '.lock'
+// A change holds the lock for one read and one rename; a wait this long means a holder is stuck.
+const LOCK_WAIT_MS = 5000
+const LANE_STATES = ['open', 'running', 'paused', 'ended'] as const
+// What a lane with no record is answered with: its state is unknown, so it keeps its place.
+const NO_STATE_HINT = 'no lane state — counted in use'
+
+type LaneState = (typeof LANE_STATES)[number]
+
+const lane_run_schema = z.object({ started_at: z.string(), owner_pid: z.number().optional() })
+
+// A process the last `lane:close` could not end even with a SIGKILL, and why (`lane-reap-settle.ts`).
+const stuck_schema = z.object({ pid: z.number(), reason: z.string() })
+
+const lane_state_schema = z.object({
+	issue: z.string(),
+	run: lane_run_schema.optional(),
+	state: z.enum(LANE_STATES),
+	launched_at: z.string().optional(),
+	changed_at: z.string(),
+	changed_by: z.string(),
+	stuck: z.array(stuck_schema).optional(),
+})
+
+type LaneRun = z.infer<typeof lane_run_schema>
+type LaneStateRecord = z.infer<typeof lane_state_schema>
+type StuckProcess = z.infer<typeof stuck_schema>
+// Each lane's record, by issue; a lane with none is left out (`read_states`).
+type LaneRecords = ReadonlyMap<string, LaneStateRecord>
+
+// The states each one moves to. A lane with no record yet (opened before the record existed) moves to
+// any of them.
+const TRANSITIONS: Record<LaneState, ReadonlyArray<LaneState>> = {
+	open: ['open', 'running', 'ended'],
+	running: ['running', 'paused', 'ended'],
+	paused: ['paused', 'running', 'ended'],
+	ended: ['ended', 'open'],
+}
+
+// One command's change: the state it leaves the lane in, and whether it launched a child — a launch
+// stamps the launch time and the run that launched it, which every other change keeps.
+interface LaneChange {
+	issue: string
+	state: LaneState
+	command: string
+	is_launch?: boolean
+}
+
+interface StateOptions {
+	directory?: string | undefined
+	now?: Date
+}
+
+type RecordOutcome =
+	{ kind: 'written'; record: LaneStateRecord } | { kind: 'skipped'; reason: string }
+
+function state_path(directory: string, issue: string): string {
+	return stamp_file.stamp_path(STATE_PREFIX, directory, `-${issue}${STATE_SUFFIX}`)
+}
+
+function is_allowed(from: LaneState | undefined, to: LaneState): boolean {
+	return from === undefined || TRANSITIONS[from].includes(to)
+}
+
+function read_record(directory: string, issue: string): LaneStateRecord | undefined {
+	const raw = stamp_file.read_stamp_text(state_path(directory, issue))
+
+	return raw === undefined ? undefined : json_value.parse_with(raw, lane_state_schema)
+}
+
+function write_record(directory: string, record: LaneStateRecord): void {
+	stamp_file.replace_stamp(state_path(directory, record.issue), record)
+}
+
+// The run a launch belongs to: the carry's start and owner, read from the same common git directory.
+function current_run(directory: string): LaneRun | undefined {
+	const carried = run_carry.read_carry(run_carry.carry_path(directory))
+
+	if (carried.kind !== 'carried') return undefined
+
+	return { started_at: carried.carry.started_at, owner_pid: carried.carry.owner_pid }
+}
+
+function launch_fields(change: LaneChange, directory: string, now: Date): Partial<LaneStateRecord> {
+	if (change.is_launch !== true) return {}
+
+	return { run: current_run(directory), launched_at: now.toISOString() }
+}
+
+function next_record(
+	change: LaneChange,
+	previous: LaneStateRecord | undefined,
+	directory: string,
+	now: Date,
+): LaneStateRecord {
+	return {
+		// An open starts a fresh life: a reopened lane keeps nothing of the run that launched it before.
+		...(change.state !== 'open' && previous),
+		issue: change.issue,
+		state: change.state,
+		changed_at: now.toISOString(),
+		changed_by: change.command,
+		...launch_fields(change, directory, now),
+	}
+}
+
+function apply_held(change: LaneChange, directory: string, now: Date): RecordOutcome {
+	const previous = read_record(directory, change.issue)
+
+	if (!is_allowed(previous?.state, change.state)) {
+		return { kind: 'skipped', reason: `no ${previous?.state ?? ''} → ${change.state} transition` }
+	}
+
+	const record = next_record(change, previous, directory, now)
+
+	write_record(directory, record)
+
+	return { kind: 'written', record }
+}
+
+const NO_DIRECTORY: RecordOutcome = { kind: 'skipped', reason: 'no git directory' }
+
+// The read, the check and the write of one record, under its lock.
+function locked(directory: string, issue: string, held: () => RecordOutcome): RecordOutcome {
+	const lock = `${state_path(directory, issue)}${LOCK_SUFFIX}`
+	const outcome = repository_lock.with_lock_sync(held, lock, LOCK_WAIT_MS)
+
+	return outcome ?? { kind: 'skipped', reason: `gave up waiting for the lock at ${lock}` }
+}
+
+function apply(change: LaneChange, directory: string, now: Date): RecordOutcome {
+	return locked(directory, change.issue, () => apply_held(change, directory, now))
+}
+
+function warn(change: LaneChange, reason: string): void {
+	console.warn(
+		`${change.command} ${session_cite.issue(change.issue)}: lane state not recorded — ${reason}`,
+	)
+}
+
+async function resolve_directory(directory: string | undefined): Promise<string | undefined> {
+	return directory ?? (await run_carry.repository_directory())
+}
+
+async function outcome_of(change: LaneChange, options: StateOptions): Promise<RecordOutcome> {
+	const directory = await resolve_directory(options.directory)
+
+	if (directory === undefined) return NO_DIRECTORY
+
+	return apply(change, directory, options.now ?? new Date())
+}
+
+async function settled_outcome(change: LaneChange, options: StateOptions): Promise<RecordOutcome> {
+	try {
+		return await outcome_of(change, options)
+	} catch (error: unknown) {
+		return { kind: 'skipped', reason: error instanceof Error ? error.message : String(error) }
+	}
+}
+
+async function record_change(
+	change: LaneChange,
+	options: StateOptions = {},
+): Promise<RecordOutcome> {
+	const outcome = await settled_outcome(change, options)
+
+	if (outcome.kind === 'skipped') warn(change, outcome.reason)
+
+	return outcome
+}
+
+async function read_state(issue: string, directory?: string): Promise<LaneStateRecord | undefined> {
+	const root = await resolve_directory(directory)
+
+	return root === undefined ? undefined : read_record(root, issue)
+}
+
+// The issue each record of `directory` is for, read off the file names `state_path` writes.
+function recorded_issues(directory: string): Array<string> {
+	const empty = state_path(directory, '')
+	const head = path.basename(empty).slice(0, -STATE_SUFFIX.length)
+
+	return readdirSync(path.dirname(empty))
+		.filter((name) => name.startsWith(head) && name.endsWith(STATE_SUFFIX))
+		.map((name) => name.slice(head.length, -STATE_SUFFIX.length))
+		.filter((issue) => issue.length > 0)
+}
+
+/** Every lane's record, a closed lane's included — the record outlives the work tree. */
+async function read_records(directory?: string): Promise<Array<LaneStateRecord>> {
+	const root = await resolve_directory(directory)
+
+	if (root === undefined) return []
+
+	const records = recorded_issues(root).map((issue) => read_record(root, issue))
+
+	return records.filter((record) => record !== undefined)
+}
+
+function stuck_held(issue: string, stuck: Array<StuckProcess>, directory: string): RecordOutcome {
+	const previous = read_record(directory, issue)
+
+	if (previous === undefined) return { kind: 'skipped', reason: 'no record' }
+
+	const record = { ...previous, stuck }
+
+	write_record(directory, record)
+
+	return { kind: 'written', record }
+}
+
+/**
+ * Note on the lane's record the processes its close could not end, leaving its state as it is: a lane
+ * a close has not finished is not `ended`. A lane with no record is not given one.
+ */
+async function record_stuck(
+	issue: string,
+	stuck: Array<StuckProcess>,
+	directory?: string,
+): Promise<RecordOutcome> {
+	const root = await resolve_directory(directory)
+
+	if (root === undefined) return NO_DIRECTORY
+
+	return locked(root, issue, () => stuck_held(issue, stuck, root))
+}
+
+/** Each of `issues`' records, by issue; an issue with none is left out. */
+async function read_states(
+	issues: ReadonlyArray<string>,
+	directory?: string,
+): Promise<LaneRecords> {
+	const root = await resolve_directory(directory)
+
+	if (root === undefined) return new Map()
+
+	const read = issues.map((issue): [string, LaneStateRecord | undefined] => [
+		issue,
+		read_record(root, issue),
+	])
+
+	return new Map(read.filter((entry): entry is [string, LaneStateRecord] => entry[1] !== undefined))
+}
+
+/** `paused since 01:28 by lane:pause` — the one wording every reader names a paused lane in. */
+function paused_text(since_ms: number, changed_by: string): string {
+	return `paused since ${figure_format.minute_of(since_ms)} by ${changed_by}`
+}
+
+/** `paused_text` for a paused record, `undefined` for any other. */
+function paused_note(record: LaneStateRecord | undefined): string | undefined {
+	if (record?.state !== 'paused') return undefined
+
+	return paused_text(Date.parse(record.changed_at), record.changed_by)
+}
+
+const lane_state = {
+	LANE_STATES,
+	NO_STATE_HINT,
+	is_allowed,
+	paused_note,
+	paused_text,
+	read_records,
+	read_state,
+	read_states,
+	record_change,
+	record_stuck,
+	state_path,
+}
+
+export { lane_state }
+export type { LaneChange, LaneRecords, LaneState, LaneStateRecord, RecordOutcome, StuckProcess }

package/scripts/lane/lane-stats.ts

@@ -1,5 +1,6 @@
 import { machine_capacity } from '#scripts/gate/machine-capacity'
-import type { GateEntry, LedgerEntry, LoadEntry } from './lane-ledger'
+import { MS_PER_MINUTE } from '#scripts/lib/timeouts'
+import type { DispatchEntry, GateEntry, LedgerEntry, LoadEntry, MergeEntry } from './lane-ledger'
 import { lane_sampler } from './lane-sampler'
 
 // The lane-limit measurement's one table row: the ledger entries of one period
@@ -21,7 +22,6 @@ import { lane_sampler } from './lane-sampler'
 // **Swap is a rate, not a level.** A sample carries `machine_capacity`'s counter — every page swapped
 // since boot — so the swap columns are what was swapped between consecutive samples, per hour.
 
-const MS_PER_MINUTE = 60_000
 const MS_PER_HOUR = 3_600_000
 // A busy lane pool finishes a gate well within this; a longer silence is time nobody was running work.
 const ACTIVE_GAP_MS = MS_PER_HOUR
@@ -40,6 +40,7 @@ const COLUMNS = [
 	'merges',
 	'merges / hour',
 	'effective lanes',
+	'lane median (min)',
 	'gate median (min)',
 	'gate max (min)',
 	'load peak',
@@ -65,7 +66,10 @@ function window_of(period_days: number, now_ms: number): StatsWindow {
 	return { since_ms: now_ms - period_days * MS_PER_DAY, until_ms: now_ms }
 }
 
-function in_window(entries: ReadonlyArray<LedgerEntry>, window: StatsWindow): Array<LedgerEntry> {
+function in_window<T extends { at: string }>(
+	entries: ReadonlyArray<T>,
+	window: StatsWindow,
+): Array<T> {
 	return entries.filter((entry) => {
 		const at = Date.parse(entry.at)
 
@@ -77,6 +81,14 @@ function is_gate(entry: LedgerEntry): entry is GateEntry {
 	return entry.kind === 'gate'
 }
 
+function is_merge(entry: LedgerEntry): entry is MergeEntry {
+	return entry.kind === 'merge'
+}
+
+function is_dispatch(entry: LedgerEntry): entry is DispatchEntry {
+	return entry.kind === 'dispatch'
+}
+
 function is_load(entry: LedgerEntry): entry is LoadEntry {
 	return entry.kind === 'load'
 }
@@ -200,8 +212,49 @@ function throughput_cells(entries: ReadonlyArray<LedgerEntry>): Array<string> {
 	return [String(merges), cell(per_hour), cell(mean(lanes))]
 }
 
+function dispatched_before(
+	dispatches: ReadonlyArray<DispatchEntry>,
+	merge: MergeEntry,
+): number | undefined {
+	const merged_at = Date.parse(merge.at)
+	const starts = dispatches
+		.filter((dispatch) => dispatch.issue === merge.issue)
+		.map((dispatch) => Date.parse(dispatch.at))
+		.filter((at) => at <= merged_at)
+
+	return peak(starts)
+}
+
+function lane_minutes(
+	dispatches: ReadonlyArray<DispatchEntry>,
+	merge: MergeEntry,
+): number | undefined {
+	const start = dispatched_before(dispatches, merge)
+
+	return start === undefined ? undefined : (Date.parse(merge.at) - start) / MS_PER_MINUTE
+}
+
+// One merge's lane time runs from the latest dispatch of its issue — looked up in the whole ledger,
+// since a lane may start before the window — to the merge. A merge no dispatch preceded is skipped.
+function lane_cell(
+	entries: ReadonlyArray<LedgerEntry>,
+	period: ReadonlyArray<LedgerEntry>,
+): string {
+	const dispatches = entries.filter(is_dispatch)
+	const minutes = period
+		.filter((entry) => is_merge(entry))
+		.map((merge) => lane_minutes(dispatches, merge))
+		.filter(is_number)
+
+	return cell(median(minutes))
+}
+
+// A reused gate ran no check, so its few milliseconds would pull the median toward a gate that never ran.
 function gate_cells(entries: ReadonlyArray<LedgerEntry>): Array<string> {
-	const minutes = entries.filter(is_gate).map((entry) => entry.elapsed_ms / MS_PER_MINUTE)
+	const minutes = entries
+		.filter(is_gate)
+		.filter((entry) => entry.is_reused !== true)
+		.map((entry) => entry.elapsed_ms / MS_PER_MINUTE)
 
 	return [cell(median(minutes)), cell(peak(minutes))]
 }
@@ -248,6 +301,7 @@ function row(entries: ReadonlyArray<LedgerEntry>, window: StatsWindow, label: Ro
 		label.limit,
 		String(label.period_days),
 		...throughput_cells(period),
+		lane_cell(entries, period),
 		...gate_cells(period),
 		...load_cells(period.filter(is_load)),
 	])

package/scripts/lane/lane-stop-stats.ts

@@ -1,20 +1,29 @@
+import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
 import { run_ship_stage } from '#scripts/run/ship/run-ship-stage'
 import { lane_ledger, type LedgerEntry, type StopEntry } from './lane-ledger'
+import type { IssueAt } from './lane-spans'
 import { lane_stage_stats } from './lane-stage-stats'
 import { lane_stats, type StatsWindow } from './lane-stats'
 
 // How long a lane stood stopped: the ledger's `stop` entries of one period reduced to one row per stop
-// reason — median, maximum, how many stops were resumed and how many never were — printed by
-// `josh lane:stats` under the per-stage table, so the stop reason worth removing next is a number.
+// reason — the wait's median, maximum and total, how many waits ended and how many never did — printed
+// by `josh lane:stats` under the per-stage table, so the stop reason worth removing next is a number.
 //
-// **The wait is derived, not recorded**: from a stop to the start of the same issue's next ship stage,
-// the way `implement` is. A stop that no ship stage followed — the lane parked, or left stopped — is
-// counted under `not resumed` and kept out of the median and the maximum, whose time has no end.
-//
-// **A re-dispatch of the issue ends the search**: the new child's ship is a fresh lane's work, not the
-// resumption of a stop that may be days old.
+// **The wait is derived, not recorded**: from a stop to whichever comes first of the same issue's next
+// ship stage (the lane resumed), its re-dispatch (a fresh lane took it over) and its park on the run's
+// event stream (the run gave up on it) — the time the stop held the issue (joshuafolkken/kit#3997). A
+// stop none of the three followed is counted under `not resumed` and kept out of the median, the
+// maximum and the total, whose time has no end.
 
-const COLUMNS = ['stop', 'median (min)', 'max (min)', 'runs', 'not resumed'] as const
+const COLUMNS = [
+	'stop',
+	'wait median (min)',
+	'wait max (min)',
+	'wait total (min)',
+	'runs',
+	'not resumed',
+	'causes',
+] as const
 const { STAGE } = run_ship_stage
 const { is_dispatch, is_number, is_stage } = lane_stage_stats
 const REASONS = [
@@ -28,9 +37,19 @@ const REASONS = [
 	STAGE.FOLLOWUP,
 	STAGE.REPORT,
 ] as const
+// `#<N> parked`, `#<N> parked (<reason>)`, `#<N> waiting on #<M>`, `#<N> cut (<phase>)` and
+// `#<N> resumed` name their issue first.
+const EVENT_ISSUE = /#([1-9]\d*)\b/u
+
+// A stop recorded before it carried a cause (joshuafolkken/kit#3998) is counted under this one.
+const UNRECORDED_CAUSE = 'unrecorded'
+const NO_CAUSES = '-'
 
+// `causes` is a preflight stop's unmet preconditions or a review stop's blocking finding kinds, every
+// one of them, else the stop's one cause.
 interface StopWait {
 	reason: string
+	causes: ReadonlyArray<string>
 	wait_ms: number | undefined
 }
 
@@ -38,51 +57,108 @@ function is_stop(entry: LedgerEntry): entry is StopEntry {
 	return entry.kind === lane_ledger.KIND.STOP
 }
 
-function redispatch_ms(stop: StopEntry, entries: ReadonlyArray<LedgerEntry>): number {
-	const from_ms = Date.parse(stop.at)
-	const later = entries
+// Every run event of `kind`, with the issue its text names first.
+function events_of(events: ReadonlyArray<RunEvent>, kind: string): Array<IssueAt> {
+	return events
+		.filter((event) => event.kind === kind)
+		.map((event) => ({
+			issue: Number(EVENT_ISSUE.exec(event.text)?.[1]),
+			at_ms: Date.parse(event.at),
+		}))
+}
+
+function parks_of(events: ReadonlyArray<RunEvent>): Array<IssueAt> {
+	return events_of(events, run_event_stream.EVENT_KIND.PARK)
+}
+
+function ends_of(
+	entries: ReadonlyArray<LedgerEntry>,
+	parks: ReadonlyArray<IssueAt>,
+): Array<IssueAt> {
+	const resumes = entries
+		.filter((entry) => is_stage(entry))
+		.map((stage) => ({ issue: stage.issue, at_ms: lane_stage_stats.started_ms(stage) }))
+	const dispatches = entries
 		.filter((entry) => is_dispatch(entry))
-		.filter((entry) => entry.issue === stop.issue)
-		.map((entry) => Date.parse(entry.at))
-		.filter((at) => at > from_ms)
+		.map((entry) => ({ issue: entry.issue, at_ms: Date.parse(entry.at) }))
 
-	return later.length === 0 ? Infinity : Math.min(...later)
+	return [...resumes, ...dispatches, ...parks]
 }
 
-function wait_ms(stop: StopEntry, entries: ReadonlyArray<LedgerEntry>): number | undefined {
+// A stage's start counts from the stop's own instant, so a ship relaunched within the same
+// millisecond still ends the wait; the stage that stopped started before it.
+function wait_ms(stop: StopEntry, ends: ReadonlyArray<IssueAt>): number | undefined {
 	const from_ms = Date.parse(stop.at)
-	const until_ms = redispatch_ms(stop, entries)
-	const starts = entries
-		.filter((entry) => is_stage(entry))
-		.filter((stage) => stage.issue === stop.issue)
-		.map((stage) => lane_stage_stats.started_ms(stage))
-		.filter((start) => start >= from_ms && start < until_ms)
+	const later = ends
+		.filter((end) => end.issue === stop.issue && end.at_ms >= from_ms)
+		.map((end) => end.at_ms - from_ms)
 
-	return starts.length === 0 ? undefined : Math.min(...starts) - from_ms
+	return later.length === 0 ? undefined : Math.min(...later)
 }
 
-function waits_of(entries: ReadonlyArray<LedgerEntry>): Array<StopWait> {
-	return entries
-		.filter(is_stop)
-		.map((stop) => ({ reason: stop.reason, wait_ms: wait_ms(stop, entries) }))
+// A stop recorded before it named its preconditions (joshuafolkken/kit#4166) or its finding kinds
+// (joshuafolkken/kit#4426) counts under its cause.
+function causes_of(stop: StopEntry): ReadonlyArray<string> {
+	const { preconditions = [], findings = [] } = stop
+	const kinds = [...preconditions, ...findings]
+
+	return kinds.length > 0 ? kinds : [stop.cause ?? UNRECORDED_CAUSE]
+}
+
+function waits_of(
+	entries: ReadonlyArray<LedgerEntry>,
+	ends: ReadonlyArray<IssueAt>,
+): Array<StopWait> {
+	return entries.filter(is_stop).map((stop) => ({
+		reason: stop.reason,
+		causes: causes_of(stop),
+		wait_ms: wait_ms(stop, ends),
+	}))
+}
+
+function total(values: ReadonlyArray<number>): number | undefined {
+	return values.length === 0 ? undefined : values.reduce((sum, value) => sum + value, 0)
+}
+
+// `infra 2, check 1` — how many of one reason's stops each cause took, the most frequent first. A stop
+// with two unmet preconditions counts once under each.
+function causes_cell(waits: ReadonlyArray<StopWait>): string {
+	const all = waits.flatMap((wait) => wait.causes)
+	const counted = [...new Set(all)].map((cause) => ({
+		cause,
+		count: all.filter((each) => each === cause).length,
+	}))
+	const ranked = counted.toSorted((left, right) => right.count - left.count)
+
+	return ranked.length === 0
+		? NO_CAUSES
+		: ranked.map(({ cause, count }) => `${cause} ${String(count)}`).join(', ')
 }
 
 function reason_row(reason: string, waits: ReadonlyArray<StopWait>): string {
 	const of_reason = waits.filter((wait) => wait.reason === reason)
-	const resumed = of_reason.map((wait) => wait.wait_ms).filter((value) => is_number(value))
+	const ended = of_reason.map((wait) => wait.wait_ms).filter((value) => is_number(value))
 
 	return lane_stats.to_row([
 		reason,
-		lane_stage_stats.cell(lane_stats.median(resumed)),
-		lane_stage_stats.cell(lane_stats.peak(resumed)),
-		String(resumed.length),
-		String(of_reason.length - resumed.length),
+		lane_stage_stats.cell(lane_stats.median(ended)),
+		lane_stage_stats.cell(lane_stats.peak(ended)),
+		lane_stage_stats.cell(total(ended)),
+		String(ended.length),
+		String(of_reason.length - ended.length),
+		causes_cell(of_reason),
 	])
 }
 
-// The period's table: `entries` is the whole ledger, filtered here to `window`.
-function table(entries: ReadonlyArray<LedgerEntry>, window: StatsWindow): string {
-	const waits = waits_of(lane_stats.in_window(entries, window))
+// The period's table: `entries` is the whole ledger, filtered here to `window` — only the stops are; a
+// wait may end after the period's last stop. `events` is the run's event stream, read for its parks.
+function table(
+	entries: ReadonlyArray<LedgerEntry>,
+	window: StatsWindow,
+	events: ReadonlyArray<RunEvent> = [],
+): string {
+	const ends = ends_of(entries, parks_of(events))
+	const waits = waits_of(lane_stats.in_window(entries, window), ends)
 
 	return [
 		lane_stats.to_row(COLUMNS),
@@ -91,6 +167,6 @@ function table(entries: ReadonlyArray<LedgerEntry>, window: StatsWindow): string
 	].join('\n')
 }
 
-const lane_stop_stats = { REASONS, table }
+const lane_stop_stats = { REASONS, events_of, table }
 
 export { lane_stop_stats }