@joshuafolkken/kit 1.1784.0 → 1.2116.0

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

@@ -0,0 +1,31 @@
+// The kind each lane ledger line carries — the discriminant `lane-ledger-schema.ts` parses on, kept
+// apart so a schema module of its own can name its kind without importing the union it joins.
+
+const KIND = {
+	MERGE: 'merge',
+	GATE: 'gate',
+	LOAD: 'load',
+	DISPATCH: 'dispatch',
+	STAGE: 'stage',
+	STOP: 'stop',
+	OVERLAP: 'overlap',
+	HELD: 'held',
+	RELEASED: 'released',
+	ROUND_ONE: 'round-one',
+	ROUND_TWO: 'round-two',
+	OFFERABLE: 'offerable',
+	CORE_WAIT: 'core-wait',
+	UNIT_FILES: 'unit-files',
+	TEST_RELATED: 'test-related',
+	TEST_PINNED: 'test-pinned',
+	SPLIT_NOTICE: 'split-notice',
+	SPLIT_FILED: 'split-filed',
+	UNPLANNED_NOTICE: 'unplanned-notice',
+	LANE_STATE: 'lane-state',
+	PUSH_MISS: 'push-miss',
+	SHIP_LAP: 'ship-lap',
+} as const
+
+const lane_ledger_kind = { KIND }
+
+export { lane_ledger_kind }

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

@@ -0,0 +1,49 @@
+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`.
+
+const { KIND } = lane_ledger_kind
+
+// 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`),
+// with `pre-detach` where a lane child's fast checks went red (joshuafolkken/kit#4478) and `unpinned`
+// 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
+// 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),
+	at: z.string(),
+	issue: z.number(),
+	reason: z.string(),
+	cause: z.string().optional(),
+	preconditions: z.array(z.string()).optional(),
+	findings: z.array(z.string()).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).
+const unplanned_notice_schema = z.object({
+	kind: z.literal(KIND.UNPLANNED_NOTICE),
+	at: z.string(),
+	issue: z.number(),
+	files: z.array(z.string()),
+})
+// 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.
+const ship_lap_schema = z.object({
+	kind: z.literal(KIND.SHIP_LAP),
+	at: z.string(),
+	issue: z.number(),
+	stage: z.string(),
+	step: z.string(),
+	elapsed_ms: z.number(),
+})
+
+const lane_ledger_schema_ship = { ship_lap_schema, stop_schema, unplanned_notice_schema }
+
+export { lane_ledger_schema_ship }

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

@@ -1,23 +1,11 @@
 import { z } from 'zod'
+import { lane_ledger_kind } from './lane-ledger-kind'
+import { lane_ledger_schema_ship } from './lane-ledger-schema-ship'
 
 // The shape of each line `lane-ledger.ts` appends and reads back — one schema per entry kind.
 
-const KIND = {
-	MERGE: 'merge',
-	GATE: 'gate',
-	LOAD: 'load',
-	DISPATCH: 'dispatch',
-	STAGE: 'stage',
-	STOP: 'stop',
-	OVERLAP: 'overlap',
-	HELD: 'held',
-	RELEASED: 'released',
-	ROUND_TWO: 'round-two',
-	OFFERABLE: 'offerable',
-	CORE_WAIT: 'core-wait',
-	UNIT_FILES: 'unit-files',
-	TEST_RELATED: 'test-related',
-} as const
+const { KIND } = lane_ledger_kind
+const { ship_lap_schema, stop_schema, unplanned_notice_schema } = lane_ledger_schema_ship
 
 const merge_schema = z.object({ kind: z.literal(KIND.MERGE), at: z.string(), issue: z.number() })
 const check_schema = z.object({
@@ -55,6 +43,9 @@ const gate_schema = z.object({
 	// A gate that reused a green record for this tree and base and started no check: counted, never
 	// timed (joshuafolkken/kit#4397).
 	is_reused: z.boolean().optional(),
+	// The lane the gate ran in, so `josh lane:breakdown` puts its checks under the lane's ship gate;
+	// absent outside a lane and on a row written before it (joshuafolkken/kit#5319).
+	issue: z.number().optional(),
 })
 // `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
@@ -86,31 +77,17 @@ const dispatch_schema = z.object({
 })
 // One finished stage of a lane's run, passed or failed: `at` is its end and `elapsed_ms` its length, so
 // its start is read from the two. `issue` is absent where the writer does not hold one — `followup`'s
-// CI wait, which is timed on a path that fails before the issue is known.
+// CI wait where the run did not know its issue. On that `ci-wait` row,
+// `check_ms` is each check seen pending and then settled, by the time it settled into the wait, and
+// `last_check` the one that settled last — the wait's critical path (joshuafolkken/kit#5295).
 const stage_schema = z.object({
 	kind: z.literal(KIND.STAGE),
 	at: z.string(),
 	stage: z.string(),
 	elapsed_ms: z.number(),
 	issue: z.number().optional(),
-})
-// 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`),
-// with `pre-detach` where a lane child's fast checks went red beside them (joshuafolkken/kit#4478),
-// 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 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),
-	at: z.string(),
-	issue: z.number(),
-	reason: z.string(),
-	cause: z.string().optional(),
-	preconditions: z.array(z.string()).optional(),
-	findings: z.array(z.string()).optional(),
+	last_check: z.string().optional(),
+	check_ms: z.record(z.string(), z.number()).optional(),
 })
 // A `josh ship` on `issue` whose actual change overlapped the open pull requests of `lanes` on `paths`
 // before its sync: it waited `waited_ms` for their ships to end, and `is_cleared` is false where the
