@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/gate/structural-checks.ts

@@ -0,0 +1,96 @@
+import { project_checks } from '#scripts/gate/project-checks'
+import type { ChangedFileScope } from '#scripts/git/changed-file-scope'
+import { buffered_process, type BufferedProcessResult } from '#scripts/lib/buffered-process'
+
+// The guard tests that judge source text alone, yet run only in `josh test:related` or a detached
+// ship's pre-detach stop: a bare Issue citation, a source with no colocated test and a `gh` spawn
+// outside `gh api` (the static half of the network guard; the calls a test *makes* are observed by
+// `test-network-guard.ts`, which only a run can answer). `josh lint:related` runs them beside its
+// lint, so a between-edits loop meets them in seconds rather than at the ship (joshuafolkken/kit#4643).
+// The targets are the pre-detach stop's too, so the two never drift.
+//
+// `josh exports:unused` stays out: its whole-program type-checker pass is several times the lint's
+// own wall clock. `josh lint:related` runs its narrowed members check after a green lint instead
+// (joshuafolkken/kit#4645).
+//
+// They run in kit alone: the guard tests are kit's own, and a consumer meets the pre-detach static
+// checks there. A change with no `.ts` file in it moves none of their verdicts.
+
+// A present directory need not hold a test the project's Vitest includes — a consumer's own
+// `scripts/claude` of shell helpers, say — and a filter that matches nothing would stop every ship.
+const GUARD_TEST_COMMAND: ReadonlyArray<string> = ['josh', 'test:unit', '--passWithNoTests']
+const STRUCTURAL_GUARD_TARGETS: ReadonlyArray<string> = [
+	'scripts/issue/session-cite-scan.test.ts',
+	'tools/test/untested-sources.test.ts',
+	'tools/gh/gh-subcommand-guard.test.ts',
+]
+const STRUCTURAL_LISTS: ReadonlyArray<ReadonlyArray<string>> = [
+	[...GUARD_TEST_COMMAND, ...STRUCTURAL_GUARD_TARGETS],
+]
+const TYPESCRIPT_SUFFIX = '.ts'
+const FAILURE_EXIT_CODE = 1
+
+interface StructuralRun {
+	list: ReadonlyArray<string>
+	result: BufferedProcessResult
+}
+
+// The front of a failed check's heading — `josh lane:value metrics-stops` counts a ship output that
+// carries the metrics totals' one.
+function failure_prefix(list: ReadonlyArray<string>): string {
+	return `✗ ${list.join(' ')} — `
+}
+
+// Each failure is headed by the check's own command and how it ended: a check that failed with no
+// output of its own (`ELIFECYCLE Command failed` alone, or nothing) otherwise names nothing to fix.
+function failure_heading(list: ReadonlyArray<string>, result: BufferedProcessResult): string {
+	const ending =
+		result.exit_code === undefined
+			? 'no exit code (timed out or ended by a signal)'
+			: `exit code ${String(result.exit_code)}`
+
+	return `${failure_prefix(list)}${ending}`
+}
+
+function failure_section(list: ReadonlyArray<string>, result: BufferedProcessResult): string {
+	const parts = [failure_heading(list, result), result.output.trim()]
+
+	return parts.filter((part) => part !== '').join('\n')
+}
+
+// The whole-tree fallback is due as the narrowed run with a source in it is; both stay kit-only.
+function is_due(scope: ChangedFileScope, root: string): boolean {
+	if (!project_checks.is_kit_repository(root)) return false
+
+	return scope.mode === 'all' || scope.files.some((file) => file.endsWith(TYPESCRIPT_SUFFIX))
+}
+
+async function run_in(root: string, list: ReadonlyArray<string>): Promise<StructuralRun> {
+	return { list, result: await buffered_process.run_buffered_process(list, { cwd: root }) }
+}
+
+// All at once and buffered, every failure reported, so one run shows all there is to fix.
+async function run_structural(scope: ChangedFileScope, root: string): Promise<number> {
+	if (!is_due(scope, root)) return 0
+
+	const runs = await Promise.all(STRUCTURAL_LISTS.map(async (list) => await run_in(root, list)))
+	const failed = runs.filter(({ result }) => buffered_process.is_process_failed(result))
+
+	if (failed.length === 0) return 0
+
+	const sections = failed.map(({ list, result }) => failure_section(list, result))
+
+	process.stdout.write(`\n${sections.join('\n\n')}\n`)
+
+	return FAILURE_EXIT_CODE
+}
+
+const structural_checks = {
+	GUARD_TEST_COMMAND,
+	STRUCTURAL_GUARD_TARGETS,
+	failure_prefix,
+	failure_section,
+	run_structural,
+}
+
+export { structural_checks }

