@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/gate/gate-ledger.ts

@@ -1,5 +1,6 @@
 import { process_identity } from '#scripts/josh/process-identity'
 import { lane_ledger, type GateCheckRecord } from '#scripts/lane/lane-ledger'
+import { related_scope } from '#scripts/test/test-related-scope'
 import { core_admission } from './core-admission'
 import { core_budget } from './core-budget'
 import { gate_plan } from './gate-plan'
@@ -13,8 +14,8 @@ import { machine_capacity } from './machine-capacity'
 //
 // **The machine is read where none of the gate's own checks runs — before the first starts and after
 // the last ends.** The load average cannot tell the two apart: a solo gate started at 4 on the 11-core
-// machine ended at 21, its own load. The reading is the core budget's own, so "quiet" means what
-// admission means by it: no whole core busy beyond the baseline the gate's weights were measured beside.
+// machine ended at 21, its own load. The reading is the core budget's own; "quiet" is no whole core
+// busy beyond the background a developer machine always carries.
 //
 // **Between the ends, the load is read off the core budget's ledger, not the CPU**.
 // Two readings missed every lane whose lint, tests or `ship` ran only while
@@ -23,7 +24,11 @@ import { machine_capacity } from './machine-capacity'
 // is what tells the two apart: another `josh` run's admitted claim is another process's place, and its
 // weight is the cores it holds. A claim still waiting holds none.
 
-const NO_LEDGER_CORES = 0
+// **The background a quiet machine still carries.** On 2026-10-07 the 11-core machine idled at about
+// 1.5 cores outside `josh` — Claude sessions 0.55, the window server 0.47, a browser 0.5. Admission
+// counts it (`machine_capacity.external_cores`, joshuafolkken/kit#4238), but a gate timed beside it is
+// still a solo gate for `josh metrics`, so it is no external load here.
+const BACKGROUND_CORES = 2
 // Often enough to catch another lane's shortest related lint, seldom enough that reading the markers —
 // a process probe each — costs the gate nothing it could measure.
 const SAMPLE_INTERVAL_MS = 3000
@@ -48,7 +53,7 @@ async function read_external_cores(): Promise<number | undefined> {
 
 	if (busy_cores === undefined) return undefined
 
-	return machine_capacity.external_cores(busy_cores, NO_LEDGER_CORES)
+	return machine_capacity.external_cores(busy_cores, BACKGROUND_CORES)
 }
 
 // The cores other processes' admitted claims hold now. This gate's own claims are written by this
@@ -88,15 +93,36 @@ async function start(ledger_path: string | undefined): Promise<GateLedgerStart>
 	return { ledger_path, readings, sampler: start_sampler(readings) }
 }
 
+// The unit leg's own facts: the whole-suite fallback it took, or the since-green no-op that ran no
+// test (joshuafolkken/kit#4457) — the two `josh lane:stats` must not time as an ordinary run.
+function unit_facts(result: GateStepResult): Pick<GateCheckRecord, 'fallback' | 'is_unmoved'> {
+	if (result.label !== gate_plan.UNIT_LABEL) return {}
+
+	return {
+		fallback: related_scope.fallback_kind(result.output),
+		...(related_scope.is_unmoved(result.output) && { is_unmoved: true }),
+	}
+}
+
 function check_records(results: ReadonlyArray<GateStepResult>): Array<GateCheckRecord> {
 	return results.map((result) => ({
 		label: result.label,
 		elapsed_ms: result.elapsed_ms,
 		is_passed: !gate_report.is_gate_step_failed(result),
 		is_reused: result.reused_at !== undefined,
+		...(result.cpu_ms !== undefined && { cpu_ms: Math.round(result.cpu_ms) }),
+		...unit_facts(result),
+		claim: result.claim,
 	}))
 }
 
