@joshuafolkken/kit 1.1471.0 → 1.1784.0

package/scripts/issue/markdown-section.ts

@@ -3,6 +3,9 @@
 // way, so the slicing lives in one place rather than being written twice.
 
 const HEADING_PREFIX = '## '
+// A body saved from GitHub's web editor ends its lines with CRLF; a kept `\r` would end every line's
+// text with it and defeat each `$`-anchored match downstream.
+const LINE_BREAK_PATTERN = /\r?\n/u
 
 function is_heading(line: string): boolean {
 	return line.trimStart().startsWith(HEADING_PREFIX)
@@ -29,21 +32,31 @@ function next_fence(line: string, fence: string): string | undefined {
 	return undefined
 }
 
-function unfenced_lines(body: string): ReadonlyArray<string> {
+function lines_of(body: string): ReadonlyArray<string> {
+	return body.split(LINE_BREAK_PATTERN)
+}
+
+// The body's lines with every fenced line, fences included, blanked. Indentation is kept, so a list
+// item's indented continuation survives.
+function fence_free_lines(body: string): ReadonlyArray<string> {
 	let fence = ''
 	const visible: Array<string> = []
 
-	for (const line of body.split('\n')) {
+	for (const line of lines_of(body)) {
 		const next = next_fence(line, fence)
-		const visible_line = line.replace(/^(?: {4}|\t).*/u, '')
 
-		visible.push(next === undefined && fence === '' ? visible_line : '')
+		visible.push(next === undefined && fence === '' ? line : '')
 		fence = next ?? fence
 	}
 
 	return visible
 }
 
+// As `fence_free_lines`, with an indented code line (4 spaces or a tab) blanked too.
+function unfenced_lines(body: string): ReadonlyArray<string> {
+	return fence_free_lines(body).map((line) => line.replace(/^(?: {4}|\t).*/u, ''))
+}
+
 function has_unfenced_line(body: string, text: string): boolean {
 	return unfenced_lines(body).some((line) => line.trim() === text)
 }
@@ -59,7 +72,7 @@ function section_lines_matching(
 	body: string,
 	is_target: (line: string) => boolean,
 ): ReadonlyArray<string> {
-	const lines = body.split('\n')
+	const lines = lines_of(body)
 	const visible = unfenced_lines(body)
 	const start = visible.findIndex((line) => is_target(line))
 
@@ -80,6 +93,7 @@ function section_lines(body: string, heading: string): ReadonlyArray<string> {
 const markdown_section = {
 	section_lines,
 	section_lines_matching,
+	fence_free_lines,
 	unfenced_lines,
 	has_line,
 	has_unfenced_line,

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

@@ -24,7 +24,7 @@ import { session_cite } from './session-cite'
 
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
-const ISSUE_FIELDS = 'body,author_association'
+const ISSUE_FIELDS = 'body,author_association,user'
 const UNKNOWN_ASSOCIATION = 'unknown'
 const USAGE = 'Usage: josh measure:rerun <issue-number>'
 const NO_BASELINE = 'no `command → value` baseline found in ## ベースライン — nothing to re-run'
@@ -36,6 +36,7 @@ const MEASURE_TIMEOUT_MS = 60_000
 const issue_schema = z.object({
 	body: z.string().nullish(),
 	author_association: z.string().nullish(),
+	user: z.looseObject({ login: z.string() }).nullish(),
 })
 
 type IssueFields = z.infer<typeof issue_schema>
@@ -88,6 +89,15 @@ async function read_issue(issue_number: string): Promise<IssueFields | undefined
 	return json === undefined ? undefined : parse_json_object_or_undefined(json, issue_schema)
 }
 
+function untrusted(issue_number: string, issue: IssueFields): BodyRead {
+	const association = issue.author_association ?? UNKNOWN_ASSOCIATION
+
+	return {
+		kind: 'refused',
+		reason: `refusing to run the baseline of ${session_cite.issue(issue_number)}: its author (${association}) is not ${gh_author_association.TRUSTED_LIST}`,
+	}
+}
+
 // The body, only when its author can write to the repository. A read that fails is refused as well:
 // an unknown author is not a trusted one.
 async function read_trusted_body(issue_number: string): Promise<BodyRead> {
@@ -97,14 +107,9 @@ async function read_trusted_body(issue_number: string): Promise<BodyRead> {
 		return { kind: 'refused', reason: `could not read issue ${session_cite.issue(issue_number)}` }
 	}
 
-	const association = issue.author_association ?? UNKNOWN_ASSOCIATION
+	const author = { login: issue.user?.login, association: issue.author_association }
 
-	if (!gh_author_association.is_trusted(association)) {
-		return {
-			kind: 'refused',
-			reason: `refusing to run the baseline of ${session_cite.issue(issue_number)}: its author is ${association}, not ${gh_author_association.TRUSTED_LIST}`,
-		}
-	}
+	if (!(await gh_author_association.is_trusted(author))) return untrusted(issue_number, issue)
 
 	return { kind: 'trusted', body: issue.body ?? '' }
 }

package/scripts/issue/plan-consumers-cli.ts

@@ -0,0 +1,39 @@
+import { plan_consumers } from '#scripts/issue/plan-consumers'
+
+// `josh plan:consumers <identifier...>` — prints each identifier's existing references and the draft
+// of a plan's existing-consumers section (`plan-consumers.ts`). A flag is refused rather than searched
+// for, since an identifier never starts with `-`.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const USAGE = 'Usage: josh plan:consumers <identifier...>'
+
+function identifiers_of(argv: ReadonlyArray<string>): Array<string> | undefined {
+	const identifiers = [...new Set(argv.map((argument) => argument.trim()))]
+
+	if (identifiers.length === 0) return undefined
+
+	return identifiers.some((identifier) => identifier === '' || identifier.startsWith('-'))
+		? undefined
+		: identifiers
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const identifiers = identifiers_of(argv)
+
+	if (identifiers === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const { text, has_failed } = await plan_consumers.report(identifiers)
+
+	console.info(text)
+
+	return has_failed ? FAILURE_EXIT_CODE : SUCCESS_EXIT_CODE
+}
+
+const plan_consumers_cli = { USAGE, run }
+
+export { plan_consumers_cli }

package/scripts/issue/plan-consumers-main.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { plan_consumers_cli } from './plan-consumers-cli'
+
+// The `josh plan:consumers` entry, kept apart from `plan-consumers-cli.ts` so a bundle carrying that
+// module never fires this guard (joshuafolkken/kit#4186).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = await plan_consumers_cli.run(process.argv.slice(ARGV_OFFSET))
+}

package/scripts/issue/plan-consumers-section.ts

@@ -0,0 +1,55 @@
+import { markdown_section } from '#scripts/issue/markdown-section'
+
+// A plan's existing-consumers section (`HEADING`) — the existing code, prompts and documents that
+// read or write each state, command, label, file or process the plan adds or changes, and what this
+// issue does with each. A concept added without it shipped while its readers still assumed the old
+// world (joshuafolkken/kit#4270, #4265 after `lane:pause`), so `issue:plan` refuses a plan that omits
+// it.
+//
+// **"None" is an answer only with its reason** (`NONE_WITH_REASON`), since a bare "none" cannot be
+// told from a section filled in to get past the check.
+
+const HEADING = '### 影響を受ける既存の利用者'
+const ANY_HEADING = /^#{1,6}\s/u
+const LIST_MARKER = /^(?:[-*+]|\d+\.)\s+/u
+const NONE_WORD = 'なし'
+const NONE_WITH_REASON = /^なし\s*[（(]\s*\S.*[）)]$/u
+const MISSING = `The plan has no \`${HEADING}\` section: list, for each state, command, label, file or process it adds or changes, the existing places that read or write it and what this issue does with each (\`pnpm josh plan:consumers <identifier...>\` drafts it), or write \`なし（<reason>）\`.`
+const EMPTY = `The plan's \`${HEADING}\` section is empty: list the existing consumers, or write \`なし（<reason>）\`.`
+const BARE_NONE = `The plan's \`${HEADING}\` section says \`なし\` without a reason: write \`なし（<reason>）\`.`
+
+// The section runs to the next heading of any level, since the plan's own sections are `###`. Fenced
+// lines are blanked first, so a `# comment` in a code block neither ends the section nor is an entry.
+function section_entries(plan: string): ReadonlyArray<string> | undefined {
+	if (!markdown_section.has_line(plan, HEADING)) return undefined
+	const raw = markdown_section.section_lines(plan, HEADING).join('\n')
+	const lines = markdown_section.fence_free_lines(raw)
+	const end = lines.findIndex((line) => ANY_HEADING.test(line.trim()))
+	const body = end === -1 ? lines : lines.slice(0, end)
+
+	return body.map((line) => line.trim().replace(LIST_MARKER, '')).filter((line) => line !== '')
+}
+
+// "None" answers for the whole section, so only a section that opens with it is read as one — a "none"
+// nested under a consumer entry is that entry's note. A reason wrapped onto later lines is joined back.
+function is_bare_none(entries: ReadonlyArray<string>): boolean {
+	const [first = ''] = entries
+
+	if (!first.startsWith(NONE_WORD) || NONE_WITH_REASON.test(first)) return false
+
+	return !NONE_WITH_REASON.test(entries.join(' '))
+}
+
+// The refusal for a plan whose section is missing, empty or a reasonless "none"; `undefined` passes.
+function refusal_of(plan: string): string | undefined {
+	const entries = section_entries(plan)
+
+	if (entries === undefined) return MISSING
+	if (entries.length === 0) return EMPTY
+
+	return is_bare_none(entries) ? BARE_NONE : undefined
+}
+
+const plan_consumers_section = { HEADING, refusal_of }
+
+export { plan_consumers_section }

package/scripts/issue/plan-consumers.ts

@@ -0,0 +1,127 @@
+import { git_grep_hits, type Hit } from '#scripts/git/git-grep-hits'
+import { plan_consumers_section } from '#scripts/issue/plan-consumers-section'
+
+// `josh plan:consumers <identifier...>` — where each identifier a plan adds or changes is already
+// read or written, so its existing-consumers section names them rather than leaving them for the
+// next incident to find. Every reference in the tracked tree — a CI workflow or a settings file reads
+// a name as surely as code does — grouped by kind, then a draft of the section for the plan to finish.
+// `.josh/` is left out: its observations and metrics record past runs rather than read the name.
+//
+// **Unlike `run:prep`'s code locations it keeps every line and every kind** — a prompt that tells a
+// run to count a label is as much a consumer of it as the code that does — but caps each kind, so one
+// common name cannot bury the rest.
+
+type Kind = 'code' | 'config' | 'doc' | 'prompt' | 'test'
+
+interface Consumers {
+	identifier: string
+	hits: ReadonlyArray<Hit>
+	has_failed: boolean
+}
+
+const PATHSPECS = [':(exclude).josh']
+const KINDS: ReadonlyArray<readonly [Kind, string]> = [
+	['code', 'code'],
+	['config', 'config and workflows'],
+	['prompt', 'prompts and skills'],
+	['doc', 'docs'],
+	['test', 'tests'],
+]
+const TEST_PATH = /(?:\.test\.ts|\.e2e\.ts|\.snap)$/u
+const CODE_PATH = /\.(?:ts|js|mjs|cjs|svelte|sh)$/u
+const PROMPT_ROOTS = ['prompts/', '.claude/']
+const MAX_HITS_PER_KIND = 20
+const MAX_DRAFT_FILES = 8
+const INDENT = '  '
+const HIT_INDENT = `${INDENT}${INDENT}`
+const HIT_SEPARATOR = '  '
+const NO_REFERENCE = ' — no reference in the tracked tree'
+const SEARCH_FAILED = ' — git grep failed; not searched'
+const DRAFT_ACTION = '<直す | 影響なし | 別 Issue>'
+const DRAFT_NO_REFERENCE = 'no existing reference'
+
+// Markdown under `prompts/` or `.claude/` instructs a run and other Markdown is read by people; the
+// rest that is neither code nor a test — workflows, settings, JSON and YAML data — is configuration.
+function markdown_kind(path: string): Kind {
+	return PROMPT_ROOTS.some((root) => path.startsWith(root)) ? 'prompt' : 'doc'
+}
+
+function kind_of(path: string): Kind {
+	if (TEST_PATH.test(path)) return 'test'
+	if (CODE_PATH.test(path)) return 'code'
+
+	return path.endsWith('.md') ? markdown_kind(path) : 'config'
+}
+
+function more_line(count: number): Array<string> {
+	return count > MAX_HITS_PER_KIND
+		? [`${HIT_INDENT}… +${String(count - MAX_HITS_PER_KIND)} more`]
+		: []
+}
+
+function format_kind(hits: ReadonlyArray<Hit>, kind: Kind, label: string): Array<string> {
+	const of_kind = hits.filter((hit) => kind_of(hit.path) === kind)
+
+	if (of_kind.length === 0) return []
+	const lines = of_kind
+		.slice(0, MAX_HITS_PER_KIND)
+		.map((hit) => `${HIT_INDENT}${hit.path}:${hit.line}${HIT_SEPARATOR}${hit.excerpt}`)
+
+	return [`${INDENT}${label}`, ...lines, ...more_line(of_kind.length)]
+}
+
+function format_consumers(consumers: Consumers): string {
+	if (consumers.has_failed) return `${consumers.identifier}${SEARCH_FAILED}`
+	if (consumers.hits.length === 0) return `${consumers.identifier}${NO_REFERENCE}`
+	const kinds = KINDS.flatMap(([kind, label]) => format_kind(consumers.hits, kind, label))
+
+	return [consumers.identifier, ...kinds].join('\n')
+}
+
+// Tests are left out of the draft: a test follows the code it covers, so it is never the consumer a
+// plan has to decide about.
+function kind_rank(path: string): number {
+	return KINDS.findIndex(([kind]) => kind === kind_of(path))
+}
+
+// Code first, in `KINDS` order, so the cap drops docs before the code a plan most has to decide on.
+function draft_files(hits: ReadonlyArray<Hit>): Array<string> {
+	const paths = [...new Set(hits.map((hit) => hit.path))]
+		.filter((path) => kind_of(path) !== 'test')
+		.toSorted((left, right) => kind_rank(left) - kind_rank(right))
+	const shown = paths.slice(0, MAX_DRAFT_FILES).map((path) => `\`${path}\``)
+	const rest = paths.length - shown.length
+
+	return rest > 0 ? [...shown, `+${String(rest)} more`] : shown
+}
+
+function draft_entry(consumers: Consumers): string {
+	const files = draft_files(consumers.hits)
+
+	if (files.length === 0) return `- \`${consumers.identifier}\`: ${DRAFT_NO_REFERENCE}`
+
+	return `- \`${consumers.identifier}\`: ${files.join(', ')} — ${DRAFT_ACTION}`
+}
+
+function format_draft(all: ReadonlyArray<Consumers>): string {
+	const entries = all.map((consumers) => draft_entry(consumers))
+
+	return ['draft:', plan_consumers_section.HEADING, '', ...entries].join('\n')
+}
+
+async function find(identifier: string): Promise<Consumers> {
+	return { identifier, ...(await git_grep_hits.search(identifier, [], PATHSPECS)) }
+}
+
+async function report(
+	identifiers: ReadonlyArray<string>,
+): Promise<{ text: string; has_failed: boolean }> {
+	const all = await Promise.all(identifiers.map(async (identifier) => await find(identifier)))
+	const sections = [...all.map((consumers) => format_consumers(consumers)), format_draft(all)]
+
+	return { text: sections.join('\n\n'), has_failed: all.some((consumers) => consumers.has_failed) }
+}
+
+const plan_consumers = { kind_of, report }
+
+export { plan_consumers }

package/scripts/josh/agent-session-environment.ts

@@ -1,7 +1,7 @@
 // The environment variables that name the **parent** agent session, and which a child session must
 // not inherit.
 //
-// `scripts/eval/eval-session.ts` and `josh run:wake` both launch a headless session. Two copies of
+// `tools/eval/eval-session.ts` and `josh run:wake` both launch a headless session. Two copies of
 // this list is the clone `CLAUDE.md`
 // prohibits, and this is the shape of clone that fails silently: the copy that drifts does not throw
 // or lint — the child dials the parent's private socket, is refused, and the session dies as

package/scripts/josh/command-usage.ts

@@ -0,0 +1,82 @@
+import { canonical_command, COMMAND_MAP } from './josh-command-map'
+import type { CommandUsage } from './josh-command-types'
+
+// The single renderer of a command's usage. `josh help <command>` prints it and
+// `tools/document/generate-command-usage.ts` writes it between a reference page's usage markers,
+// so the terminal and the page are one text (#3932). The usage itself sits on each command's entry
+// (#4185); which page renders it is the page's own `<!-- usage: <command> -->` span.
+
+const USAGE_PAGES: ReadonlyArray<string> = [
+	'docs/josh-commands.md',
+	'docs/josh-commands-run.md',
+	'docs/josh-commands-backlog.md',
+	'docs/josh-commands-automation.md',
+]
+const NOTE_GAP = 3
+
+interface ExampleLine {
+	command: string
+	note: string | undefined
+}
+
+function usage_for(name: string): CommandUsage | undefined {
+	return Object.hasOwn(COMMAND_MAP, name) ? COMMAND_MAP[name]?.usage : undefined
+}
+
+function example_line(name: string, example: CommandUsage['examples'][number]): ExampleLine {
+	const command = example.arguments ? `pnpm josh ${name} ${example.arguments}` : `pnpm josh ${name}`
+
+	return { command, note: example.note }
+}
+
+// Every comment starts in one column, so a block reads as a table of what each spelling does.
+function format_examples(name: string, usage: CommandUsage): string {
+	const lines = usage.examples.map((example) => example_line(name, example))
+	const width = Math.max(...lines.map((line) => line.command.length)) + NOTE_GAP
+	const rendered = lines.map((line) =>
+		line.note === undefined ? line.command : `${line.command.padEnd(width)}# ${line.note}`,
+	)
+
+	return ['```bash', ...rendered, '```'].join('\n')
+}
+
+function code_span(text: string): string {
+	return `\`${text}\``
+}
+
+function format_flags(flags: NonNullable<CommandUsage['flags']>): string {
+	const items = flags.map(
+		(flag) =>
+			`- ${flag.names.map((spelling) => code_span(spelling)).join(' / ')} — ${flag.description}`,
+	)
+
+	return ['**Options:**', '', ...items].join('\n')
+}
+
+function format_usage(name: string): string | undefined {
+	const usage = usage_for(name)
+	if (usage === undefined) return undefined
+	const flags = usage.flags === undefined ? [] : [format_flags(usage.flags)]
+
+	return [format_examples(name, usage), ...flags].join('\n\n')
+}
+
+// `josh help <command>`: the synopsis line, the description, then the usage block. An alias
+// resolves to its command; a name that is neither answers `undefined`.
+function format_command_help(input: string): string | undefined {
+	const name = canonical_command(input)
+	const entry = Object.hasOwn(COMMAND_MAP, name) ? COMMAND_MAP[name] : undefined
+	if (entry === undefined) return undefined
+	const [synopsis] = entry.reference
+	const head = synopsis ? `josh ${name} ${synopsis}` : `josh ${name}`
+
+	return [head, '', entry.description, '', format_usage(name)].join('\n')
+}
+
+const command_usage = {
+	USAGE_PAGES,
+	format_command_help,
+	format_usage,
+}
+
+export { command_usage }

package/scripts/josh/file-map-stamp.ts

@@ -3,7 +3,7 @@ import { stamp_file } from './stamp-file'
 
 // A stamp whose payload is "when this was taken, and the digest of every file it covers".
 //
-// `scripts/eval/eval-stamp.ts` was the only holder of this shape. `josh review:brief` needs two more
+// `tools/eval/eval-stamp.ts` was the only holder of this shape. `josh review:brief` needs two more
 // records of exactly the same kind — the gate's result, and the snapshot round 1 takes so round 2
 // can name the fix delta — and copying the payload type, its validation, the guarded read and the
 // comparison into a second module is the clone `CLAUDE.md` prohibits. What genuinely differs between
@@ -48,6 +48,14 @@ interface FileMapStamp {
 	// reads it and the two `josh review:brief` records, which assert a completed past fact by
 	// existing at all, neither write nor read it.
 	completed_at?: string
+	// The git blob of each mapped path as it was read — written only by the round-1 review snapshot
+	// (`review-round-one-blobs.ts`). When `base` moves, round 2 carries these onto the new base and
+	// measures the fix delta from there; a record without them falls back to the moved-base refusal.
+	blobs?: Record<string, string>
+	// The fingerprint of what the vouched check reads beside the files — its tools' versions and its
+	// environment (`verification-inputs.ts`, joshuafolkken/kit#4495). Written by a record created with an
+	// `inputs` source; a reader of such a record refuses one whose fingerprint is absent or differs.
+	inputs?: string
 }
 
 // Takes `unknown` rather than the declared field type, because the declared type is an assertion
@@ -64,28 +72,38 @@ function is_file_map(value: unknown): value is Record<string, string> {
 // reader treats an absent field as the safe answer — "not running" for a `pid`, "cannot be reused"
 // for a `base`. Spread rather than assigned, because `exactOptionalPropertyTypes` makes an explicit
 // `undefined` a different thing from an absent key.
-function optional_fields(
-	pid: unknown,
-	base: unknown,
-	completed_at: unknown,
-	process_start: unknown,
-): Partial<FileMapStamp> {
+function identity_fields({ pid, process_start }: Partial<FileMapStamp>): Partial<FileMapStamp> {
 	return {
 		...(typeof pid === 'number' && { pid }),
+		...(typeof process_start === 'string' && { process_start }),
+	}
+}
+
+function tree_fields({ base, completed_at, blobs }: Partial<FileMapStamp>): Partial<FileMapStamp> {
+	return {
 		...(typeof base === 'string' && { base }),
 		...(typeof completed_at === 'string' && { completed_at }),
-		...(typeof process_start === 'string' && { process_start }),
+		...(is_file_map(blobs) && { blobs }),
 	}
 }
 
+function input_fields({ inputs }: Partial<FileMapStamp>): Partial<FileMapStamp> {
+	return typeof inputs === 'string' ? { inputs } : {}
+}
+
 function parse_stamp(raw: string): FileMapStamp | undefined {
-	const { taken_at, files, pid, base, completed_at, process_start } = JSON.parse(
-		raw,
-	) as Partial<FileMapStamp>
+	const parsed = JSON.parse(raw) as Partial<FileMapStamp>
+	const { taken_at, files } = parsed
 
 	if (typeof taken_at !== 'string' || !is_file_map(files)) return undefined
 
-	return { taken_at, files, ...optional_fields(pid, base, completed_at, process_start) }
+	return {
+		taken_at,
+		files,
+		...identity_fields(parsed),
+		...tree_fields(parsed),
+		...input_fields(parsed),
+	}
 }
 
 // Whether the process that wrote this record is still running. It takes the
@@ -152,14 +170,22 @@ function changed_since(stamp: FileMapStamp, tree: Record<string, string>): Reado
 interface FileMapStampAccess {
 	stamp_path: () => string
 	// `base` is written by the one record that is acted on rather than merely reported — the
-	// green-gate reuse. The others omit it and are unaffected.
-	write: (files: Record<string, string>, target?: string, base?: string) => string
+	// green-gate reuse. The others omit it and are unaffected. `blobs` is the round-1 snapshot's alone.
+	write: (
+		files: Record<string, string>,
+		target?: string,
+		base?: string,
+		blobs?: Record<string, string>,
+	) => string
 	// Marks an existing record as belonging to a run that finished. It
 	// amends rather than rewrites, and answers `undefined` where there is no record to amend: a run
 	// whose record never got written has nothing to assert a completion about, and inventing one here
 	// would manufacture the very vouching the field exists to withhold.
 	complete: (target?: string) => string | undefined
 	read: (source?: string) => FileMapStamp | undefined
+	// Whether `stamp` was written under the inputs fingerprint read now; always `true` for a record
+	// created without an `inputs` source, which never vouches for a check.
+	describes_inputs: (stamp: FileMapStamp) => boolean
 	// For a record whose meaning is its existence rather than its contents — the in-flight gate marker.
 	// A record nobody removes would go on asserting a gate that ended.
 	remove: (target?: string) => void
@@ -219,7 +245,11 @@ function complete_at(target: string): string | undefined {
 // The destination is a parameter on both sides so a test can exercise the round trip without
 // overwriting the record a real run may be relying on — two commands share one path by design, and a
 // suite that wrote to it would be a second writer nobody declared.
-function create(prefix: string, root?: string): FileMapStampAccess {
+//
+// `inputs` answers the fingerprint of what the record vouches for beside its files
+// (`verification-inputs.ts`); it is read at each write and each comparison, so a tool reinstalled or an
+// environment variable changed between them leaves the record standing for nobody.
+function create(prefix: string, root?: string, inputs?: () => string): FileMapStampAccess {
 	function resolve(): string {
 		return stamp_file.stamp_path(prefix, root)
 	}
@@ -229,15 +259,18 @@ function create(prefix: string, root?: string): FileMapStampAccess {
 		// `base` goes into the payload undefined and all — `JSON.stringify` drops an undefined value,
 		// so a caller that has no base writes exactly the record it wrote before this field existed.
 		// `own_fields` is what writes the pid, and the writing process's start time beside it — assembled in one place so no record can carry half an identity.
-		write: (files, target = resolve(), base?: string) =>
+		write: (files, target = resolve(), base?: string, blobs?: Record<string, string>) =>
 			stamp_file.write_stamp(target, {
 				taken_at: new Date().toISOString(),
 				files,
 				...process_identity.own_fields(),
 				base,
+				blobs,
+				inputs: inputs?.(),
 			}),
 		complete: (target = resolve()) => complete_at(target),
 		read: (source = resolve()) => read_at(source),
+		describes_inputs: (stamp) => inputs === undefined || stamp.inputs === inputs(),
 		remove: (target = resolve()) => {
 			stamp_file.remove_stamp(target)
 		},