package/scripts/gate/toolchain-inputs.ts

@@ -0,0 +1,115 @@
+import { createHash } from 'node:crypto'
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+
+// **The toolchain's inputs, listed once** (joshuafolkken/kit#4496): the files whose content moves what
+// a tool answers while every source stays byte-identical — the installed packages, the eslint config
+// and the TypeScript program's options. Every result kept across runs is discarded when they move:
+// the metrics base cache (`metrics-base-cache.ts`), the hook bundles (`hook-bundle-stamp.ts`), the
+// warm ESLint daemon (`eslint-daemon.ts`) and the gate's verdicts (`verification-inputs.ts`). A file
+// added here reaches all of them.
+//
+// Loaded by plain `node` on every hook launch (`tools/hooks/hook-bundle-ready.ts`), so this module
+// imports `node:` built-ins alone.
+
+// The package manager's manifest, lock and settings files, and the record pnpm rewrites on every
+// install — a consumer's eslint config imports its rules from installed packages.
+const PACKAGE_FILES: ReadonlyArray<string> = [
+	'package.json',
+	'pnpm-lock.yaml',
+	'pnpm-workspace.yaml',
+	'package-lock.json',
+	'yarn.lock',
+	'bun.lock',
+	'bun.lockb',
+	'.npmrc',
+	'node_modules/.modules.yaml',
+]
+// The root entries of the eslint flat config and of the TypeScript program, and the directories of
+// the rule modules and the shared compiler options they import.
+const CONFIG_ENTRIES: ReadonlyArray<RegExp> = [
+	/^eslint\.config\.[cm]?[jt]s$/u,
+	/^tsconfig(?:\.[\w-]+)?\.json$/u,
+]
+const CONFIG_DIRECTORIES: ReadonlySet<string> = new Set(['eslint', 'tsconfig'])
+// A test beside the rule modules configures nothing.
+const TEST_MARKER = '.test.'
+const SEPARATOR = '/'
+const DIGEST_ALGORITHM = 'sha256'
+
+// Code-unit order, so the digest does not depend on the locale of the machine that computes it.
+function by_code_unit(left: string, right: string): number {
+	if (left === right) return 0
+
+	return left < right ? -1 : 1
+}
+
+function to_posix(relative: string): string {
+	return relative.split(path.sep).join(SEPARATOR)
+}
+
+function is_config_entry(name: string): boolean {
+	return CONFIG_ENTRIES.some((entry) => entry.test(name))
+}
+
+function is_config_module(relative: string): boolean {
+	const [top = ''] = relative.split(SEPARATOR, 1)
+
+	return CONFIG_DIRECTORIES.has(top) && !path.basename(relative).includes(TEST_MARKER)
+}
+
+// Whether the root-relative `relative` is a toolchain input.
+function is_input(relative: string): boolean {
+	const posix = to_posix(relative)
+	if (PACKAGE_FILES.includes(posix)) return true
+
+	return is_config_entry(posix) || is_config_module(posix)
+}
+
+// Files only: a directory moves on every entry created in it, an editor's temp file too.
+function modules_under(root: string, directory: string): ReadonlyArray<string> {
+	const absolute = path.join(root, directory)
+	if (!existsSync(absolute)) return []
+
+	return readdirSync(absolute, { recursive: true, withFileTypes: true })
+		.filter((entry) => entry.isFile())
+		.map((entry) => to_posix(path.relative(root, path.join(entry.parentPath, entry.name))))
+		.filter((relative) => is_config_module(relative))
+}
+
+// The root-relative toolchain inputs present under `root`, in code-unit order.
+function paths(root: string): ReadonlyArray<string> {
+	const present = PACKAGE_FILES.filter((relative) => existsSync(path.join(root, relative)))
+	const entries = readdirSync(root).filter((name) => is_config_entry(name))
+	const modules = [...CONFIG_DIRECTORIES].flatMap((directory) => modules_under(root, directory))
+
+	return [...present, ...entries, ...modules].toSorted(by_code_unit)
+}
+
+function read_or_empty(file: string): Uint8Array {
+	try {
+		return readFileSync(file)
+	} catch {
+		return new Uint8Array()
+	}
+}
+
+// **The fingerprint of the toolchain under `root`**: each input's path and content, in code-unit
+// order, so an added, removed, renamed or edited input changes it. A file gone between the listing
+// and its read hashes as empty.
+function digest(root: string): string {
+	const hash = createHash(DIGEST_ALGORITHM)
+
+	for (const relative of paths(root)) {
+		hash
+			.update(`${relative}\0`)
+			.update(read_or_empty(path.join(root, relative)))
+			.update('\0')
+	}
+
+	return hash.digest('hex')
+}
+
+const toolchain_inputs = { digest, is_input, PACKAGE_FILES, paths }
+
+export { toolchain_inputs }

