@joshuafolkken/kit 1.2114.0 → 1.3000.0

package/scripts/lane/lane-launch-cli.ts

@@ -1,11 +1,13 @@
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
-import { josh_command } from '#scripts/josh/josh-run'
+import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
 import { lane_vacant } from '#scripts/lane/lane-vacant'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { INSTALL_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { run_event_setup } from '#scripts/run/event/run-event-setup'
 import { execa } from 'execa'
+import { lane_launch_admission } from './lane-launch-admission'
+import { lane_launch_pending } from './lane-launch-pending'
 
 // `josh lane:launch <issue> [--stash <message>]` — one composite command for a `backlogrun` lane-start
 // event. Opening one lane was four to six turns of the parent: `lane:open`,
@@ -28,6 +30,8 @@ const USAGE = 'Usage: josh lane:launch <issue-number> [--stash <message>]'
 
 const OPTIONS = { stash: { type: 'string' } } as const
 
+const PREPARED: JoshResult = { code: SUCCESS_EXIT_CODE, out: '' }
+
 // The stash message is present only for the first lane — the caller passes `--stash` there and nowhere
 // else, so "only the first lane pops and re-installs" is preserved by which invocation carries it.
 interface LaunchContext {
@@ -53,50 +57,66 @@ function read_context(argv: ReadonlyArray<string>): LaunchContext | undefined {
 	return { issue, stash: parsed.values.stash }
 }
 
+// Where the chain ended. `unopened` is a `lane:open` refusal — no lane was taken; `failed` is a step
+// after it, which leaves the opened lane holding a seat, so a caller cannot read the two alike. Either
+// carries the failing step's own explanation as `detail`, when it said one.
+type Refusal = { kind: 'unopened'; detail?: string } | { kind: 'failed'; detail?: string }
+
+type LaunchOutcome = Refusal | { kind: 'launched'; pid: string } | { kind: 'waiting' }
+
+// The step's stderr, or its stdout when stderr is empty; nothing when it said neither.
+function failure_detail(result: JoshResult): string | undefined {
+	const detail = (result.err ?? '').trim() || result.out.trim()
+
+	return detail === '' ? undefined : detail
+}
+
+function refused(kind: Refusal['kind'], result: JoshResult): Refusal {
+	const detail = failure_detail(result)
+
+	return detail === undefined ? { kind } : { kind, detail }
+}
+
 // The pop brought in the `pnpm-lock.yaml` `josh latest` rewrote, so this one lane installs a second
 // time against it. Output is captured and surfaced only on failure, so the composite's stdout stays
 // the child's pid alone.
-async function install(directory: string): Promise<boolean> {
+async function install(directory: string): Promise<JoshResult> {
 	const result = await execa(PNPM, ['--dir', directory, 'install', '--frozen-lockfile'], {
 		reject: false,
 		timeout: INSTALL_TIMEOUT_MS,
 	})
+	const installed = {
+		code: result.exitCode ?? FAILURE_EXIT_CODE,
+		out: result.stdout,
+		err: result.stderr,
+	}
 
-	if ((result.exitCode ?? FAILURE_EXIT_CODE) === SUCCESS_EXIT_CODE) return true
-
-	console.error(result.stderr === '' ? result.stdout : result.stderr)
+	if (installed.code !== SUCCESS_EXIT_CODE) console.error(failure_detail(installed) ?? '')
 
-	return false
+	return installed
 }
 
 // The first lane pops the shared stash and re-installs against the lock it brought in; a pop that
 // refused (`no-match` / `ambiguous`) stops the lane rather than dispatching onto an unprepared tree.
 // A caller without `--stash` skips both, which is every lane after the first. The re-install is a
 // stage of its own on the run's stream, as the install `lane:open` ran was.
-async function prepare(context: LaunchContext, directory: string): Promise<boolean> {
+async function prepare(context: LaunchContext, directory: string): Promise<JoshResult> {
 	const { issue, stash } = context
 
-	if (stash === undefined) return true
+	if (stash === undefined) return PREPARED
 
 	const popped = await josh_command.josh_run(
 		['stash:pop', stash, '--dir', directory],
 		should_forward_stderr,
 	)
 
-	if (popped.code !== SUCCESS_EXIT_CODE) return false
+	if (popped.code !== SUCCESS_EXIT_CODE) return popped
 
 	await run_event_setup.emit(run_event_setup.installing(issue))
 
 	return await install(directory)
 }
 
-// Where the chain ended. `unopened` is a `lane:open` refusal — no lane was taken; `failed` is a step
-// after it, which leaves the opened lane holding a seat, so a caller cannot read the two alike.
-type LaunchOutcome = { kind: 'launched'; pid: string } | { kind: 'unopened' } | { kind: 'failed' }
-
-const UNOPENED: LaunchOutcome = { kind: 'unopened' }
-const FAILED: LaunchOutcome = { kind: 'failed' }
-
 async function close_if_vacant(lane: LaneInfo | undefined): Promise<void> {
 	if (lane === undefined || !(await lane_vacant.is_vacant(lane))) return
 
@@ -114,27 +134,27 @@ async function close_if_vacant(lane: LaneInfo | undefined): Promise<void> {
 // — a run cut between the open and the dispatch leaves one. It is reopened
 // rather than reused because nothing recorded whether its install finished. A lane with work or a live
 // process in it still meets `lane:open`'s refusal.
-async function lane_directory(issue: string): Promise<string | undefined> {
+async function lane_directory(issue: string): Promise<JoshResult> {
 	const kept = await lane_registry.find_open_lane(issue)
 
-	if (kept?.output !== undefined) return kept.directory
+	if (kept?.output !== undefined) return { code: SUCCESS_EXIT_CODE, out: kept.directory }
 
 	await close_if_vacant(kept)
 
-	const opened = await josh_command.josh_run(['lane:open', issue], should_forward_stderr)
-
-	return opened.code === SUCCESS_EXIT_CODE ? opened.out : undefined
+	return await josh_command.josh_run(['lane:open', issue], should_forward_stderr)
 }
 
 // The launch chain in-process. The CLI prints the pid; `backlog:drive` launches through this same
 // chain. The dispatch is said on the run's stream before it starts, so the board draws a lane that is
 // ready apart from one still being filled.
-async function launch_lane(context: LaunchContext): Promise<LaunchOutcome> {
-	const directory = await lane_directory(context.issue)
+async function launch_admitted(context: LaunchContext): Promise<LaunchOutcome> {
+	const opened = await lane_directory(context.issue)
+
+	if (opened.code !== SUCCESS_EXIT_CODE) return refused('unopened', opened)
 
-	if (directory === undefined) return UNOPENED
+	const prepared = await prepare(context, opened.out)
 
-	if (!(await prepare(context, directory))) return FAILED
+	if (prepared.code !== SUCCESS_EXIT_CODE) return refused('failed', prepared)
 
 	await run_event_setup.emit(run_event_setup.dispatching(context.issue))
 
@@ -143,7 +163,17 @@ async function launch_lane(context: LaunchContext): Promise<LaunchOutcome> {
 		should_forward_stderr,
 	)
 
-	return dispatched.code === SUCCESS_EXIT_CODE ? { kind: 'launched', pid: dispatched.out } : FAILED
+	if (dispatched.code !== SUCCESS_EXIT_CODE) return refused('failed', dispatched)
+
+	return { kind: 'launched', pid: dispatched.out }
+}
+
+async function launch_lane(context: LaunchContext): Promise<LaunchOutcome> {
+	return await lane_launch_admission.launch(context, launch_admitted)
+}
+
+async function launch_ready_lane(context: LaunchContext): Promise<LaunchOutcome> {
+	return await lane_launch_pending.launch(context, launch_admitted)
 }
 
 async function launch(context: LaunchContext): Promise<number> {
@@ -168,7 +198,13 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	return await launch(context)
 }
 
-const lane_launch_cli = { launch_lane, read_context, run }
+const lane_launch_cli = {
+	keep_pending: lane_launch_pending.keep,
+	launch_lane,
+	launch_ready_lane,
+	read_context,
+	run,
+}
 
 export type { LaunchContext, LaunchOutcome }
 export { lane_launch_cli }

package/scripts/lane/lane-launch-pending.ts

@@ -0,0 +1,44 @@
+import { core_budget } from '#scripts/gate/core-budget'
+import { lane_launch_admission } from './lane-launch-admission'
+import type { LaunchContext, LaunchOutcome } from './lane-launch-cli'
+
+type Claim = ReturnType<typeof core_budget.claim>
+// One waiting claim per issue: the driver launches a pass's lanes side by side
+// (joshuafolkken/kit#5519), so one issue's claim must not release another's.
+const pending = new Map<string, Claim>()
+
+function keep(issues: ReadonlyArray<string>): void {
+	for (const [issue, claim] of pending) {
+		if (issues.includes(issue)) continue
+
+		core_budget.release(claim)
+		pending.delete(issue)
+	}
+}
+
+function claim_for(issue: string): Claim {
+	const claim = pending.get(issue) ?? core_budget.claim(0, lane_launch_admission.options_of(issue))
+
+	pending.set(issue, claim)
+
+	return claim
+}
+
+// A wait is not a failed launch or a running child: the driver keeps collecting children and
+// checking its window. Only a later offered pass with room may actually open and dispatch.
+async function launch(
+	context: LaunchContext,
+	run: (context: LaunchContext) => Promise<LaunchOutcome>,
+): Promise<LaunchOutcome> {
+	const handle = await core_budget.poll_claim(claim_for(context.issue))
+
+	if (handle === undefined) return { kind: 'waiting' }
+
+	pending.delete(context.issue)
+
+	return await lane_launch_admission.run_reserved(context, run, handle)
+}
+
+const lane_launch_pending = { keep, launch }
+
+export { lane_launch_pending }

package/scripts/lane/lane-ledger-archive.ts

@@ -0,0 +1,200 @@
+import {
+	closeSync,
+	constants,
+	existsSync,
+	fstatSync,
+	openSync,
+	readSync,
+	statSync,
+	truncateSync,
+	writeSync,
+} from 'node:fs'
+import { repository_lock } from '#scripts/git/repository-lock'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { atomic_write } from '#scripts/lib/atomic-write'
+import { json_value } from '#scripts/lib/json-value'
+import { z } from 'zod'
+import { lane_ledger, type LedgerEntry } from './lane-ledger'
+import { lane_ledger_write } from './lane-ledger-write'
+import type { MeasureContext } from './lane-sampler'
+
+// The ledger's records past the retention, moved to an archive beside it (joshuafolkken/kit#7038), so
+// the ledger every lane step reads stays a few days long. **Merges stay**: they are a line per lane, and
+// the baseline counts them across all time (`lane-baseline.ts`).
+//
+// **The ledger is replaced by a rename** — the tail reader (`lane-ledger-tail.ts`) reads another inode
+// again whole. A descriptor stays open on the old ledger across the rename: bytes landing past the last
+// complete line the rotation read are carried into the replacement, and an append that opened the old
+// ledger before the rename is read back off that descriptor afterwards and carried too. The archive takes
+// its lines in one append before the ledger is replaced, and a replace that throws truncates it back: a
+// rotation cut short leaves each record in exactly one file. One rotation at a time, under a lock no
+// rotation waits on.
+//
+// The readers of a lane's history — `josh lane:stats`, the per-issue `lane:net` / `lane:why` /
+// `lane:breakdown` / `cost:audit` — read the archive before the ledger (`read_history`).
+
+const RETENTION_DAYS = 14
+const MS_PER_DAY = 86_400_000
+const LEDGER_SUFFIX_PATTERN = /\.jsonl$/u
+const ARCHIVE_SUFFIX = '-archive.jsonl'
+const LOCK_SUFFIX = '.rotate.lock'
+// The writer's own mode and flags (`lane-ledger-write.ts`), which takes one record, not lines of text.
+const LEDGER_FILE_MODE = 0o600
+const { O_APPEND, O_CREAT, O_NOFOLLOW, O_RDONLY, O_WRONLY } = constants
+// eslint-disable-next-line no-bitwise -- POSIX open flags are a bit field; `||` here would be a bug
+const APPEND_FLAGS = O_WRONLY | O_APPEND | O_CREAT | O_NOFOLLOW
+// eslint-disable-next-line no-bitwise -- POSIX open flags are a bit field; `||` here would be a bug
+const READ_FLAGS = O_RDONLY | O_NOFOLLOW
+// One claim and no wait: a rotation already holding the lock does this one's work.
+const NO_WAIT_MS = 0
+
+const { LINE_SEPARATOR } = lane_ledger_write
+const { KIND } = lane_ledger
+const record_schema = z.looseObject({ kind: z.string(), at: z.string() })
+
+type ReadContext = Pick<MeasureContext, 'ledger_path'>
+
+interface Partition {
+	readonly archived: string
+	readonly count: number
+	readonly kept: string
+}
+
+interface Move extends Partition {
+	readonly descriptor: number
+	readonly end: number
+}
+
+function archive_of(ledger: string): string {
+	return `${ledger.replace(LEDGER_SUFFIX_PATTERN, '')}${ARCHIVE_SUFFIX}`
+}
+
+// Whether a line holds a record past the cutoff; a malformed line stays, as the reader skips it anyway.
+function is_past(line: string, cutoff_ms: number): boolean {
+	const record = record_schema.safeParse(json_value.parse_or_undefined(line)).data
+
+	if (record === undefined || record.kind === KIND.MERGE) return false
+
+	return Date.parse(record.at) < cutoff_ms
+}
+
+// `text` is complete lines only.
+function partition(text: string, cutoff_ms: number): Partition {
+	const archived: Array<string> = []
+	const kept: Array<string> = []
+	const lines = text.split(LINE_SEPARATOR).slice(0, -1)
+
+	for (const line of lines) {
+		const side = is_past(line, cutoff_ms) ? archived : kept
+
+		side.push(`${line}${LINE_SEPARATOR}`)
+	}
+
+	return { archived: archived.join(''), count: archived.length, kept: kept.join('') }
+}
+
+// The bytes the descriptor's file holds past `from`.
+function bytes_past(descriptor: number, from: number): Buffer {
+	const buffer = Buffer.alloc(Math.max(fstatSync(descriptor).size - from, 0))
+	const read = readSync(descriptor, buffer, 0, buffer.length, from)
+
+	return buffer.subarray(0, read)
+}
+
+// One `O_APPEND` write to a file this account owns, never through a planted link.
+function append_text(target: string, text: Uint8Array): void {
+	const descriptor = openSync(target, APPEND_FLAGS, LEDGER_FILE_MODE)
+
+	try {
+		if (!stamp_file.is_own_regular_file(target)) {
+			throw new Error(`Not an owned regular file: ${target}`)
+		}
+
+		writeSync(descriptor, text)
+	} finally {
+		closeSync(descriptor)
+	}
+}
+
+function size_of(target: string): number {
+	return existsSync(target) ? statSync(target).size : 0
+}
+
+// The old ledger's length the replacement carried.
+function move(ledger: string, moved: Move): number {
+	const archive = archive_of(ledger)
+	const previous = size_of(archive)
+
+	append_text(archive, Buffer.from(moved.archived))
+
+	try {
+		const landed = bytes_past(moved.descriptor, moved.end)
+
+		atomic_write.replace_file(ledger, Buffer.concat([Buffer.from(moved.kept), landed]), {
+			mode: LEDGER_FILE_MODE,
+		})
+
+		return moved.end + landed.length
+	} catch (error) {
+		truncateSync(archive, previous)
+		throw error
+	}
+}
+
+function rotate_open(ledger: string, descriptor: number, cutoff_ms: number): number {
+	const read = bytes_past(descriptor, 0)
+	const end = read.lastIndexOf(LINE_SEPARATOR) + 1
+	const split = partition(read.toString('utf8', 0, end), cutoff_ms)
+
+	if (split.count === 0) return 0
+
+	const carried = move(ledger, { ...split, descriptor, end })
+	const late = bytes_past(descriptor, carried)
+
+	if (late.length > 0) append_text(ledger, late)
+
+	return split.count
+}
+
+function rotate_held(ledger: string, cutoff_ms: number): number {
+	const descriptor = openSync(ledger, READ_FLAGS)
+
+	try {
+		return rotate_open(ledger, descriptor, cutoff_ms)
+	} finally {
+		closeSync(descriptor)
+	}
+}
+
+// The count of records moved: 0 when none is past the retention, the ledger is absent or not this
+// account's, or another rotation holds the lock.
+function rotate(ledger: string, now_ms: number = Date.now()): number {
+	if (!existsSync(ledger) || !stamp_file.is_own_regular_file(ledger)) return 0
+
+	const cutoff_ms = now_ms - RETENTION_DAYS * MS_PER_DAY
+	const lock = `${ledger}${LOCK_SUFFIX}`
+
+	return repository_lock.with_lock_sync(() => rotate_held(ledger, cutoff_ms), lock, NO_WAIT_MS) ?? 0
+}
+
+// This repository's ledger rotated; a test run has no ledger (`lane_ledger.target`).
+async function rotate_target(): Promise<number> {
+	const ledger = await lane_ledger.target()
+
+	return ledger === undefined ? 0 : rotate(ledger)
+}
+
+// The archive's records, then the ledger's — every entry the ledger held before any rotation.
+function history_at(ledger: string): ReadonlyArray<LedgerEntry> {
+	return [...lane_ledger.read_entries(archive_of(ledger)), ...lane_ledger.read_entries(ledger)]
+}
+
+async function read_history(context: ReadContext): Promise<ReadonlyArray<LedgerEntry>> {
+	const ledger = context.ledger_path ?? (await lane_ledger.target())
+
+	return ledger === undefined ? [] : history_at(ledger)
+}
+
+const lane_ledger_archive = { archive_of, history_at, read_history, rotate, rotate_target }
+
+export { lane_ledger_archive }

package/scripts/lane/lane-ledger-kind.ts

@@ -8,12 +8,14 @@ const KIND = {
 	DISPATCH: 'dispatch',
 	STAGE: 'stage',
 	STOP: 'stop',
+	CHAIN: 'chain',
 	OVERLAP: 'overlap',
 	HELD: 'held',
 	RELEASED: 'released',
 	ROUND_ONE: 'round-one',
 	ROUND_TWO: 'round-two',
 	OFFERABLE: 'offerable',
+	OFFER: 'offer',
 	CORE_WAIT: 'core-wait',
 	UNIT_FILES: 'unit-files',
 	TEST_RELATED: 'test-related',
@@ -23,7 +25,10 @@ const KIND = {
 	UNPLANNED_NOTICE: 'unplanned-notice',
 	LANE_STATE: 'lane-state',
 	PUSH_MISS: 'push-miss',
+	EARLY_PUSH: 'early-push',
 	SHIP_LAP: 'ship-lap',
+	SIZE: 'size',
+	LIMIT: 'limit',
 } as const
 
 const lane_ledger_kind = { KIND }

package/scripts/lane/lane-ledger-pinned-origin.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod'
+
+// What started a `josh test:pinned` run (joshuafolkken/kit#5262), in a leaf of its own
+// (joshuafolkken/kit#5334): `test-pinned-ledger.ts` parses `--origin` with it on a path most suites
+// import, so reading it from `lane-ledger-schema.ts` made every ledger schema change reach them.
+const pinned_origin_schema = z.enum(['run-review', 'pre-detach', 'manual'])
+
+const lane_ledger_pinned_origin = { pinned_origin_schema }
+
+export { lane_ledger_pinned_origin }

package/scripts/lane/lane-ledger-schema-load.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod'
+import { lane_ledger_kind } from './lane-ledger-kind'
+
+// The machine-load sample `lane-sampler.ts` writes once a minute, joined into the entry union by
+// `lane-ledger-schema.ts`.
+
+const { KIND } = lane_ledger_kind
+
+// One process kind's summed readings (`lane-process-load.ts`). `footprint_mb` counts the compressed
+// pages `rss_mb` leaves out (joshuafolkken/kit#7244); absent where no footprint could be read, and on
+// rows written before it.
+const process_kind_schema = z.object({
+	kind: z.string(),
+	cpu_percent: z.number(),
+	rss_mb: z.number(),
+	footprint_mb: z.number().optional(),
+	count: z.number(),
+})
+// `available_mb`, `swapped_mb` and `lanes` are optional because each read can fail on its own — a
+// platform with no memory reading, a `git worktree` call that did not answer — and a sample is still
+// worth its load. `swapped_mb` is `machine_capacity`'s counter, every page swapped since boot.
+// Both memory fields were renamed with their meaning (joshuafolkken/kit#3593): an older row's
+// `free_mb` / `swap_mb` are stripped on read, so the two measurements never share a column.
+const load_schema = z.object({
+	kind: z.literal(KIND.LOAD),
+	at: z.string(),
+	load: z.number(),
+	available_mb: z.number().optional(),
+	swapped_mb: z.number().optional(),
+	lanes: z.number().optional(),
+	// The heaviest process kinds at the instant of the sample (`lane-process-load.ts`), so the load the
+	// core budget's ledger does not explain can be read back by what made it (joshuafolkken/kit#3874).
+	processes: z.array(process_kind_schema).optional(),
+	// The resident apps' summed size (`lane_process_load.RESIDENT_APPS`, joshuafolkken/kit#5658).
+	resident_mb: z.number().optional(),
+	// The host's sleep since boot (`lane-load.ts`, joshuafolkken/kit#7026).
+	slept_ms: z.number().optional(),
+	// The boot and last-wake instants, epoch ms (`kern.boottime`, `kern.waketime`).
+	booted_ms: z.number().optional(),
+	woke_ms: z.number().optional(),
+})
+
+const lane_ledger_schema_load = { load_schema }
+
+export { lane_ledger_schema_load }

package/scripts/lane/lane-ledger-schema-offer.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod'
+import { lane_ledger_kind } from './lane-ledger-kind'
+
+// The decision one `backlog:next` ask reached, joined into the entry union by `lane-ledger-schema.ts`
+// (joshuafolkken/kit#7306). `verdict` is the ask's answer — `run`, `triage`, `retry`, `wait`, `stop`,
+// `none` or `error`; `seen` the opted-in issues it read; `started` the numbers it offered; `excluded`
+// each issue it held back and why; `is_unchanged` whether every page of the listing answered 304.
+
+const { KIND } = lane_ledger_kind
+
+const exclusion_schema = z.object({ issue: z.number(), reason: z.string() })
+
+const offer_schema = z.object({
+	kind: z.literal(KIND.OFFER),
+	at: z.string(),
+	verdict: z.string(),
+	seen: z.array(z.number()),
+	started: z.array(z.number()),
+	excluded: z.array(exclusion_schema),
+	is_unchanged: z.boolean(),
+})
+
+type OfferEntry = z.infer<typeof offer_schema>
+type OfferRecord = Omit<OfferEntry, 'kind' | 'at'>
+type OfferExclusion = z.infer<typeof exclusion_schema>
+
+const lane_ledger_schema_offer = { offer_schema }
+
+export type { OfferEntry, OfferExclusion, OfferRecord }
+export { lane_ledger_schema_offer }

package/scripts/lane/lane-ledger-schema-ship.ts

@@ -2,10 +2,19 @@ import { z } from 'zod'
 import { lane_ledger_kind } from './lane-ledger-kind'
 
 // The lane ledger lines `josh ship` writes about itself — a stop, the preflight's `unplanned` notice
-// and the inner steps of a stage — joined into the entry union by `lane-ledger-schema.ts`.
+// and the inner steps of a stage — and each `josh run:chain` ahead of it, joined into the entry union by `lane-ledger-schema.ts`.
 
 const { KIND } = lane_ledger_kind
 
+// Every early-push decision, including a skip before a push process could start.
+const early_push_schema = z.object({
+	kind: z.literal(KIND.EARLY_PUSH),
+	at: z.string(),
+	issue: z.number().optional(),
+	source: z.enum(['review', 'ship']),
+	result: z.string(),
+})
+
 // A `josh ship` that stopped on `issue`: `reason` is the stage it stopped at, or `conflict` — the
 // retrospective's stop reason — and `cause` why (`run-ship-stop-cause.ts`), absent on a stop recorded
 // before it had one. `preconditions` names the kinds a preflight stop found unmet (`run-ship-preflight.ts`),
@@ -13,7 +22,9 @@ const { KIND } = lane_ledger_kind
 // where its `test:pinned` did (joshuafolkken/kit#5228), beside them or alone, absent on any other
 // stop and on one recorded before it had them. `findings` names the `<category>:<severity>` of each
 // finding that decided a review or round-2 stop — the blocking ones, else the fixed ones
-// (joshuafolkken/kit#4426), absent where none decided the stop. How long it stayed stopped is derived
+// (joshuafolkken/kit#4426), absent where none decided the stop. `base` is the change base a review
+// failure or a followup `check` stopped on, so its re-ship can tell a fix-only tree from a moved base
+// (joshuafolkken/kit#6141, joshuafolkken/kit#6675), absent on every other stop. How long it stayed stopped is derived
 // from the next ship stage, not recorded, so a resumed ship never has to know the stop it ends.
 const stop_schema = z.object({
 	kind: z.literal(KIND.STOP),
@@ -23,6 +34,20 @@ const stop_schema = z.object({
 	cause: z.string().optional(),
 	preconditions: z.array(z.string()).optional(),
 	findings: z.array(z.string()).optional(),
+	base: z.string().optional(),
+})
+// One `josh run:chain` on `issue`, done or stopped: `at` is its end and `elapsed_ms` its length, so the
+// next run's start ends the wait after a stop. `stage` names where it stopped and `reason` why — the
+// stage exited non-zero (`exit`) or exited 0 on a notice that holds the run (`hold`) — both absent on a
+// run that finished. `join` marks the half after the review (joshuafolkken/kit#7024).
+const chain_schema = z.object({
+	kind: z.literal(KIND.CHAIN),
+	at: z.string(),
+	issue: z.number(),
+	elapsed_ms: z.number(),
+	join: z.boolean(),
+	stage: z.string().optional(),
+	reason: z.enum(['exit', 'hold']).optional(),
 })
 // The ship's `unplanned` answer `josh check:related` printed to the lane of `issue` ahead of the ship,
 // so a preflight `unplanned` stop after it is told apart in `lane:stats` (joshuafolkken/kit#5203).
@@ -34,7 +59,15 @@ const unplanned_notice_schema = z.object({
 })
 // One inner step of a `josh ship` stage on `issue` — the overlap wait inside `sync`, the scoped pair
 // inside `gate` — so `lane:breakdown` names what a stage spent its time on (joshuafolkken/kit#5294).
-// `at` is its end and `elapsed_ms` its length, as on a stage row.
+// `at` is its end and `elapsed_ms` its length, as on a stage row. `fallback` names why a scoped pair's
+// check read the whole branch change (`since-green.ts`, joshuafolkken/kit#5531). `runs` counts the times
+// this ship process ran the scoped pair's checks, this one included, and `rerun` names why a run after
+// the first ran again (`run-ship-pair-runs.ts`, joshuafolkken/kit#5538) — both absent on a lap that ran none.
+// On a `josh gate` lap `rerun` names why the gate ran and `reused_tree` the tree hash of a gate the ship
+// reused rather than started (`run-ship-gate-runs.ts`, joshuafolkken/kit#5567). On a scoped pair lap
+// `named` counts the files the pair was narrowed to, and `unsplit` is the reason the import graph could
+// not split a merge (`test-related-synced.ts`), both absent where neither happened — read by
+// `lane:stats --pairs` (joshuafolkken/kit#6189), written by the ship (joshuafolkken/kit#6196).
 const ship_lap_schema = z.object({
 	kind: z.literal(KIND.SHIP_LAP),
 	at: z.string(),
@@ -42,8 +75,41 @@ const ship_lap_schema = z.object({
 	stage: z.string(),
 	step: z.string(),
 	elapsed_ms: z.number(),
+	fallback: z.string().optional(),
+	runs: z.number().optional(),
+	rerun: z.string().optional(),
+	reused_tree: z.string().optional(),
+	is_reused: z.boolean().optional(),
+	named: z.number().optional(),
+	unsplit: z.string().optional(),
+})
+
+// A merging `josh followup`'s size of `issue`: the Issue's declared size estimate and the branch's
+// measured diff, test files excluded, so `lane:stats` reads how far estimates miss the guide's
+// counting (joshuafolkken/kit#5384). Written before the merge, while the branch is still checked out.
+// `missed` marks a diff past the split notice bar: a size the pre-dispatch assessment let through, as
+// the started lane is never split (joshuafolkken/kit#7183).
+const counts_schema = z.object({ files: z.number(), lines: z.number() })
+const size_schema = z.object({
+	kind: z.literal(KIND.SIZE),
+	at: z.string(),
+	issue: z.number(),
+	declared: counts_schema,
+	actual: counts_schema,
+	missed: z.boolean().optional(),
 })
 
-const lane_ledger_schema_ship = { ship_lap_schema, stop_schema, unplanned_notice_schema }
+type ChainEntry = z.infer<typeof chain_schema>
+type ChainRecord = Omit<ChainEntry, 'kind' | 'at'>
+
+const lane_ledger_schema_ship = {
+	chain_schema,
+	early_push_schema,
+	ship_lap_schema,
+	size_schema,
+	stop_schema,
+	unplanned_notice_schema,
+}
 
+export type { ChainEntry, ChainRecord }
 export { lane_ledger_schema_ship }