@joshuafolkken/kit 1.921.0 → 1.947.0

package/scripts/init/project-profile.ts

@@ -1,6 +1,7 @@
 import { existsSync, readdirSync, readFileSync, type Dirent } from 'node:fs'
 import path from 'node:path'
 import { repo_origin } from '#scripts/discovery/repo-origin'
+import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
 import { execaSync } from 'execa'
 
 type ProjectProfile = 'static' | 'node'
@@ -52,10 +53,6 @@ function read_manifest(root: string): Record<string, unknown> | undefined {
 	return parsed as Record<string, unknown>
 }
 
-function has_entries(value: unknown): boolean {
-	return typeof value === 'object' && value !== null && Object.keys(value).length > 0
-}
-
 function is_record(value: unknown): value is Record<string, unknown> {
 	return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
@@ -70,8 +67,20 @@ function has_build_script(value: unknown): boolean {
 	return is_record(value) && ('build' in value || 'dev' in value)
 }
 
+// kit itself is not evidence of a Node toolchain: `pnpm add -D @joshuafolkken/kit` before
+// `josh init` is the documented order, and it must still leave an `index.html` site static
+// (joshuafolkken/kit#2693).
+function has_project_dependencies(value: unknown): boolean {
+	if (!is_record(value)) return false
+
+	return Object.keys(value).some((name) => name !== KIT_PACKAGE_NAME)
+}
+
 function inferred_profile(manifest: Record<string, unknown>): ProfileResult {
-	if (has_entries(manifest['dependencies']) || has_entries(manifest['devDependencies'])) {
+	if (
+		has_project_dependencies(manifest['dependencies']) ||
+		has_project_dependencies(manifest['devDependencies'])
+	) {
 		return { profile: 'node', reason: 'package dependencies' }
 	}
 

package/scripts/issue/issue-merged.ts

@@ -0,0 +1,75 @@
+import { git_gh_api_path } from '#scripts/git/git-gh-api-path'
+import { git_gh_exec } from '#scripts/git/git-gh-exec'
+
+// Whether an issue was closed by a merge, read from its REST timeline (joshuafolkken/kit#2701). The
+// issue's own `state_reason` cannot tell: a pull request's `closes #N` and a person's "Close as
+// completed" both answer `completed`. What only a merge leaves is a merged pull request referencing
+// the issue, so the answer is the conjunction — closed now, as completed, and referenced by a merged
+// pull request. A manual "completed" close still reads as merged when a merged pull request also
+// references the issue — the one case the timeline cannot separate — and every other doubt falls to
+// `false`, because a sweep deletes work on this answer.
+
+const CLOSED_EVENT = 'closed'
+const REOPENED_EVENT = 'reopened'
+const MERGED_REFERENCE = 'merged-reference'
+// A close by a pull request's `closes #N` carries no reason in the timeline; a person's "Close as
+// completed" carries `completed`. Any other reason — `not_planned`, `duplicate` — is not a merge, and
+// neither is one GitHub adds later.
+const COMPLETED_REASONS: ReadonlySet<string> = new Set(['', 'completed'])
+const FIELD_SEPARATOR = '\t'
+const LINE_SEPARATOR = '\n'
+// One `<event>\t<state_reason>` line per closed/reopened event, and a `merged-reference` line per
+// merged pull request that cross-references the issue — the three kinds the answer reads.
+const TIMELINE_FILTER = [
+	'.[]',
+	'| if .event == "cross-referenced" and .source.issue.pull_request.merged_at != null',
+	String.raw`then "${MERGED_REFERENCE}\t"`,
+	`elif .event == "${CLOSED_EVENT}" or .event == "${REOPENED_EVENT}"`,
+	String.raw`then "\(.event)\t\(.state_reason // "")"`,
+	'else empty end',
+].join(' ')
+
+interface TimelineRow {
+	event: string
+	reason: string
+}
+
+function parse_rows(raw: string): Array<TimelineRow> {
+	return raw
+		.split(LINE_SEPARATOR)
+		.filter((line) => line !== '')
+		.map((line) => {
+			const [event = '', reason = ''] = line.split(FIELD_SEPARATOR)
+
+			return { event, reason }
+		})
+}
+
+// The last closed/reopened event is the issue's current state, so a reopened issue is not merged
+// even with a merged reference from an earlier attempt.
+function is_merged_close(rows: ReadonlyArray<TimelineRow>): boolean {
+	const last = rows.findLast((row) => row.event === CLOSED_EVENT || row.event === REOPENED_EVENT)
+
+	if (last?.event !== CLOSED_EVENT || !COMPLETED_REASONS.has(last.reason)) return false
+
+	return rows.some((row) => row.event === MERGED_REFERENCE)
+}
+
+async function read_merged(issue: string): Promise<boolean> {
+	try {
+		const raw = await git_gh_exec.exec_gh_api({
+			path: `${git_gh_api_path.issue_api_path(issue)}/timeline?per_page=100`,
+			should_paginate: true,
+			jq_filter: TIMELINE_FILTER,
+		})
+
+		return is_merged_close(parse_rows(raw))
+	} catch {
+		return false
+	}
+}
+
+const issue_merged = { is_merged_close, parse_rows, read_merged }
+
+export type { TimelineRow }
+export { issue_merged }

package/scripts/issue/measure-rerun-cli.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env tsx
 import { execSync } from 'node:child_process'
-import { appendFile, readFile } from 'node:fs/promises'
+import { readFile } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'
 import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
 import { baseline_measure, type Baseline } from './baseline-measure'
@@ -47,7 +47,7 @@ async function append_ledger(lines: ReadonlyArray<string>): Promise<void> {
 	// (joshuafolkken/kit#2419).
 	const ledger_path = observation_ledger_home.ledger_path()
 
-	await appendFile(ledger_path, `${lines.join('\n')}\n`, 'utf8')
+	await observation_ledger_home.append(ledger_path, lines)
 	console.info(`Recorded ${String(lines.length)} refuted premise(s) in ${ledger_path}.`)
 }
 

package/scripts/josh/__snapshots__/josh-command-map.test.ts.snap

@@ -116,6 +116,7 @@ exports[`COMMAND_MAP — reference metadata > keeps every canonical command and
     "rsp": "run:step",
     "rst": "run:status",
     "rt": "reconcile-templates",
+    "rtd": "run:tidy",
     "rtl": "run:tail",
     "rtr": "retrospective",
     "rug": "rule:guard",
@@ -1041,6 +1042,15 @@ exports[`COMMAND_MAP — reference metadata > keeps every canonical command and
         "network",
       ],
     ],
+    "run:tidy": [
+      "",
+      "automation",
+      [
+        "git",
+        "network",
+        "files",
+      ],
+    ],
     "run:wake": [
       "[options]",
       "automation",

package/scripts/josh/josh-command-map.ts

@@ -135,6 +135,7 @@ const ALIASES: Record<string, string> = {
 	rh: 'run:hold',
 	rr: 'run:release',
 	rc: 'run:carry',
+	rtd: 'run:tidy',
 	rw: 'run:wake',
 	rct: 'run:cut',
 	rv: 'run:liveness',

package/scripts/josh/josh-command-types.ts

@@ -69,8 +69,6 @@ interface CommandEntry {
 // (joshuafolkken/kit#914).
 const GATE_COMMAND = 'gate'
 
-const PE = ['pnpm', 'exec'] as const
-
 // joshuafolkken/kit#1256: three of the gate's four checks keep a content-addressed cache, so a
 // second run reads only what changed. eslint had one from the start; the type check and the spell
 // check rescanned the whole tree every time, which cost 10.5s of CPU against 2.8s cached.
@@ -219,7 +217,6 @@ export {
 	GATE_COMMAND,
 	IGNORED_CACHE_FILES,
 	OPTIONAL_ENV_FILE_FLAGS,
-	PE,
 	SHARED_CACHE_SPECS,
 	TS_BUILD_INFO_FILE,
 	TS_CACHE_FLAGS,

package/scripts/josh/josh-commands-ai.ts

@@ -147,6 +147,12 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['[issue|--force]', 'automation', ['files']],
 		default_script_arguments: ['--release'],
 	},
+	'run:tidy': {
+		script: 'scripts/run/run-tidy-cli.ts',
+		description: 'Close merged lanes and drop stashes whose issues are all merged',
+		category: 'AI tools',
+		reference: ['', 'automation', ['git', 'network', 'files']],
+	},
 	'run:carry': {
 		script: 'scripts/run/run-carry-cli.ts',
 		description: 'Carry one invocation’s budget across its own session cuts',

package/scripts/josh/josh-commands-development.ts

@@ -1,10 +1,4 @@
-import {
-	ESLINT_CACHE_FLAGS,
-	GATE_COMMAND,
-	PE,
-	TS_CACHE_FLAGS,
-	type CommandEntry,
-} from './josh-command-types'
+import { GATE_COMMAND, type CommandEntry } from './josh-command-types'
 
 const FILE_ARGUMENTS = '[files...]'
 const REQUIRED_FILE_ARGUMENTS = '<files...>'
@@ -28,7 +22,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 	},
 	lint: {
 		script: 'scripts/lint/lint-parallel.ts',
-		description: 'Check code with prettier and eslint',
+		description: 'Check code with prettier and eslint (skips a tool a static project lacks)',
 		category: 'Development',
 		reference: ['', 'developer', ['processes']],
 	},
@@ -66,15 +60,8 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['', 'developer', ['none']],
 	},
 	format: {
-		// prettier first here, unlike `format:edited`, and deliberately: `eslint --fix` exits 1
-		// whenever a non-autofixable error remains, so putting it first behind `&&` would mean one
-		// unused variable anywhere in the tree stops prettier from running at all.
-		shell: [
-			'sh',
-			'-c',
-			`pnpm exec prettier --write . && pnpm exec eslint . --fix ${ESLINT_CACHE_FLAGS.join(' ')}`,
-		],
-		description: 'Format code with prettier and eslint',
+		script: 'scripts/lint/format.ts',
+		description: 'Format code with prettier and eslint (skips a tool a static project lacks)',
 		category: 'Development',
 		reference: ['', 'developer', ['files', 'processes']],
 	},
@@ -195,8 +182,8 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		argument_targets: ['test:unit', 'test:e2e'],
 	},
 	check: {
-		shell: [...PE, 'tsc', '--noEmit', ...TS_CACHE_FLAGS],
-		description: 'Type-check TypeScript project',
+		script: 'scripts/gate/type-check-command.ts',
+		description: 'Type-check with tsc (skips a static project with no TypeScript to check)',
 		category: 'Development',
 		reference: ['[arguments...]', 'developer', ['processes']],
 	},

package/scripts/lint/format.ts

@@ -0,0 +1,68 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { project_checks } from '#scripts/gate/project-checks'
+import { ESLINT_CACHE_FLAGS } from '#scripts/josh/josh-command-types'
+import { composite_arguments, USAGE_ERROR_EXIT_CODE } from '#scripts/josh/josh-composite-arguments'
+import { execa } from 'execa'
+
+const COMMAND_NAME = 'format'
+const ARGV_OFFSET = 2
+const FAIL_EXIT_CODE = 1
+const PRETTIER_ARGS = ['exec', 'prettier', '--write', '.'] as const
+const ESLINT_FIX_ARGS = ['exec', 'eslint', '.', '--fix', ...ESLINT_CACHE_FLAGS] as const
+
+async function run_step(args: ReadonlyArray<string>, directory: string): Promise<number> {
+	const result = await execa('pnpm', args, { cwd: directory, stdio: 'inherit', reject: false })
+
+	return result.exitCode ?? FAIL_EXIT_CODE
+}
+
+// prettier first, deliberately: `eslint --fix` exits 1 whenever a non-autofixable error remains, so
+// putting it first would mean one unused variable anywhere in the tree stops prettier from running.
+// A static project without Prettier or ESLint is skipped with the same reason `josh lint` prints
+// (joshuafolkken/kit#2693, joshuafolkken/kit#2606).
+async function run_unless_skipped(
+	check: string,
+	reason: string | undefined,
+	args: ReadonlyArray<string>,
+	directory: string,
+): Promise<number> {
+	if (reason === undefined) return await run_step(args, directory)
+	console.info(project_checks.skip_notice(check, reason))
+
+	return 0
+}
+
+async function run_format(directory: string): Promise<number> {
+	const prettier_reason = project_checks.prettier_skip_reason(directory)
+	const prettier_exit_code = await run_unless_skipped(
+		'prettier',
+		prettier_reason,
+		PRETTIER_ARGS,
+		directory,
+	)
+	if (prettier_exit_code !== 0) return prettier_exit_code
+	const eslint_reason = project_checks.eslint_skip_reason(directory)
+
+	return await run_unless_skipped('eslint', eslint_reason, ESLINT_FIX_ARGS, directory)
+}
+
+// The argument refusal survives leaving the `sh -c` composite shape: both tools run over the whole
+// tree, so a path passed here would be silently discarded and every file rewritten instead.
+async function run(argv: ReadonlyArray<string>, directory: string): Promise<number> {
+	if (argv.length > 0) {
+		console.error(composite_arguments.format_rejection(COMMAND_NAME, []))
+
+		return USAGE_ERROR_EXIT_CODE
+	}
+
+	return await run_format(directory)
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	process.exitCode = await run(process.argv.slice(ARGV_OFFSET), process.cwd())
+}
+
+const format = { run, run_format }
+
+export { ESLINT_FIX_ARGS, format }

package/scripts/lint/lint-parallel.ts

@@ -34,32 +34,25 @@ function skipped(check: string, reason: string): BufferedProcessResult {
 	return { output: `${project_checks.skip_notice(check, reason)}\n`, exit_code: 0, elapsed_ms: 0 }
 }
 
-async function run_static_prettier(directory: string): Promise<BufferedProcessResult> {
-	if (!project_checks.has_files(directory, project_checks.WEB_FILES)) {
-		return skipped('prettier', 'no HTML, CSS or JavaScript files were found')
-	}
-
-	if (!project_checks.has_bin(directory, 'prettier')) {
-		return skipped('prettier', 'prettier is not installed')
-	}
+async function run_prettier(
+	directory: string,
+	prettier_args: ReadonlyArray<string>,
+): Promise<BufferedProcessResult> {
+	const reason = project_checks.prettier_skip_reason(directory)
+	if (reason !== undefined) return skipped('prettier', reason)
 
-	return await buffered_process.run_buffered_process(PRETTIER_ARGS)
+	return await buffered_process.run_buffered_process(prettier_args)
 }
 
-async function run_static_eslint(directory: string): Promise<BufferedProcessResult> {
-	if (!project_checks.has_files(directory, project_checks.SCRIPT_FILES)) {
-		return skipped('eslint', 'no JavaScript or TypeScript files were found')
-	}
-
-	if (!project_checks.has_config(directory, project_checks.ESLINT_CONFIGS)) {
-		return skipped('eslint', 'no ESLint configuration was found')
-	}
-
-	if (!project_checks.has_bin(directory, 'eslint')) {
-		return skipped('eslint', 'eslint is not installed')
-	}
+async function run_checked_eslint(
+	directory: string,
+	eslint_args: ReadonlyArray<string>,
+	cache_file: string,
+): Promise<BufferedProcessResult> {
+	const reason = project_checks.eslint_skip_reason(directory)
+	if (reason !== undefined) return skipped('eslint', reason)
 
-	return await run_eslint(ESLINT_ARGS, ESLINT_CACHE_FILE)
+	return await run_eslint(eslint_args, cache_file)
 }
 
 function lint_exit_code(prettier: BufferedProcessResult, eslint: BufferedProcessResult): number {
@@ -70,15 +63,19 @@ function lint_exit_code(prettier: BufferedProcessResult, eslint: BufferedProcess
 
 // The two checks are run from here whether they were pointed at the whole tree or at one change's
 // files, so `josh lint:related` reaches prettier and eslint through the same buffering, the same
-// "one failure does not abort the other" reading, and the same exit code (joshuafolkken/kit#1298).
+// "one failure does not abort the other" reading, and the same exit code (joshuafolkken/kit#1298) —
+// and through the same static-project skip, so a narrowed run never reaches a tool the whole-tree
+// run would have skipped (joshuafolkken/kit#2709). The skip reasons answer nothing for a node
+// project, so the one path serves both profiles.
 async function run_lint_checks(
 	prettier_args: ReadonlyArray<string>,
 	eslint_args: ReadonlyArray<string>,
 	eslint_cache_file: string = ESLINT_CACHE_FILE,
 ): Promise<number> {
+	const directory = process.cwd()
 	const [prettier, eslint] = await Promise.all([
-		buffered_process.run_buffered_process(prettier_args),
-		run_eslint(eslint_args, eslint_cache_file),
+		run_prettier(directory, prettier_args),
+		run_checked_eslint(directory, eslint_args, eslint_cache_file),
 	])
 
 	write_output(prettier)
@@ -88,17 +85,7 @@ async function run_lint_checks(
 }
 
 async function run_lint_parallel_checks(): Promise<number> {
-	const directory = process.cwd()
-	if (!project_checks.is_static(directory)) return await run_lint_checks(PRETTIER_ARGS, ESLINT_ARGS)
-	const [prettier, eslint] = await Promise.all([
-		run_static_prettier(directory),
-		run_static_eslint(directory),
-	])
-
-	write_output(prettier)
-	write_output(eslint)
-
-	return lint_exit_code(prettier, eslint)
+	return await run_lint_checks(PRETTIER_ARGS, ESLINT_ARGS)
 }
 
 // `process.exitCode` rather than `process.exit()`: both reports are buffered and written here in

package/scripts/observations/observation-ledger-home.ts

@@ -1,6 +1,8 @@
+import { appendFile, mkdir } from 'node:fs/promises'
 import path from 'node:path'
 import { repo_discovery } from '#scripts/discovery/repo-discovery'
 import { OBSERVATION_LEDGER_PATH } from './observation-ledger'
+import { observation_ledger_migrate } from './observation-ledger-migrate'
 
 // Where the observation ledger is read and written, whichever work tree a command runs in
 // (joshuafolkken/kit#2419).
@@ -23,10 +25,28 @@ function is_lane(cwd: string = process.cwd()): boolean {
 	return path.resolve(ledger_root(cwd)) !== path.resolve(cwd)
 }
 
+// **Resolving the path migrates the ledger first** (joshuafolkken/kit#2724). Every reader and writer
+// asks here — `review:record --check`, `review:findings`, the retrospective, the stash carry's
+// duplicate check — so none of them can read an empty new ledger while the lines still sit at the old
+// path, which for the review-record check would answer `not-required` for a round never recorded.
 function ledger_path(cwd: string = process.cwd()): string {
-	return path.join(ledger_root(cwd), OBSERVATION_LEDGER_PATH)
+	const root = ledger_root(cwd)
+
+	observation_ledger_migrate.migrate(root)
+
+	return path.join(root, OBSERVATION_LEDGER_PATH)
+}
+
+// The one append every ledger writer goes through. A consumer that does not keep the ledger has no
+// `docs/` at its root, so the parent is created first — the one write path that can bring the ledger
+// into existence there (joshuafolkken/kit#2402).
+async function append(target: string, lines: ReadonlyArray<string>): Promise<void> {
+	if (lines.length === 0) return
+
+	await mkdir(path.dirname(target), { recursive: true })
+	await appendFile(target, `${lines.join('\n')}\n`, 'utf8')
 }
 
-const observation_ledger_home = { is_lane, ledger_path, ledger_root }
+const observation_ledger_home = { append, is_lane, ledger_path, ledger_root }
 
 export { observation_ledger_home }

package/scripts/observations/observation-ledger-line.ts

@@ -83,10 +83,21 @@ function broken_ledger_lines(content: string): ReadonlyArray<BrokenLine> {
 		.filter((entry): entry is BrokenLine => entry.reason !== undefined)
 }
 
+// The lines of `candidates` the ledger does not already hold, in their order. The ledger is
+// append-only and the digest counts repeats, so every path that moves lines into it — the stash carry
+// (`run-tidy.ts`) and the old-path migration (`observation-ledger-migrate.ts`) — asks this rather than
+// appending blind: the same line arriving twice would read as a recurrence.
+function missing_lines(candidates: ReadonlyArray<string>, ledger: string): Array<string> {
+	const present = new Set(ledger.split('\n'))
+
+	return candidates.filter((line) => !present.has(line))
+}
+
 const observation_ledger_line = {
 	broken_ledger_lines,
 	is_ledger_entry_line,
 	line_reason,
+	missing_lines,
 }
 
 export type { BrokenLine }

package/scripts/observations/observation-ledger-migrate.ts

@@ -0,0 +1,146 @@
+import { appendFileSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync } from 'node:fs'
+import path from 'node:path'
+import {
+	LEGACY_OBSERVATION_LEDGER_PATH,
+	MIGRATION_CLAIM_SUFFIX,
+	OBSERVATION_LEDGER_PATH,
+} from './observation-ledger'
+import { observation_ledger_line } from './observation-ledger-line'
+
+// Moves the ledger's lines from the path it had before joshuafolkken/kit#2724 to the one it has now
+// (`observation-ledger.ts` carries why both are recognized). Changing the constant alone split the
+// appends across two files: a run still on the old code recreated `docs/observations.md`, and a
+// consumer repository's existing ledger stayed where nothing read it. So resolving the ledger's path
+// migrates first (`observation-ledger-home.ts`), and whatever reached the old path lands at the tail
+// of the new one before anything reads or appends.
+//
+// **The old file is claimed with a rename before it is read.** Two sessions resolving the ledger at
+// once would otherwise both read it and both copy its lines — and a repeated line under one key is
+// what promotes an observation to an issue. A rename succeeds for exactly one of them; the other finds
+// nothing.
+//
+// **A claim whose process is gone is absorbed like the old file itself.** A process killed between the
+// rename and the append leaves the ledger's lines only in the claim file; the next migration finds it
+// by its name and moves it, so no line is stranded where nothing looks.
+//
+// **Synchronous on purpose**: the path resolver every reader and writer calls is synchronous, and a
+// migration with no await point cannot be interleaved with another write in the same process.
+
+const NEWLINE = '\n'
+const NO_SIGNAL = 0
+const NO_SUCH_PROCESS = 'ESRCH'
+
+function claim_path(legacy: string): string {
+	return `${legacy}.${String(process.pid)}${MIGRATION_CLAIM_SUFFIX}`
+}
+
+function claim(from: string, to: string): boolean {
+	try {
+		renameSync(from, to)
+
+		return true
+	} catch {
+		return false
+	}
+}
+
+// Only `ESRCH` means the process is gone; `EPERM` means it runs under another user, and its claim is
+// still its own.
+function is_alive(pid: number): boolean {
+	try {
+		process.kill(pid, NO_SIGNAL)
+
+		return true
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code !== NO_SUCH_PROCESS
+	}
+}
+
+// A claim is named `<old ledger>.<pid>.migrating`, so the pid is what sits between the two.
+function is_stale_claim(name: string, legacy_name: string): boolean {
+	const prefix = `${legacy_name}.`
+
+	if (!name.startsWith(prefix) || !name.endsWith(MIGRATION_CLAIM_SUFFIX)) return false
+
+	const pid = Number(name.slice(prefix.length, -MIGRATION_CLAIM_SUFFIX.length))
+
+	return Number.isSafeInteger(pid) && !is_alive(pid)
+}
+
+function stale_claims(legacy: string): ReadonlyArray<string> {
+	const directory = path.dirname(legacy)
+
+	try {
+		return readdirSync(directory)
+			.filter((name) => is_stale_claim(name, path.basename(legacy)))
+			.map((name) => path.join(directory, name))
+	} catch {
+		return []
+	}
+}
+
+function terminated(content: string): string {
+	return content.length === 0 || content.endsWith(NEWLINE) ? content : `${content}${NEWLINE}`
+}
+
+function read_or_undefined(file_path: string): string | undefined {
+	try {
+		return readFileSync(file_path, 'utf8')
+	} catch {
+		return undefined
+	}
+}
+
+// What of the claimed file goes to the ledger's tail: all of it, verbatim, when there is no ledger yet,
+// and otherwise only the lines the ledger does not already hold. **The old file can come back after
+// its lines were moved** — `git restore`, `git reset --hard` or a stash without `-u` restores a
+// tracked old ledger beside the untracked new one — and copying it whole again would repeat every line
+// in the history, which the digest reads as every observation recurring.
+function carried(content: string, ledger: string | undefined): string {
+	if (ledger === undefined) return terminated(content)
+
+	const lines = content.split(NEWLINE).filter((line) => line.length > 0)
+	const missing = observation_ledger_line.missing_lines(lines, ledger)
+
+	return missing.length === 0 ? '' : `${missing.join(NEWLINE)}${NEWLINE}`
+}
+
+// Moves one claimed file's lines to the tail of the ledger, then removes the claim.
+function absorb(claimed: string, target: string): void {
+	mkdirSync(path.dirname(target), { recursive: true })
+	appendFileSync(target, carried(readFileSync(claimed, 'utf8'), read_or_undefined(target)), 'utf8')
+	rmSync(claimed)
+}
+
+function absorb_stale(legacy: string, target: string): number {
+	let count = 0
+
+	for (const stale of stale_claims(legacy)) {
+		const claimed = claim_path(legacy)
+
+		if (!claim(stale, claimed)) continue
+
+		absorb(claimed, target)
+		count += 1
+	}
+
+	return count
+}
+
+// Returns whether anything was moved. `root` is the checkout the ledger lives in.
+function migrate(root: string): boolean {
+	const legacy = path.join(root, LEGACY_OBSERVATION_LEDGER_PATH)
+	const target = path.join(root, OBSERVATION_LEDGER_PATH)
+	const recovered = absorb_stale(legacy, target)
+	const claimed = claim_path(legacy)
+
+	if (!claim(legacy, claimed)) return recovered > 0
+
+	absorb(claimed, target)
+
+	return true
+}
+
+const observation_ledger_migrate = { claim_path, migrate }
+
+export { observation_ledger_migrate }