package/scripts/gate/verification-gate.ts

@@ -3,18 +3,19 @@ import { fileURLToPath } from 'node:url'
 import type { FileMapStamp } from '#scripts/josh/file-map-stamp'
 import { GATE_COMMAND } from '#scripts/josh/josh-command-types'
 import { composite_arguments, USAGE_ERROR_EXIT_CODE } from '#scripts/josh/josh-composite-arguments'
-import { lane_ledger } from '#scripts/lane/lane-ledger'
+import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { lane_ledger_write } from '#scripts/lane/lane-ledger-write'
 import { FAIL_EXIT_CODE } from '#scripts/lib/buffered-process'
 import { review_stamps } from '#scripts/review/review-stamps'
 import { review_tree } from '#scripts/review/review-tree'
 import { unit_worker_share } from '#scripts/test/unit-worker-share'
 import { check_reuse, type CheckRecords } from './check-reuse'
-import { free_cores } from './free-cores'
 import { gate_ledger, type GateLedgerStart } from './gate-ledger'
 import { gate_plan, type GatePlan } from './gate-plan'
 import { gate_report, type GateStepResult } from './gate-report'
 import { gate_run_steps, type ReusedChecks } from './gate-run-steps'
 import { gate_skip } from './gate-skip'
+import { gate_static_group } from './gate-static-group'
 import { build_gate_step, build_gate_steps, UNIT_WORKER_FLAG } from './gate-steps'
 import { gate_tree, type GateTree } from './gate-tree'
 import { project_checks } from './project-checks'