@@ -137,6 +114,23 @@ const held_schema = z.object({
 // The end of a hold no dispatch ended: every lane taken — one opened outside the driver included — or
 // the run finished, so no free lane is owed a child any more.
 const released_schema = z.object({ kind: z.literal(KIND.RELEASED), at: z.string() })
+// A `lane:pause` (`paused`) or `lane:resume` (`running`) of `issue`'s lane, so a measurement reads the
+// time its processes stood stopped (joshuafolkken/kit#5168) — the lane state file keeps only the last.
+const lane_state_schema = z.object({
+	kind: z.literal(KIND.LANE_STATE),
+	at: z.string(),
+	issue: z.number(),
+	state: z.enum(['paused', 'running']),
+})
+// The round 1 a `josh ship` acted on for `issue`: `verdict` is the reviewer's — `clean`, `fixed`,
+// `blocking` — or `reused` where a round recorded before the ship still described the tree, so the
+// period's ship-time rounds that passed with no fix are counted (joshuafolkken/kit#4620).
+const round_one_schema = z.object({
+	kind: z.literal(KIND.ROUND_ONE),
+	at: z.string(),
+	issue: z.number(),
+	verdict: z.string(),
+})
 // One `review:round2` decision a `josh ship` acted on for `issue`: `verdict` and the stable reason
 // `code` it fell under, so the period's skips and runs are counted by why (joshuafolkken/kit#4064).
 const round_two_schema = z.object({
@@ -190,6 +184,55 @@ const test_related_schema = z.object({
 	trigger_files: z.array(z.string()).optional(),
 	elapsed_ms: z.number(),
 })
+// One `josh test:pinned` run that probed (joshuafolkken/kit#5078): `held` hunks the verdict cache
+// answered, and each probed hunk's `file`, the test files it ran (`tests`, absent where vitest wrote no
+// report) and its wall time. `issue` is the lane it ran in, absent outside a lane. `rewired` counts the
+// hunks not probed as an import moved under a new name (joshuafolkken/kit#5235), absent on older rows.
+// `origin` is what started the run, and `discarded` marks a `run:review` background run stopped before
+// its answer, written by the stop with its wall time so far (joshuafolkken/kit#5262); both absent on
+// older rows.
+const pinned_origin_schema = z.enum(['run-review', 'pre-detach', 'manual'])
+const test_pinned_probe_schema = z.object({
+	file: z.string(),
+	tests: z.number().optional(),
+	elapsed_ms: z.number(),
+})
+const test_pinned_schema = z.object({
+	kind: z.literal(KIND.TEST_PINNED),
+	at: z.string(),
+	issue: z.number().optional(),
+	held: z.number(),
+	rewired: z.number().optional(),
+	probes: z.array(test_pinned_probe_schema),
+	elapsed_ms: z.number(),
+	origin: pinned_origin_schema.optional(),
+	discarded: z.boolean().optional(),
+})
+// The split notice shown to the lane of `issue`, with the measured diff it fired on — written once per
+// Issue, by whichever of `josh lint:related`, `test:related` or `main:merge` showed it first
+// (joshuafolkken/kit#4695).
+const split_notice_schema = z.object({
+	kind: z.literal(KIND.SPLIT_NOTICE),
+	at: z.string(),
+	issue: z.number(),
+	files: z.number(),
+	lines: z.number(),
+})
+// One `josh issue:file --route split` filed from the lane of `issue`; `child` is its reference.
+const split_filed_schema = z.object({
+	kind: z.literal(KIND.SPLIT_FILED),
+	at: z.string(),
+	issue: z.number(),
+	child: z.string(),
+})
+// A pre-push hook that could not reuse the green gate record and ran the `whole` or the `related`
+// suite: `reason` is the miss's kind (`hook_gate_reuse.miss_kind`), never its sentence (joshuafolkken/kit#5234).
+const push_miss_schema = z.object({
+	kind: z.literal(KIND.PUSH_MISS),
+	at: z.string(),
+	scope: z.enum(['whole', 'related']),
+	reason: z.string(),
+})
 const entry_schema = z.discriminatedUnion('kind', [
 	merge_schema,
 	gate_schema,
@@ -200,11 +243,19 @@ const entry_schema = z.discriminatedUnion('kind', [
 	overlap_schema,
 	held_schema,
 	released_schema,
+	round_one_schema,
 	round_two_schema,
 	offerable_schema,
 	core_wait_schema,
 	unit_files_schema,
 	test_related_schema,
+	test_pinned_schema,
+	split_notice_schema,
+	split_filed_schema,
+	unplanned_notice_schema,
+	lane_state_schema,
+	push_miss_schema,
+	ship_lap_schema,
 ])
 
 type LedgerEntry = z.infer<typeof entry_schema>
@@ -216,6 +267,7 @@ type StageEntry = z.infer<typeof stage_schema>
 type StopEntry = z.infer<typeof stop_schema>
 type OverlapEntry = z.infer<typeof overlap_schema>
 type HeldEntry = z.infer<typeof held_schema>
+type RoundOneEntry = z.infer<typeof round_one_schema>
 type RoundTwoEntry = z.infer<typeof round_two_schema>
 type OfferableEntry = z.infer<typeof offerable_schema>
 type CoreWaitEntry = z.infer<typeof core_wait_schema>
@@ -224,6 +276,21 @@ type UnitFilesEntry = z.infer<typeof unit_files_schema>
 type UnitFileRecord = z.infer<typeof unit_file_schema>
 type TestRelatedEntry = z.infer<typeof test_related_schema>
 type TestRelatedRecord = Omit<TestRelatedEntry, 'kind' | 'at'>
+type TestPinnedEntry = z.infer<typeof test_pinned_schema>
+type TestPinnedRecord = Omit<TestPinnedEntry, 'kind' | 'at'>
+type SplitNoticeEntry = z.infer<typeof split_notice_schema>
+type SplitNoticeRecord = Omit<SplitNoticeEntry, 'kind' | 'at'>
+type SplitFiledEntry = z.infer<typeof split_filed_schema>
+type SplitFiledRecord = Omit<SplitFiledEntry, 'kind' | 'at'>
+type UnplannedNoticeEntry = z.infer<typeof unplanned_notice_schema>
+type UnplannedNoticeRecord = Omit<UnplannedNoticeEntry, 'kind' | 'at'>
+type LaneStateChangeEntry = z.infer<typeof lane_state_schema>
+type LaneStateChangeRecord = Omit<LaneStateChangeEntry, 'kind' | 'at'>
+type PushMissEntry = z.infer<typeof push_miss_schema>
+type PushMissRecord = Omit<PushMissEntry, 'kind' | 'at'>
+type ShipLapEntry = z.infer<typeof ship_lap_schema>
+type ShipLapRecord = Omit<ShipLapEntry, 'kind' | 'at'>
+type RoundOneRecord = Omit<RoundOneEntry, 'kind' | 'at'>
 type RoundTwoRecord = Omit<RoundTwoEntry, 'kind' | 'at'>
 // What a finished gate reports; the ledger stamps the kind and the time.
 type GateRecord = Omit<GateEntry, 'kind' | 'at'>
@@ -235,7 +302,7 @@ type HeldRecord = Omit<HeldEntry, 'kind' | 'at' | 'waiting'> & {
 	waiting?: ReadonlyArray<number> | undefined
 }
 
-const lane_ledger_schema = { KIND, entry_schema }
+const lane_ledger_schema = { KIND, entry_schema, pinned_origin_schema }
 
 export type {
 	CoreWaitEntry,
@@ -246,21 +313,37 @@ export type {
 	GateRecord,
 	HeldEntry,
 	HeldRecord,
+	LaneStateChangeEntry,
+	LaneStateChangeRecord,
 	LedgerEntry,
 	LoadEntry,
 	MergeEntry,
 	OfferableEntry,
 	OverlapEntry,
 	OverlapRecord,
+	PushMissEntry,
+	PushMissRecord,
+	RoundOneEntry,
+	RoundOneRecord,
 	RoundTwoEntry,
 	RoundTwoRecord,
+	ShipLapEntry,
+	ShipLapRecord,
+	SplitFiledEntry,
+	SplitFiledRecord,
+	SplitNoticeEntry,
+	SplitNoticeRecord,
 	StageEntry,
 	StageRecord,
 	StopEntry,
 	StopRecord,
+	TestPinnedEntry,
+	TestPinnedRecord,
 	TestRelatedEntry,
 	TestRelatedRecord,
 	UnitFileRecord,
 	UnitFilesEntry,
+	UnplannedNoticeEntry,
+	UnplannedNoticeRecord,
 }
 export { lane_ledger_schema }

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

@@ -0,0 +1,257 @@
+import { closeSync, constants, openSync, writeSync } from 'node:fs'
+import { durable_state } from '#scripts/josh/durable-state'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { run_carry } from '#scripts/run/carry/run-carry'
+import {
+	lane_ledger_schema,
+	type CoreWaitRecord,
+	type GateRecord,
+	type HeldRecord,
+	type LaneStateChangeRecord,
+	type LedgerEntry,
+	type OverlapRecord,
+	type PushMissRecord,
+	type RoundOneRecord,
+	type RoundTwoRecord,
+	type ShipLapRecord,
+	type SplitFiledRecord,
+	type SplitNoticeRecord,
+	type StageRecord,
+	type StopRecord,
+	type TestPinnedRecord,
+	type TestRelatedRecord,
+	type UnitFileRecord,
+	type UnplannedNoticeRecord,
+} from './lane-ledger-schema'
+
+// The measurement ledger the lane limit is tuned against: one JSON line per
+// lane merge, per finished `josh gate`, per machine-load sample, per lane dispatch, per finished
+// `josh ship` stage, per stopped `josh ship`, per round-2 decision, per core-budget wait and per
+// `josh test:related` run, read back by `josh lane:stats` through `lane-ledger.ts`. Each line's shape
+// is `lane-ledger-schema.ts`.
+//
+// **The writers' leaf, apart from the reader** (joshuafolkken/kit#5202). The gate, `followup`, `josh
+// ship`, the dispatch and the backlog driver write here, and dozens of suites import them; the reading
+// and the measurement modules built on it import `lane-ledger.ts`, so a change there no longer reaches
+// every suite a writer sits under.
+//
+// **Its own file rather than the run's event stream.** The stream is capped at 500 events and is
+// rewritten whole on every append, which is right for "where is the run" and wrong for a measurement
+// that spans days of one-a-minute load samples. This file is only ever appended to, so concurrent lanes
+// never lose each other's lines to a read-modify-write race.
+//
+// **Keyed on the common git directory, the event stream's key**, so a lane child's gate, the parent's
+// merge and the sampler all land in one ledger per repository. It is a durable record
+// (`durable-state.ts`), so a period runs across a reboot.
+
+const LEDGER_PREFIX = durable_state.PREFIX.LANE_LEDGER
+const LEDGER_SUFFIX = '.jsonl'
+const LINE_SEPARATOR = '\n'
+// `followup`'s wait for CI — a stage of a lane's run that no `josh ship` stage is the whole of.
+const CI_WAIT_STAGE = 'ci-wait'
+// The part of `followup`'s waits CodeRabbit spent running or rate-limited, and the rate-limited part
+// alone (joshuafolkken/kit#4574).
+const CODERABBIT_WAIT_STAGE = 'coderabbit-wait'
+const CODERABBIT_RATE_LIMIT_STAGE = 'coderabbit-rate-limit'
+// The rate-limit window `followup` waited out before posting its one `@coderabbitai review`
+// (joshuafolkken/kit#5289).
+const CODERABBIT_RETRIGGER_STAGE = 'coderabbit-retriggered'
+// A detached `josh ship`'s fast checks in the agent's own turn — not a resumable ship stage, since the
+// supervised gate runs them again (joshuafolkken/kit#4382).
+const PRE_DETACH_STAGE = 'pre-detach'
+// A ship's round 1 that reused a recorded review instead of running one (joshuafolkken/kit#4620).
+const ROUND_ONE_REUSED = 'reused'
+const LEDGER_FILE_MODE = 0o600
+// The flags `detached-launch.ts` appends its log with, for the same deterministic shared-temp path.
+const { O_APPEND, O_CREAT, O_NOFOLLOW, 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
+
+const { KIND } = lane_ledger_schema
+
+function target_of(repository: string): string {
+	return durable_state.path(LEDGER_PREFIX, repository, LEDGER_SUFFIX)
+}
+
+// The ledger of the repository this checkout belongs to, or `undefined` outside one. `git rev-parse`
+// rejects outside a repository, and `josh gate` resolves this before it runs a check, so the rejection
+// is read as "no ledger" rather than allowed to fail the gate it would only have measured.
+//
+// **A test run has no ledger either.** The writers sit on paths dozens of suites exercise — a ship
+// stage, a dispatch, a `followup` — and one suite that forgot to mock this module would append its
+// fixture durations to the real measurement; a test that writes passes its own path instead.
+async function target(): Promise<string | undefined> {
+	if (process.env['VITEST'] !== undefined) return undefined
+
+	try {
+		const repository = await run_carry.repository_directory()
+
+		return repository === undefined ? undefined : target_of(repository)
+	} catch {
+		return undefined
+	}
+}
+
+// **Append, never rewrite** — `O_APPEND` keeps each short line whole across concurrent writers, and
+// `O_NOFOLLOW` plus `stamp_file`'s ownership test keep a planted link or another account's file from
+// receiving it. Any JSON-lines log takes it — the durable review stop log too (joshuafolkken/kit#4519).
+function append(path: string, entry: object): void {
+	const descriptor = openSync(path, APPEND_FLAGS, LEDGER_FILE_MODE)
+
+	try {
+		if (stamp_file.is_own_regular_file(path)) {
+			writeSync(descriptor, `${JSON.stringify(entry)}${LINE_SEPARATOR}`)
+		}
+	} finally {
+		closeSync(descriptor)
+	}
+}
+
+// Best-effort: a measurement must never fail the gate or the merge it measures, so every error — no
+// repository, an unwritable temp root — is dropped.
+async function record(entry: LedgerEntry, path?: string): Promise<void> {
+	try {
+		const destination = path ?? (await target())
+
+		if (destination !== undefined) append(destination, entry)
+	} catch {
+		// Reporting is best-effort: a failed append is dropped rather than raised into the caller's work.
+	}
+}
+
+function now_iso(): string {
+	return new Date().toISOString()
+}
+
+// One finished `josh gate`, whether it passed or not — a failing gate cost the lane its time as well.
+async function record_gate(path: string, gate: GateRecord): Promise<void> {
+	await record({ kind: KIND.GATE, at: now_iso(), ...gate }, path)
+}
+
+async function record_merge(issue: number, at: Date = new Date()): Promise<void> {
+	await record({ kind: KIND.MERGE, at: at.toISOString(), issue })
+}
+
+async function record_dispatch(issue: number, path?: string): Promise<void> {
+	await record({ kind: KIND.DISPATCH, at: now_iso(), issue }, path)
+}
+
+async function record_stage(stage: StageRecord, path?: string): Promise<void> {
+	await record({ kind: KIND.STAGE, at: now_iso(), ...stage }, path)
+}
+
+async function record_stop(stop: StopRecord, path?: string): Promise<void> {
+	await record({ kind: KIND.STOP, at: now_iso(), ...stop }, path)
+}
+
+async function record_overlap(overlap: OverlapRecord, path?: string): Promise<void> {
+	await record({ kind: KIND.OVERLAP, at: now_iso(), ...overlap }, path)
+}
+
+// `waiting` is written only when the offer named issues, so a hold that waited on none stays one short line.
+async function record_held(held: HeldRecord, path?: string): Promise<void> {
+	const waiting = held.waiting ?? []
+	const named = waiting.length > 0 ? { waiting: [...waiting] } : {}
+
+	await record({ kind: KIND.HELD, at: now_iso(), reason: held.reason, ...named }, path)
+}
+
+async function record_released(path?: string): Promise<void> {
+	await record({ kind: KIND.RELEASED, at: now_iso() }, path)
+}
+
+async function record_lane_state(change: LaneStateChangeRecord, path?: string): Promise<void> {
+	await record({ kind: KIND.LANE_STATE, at: now_iso(), ...change }, path)
+}
+
+async function record_offerable(is_offerable: boolean, path?: string): Promise<void> {
+	await record({ kind: KIND.OFFERABLE, at: now_iso(), is_offerable }, path)
+}
+
+async function record_round_one(round_one: RoundOneRecord, path?: string): Promise<void> {
+	await record({ kind: KIND.ROUND_ONE, at: now_iso(), ...round_one }, path)
+}
+
+async function record_round_two(round_two: RoundTwoRecord, path?: string): Promise<void> {
+	await record({ kind: KIND.ROUND_TWO, at: now_iso(), ...round_two }, path)
+}
+
+async function record_core_wait(wait: CoreWaitRecord, path?: string): Promise<void> {
+	await record({ kind: KIND.CORE_WAIT, at: now_iso(), ...wait }, path)
+}
+
+async function record_unit_files(
+	files: ReadonlyArray<UnitFileRecord>,
+	path?: string,
+): Promise<void> {
+	await record({ kind: KIND.UNIT_FILES, at: now_iso(), files: [...files] }, path)
+}
+
+async function record_test_related(run: TestRelatedRecord, path?: string): Promise<void> {
+	await record({ kind: KIND.TEST_RELATED, at: now_iso(), ...run }, path)
+}
+
+async function record_test_pinned(run: TestPinnedRecord, path?: string): Promise<void> {
+	await record({ kind: KIND.TEST_PINNED, at: now_iso(), ...run }, path)
+}
+
+async function record_split_notice(notice: SplitNoticeRecord, path?: string): Promise<void> {
+	await record({ kind: KIND.SPLIT_NOTICE, at: now_iso(), ...notice }, path)
+}
+
+async function record_split_filed(filed: SplitFiledRecord, path?: string): Promise<void> {
+	await record({ kind: KIND.SPLIT_FILED, at: now_iso(), ...filed }, path)
+}
+
+async function record_push_miss(miss: PushMissRecord, path?: string): Promise<void> {
+	await record({ kind: KIND.PUSH_MISS, at: now_iso(), ...miss }, path)
+}
+
+async function record_ship_lap(lap: ShipLapRecord, path?: string): Promise<void> {
+	await record({ kind: KIND.SHIP_LAP, at: now_iso(), ...lap }, path)
+}
+
+async function record_unplanned_notice(
+	notice: UnplannedNoticeRecord,
+	path?: string,
+): Promise<void> {
+	await record({ kind: KIND.UNPLANNED_NOTICE, at: now_iso(), ...notice }, path)
+}
+
+const lane_ledger_write = {
+	CI_WAIT_STAGE,
+	CODERABBIT_RATE_LIMIT_STAGE,
+	CODERABBIT_RETRIGGER_STAGE,
+	CODERABBIT_WAIT_STAGE,
+	KIND,
+	LINE_SEPARATOR,
+	PRE_DETACH_STAGE,
+	ROUND_ONE_REUSED,
+	append,
+	record,
+	record_core_wait,
+	record_dispatch,
+	record_gate,
+	record_held,
+	record_lane_state,
+	record_released,
+	record_merge,
+	record_overlap,
+	record_offerable,
+	record_push_miss,
+	record_round_one,
+	record_round_two,
+	record_ship_lap,
+	record_split_filed,
+	record_split_notice,
+	record_stage,
+	record_stop,
+	record_test_pinned,
+	record_test_related,
+	record_unit_files,
+	record_unplanned_notice,
+	target,
+	target_of,
+}
+
+export { lane_ledger_write }