+// A gate that reused a green record started no check: its line is counted as reused, never timed.
+async function record_reused(ledger_path: string | undefined, elapsed_ms: number): Promise<void> {
+	if (ledger_path === undefined) return
+
+	await lane_ledger.record_gate(ledger_path, { elapsed_ms, is_passed: true, is_reused: true })
+}
+
 // The caller measures the elapsed time before this, so the end's reading is never part of it.
 async function record(
 	begun: GateLedgerStart,
@@ -119,8 +145,10 @@ async function record(
 }
 
 const gate_ledger = {
+	BACKGROUND_CORES,
 	SAMPLE_INTERVAL_MS,
 	record,
+	record_reused,
 	start,
 }
 

package/scripts/gate/gate-plan.ts

@@ -49,6 +49,7 @@ interface GateCheck {
 const LINT_LABEL = 'lint'
 const TYPE_CHECK_LABEL = 'check'
 const UNIT_LABEL = 'test:unit'
+const UNIT_TARGET = 'test:related'
 const BEHAVIOR_LABEL = 'behavior'
 const METRICS_LABEL = 'metrics'
 const EXPORTS_LABEL = 'exports'
@@ -78,15 +79,18 @@ const WARNING_CHECKER_LABELS: ReadonlyArray<string> = [LINT_LABEL, TYPE_CHECK_LA
 //
 // **The two zero weights are measured, and they stay zero.** These are warm runs on the 11-core
 // machine. `behavior` took 0.6s of wall for 0.7s of CPU, which
-// is node starting up. `exports:unused` took 5.5s of wall for 9.0s of CPU, about 1.6 cores. Floored,
-// that would be one core, but a reservation lasts the whole gate's plan, not the check's five seconds.
-// It would lower `RESERVED_CORES` from 4 to 5 and cut the solo unit cap from 7 workers to 6 for the
-// full length of the unit suite, to cover a burst that ends before lint does. Nothing has measured
+// is node starting up. `exports:unused` took 5.5s of wall for 9.0s of CPU, about 1.6 cores. Rounded
+// up, that would be two cores, but a reservation lasts the whole gate's plan, not the check's five
+// seconds. It would raise `RESERVED_CORES` from 6 to 8 and cut the solo unit cap from 5 workers to 3
+// for the full length of the unit suite, to cover a burst that ends before lint does. Nothing has measured
 // that trade, so the measured shape stays.
 const STATIC_CHECKS: ReadonlyArray<GateCheck> = [
+	// **The lint reads the branch's changed files, not the whole tree** (joshuafolkken/kit#4085), and
+	// falls back to the whole tree in CI and on a changed configuration (`lint-gate-scope.ts`).
 	{
 		label: LINT_LABEL,
 		target: 'lint',
+		args: ['--changed'],
 		reserved_cores: core_budget.CORE_WEIGHTS.lint,
 		memory_mb: core_budget.MEMORY_MB.lint,
 	},
@@ -120,13 +124,23 @@ const STATIC_CHECKS: ReadonlyArray<GateCheck> = [
 		memory_mb: core_budget.MEMORY_MB.eslint_scan,
 		is_kit_only: true,
 	},
+	// The lockfile policy check is network-bound and usually instant: it verifies only when the
+	// lockfile or `pnpm-workspace.yaml` moved from the merge-base (joshuafolkken/kit#4090), so it
+	// reserves no core. Kit's own until a consumer's private-registry entries are known to verify.
+	{ label: 'lockfile', target: 'lockfile:policy', reserved_cores: 0, is_kit_only: true },
 ]
 
 // The checks, in the order their output is printed — the static set, then the unit suite last (the
 // one check that fans out across every core, and the one the `--no-unit` split drops).
+//
+// **The unit check runs the tests the change can reach, not the whole suite**
+// (joshuafolkken/kit#4065): `josh test:related` narrows through the module graph and the test-read
+// map, and runs the whole suite — refreshing that map — whenever it cannot tell. The label stays
+// `test:unit`, the name every ledger, reservation and record knows the check by. CI runs the whole
+// sharded suite regardless.
 const GATE_CHECKS: ReadonlyArray<GateCheck> = [
 	...STATIC_CHECKS,
-	{ label: UNIT_LABEL, target: UNIT_LABEL, reserved_cores: 0 },
+	{ label: UNIT_LABEL, target: UNIT_TARGET, reserved_cores: 0 },
 ]
 
 // **Selecting is not skipping, and the difference is where the unit suite runs rather than whether
@@ -152,7 +166,7 @@ function has_unit_check(checks: ReadonlyArray<GateCheck>): boolean {
 	return checks.some((check) => check.label === UNIT_LABEL)
 }
 
-// What the non-elastic checks hold between them: 2 + 1 + 1. Reduced over `STATIC_CHECKS`
+// What the non-elastic checks hold between them: 2 + 2 + 2. Reduced over `STATIC_CHECKS`
 // rather than over every check, because that is the set the sentence above names: `resolve_unit_worker_cap`
 // spends this as the cores the unit suite must leave to its siblings, so summing the unit check into
 // it would have the suite subtract its own reservation from its own budget the day that reservation
@@ -219,7 +233,7 @@ function shared_cores(available_cores: number, concurrent_runs: number): number
 
 // Admit checks in declaration order while the running set's reserved cores still fit **this run's
 // share** of the machine. On a machine running one gate that share is the machine, so this bites
-// only below four cores — the three reserving checks want four between them — and there it is the
+// only below six cores — the three reserving checks want six between them — and there it is the
 // difference between two checks sharing a core and four fighting over it.
 //
 // **Under concurrency it is the only lever there is, and that is a measurement rather than a
@@ -309,8 +323,9 @@ function solo_unit_weight(available_cores: number): number {
 // once**: no second set of weights is introduced, so a change to the measured reservation moves the
 // admission with it.
 //
-// **A solo gate's four weights sum to exactly the core count** — `reserved(2 + 1 + 1) +
-// unit_cap(cores - 4)` is `cores` — which is what lets every check of a lone gate be admitted at once,
+// **A solo gate's four weights sum to exactly the core count** — `reserved(2 + 2 + 2) +
+// unit_cap(cores - 6)` is `cores` — which is what lets every check of a lone gate on a machine with room
+// (its busy cores within what the ledger holds, `core-budget.ts`) be admitted at once,
 // its concurrency unchanged. A machine below the measured one leaves the unit suite uncapped and reads
 // its weight from the same identity, `cores - RESERVED_CORES` clamped at zero, so the sum is the core
 // count there too.
@@ -339,22 +354,33 @@ function check_memory(check: GateCheck, plan: GatePlan, available_cores: number)
 // and hold every later claim behind it. One weight for the suite however it is started. **Floored at one
 // worker**: on a machine the static checks fill, a four-core CI runner among them, the gate's solo
 // weight is zero because its siblings hold every core — a direct run has no siblings, and vitest still
-// occupies a core.
+// occupies a core. **Plus vitest's own process** (joshuafolkken/kit#4362): the workers are the share,
+// and the claim holds the process that drives them on top (`unit_worker_share.cap_to_claim` takes it
+// back off).
 function direct_unit_weight(
 	available_cores: number = availableParallelism(),
 	live_runs: number = unit_worker_share.live_run_count(),
 ): number {
-	const weight =
+	const workers =
 		unit_worker_share.current_share(available_cores, live_runs) ?? solo_unit_weight(available_cores)
 
-	return Math.max(unit_worker_share.MIN_WORKERS, weight)
+	return Math.max(unit_worker_share.MIN_WORKERS, workers) + unit_worker_share.MAIN_PROCESS_CORES
 }
 
-// What a unit run started directly holds: one worker's peak for each worker `direct_unit_weight` gives it.
+// What a unit run started directly holds: one worker's peak for each core `direct_unit_weight` gives
+// it, vitest's own process counted as one more.
 function direct_unit_memory(): number {
 	return unit_memory(direct_unit_weight())
 }
 
+// The claim every unit run started directly declares — `josh test:unit`, `josh test:related` and the
+// pre-push hook — declared once so the three cannot drift apart.
+const DIRECT_UNIT_CLAIM = {
+	core_weight: direct_unit_weight,
+	memory_mb: direct_unit_memory,
+	is_unit_claim: true,
+} as const
+
 function unit_cap_for(
 	checks: ReadonlyArray<GateCheck>,
 	available_cores: number,
@@ -398,25 +424,6 @@ function resolve_gate_plan(
 	}
 }
 
-// The unit cap bounded by the cores free of load from outside the core budget's ledger
-// (`free-cores.ts`), so the run count's share is never wider than what is free. A plan with no unit
-// step carries no cap, and an unread machine leaves the cap as resolved (`unit_worker_share.cap_to_free`).
-function bound_by_free(
-	plan: GatePlan,
-	available_cores: number,
-	free_cores: number | undefined,
-): GatePlan {
-	if (!has_unit_check(plan.checks)) return plan
-
-	const unit_worker_cap = unit_worker_share.cap_to_free(
-		plan.unit_worker_cap,
-		free_cores,
-		available_cores,
-	)
-
-	return { ...plan, unit_worker_cap }
-}
-
 // Printed once per run, so a gate that was slow on someone else's machine can be read without
 // re-deriving the plan from their core count.
 //
@@ -460,6 +467,7 @@ function format_gate_plan(
 }
 
 const gate_plan = {
+	DIRECT_UNIT_CLAIM,
 	EXPORTS_LABEL,
 	GATE_CHECKS,
 	LINT_LABEL,
@@ -469,11 +477,10 @@ const gate_plan = {
 	STATIC_CHECKS,
 	TYPE_CHECK_LABEL,
 	UNIT_LABEL,
+	UNIT_TARGET,
 	WARNING_CHECKER_LABELS,
-	bound_by_free,
 	check_memory,
 	check_weight,
-	direct_unit_memory,
 	direct_unit_weight,
 	format_gate_plan,
 	format_machine,

package/scripts/gate/gate-report.ts

@@ -2,6 +2,7 @@ import { GATE_COMMAND } from '#scripts/josh/josh-command-types'
 import { josh_verdict } from '#scripts/josh/josh-verdict'
 import { buffered_process, type BufferedProcessResult } from '#scripts/lib/buffered-process'
 import { status_icons } from '#scripts/lib/status-icons'
+import { MS_PER_SECOND } from '#scripts/lib/timeouts'
 import { NOT_USED_MARKER, NOTHING_TO_CHECK_MARKER } from '#scripts/test/skip-marker'
 import { test_unit_guard } from '#scripts/test/test-unit-guard'
 import { gate_log } from './gate-log'
@@ -31,6 +32,18 @@ interface GateStepResult extends BufferedProcessResult {
 	// Set when the check was not started because its inputs match the record taken at this time
 	// (`check-reuse.ts`).
 	reused_at?: string | undefined
+	// The CPU milliseconds the check's process tree spent, where the gate could read it (`check-cpu.ts`).
+	cpu_ms?: number | undefined
+	// The check's place in the core budget, absent on a check that claimed none (`gate-run-steps.ts`).
+	claim?: CheckClaim | undefined
+}
+
+// The width a check asked the core budget for, the width it ran at and how long it waited for it, so
+// whether a unit claim's wait for room paid off is read per run (joshuafolkken/kit#4451).
+interface CheckClaim {
+	requested: number
+	granted: number
+	waited_ms: number
 }
 
 function is_gate_step_failed(result: GateStepResult): boolean {
@@ -147,7 +160,6 @@ function should_print_body(result: GateStepResult, is_verbose: boolean): boolean
 // Seconds to one decimal, which is the resolution the answer is read at: the question a gate's
 // timing answers is "which of the four is the long pole", and no check is ever separated from
 // another by less than a tenth of a second.
-const MS_PER_SECOND = 1000
 const SECONDS_DECIMALS = 1
 
 function format_seconds(elapsed_ms: number): string {
@@ -285,5 +297,5 @@ const gate_report = {
 	report_gate_steps,
 }
 
-export type { GateReport, GateStep, GateStepResult }
+export type { CheckClaim, GateReport, GateStep, GateStepResult }
 export { gate_report }

package/scripts/gate/gate-run-steps.ts

@@ -2,17 +2,24 @@ import { availableParallelism } from 'node:os'
 import { bounded_pool } from '#scripts/lib/bounded-pool'
 import { buffered_process } from '#scripts/lib/buffered-process'
 import { unit_worker_share } from '#scripts/test/unit-worker-share'
-import { core_budget } from './core-budget'
+import { check_cpu, type CheckCpu } from './check-cpu'
+import { core_budget, type Admission } from './core-budget'
+import { free_cores } from './free-cores'
 import { gate_plan, type GatePlan } from './gate-plan'
-import type { GateStep, GateStepResult } from './gate-report'
-import { build_gate_step } from './gate-steps'
+import type { CheckClaim, GateStep, GateStepResult } from './gate-report'
+import { build_gate_step, with_granted_workers } from './gate-steps'
 import { project_checks } from './project-checks'
 
 // Running the gate's checks: each one under its place in the machine-wide budget, a reused one
 // (`check-reuse.ts`) without starting it. `verification-gate.ts` decides what runs and records the
 // outcome; this module only runs it.
 
-async function run_gate_step(step: GateStep): Promise<GateStepResult> {
+// `cpu` is the gate's shared reader, so concurrent checks each take their own growth; a lone call
+// reads its child alone from a baseline of its own.
+async function run_gate_step(
+	step: GateStep,
+	cpu: CheckCpu = check_cpu.check_cpu_reader(),
+): Promise<GateStepResult> {
 	if (step.skip_reason !== undefined) {
 		return {
 			label: step.label,
@@ -28,7 +35,7 @@ async function run_gate_step(step: GateStep): Promise<GateStepResult> {
 		step.cwd === undefined ? {} : { cwd: step.cwd },
 	)
 
-	return { label: step.label, command: step.command_args.join(' '), ...result }
+	return { label: step.label, command: step.command_args.join(' '), ...result, cpu_ms: cpu() }
 }
 
 // This gate's share of the machine, resolved once at the gate's entry and carried down as one value.
@@ -55,6 +62,8 @@ interface ReservedStep {
 	step: GateStep
 	weight: number
 	memory_mb: number
+	// The plan's `--maxWorkers` for the unit suite, the width the free memory bounds once it is admitted.
+	worker_cap: number | undefined
 	// When the check's own green record was taken, for a check `check-reuse.ts` found reusable.
 	reused_at: string | undefined
 }
@@ -72,6 +81,7 @@ async function build_reserved_steps(
 			step: await build_gate_step(check, process.cwd(), plan),
 			weight: gate_plan.check_weight(check, plan, available_cores),
 			memory_mb: gate_plan.check_memory(check, plan, available_cores),
+			worker_cap: plan.unit_worker_cap,
 			reused_at: reused.get(check.label),
 		})),
 	)
@@ -90,6 +100,34 @@ function reused_result(step: GateStep, reused_at: string): GateStepResult {
 	}
 }
 
+// What the check asked the budget for and what it ran at, for its ledger row (`gate-ledger.ts`).
+function claim_of(requested: number, admission: Admission): CheckClaim {
+	return {
+		requested,
+		granted: admission.granted ?? requested,
+		waited_ms: admission.waited_ms ?? 0,
+	}
+}
+
+// **The unit step's width is bounded by the free memory too** (joshuafolkken/kit#4528). The plan's cap
+// and the granted width are sized from the cores alone, and the `--maxWorkers` they become skips the
+// guard's own reading (`test-unit-guard.ts`), so the memory is read here, once the claim is admitted
+// and the suite is about to start. The free cores are not applied: the admission has already narrowed
+// the claim to them (joshuafolkken/kit#4167).
+async function admitted_step(
+	reserved: ReservedStep,
+	admission: Admission,
+	available_cores: number,
+): Promise<GateStep> {
+	if (reserved.step.label !== gate_plan.UNIT_LABEL) return reserved.step
+
+	const { memory_workers } = await free_cores.read({ available_cores })
+	const asked = admission.granted ?? reserved.worker_cap
+	const workers = unit_worker_share.cap_to_free(asked, memory_workers, available_cores)
+
+	return with_granted_workers(reserved.step, workers)
+}
+
 // **A nested gate takes no reservation, and the budget is what makes that necessary rather than
 // merely tidy**. The unit step spawns the suite, which runs this repository's
 // own gate tests; each of those is a gate inside the outer gate's unit reservation, and a place it
@@ -98,20 +136,26 @@ function reused_result(step: GateStep, reused_at: string): GateStepResult {
 async function run_reserved_step(
 	reserved: ReservedStep,
 	budget: BudgetContext,
+	cpu: CheckCpu,
 ): Promise<GateStepResult> {
 	if (reserved.reused_at !== undefined) return reused_result(reserved.step, reserved.reused_at)
-	if (!budget.is_reserved) return await run_gate_step(reserved.step)
+	if (!budget.is_reserved) return await run_gate_step(reserved.step, cpu)
 
 	return await core_budget.with_core_reservation(
 		reserved.weight,
 		async (admission) => ({
-			...(await run_gate_step(reserved.step)),
+			...(await run_gate_step(
+				await admitted_step(reserved, admission, budget.available_cores),
+				cpu,
+			)),
 			budget_note: core_budget.describe_overflow(admission),
+			claim: claim_of(reserved.weight, admission),
 		}),
 		{
 			budget: budget.available_cores,
 			memory_mb: reserved.memory_mb,
 			command: `gate ${reserved.step.label}`,
+			is_unit: reserved.step.label === gate_plan.UNIT_LABEL,
 		},
 	)
 }
@@ -129,6 +173,7 @@ async function run_gate_steps(
 	reused: ReusedChecks = new Map(),
 ): Promise<ReadonlyArray<GateStepResult>> {
 	const reserved = await build_reserved_steps(plan, budget.available_cores, reused)
+	const cpu = check_cpu.check_cpu_reader()
 
 	// **The checks run under the held mark, so a check's own dispatch claims nothing**.
 	// Each check is a `pnpm josh <target>` child, and a target that declares
@@ -139,7 +184,7 @@ async function run_gate_steps(
 			await bounded_pool.bounded_map(
 				reserved,
 				plan.concurrency,
-				async (entry) => await run_reserved_step(entry, budget),
+				async (entry) => await run_reserved_step(entry, budget, cpu),
 			),
 	)
 }

package/scripts/gate/gate-skip.ts

@@ -64,10 +64,19 @@ const FORCE_FLAG = '--force'
 // rewritten by the hook's own install each cost minutes before anyone could tell them apart.
 type GateReuse = { stamp: FileMapStamp } | { miss: string }
 
+// The fingerprint of every declared check's tools and environment (`verification-inputs.ts`).
+const INPUTS_MOVED = 'a checked tool or environment variable changed since the green gate'
+
 function base_moved(recorded: string | undefined, base: string): string {
 	return `the merge base moved since the green gate (${recorded ?? 'none'} → ${base})`
 }
 
+function stamp_miss(stamp: FileMapStamp, base: string): string | undefined {
+	if (stamp.base !== base) return base_moved(stamp.base, base)
+
+	return review_stamps.gate_stamp.describes_inputs(stamp) ? undefined : INPUTS_MOVED
+}
+
 function gate_reuse(
 	tree: Record<string, string>,
 	base: string | undefined,
@@ -79,9 +88,10 @@ function gate_reuse(
 	const stamp = review_brief.matching_stamp(review_stamps.gate_stamp.read(source), tree)
 
 	if (stamp === undefined) return { miss: 'no green gate record matches the changed files' }
-	if (stamp.base !== base) return { miss: base_moved(stamp.base, base) }
 
-	return { stamp }
+	const miss = stamp_miss(stamp, base)
+
+	return miss === undefined ? { stamp } : { miss }
 }
 
 function stamp_of(reuse: GateReuse): FileMapStamp | undefined {

package/scripts/gate/gate-steps.ts

@@ -42,6 +42,17 @@ async function build_gate_step(
 	return { label: check.label, command_args, cwd, skip_reason }
 }
 
+// The unit step at a narrower worker count: the one its claim was admitted at past the wait cap
+// (`core_admission.narrowed_weight`), or the one the free memory holds (`gate-run-steps.ts`). Any
+// other step, or one left as asked, is returned unchanged.
+function with_granted_workers(step: GateStep, granted: number | undefined): GateStep {
+	if (granted === undefined || step.label !== UNIT_LABEL) return step
+
+	const kept = step.command_args.filter((argument) => !argument.startsWith(`${UNIT_WORKER_FLAG}=`))
+
+	return { ...step, command_args: [...kept, `${UNIT_WORKER_FLAG}=${String(granted)}`] }
+}
+
 async function build_gate_steps(
 	start_directory: string,
 	plan: GatePlan = gate_plan.resolve_gate_plan(),
@@ -51,4 +62,4 @@ async function build_gate_steps(
 	)
 }
 
-export { build_gate_step, build_gate_steps, UNIT_WORKER_FLAG }
+export { build_gate_step, build_gate_steps, UNIT_WORKER_FLAG, with_granted_workers }

package/scripts/gate/input-fingerprint.ts

@@ -0,0 +1,42 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { stamp_file } from '#scripts/josh/stamp-file'
+
+// **The one fingerprint every kept result is computed with** (joshuafolkken/kit#4497). A reuse of a
+// verdict holds only while what it read holds, and each reader of a verdict once computed that on its
+// own — the ESLint cache's import closure, the test-read map's dirty files, the gate's tool versions —
+// so a miss in one (joshuafolkken/kit#4407, #4415, #4423, #4425) was a miss nowhere else. Every one now
+// digests a file, a set of files and a set of named entries here.
+
+// The digest of a path that does not exist, or cannot be read, so it still differs from any content.
+const ABSENT = 'absent'
+
+function of_content(content: Buffer | string): string {
+	return stamp_file.digest(content)
+}
+
+// One digest over `entries`, independent of their order.
+function of_entries(entries: Iterable<string>): string {
+	return of_content([...entries].toSorted((left, right) => left.localeCompare(right)).join('\n'))
+}
+
+function of_file(file_path: string): string {
+	try {
+		return of_content(readFileSync(file_path))
+	} catch {
+		return ABSENT
+	}
+}
+
+// Each of `relatives` (relative to `root`) keyed to the digest of its content, in path order.
+function of_files(root: string, relatives: Iterable<string>): Record<string, string> {
+	const sorted = [...new Set(relatives)].toSorted((left, right) => left.localeCompare(right))
+
+	return Object.fromEntries(
+		sorted.map((relative) => [relative, of_file(path.join(root, relative))]),
+	)
+}
+
+const input_fingerprint = { ABSENT, of_entries, of_file, of_files }
+
+export { input_fingerprint }