@@ -165,11 +166,17 @@ async function run_marked_gate<T>(
 // The concurrent-run count is read here rather than inside `gate-plan.ts` for the reason the core
 // count already is: that module stays a pure function of its inputs, and the machine is asked once and
 // handed to both calls. Counted *before* the unit step writes its own marker, so `+ 1` is this gate.
-// `free` bounds the unit cap the run count produced (`gate_plan.bound_by_free`).
+//
+// **The free cores do not cap the plan** (joshuafolkken/kit#4167). The unit claim's admission narrows it
+// to the room the outside load leaves, read over its wait rather than once at the gate's start — a
+// width fixed off one busy instant held for the whole suite (`core_admission.is_too_narrow`).
+//
+// A `--static-group` narrows the resolved plan's checks and keeps its concurrency, which the full static
+// set sized: a cap above the narrowed count never binds.
 function announce_gate_plan(
 	is_unit_included: boolean,
 	available_cores: number,
-	free: number | undefined,
+	static_group?: string,
 ): GatePlan {
 	const concurrent_runs = unit_worker_share.live_run_count() + unit_worker_share.SOLO_RUNS
 	const is_kit_repository = project_checks.is_kit_repository(process.cwd())
@@ -179,7 +186,10 @@ function announce_gate_plan(
 		is_unit_included,
 		is_kit_repository,
 	)
-	const plan = gate_plan.bound_by_free(resolved, available_cores, free)
+	const plan = {
+		...resolved,
+		checks: gate_static_group.narrow_checks(resolved.checks, static_group),
+	}
 
 	process.stdout.write(`${gate_plan.format_gate_plan(plan, available_cores, concurrent_runs)}\n`)
 
@@ -198,6 +208,8 @@ interface GateOptions {
 	// Whether the unit suite is one of this gate's checks. Defaults to true everywhere; only
 	// `--no-unit` turns it off, for the CI job that runs the suite on a runner of its own.
 	is_unit_included?: boolean
+	// The one static group a CI matrix leg runs (`gate-static-group.ts`); set only with the unit suite off.
+	static_group?: string | undefined
 	stamp_path?: string
 	marker_path?: string
 	// The gate log's destination, a parameter for the same reason the two above are: this suite runs
@@ -217,10 +229,6 @@ interface GateOptions {
 	// Where each check's own green record lives (`check-reuse.ts`). Only the CLI entry resolves it, for
 	// the ledger's reason: a suite whose checks never ran must not record them green on the live tree.
 	check_records?: CheckRecords | undefined
-	// The cores free of load from outside the core budget's ledger (`free-cores.ts`). Only the CLI entry
-	// resolves it, for the ledger's reason: a suite driving the gate never reads the machine, so its plan
-	// does not depend on what else happened to be running.
-	read_free_cores?: ((available_cores: number) => Promise<number | undefined>) | undefined
 }
 
 // **Per-check records belong to the full local gate alone**: CI's `--no-unit` gate is the safety net
@@ -260,7 +268,10 @@ function scoped_precheck_refusal(tree: GateTree, options: GateOptions): string |
 		return undefined
 	}
 
-	return scoped_green.refusal_for(tree.files, tree.base, options.scoped_sources)
+	return scoped_green.refusal_for(tree.files, tree.base, {
+		is_lane_child: lane_child_marker.is_child_of(process.cwd()),
+		...options.scoped_sources,
+	})
 }
 
 // **A partial gate records nothing green, and this is the same rule as the skip one layer out**.
@@ -325,9 +336,7 @@ async function run_checked_gate(
 	// Resolved at the gate's entry, before this gate sets `JOSH_UNIT_RUN_MARKED`, so a gate nested in the
 	// unit suite reads the flag as set and reserves nothing.
 	const budget = gate_run_steps.default_budget()
-	// Read before the count for the ledger's reason: the reading waits out a sample window.
-	const free = await options.read_free_cores?.(budget.available_cores)
-	const plan = announce_gate_plan(is_unit_included, budget.available_cores, free)
+	const plan = announce_gate_plan(is_unit_included, budget.available_cores, options.static_group)
 	const reused = await checks_to_reuse(plan, tree, options)
 
 	// **The gate holds the unit-run marker for its whole run, not just its unit step.** The step that
@@ -353,17 +362,30 @@ function reusable_stamp(tree: GateTree, options: GateOptions): FileMapStamp | un
 	return gate_skip.reusable_green_gate(tree.files, tree.base, options.stamp_path)
 }
 
+// The reuse leaves its line in the ledger too, so `josh lane:stats` counts the gates it saved
+// (joshuafolkken/kit#4397).
+async function reuse_gate(
+	stamp: FileMapStamp,
+	options: GateOptions,
+	started_at: number,
+): Promise<number> {
+	process.stdout.write(`${gate_skip.format_skip(stamp.taken_at)}\n`)
+	await gate_ledger.record_reused(options.ledger_path, performance.now() - started_at)
+
+	return 0
+}
+
 // The two ways a gate ends before it runs a check: a green record it can reuse (exit 0), and the
 // scoped pre-check refusing a tree the pair has not been green on (exit 1). `undefined` means neither
 // fired and the checks run. **Nothing else stands between the skip and the checks.**
-function short_circuit_gate(tree: GateTree, options: GateOptions): number | undefined {
+async function short_circuit_gate(
+	tree: GateTree,
+	options: GateOptions,
+	started_at: number,
+): Promise<number | undefined> {
 	const reusable = reusable_stamp(tree, options)
 
-	if (reusable !== undefined) {
-		process.stdout.write(`${gate_skip.format_skip(reusable.taken_at)}\n`)
-
-		return 0
-	}
+	if (reusable !== undefined) return await reuse_gate(reusable, options, started_at)
 
 	const scoped_refusal = scoped_precheck_refusal(tree, options)
 
@@ -379,7 +401,7 @@ async function run_verification_gate(options: GateOptions = {}): Promise<number>
 	// four checks alone took — the gate's own bookkeeping is part of the wait either way.
 	const started_at = performance.now()
 	const tree = await gate_tree.read_gate_tree()
-	const short_circuit = short_circuit_gate(tree, options)
+	const short_circuit = await short_circuit_gate(tree, options, started_at)
 
 	if (short_circuit !== undefined) return short_circuit
 
@@ -402,31 +424,48 @@ const ACCEPTED_FLAGS: ReadonlyArray<string> = [VERBOSE_FLAG, gate_skip.FORCE_FLA
 
 // The flags are the caller's, the destinations are the run's, so the two are merged here rather than
 // letting an option override a flag the user typed.
+function unknown_arguments(extra_arguments: ReadonlyArray<string>): ReadonlyArray<string> {
+	return extra_arguments.filter(
+		(argument) =>
+			!ACCEPTED_FLAGS.includes(argument) && gate_static_group.group_of(argument) === undefined,
+	)
+}
+
+// The shared refusal, plus the arguments it is actually about. Some flags are accepted, so the bare
+// "takes no extra arguments" would send a reader to drop the ones that work. The list is interpolated
+// rather than spelled out here, so adding a flag cannot leave this line stale.
+function write_refusal(unknown: ReadonlyArray<string>): void {
+	const groups = Object.keys(gate_static_group.STATIC_GROUPS).join('|')
+
+	process.stderr.write(
+		`${composite_arguments.format_rejection(GATE_COMMAND, GATE_TARGETS)}\n` +
+			`  refused: ${unknown.join(' ')}\n` +
+			`  accepted here: ${ACCEPTED_FLAGS.join(' ')} ${gate_static_group.STATIC_GROUP_FLAG_PREFIX}<${groups}>\n`,
+	)
+}
+
 async function run_gate_command(
 	extra_arguments: ReadonlyArray<string>,
 	options: GateOptions = {},
 ): Promise<number> {
-	const unknown = extra_arguments.filter((argument) => !ACCEPTED_FLAGS.includes(argument))
+	const unknown = unknown_arguments(extra_arguments)
 
 	if (unknown.length > 0) {
-		// The shared refusal, plus the arguments it is actually about. Some flags are accepted, so the
-		// bare "takes no extra arguments" would send a reader to drop the ones that work. The list is
-		// interpolated rather than spelled out here, so adding a flag cannot leave this line stale.
-		process.stderr.write(
-			`${composite_arguments.format_rejection(GATE_COMMAND, GATE_TARGETS)}\n` +
-				`  refused: ${unknown.join(' ')}\n` +
-				`  accepted here: ${ACCEPTED_FLAGS.join(' ')}\n`,
-		)
+		write_refusal(unknown)
 
 		return USAGE_ERROR_EXIT_CODE
 	}
 
+	// A static group is a part of the static set, so it implies `--no-unit` and every withholding that flag carries.
+	const static_group = gate_static_group.find_group(extra_arguments)
+
 	return await run_verification_gate({
 		is_scoped_enforced: true,
 		...options,
 		is_verbose: extra_arguments.includes(VERBOSE_FLAG),
 		is_forced: extra_arguments.includes(gate_skip.FORCE_FLAG),
-		is_unit_included: !extra_arguments.includes(NO_UNIT_FLAG),
+		is_unit_included: !extra_arguments.includes(NO_UNIT_FLAG) && static_group === undefined,
+		static_group,
 	})
 }
 
@@ -436,9 +475,8 @@ async function run_gate_command(
 // process end on its own, which it can, since every child has already exited by here.
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
 	process.exitCode = await run_gate_command(process.argv.slice(FIRST_ARGUMENT_INDEX), {
-		ledger_path: await lane_ledger.target(),
+		ledger_path: await lane_ledger_write.target(),
 		check_records: check_reuse.DEFAULT_RECORDS,
-		read_free_cores: async (available_cores) => await free_cores.read({ available_cores }),
 	})
 }
 

package/scripts/gate/verification-inputs.ts

@@ -0,0 +1,265 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { lint_related_scope } from '#scripts/lint/lint-related-scope'
+import { gate_labels } from './gate-labels'
+import { input_fingerprint } from './input-fingerprint'
+import { toolchain_inputs } from './toolchain-inputs'
+
+// **What each verification depends on, declared once** (joshuafolkken/kit#4495). Every reuse of a
+// verdict — the whole gate (`gate-skip.ts`), one check (`check-reuse.ts`), a scoped record
+// (`scoped-green.ts`) and the since-green narrowing (`since-green.ts`) — answers from the declaration
+// here — the paths through `check-inputs.ts`, the tools and environment through `fingerprint` — so a
+// new reuse picks a declaration rather than writing its own invalidation.
+//
+// A declaration names:
+// - `is_input` — whether a path is a content input; `undefined` leaves it to `reads`.
+// - `reads` — `matched`: the inputs are the paths `is_input` accepts. `recorded`: the inputs are the
+//   files a run read, as the run recorded them — the test-read map (joshuafolkken/kit#4314), whose
+//   file digests are `input-fingerprint.ts`'s — so a path is an input only when some recorded test
+//   reads it.
+// - `is_config` — the files that configure the check: one that moves invalidates the verdict whatever
+//   else moved, and stops the since-green narrowing.
+// - `tools` — the packages whose installed version runs the check.
+// - `env` — the environment variables whose value changes the verdict.
+//
+// **A check with no declaration always runs**: `cspell` reads every text file and `behavior` reads a
+// transcript outside the tree. Naming inputs for either would be a guess, and a wrong guess is a check
+// reported green without having run. **The declarations over-approximate, never under**: a path in
+// doubt is an input. `metrics` reads the scripts it counts, the approvals under
+// `.josh/metrics-accepted/` (JSON) and the Markdown it measures (joshuafolkken/kit#4085). `lint` is
+// prettier plus eslint, so its inputs are the sources plus every file prettier formats, less what
+// prettier's own ignore files leave out — prettier answers that itself (`check-inputs.ts`).
+
+const GIT_IGNORE = '.gitignore'
+const PRETTIER_IGNORE = '.prettierignore'
+const PRETTIER_IGNORE_FILES = [GIT_IGNORE, PRETTIER_IGNORE] as const
+
+// A manifest or lock file moves the installed tools (`toolchain-inputs.ts`, the list every kept result
+// shares), and an ignore or editor file moves what prettier formats — a configuration of every
+// declared check.
+const MANIFEST = 'package.json'
+
+const TOOLCHAIN_FILES: ReadonlySet<string> = new Set([
+	...toolchain_inputs.PACKAGE_FILES.map((relative) => path.basename(relative)),
+	'.editorconfig',
+	...PRETTIER_IGNORE_FILES,
+])
+
+const PRETTIER_CONFIG_PREFIX = '.prettierrc'
+
+// A file name starting with one of these configures the TypeScript program a check compiles, and the
+// test runner for the unit step.
+const COMPILER_CONFIG_PREFIXES = ['tsconfig', 'svelte.config.'] as const
+const TEST_CONFIG_PREFIXES = [...COMPILER_CONFIG_PREFIXES, 'vitest.config.', 'vite.config.']
+
+// A file name starting with one of these, or a path under one of the directories, configures prettier,
+// eslint or the TypeScript program its type-aware rules read. Prettier keys its cache on the options
+// too, so a changed `prettier.config.*` re-checks every file the whole-tree run reads.
+const LINT_CONFIG_PREFIXES = ['eslint.config.', 'prettier.config.', ...COMPILER_CONFIG_PREFIXES]
+const LINT_CONFIG_DIRECTORIES: ReadonlySet<string> = new Set(['eslint', 'prettier', 'tsconfig'])
+
+const SOURCE_EXTENSIONS: ReadonlySet<string> = new Set([
+	'.ts',
+	'.tsx',
+	'.mts',
+	'.cts',
+	'.js',
+	'.jsx',
+	'.mjs',
+	'.cjs',
+	'.svelte',
+	'.vue',
+	'.json',
+	'.jsonc',
+])
+
+const MARKDOWN_EXTENSION = '.md'
+// `NODE_OPTIONS` is left out: package managers and hooks set it differently around the same check,
+// and it tunes the runtime rather than what a check answers.
+const COMMON_ENV = ['NODE_ENV'] as const
+const ABSENT = 'absent'
+
+type Environment = Readonly<Record<string, string | undefined>>
+
+// Whether prettier would leave `relative` out; `false` when prettier cannot be asked, which keeps the
+// path an input.
+type PrettierIgnored = (relative: string) => Promise<boolean>
+
+type FileTest = (relative: string, is_ignored: PrettierIgnored) => Promise<boolean>
+
+type InputReads = 'matched' | 'recorded'
+
+interface InputDeclaration {
+	readonly is_input: FileTest | undefined
+	readonly reads: InputReads
+	readonly is_config: (relative: string) => boolean
+	readonly tools: ReadonlyArray<string>
+	readonly env: ReadonlyArray<string>
+}
+
+function is_source(relative: string): boolean {
+	return SOURCE_EXTENSIONS.has(path.extname(relative))
+}
+
+async function is_lint_input(relative: string, is_ignored: PrettierIgnored): Promise<boolean> {
+	if (is_source(relative)) return true
+	if (!lint_related_scope.is_lintable(relative)) return false
+
+	return !(await is_ignored(relative))
+}
+
+async function is_source_input(relative: string): Promise<boolean> {
+	return is_source(relative)
+}
+
+async function is_metrics_input(relative: string): Promise<boolean> {
+	return is_source(relative) || path.extname(relative) === MARKDOWN_EXTENSION
+}
+
+function configures_toolchain(relative: string): boolean {
+	const name = path.basename(relative)
+
+	return TOOLCHAIN_FILES.has(name) || name.startsWith(PRETTIER_CONFIG_PREFIX)
+}
+
+function names_any(relative: string, prefixes: ReadonlyArray<string>): boolean {
+	const name = path.basename(relative)
+
+	return configures_toolchain(relative) || prefixes.some((prefix) => name.startsWith(prefix))
+}
+
+function configures_compiler(relative: string): boolean {
+	return names_any(relative, COMPILER_CONFIG_PREFIXES)
+}
+
+function configures_tests(relative: string): boolean {
+	return names_any(relative, TEST_CONFIG_PREFIXES)
+}
+
+function configures_lint(relative: string): boolean {
+	const [top = ''] = relative.split('/', 1)
+
+	return LINT_CONFIG_DIRECTORIES.has(top) || names_any(relative, LINT_CONFIG_PREFIXES)
+}
+
+const LINT: InputDeclaration = {
+	is_input: is_lint_input,
+	reads: 'matched',
+	is_config: configures_lint,
+	tools: ['prettier', 'eslint', 'typescript'],
+	env: COMMON_ENV,
+}
+
+const UNIT: InputDeclaration = {
+	is_input: undefined,
+	reads: 'recorded',
+	is_config: configures_tests,
+	tools: ['vitest', 'typescript'],
+	env: [...COMMON_ENV, 'TZ'],
+}
+
+function compiled(is_input: FileTest): InputDeclaration {
+	return {
+		is_input,
+		reads: 'matched',
+		is_config: configures_compiler,
+		tools: ['typescript'],
+		env: COMMON_ENV,
+	}
+}
+
+// **cspell reads every file with dotfiles**, so any moved file — its config and word lists among
+// them — answers "run again" (joshuafolkken/kit#5156).
+async function is_any_file(): Promise<boolean> {
+	return true
+}
+
+const SPELLING: InputDeclaration = {
+	is_input: is_any_file,
+	reads: 'matched',
+	is_config: configures_toolchain,
+	tools: ['cspell'],
+	env: COMMON_ENV,
+}
+
+const DECLARATIONS: ReadonlyMap<string, InputDeclaration> = new Map([
+	[gate_labels.LINT_LABEL, LINT],
+	[gate_labels.SPELL_CHECK_LABEL, SPELLING],
+	[gate_labels.TYPE_CHECK_LABEL, compiled(is_source_input)],
+	[gate_labels.EXPORTS_LABEL, compiled(is_source_input)],
+	[gate_labels.METRICS_LABEL, compiled(is_metrics_input)],
+	[gate_labels.UNIT_LABEL, UNIT],
+])
+
+function declaration_of(label: string): InputDeclaration | undefined {
+	return DECLARATIONS.get(label)
+}
+
+function is_declared(label: string): boolean {
+	return DECLARATIONS.has(label)
+}
+
+// Whether any of `relatives` (repository-root relative) configures the check `label` — `true` for an
+// undeclared one, which no narrowing can read past.
+function configures(label: string, relatives: ReadonlyArray<string>): boolean {
+	const declaration = DECLARATIONS.get(label)
+
+	return declaration === undefined || relatives.some((relative) => declaration.is_config(relative))
+}
+
+function tool_version(root: string, tool: string): string {
+	try {
+		const manifest: unknown = JSON.parse(
+			readFileSync(path.join(root, 'node_modules', tool, MANIFEST), 'utf8'),
+		)
+
+		return typeof manifest === 'object' && manifest !== null && 'version' in manifest
+			? String(manifest.version)
+			: ABSENT
+	} catch {
+		return ABSENT
+	}
+}
+
+function entries_of(
+	declaration: InputDeclaration,
+	root: string,
+	environment: Environment,
+): ReadonlyArray<string> {
+	return [
+		...declaration.tools.map((tool) => `tool:${tool}=${tool_version(root, tool)}`),
+		...declaration.env.map((name) => `env:${name}=${environment[name] ?? ABSENT}`),
+	]
+}
+
+// **The fingerprint of what the checks `labels` read beside the files**: the installed version of every
+// declared tool and the value of every declared environment variable, sorted into one digest. The
+// file contents are the record's own file map (`file-map-stamp.ts`) and the merge base its `base`, so a
+// reuse matches all three. One label answers a check's record; every declared label the whole gate's.
+function fingerprint(
+	labels: ReadonlyArray<string>,
+	root: string = PROJECT_ROOT,
+	environment: Environment = process.env,
+): string {
+	const declarations = labels.flatMap((label) => DECLARATIONS.get(label) ?? [])
+	const entries = new Set(
+		declarations.flatMap((declaration) => entries_of(declaration, root, environment)),
+	)
+
+	return input_fingerprint.of_entries(entries)
+}
+
+const DECLARED_LABELS: ReadonlyArray<string> = [...DECLARATIONS.keys()]
+
+const verification_inputs = {
+	configures,
+	declaration_of,
+	DECLARED_LABELS,
+	fingerprint,
+	is_declared,
+	PRETTIER_IGNORE_FILES,
+}
+
+export type { InputDeclaration, InputReads, PrettierIgnored }
+export { verification_inputs }