@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/review/review-interaction.ts

@@ -0,0 +1,94 @@
+import { project_checks } from '#scripts/gate/project-checks'
+import { changed_paths } from '#scripts/git/changed-paths'
+import { session_cite } from '#scripts/issue/session-cite'
+import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
+import { review_finding_ledger } from './review-finding-ledger'
+
+// The interaction review — one adversarial pass after `/code-review`, over a change to the run
+// tooling (joshuafolkken/kit#4276).
+//
+// **`/code-review` reads the diff for its own correctness, and the defects came from elsewhere**: most
+// of them were a new mechanism meeting an existing one — a pause meeting the next run, a count meeting
+// the per-second repaint. This pass is given one role, to find the existing features the change
+// breaks, and is due only where those meetings happen: the four directories below, in the kit
+// repository alone — a consumer's own `scripts/run/` is not kit's run tooling.
+//
+// **Its round is its own ledger line, `- ri:`**, so the merge gate tells it apart from `/code-review`'s
+// and `josh followup` refuses a due change that has none. The verdicts mirror `review_record.check`'s:
+// `not-required` covers both a change outside the directories and a checkout that keeps no ledger.
+
+const TARGET_DIRECTORIES = ['scripts/run/', 'scripts/lane/', 'scripts/backlog/', 'scripts/hooks/']
+
+const NOT_DUE_LINE =
+	'Interaction review not due: this is not the kit repository, or the change touches none of scripts/run/, scripts/lane/, scripts/backlog/ or scripts/hooks/.'
+
+const ROLE_LINES = [
+	'## Interaction review',
+	'This pass is not a second `/code-review`: do not hunt for bugs inside the diff — the round before it did. Your role is to find three existing features this change breaks. Check only these three:',
+	'1. Every state, command, label, file or process this change adds or gives a new meaning to — who else reads or writes it? Search the repository outside the diff for each. Where the plan has a `### 影響を受ける既存の利用者` section, check it names them all.',
+	'2. Does each of those readers and writers still behave correctly when the new state or value reaches it (for example, a paused lane counted as running)?',
+	'3. Does the change add heavy or synchronous work to a path called repeatedly — every second, every Bash call, every edit?',
+	"Report each break with the reader's `file:line` and the change's, rated by the rubric's severities; it is disposed of by `prompts/review.md` → \"Interaction review\".",
+]
+
+type InteractionStatus = 'ok' | 'missing' | 'not-required'
+
+function due_paths(
+	paths: ReadonlyArray<string>,
+	checkout: string = process.cwd(),
+): ReadonlyArray<string> {
+	if (!project_checks.is_kit_repository(checkout)) return []
+
+	return paths.filter((file) => TARGET_DIRECTORIES.some((directory) => file.startsWith(directory)))
+}
+
+function brief_block(targets: ReadonlyArray<string>): string {
+	const listed = targets.map((file) => `- ${file}`)
+
+	return [...ROLE_LINES, 'Changed in the run tooling:', ...listed].join('\n')
+}
+
+async function status_of(
+	issue: number,
+	paths: ReadonlyArray<string>,
+	root: string = observation_ledger_home.ledger_root(),
+): Promise<InteractionStatus> {
+	const content = due_paths(paths).length > 0 ? await observation_ledger_home.read(root) : undefined
+
+	if (content === undefined) return 'not-required'
+
+	return review_finding_ledger.has_issue_record(content, issue, 'interaction') ? 'ok' : 'missing'
+}
+
+// The status over this checkout's change — the reading `review:brief` takes.
+async function status(issue: number, root?: string): Promise<InteractionStatus> {
+	return await status_of(issue, await changed_paths.read_changed_paths(false), root)
+}
+
+const MISSING_REASON =
+	'This change touches the run tooling, and no interaction review is recorded for its issue — the pass that looks for the existing features a change breaks, which `/code-review` does not (joshuafolkken/kit#4276).'
+
+const REMEDY =
+	'Run it from `pnpm josh review:brief --interaction`, then record it with `pnpm josh review:record --interaction --issue <N> [<category>:<severity>:<file> ...]` — a clean pass is a call with no findings — and reissue the merge.'
+
+function refusal_message(issue: number): string {
+	return [MISSING_REASON, `Issue: ${session_cite.issue(issue)}`, REMEDY].join('\n')
+}
+
+// The merge gate's half: the refusal for a due change with no recorded pass, else `undefined`.
+async function refusal(issue: number, root?: string): Promise<string | undefined> {
+	return (await status(issue, root)) === 'missing' ? refusal_message(issue) : undefined
+}
+
+const review_interaction = {
+	brief_block,
+	due_paths,
+	NOT_DUE_LINE,
+	refusal,
+	refusal_message,
+	status,
+	status_of,
+}
+
+export type { InteractionStatus }
+export { review_interaction }

package/scripts/review/review-readers-scan.ts

@@ -0,0 +1,163 @@
+// The exported names a diff edits, read from one file's `git diff -U0` and its new text
+// (joshuafolkken/kit#4515). Pure: `review-untouched-readers.ts` reads the diff and searches each name.
+//
+// **A name is edited when a changed line falls inside its top-level declaration** — from the
+// declaration's first line to the line before the next one. Only a name another module can reach is
+// returned, spelled the way a reader writes it: a direct export as itself, a member of an exported
+// namespace object (`export { issue_merged }`) as `issue_merged.read_merged`. The namespace object
+// itself is skipped — a member added to it changes none of its readers.
+
+const HUNK_HEADER = /^@@ -\d+(?:,\d+)? \+(?<start>\d+)(?:,(?<count>\d+))? @@/u
+const DECLARATION =
+	/^(?:export\s+)?(?:async\s+)?(?:function\*?|const|let|class|type|interface|enum)\s+(?<name>\w+)/u
+const EXPORT_LIST = /^export\s+(?:type\s+)?\{(?<names>[^}]*)\}/gmu
+const IDENTIFIER = /^(?:type\s+)?(?<name>\w+)/u
+const DIRECT_EXPORT = /^export\s/u
+const LIST_SEPARATOR = ','
+// A blank line or a comment line — `//`, `/*`, or a block comment's ` *` continuation.
+const PREAMBLE = /^(?:\s*$|\s*\/[/*]|\s+\*)/u
+// From a 1-based line number to the index of the line above it.
+const TWO = 2
+
+interface Declaration {
+	name: string
+	line: number
+	is_exported: boolean
+}
+
+interface Edited {
+	// The spelling a reader uses — `name` or `namespace.member`.
+	target: string
+	line: number
+}
+
+function to_range(start: number, count: number): Array<number> {
+	return Array.from({ length: count }, (_unused, offset) => start + offset)
+}
+
+// A pure deletion (`+c,0`) is placed on the line before it, which still lies inside the declaration
+// it was cut from.
+function hunk_lines(header: string): Array<number> {
+	const groups = HUNK_HEADER.exec(header)?.groups
+
+	if (groups === undefined) return []
+
+	const start = Number(groups['start'])
+	const count = groups['count'] === undefined ? 1 : Number(groups['count'])
+
+	return count === 0 ? [start] : to_range(start, count)
+}
+
+function changed_lines(diff: string): Array<number> {
+	return diff.split('\n').flatMap((line) => hunk_lines(line))
+}
+
+function to_declaration(text: string, index: number): Declaration | undefined {
+	const name = DECLARATION.exec(text)?.groups?.['name']
+
+	if (name === undefined) return undefined
+
+	return { name, line: index + 1, is_exported: DIRECT_EXPORT.test(text) }
+}
+
+function declarations(source: string): Array<Declaration> {
+	const found = source.split('\n').map((text, index) => to_declaration(text, index))
+
+	return found.filter((entry): entry is Declaration => entry !== undefined)
+}
+
+function first_identifier(entry: string): string | undefined {
+	return IDENTIFIER.exec(entry.trim())?.groups?.['name']
+}
+
+function list_names(list: string): Array<string> {
+	const names = list.split(LIST_SEPARATOR).map((entry) => first_identifier(entry))
+
+	return names.filter((name): name is string => name !== undefined)
+}
+
+function exported_names(source: string): Set<string> {
+	const lists = [...source.matchAll(EXPORT_LIST)].map((match) => match.groups?.['names'] ?? '')
+
+	return new Set(lists.flatMap((list) => list_names(list)))
+}
+
+// The members of `const <name> = { … }`, or `undefined` where `name` is not an object literal. `name`
+// is a `\w+` match, so it carries no pattern syntax.
+function namespace_members(source: string, name: string): Array<string> | undefined {
+	const literal = new RegExp(String.raw`^const\s+${name}\s*=\s*\{(?<body>[^}]*)\}`, 'mu')
+	const body = literal.exec(source)?.groups?.['body']
+
+	return body === undefined ? undefined : list_names(body)
+}
+
+function namespaces(source: string, exported: ReadonlySet<string>): Map<string, Array<string>> {
+	const entries = [...exported].map((name) => [name, namespace_members(source, name)] as const)
+
+	return new Map(
+		entries.filter((entry): entry is [string, Array<string>] => entry[1] !== undefined),
+	)
+}
+
+// The line after a declaration's own text: the next declaration's line, moved back past the blank and
+// comment lines that introduce it — a comment edited above `b` edits `b`, not the `a` before it.
+function range_end(texts: ReadonlyArray<string>, next: number | undefined): number {
+	if (next === undefined) return Infinity
+
+	let end = next
+
+	while (end > 1 && PREAMBLE.test(texts[end - TWO] ?? '')) end -= 1
+
+	return end
+}
+
+function touched(source: string, lines: ReadonlySet<number>): Array<Declaration> {
+	const found = declarations(source)
+	const texts = source.split('\n')
+
+	return found.filter((declaration, index) => {
+		const end = range_end(texts, found[index + 1]?.line)
+
+		return [...lines].some((line) => line >= declaration.line && line < end)
+	})
+}
+
+function namespace_of(
+	name: string,
+	spaces: ReadonlyMap<string, ReadonlyArray<string>>,
+): string | undefined {
+	return [...spaces].find(([, members]) => members.includes(name))?.[0]
+}
+
+interface ExportView {
+	exported: ReadonlySet<string>
+	spaces: ReadonlyMap<string, ReadonlyArray<string>>
+}
+
+function target_of(declaration: Declaration, view: ExportView): string | undefined {
+	const { name } = declaration
+
+	if (view.spaces.has(name)) return undefined
+	if (declaration.is_exported || view.exported.has(name)) return name
+
+	const space = namespace_of(name, view.spaces)
+
+	return space === undefined ? undefined : `${space}.${name}`
+}
+
+function edited(source: string, diff: string): Array<Edited> {
+	const exported = exported_names(source)
+	const view = { exported, spaces: namespaces(source, exported) }
+	const edited_declarations = touched(source, new Set(changed_lines(diff)))
+	const found_targets = edited_declarations.map((declaration) => ({
+		target: target_of(declaration, view),
+		line: declaration.line,
+	}))
+
+	return found_targets.filter((entry): entry is Edited => entry.target !== undefined)
+}
+
+const review_readers_scan = { changed_lines, edited }
+
+export type { Edited }
+export { review_readers_scan }

package/scripts/review/review-record-cli.ts

@@ -1,11 +1,10 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
 import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
 import { review_comment_round } from './review-comment-round'
-import { review_finding_ledger, type Finding } from './review-finding-ledger'
+import { review_finding_ledger, type Finding, type LineKind } from './review-finding-ledger'
+import { review_interaction } from './review-interaction'
 import { review_record, type RecordVerdict } from './review-record'
 
 // `josh review:record --issue <N> [<category>:<severity>:<file> ...]` — the one write path for a
@@ -23,16 +22,21 @@ import { review_record, type RecordVerdict } from './review-record'
 // `josh review:record --check --issue <N>` is the read half `pnpm josh followup` runs before it
 // merges: `ok` / `not-required` exit zero, `missing` exits non-zero so the
 // merge is refused until the round is recorded. It mirrors `josh review:attest --check`.
+//
+// **`--interaction` records and checks the interaction review's pass instead** (`review-interaction.ts`):
+// the same grammar under `- ri:`. It takes no `--comment` — the pass runs before the pull request, and
+// a pass kept only on the issue would leave the merge gate reading it as missing.
 
-const ARGV_OFFSET = 2
 const FAILURE_EXIT_CODE = 1
 const USAGE =
-	'Usage: josh review:record --issue <N> [--comment] [<category>:<severity>:<file> ...] | josh review:record --check --issue <N>'
+	'Usage: josh review:record --issue <N> [--comment | --interaction] [<category>:<severity>:<file> ...] | josh review:record --check [--interaction] --issue <N>'
 const FILE_HINT = '  <file>: the cited path, optionally with :line'
-const CHECK_USAGE = 'Usage: josh review:record --check --issue <N>'
+const CHECK_USAGE = 'Usage: josh review:record --check [--interaction] --issue <N>'
 const RECORDED_LINE = 'Recorded: the review round for this issue is in the ledger.'
 const NOT_REQUIRED_LINE =
 	'No review-finding ledger is kept in this checkout, so there is nothing to check.'
+const INTERACTION_NOT_REQUIRED_LINE =
+	'No interaction review is due: the change touches no run tooling, or this checkout keeps no ledger.'
 const CARRIED_LINE =
 	'review-finding line(s) recorded on closed issues after their pull requests opened into the ledger.'
 const CARRY_FAILED_LINE =
@@ -41,6 +45,7 @@ const OPTIONS = {
 	issue: { type: 'string' },
 	check: { type: 'boolean' },
 	comment: { type: 'boolean' },
+	interaction: { type: 'boolean' },
 } as const
 
 interface Request {
@@ -51,6 +56,7 @@ interface Request {
 interface Parsed {
 	check: boolean
 	comment: boolean
+	interaction: boolean
 	issue: string | undefined
 	positionals: ReadonlyArray<string>
 }
@@ -99,6 +105,7 @@ function parse_argv(argv: ReadonlyArray<string>): Parsed | undefined {
 	return {
 		check: parsed.values.check === true,
 		comment: parsed.values.comment === true,
+		interaction: parsed.values.interaction === true,
 		issue: parsed.values.issue,
 		positionals: parsed.positionals,
 	}
@@ -129,13 +136,17 @@ function usage_text(): string {
 	].join('\n')
 }
 
-function build_lines(request: Request, date: string): ReadonlyArray<string> {
+function build_lines(
+	request: Request,
+	date: string,
+	kind: LineKind = 'code',
+): ReadonlyArray<string> {
 	if (request.findings.length === 0) {
-		return [review_finding_ledger.zero_round_line(date, request.issue)]
+		return [review_finding_ledger.zero_round_line(date, request.issue, kind)]
 	}
 
 	return request.findings.map((finding) =>
-		review_finding_ledger.finding_line(finding, date, request.issue),
+		review_finding_ledger.finding_line(finding, date, request.issue, kind),
 	)
 }
 
@@ -143,28 +154,62 @@ function confirmation(count: number, ledger_path: string): string {
 	return `Recorded ${String(count)} review-finding line(s) in ${ledger_path}.`
 }
 
-function check_line(verdict: RecordVerdict): string {
-	return verdict.status === 'ok' ? RECORDED_LINE : NOT_REQUIRED_LINE
+type CheckStatus = RecordVerdict['status']
+
+interface CheckMode {
+	status: (issue: number, root: string) => Promise<CheckStatus>
+	refusal: (issue: number) => string
+	not_required: string
 }
 
-async function run_check(issue: string | undefined, root: string): Promise<number> {
-	if (issue === undefined || !issue_number_shape.ISSUE_NUMBER_PATTERN.test(issue)) {
-		console.error(CHECK_USAGE)
+async function code_status(issue: number, root: string): Promise<CheckStatus> {
+	const verdict = await review_record.check(issue, root)
+
+	return verdict.status
+}
+
+// The two rounds a check reads, each with its own ledger line, refusal and quiet answer.
+const CHECK_MODES: Record<LineKind, CheckMode> = {
+	code: {
+		status: code_status,
+		refusal: review_record.refusal_message,
+		not_required: NOT_REQUIRED_LINE,
+	},
+	interaction: {
+		status: review_interaction.status,
+		refusal: review_interaction.refusal_message,
+		not_required: INTERACTION_NOT_REQUIRED_LINE,
+	},
+}
+
+function kind_of(parsed: Parsed): LineKind {
+	return parsed.interaction ? 'interaction' : 'code'
+}
+
+async function report_check(issue: number, mode: CheckMode, root: string): Promise<number> {
+	const status = await mode.status(issue, root)
+
+	if (status === 'missing') {
+		console.error(mode.refusal(issue))
 
 		return FAILURE_EXIT_CODE
 	}
 
-	const verdict = await review_record.check(Number(issue), root)
+	console.info(status === 'ok' ? RECORDED_LINE : mode.not_required)
 
-	if (verdict.status === 'ok' || verdict.status === 'not-required') {
-		console.info(check_line(verdict))
+	return 0
+}
 
-		return 0
-	}
+async function run_check(parsed: Parsed, root: string): Promise<number> {
+	const { issue } = parsed
+
+	if (issue === undefined || !issue_number_shape.ISSUE_NUMBER_PATTERN.test(issue)) {
+		console.error(CHECK_USAGE)
 
-	console.error(review_record.refusal_message(Number(issue)))
+		return FAILURE_EXIT_CODE
+	}
 
-	return FAILURE_EXIT_CODE
+	return await report_check(Number(issue), CHECK_MODES[kind_of(parsed)], root)
 }
 
 // **A comment that could not be posted fails the record**: it is the round's only copy, so a
@@ -216,7 +261,7 @@ async function append_round(
 }
 
 async function run_record(parsed: Parsed, now: Date, root: string): Promise<number> {
-	const request = to_request(parsed)
+	const request = parsed.comment && parsed.interaction ? undefined : to_request(parsed)
 
 	if (request === undefined) {
 		console.error(usage_text())
@@ -224,7 +269,7 @@ async function run_record(parsed: Parsed, now: Date, root: string): Promise<numb
 		return FAILURE_EXIT_CODE
 	}
 
-	const lines = build_lines(request, observation_ledger_home.ledger_date(now))
+	const lines = build_lines(request, observation_ledger_home.ledger_date(now), kind_of(parsed))
 
 	if (parsed.comment) return await post_comment(request.issue, lines)
 
@@ -247,15 +292,11 @@ async function run(
 		return FAILURE_EXIT_CODE
 	}
 
-	if (parsed.check) return await run_check(parsed.issue, root)
+	if (parsed.check) return await run_check(parsed, root)
 
 	return await run_record(parsed, now, root)
 }
 
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv, new Date())
-}
-
 const review_record_cli = {
 	accepted_values,
 	build_lines,
@@ -264,6 +305,4 @@ const review_record_cli = {
 	usage_text,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
-
 export { review_record_cli }

package/scripts/review/review-record-main.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { review_record_cli } from './review-record-cli'
+
+// The `josh review:record` entry, kept apart from `review-record-cli.ts` because `run-ship-review.ts`
+// imports that one: a bundle is one file, so a main guard there would fire for every command that
+// carries it (joshuafolkken/kit#4186).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = await review_record_cli.run(process.argv.slice(ARGV_OFFSET), new Date())
+}

package/scripts/review/review-round-one-blobs.ts

@@ -0,0 +1,221 @@
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
+import { review_tree } from './review-tree'
+
+// Round 1's files as git blobs, so round 2 can still name the fix delta after the change base moved
+// (joshuafolkken/kit#4165).
+//
+// **A lane merges the default branch between the rounds**, which moves the base, and the round-1 file
+// map then covers a different set of paths from the one read now. Its digests cannot be carried onto
+// the new base; blobs can. `capture` writes each round-1 path into the object store — nothing else:
+// no index, no commit, no ref. `carried_delta` then carries each path three ways — the old base, round
+// 1, the new base — and names the paths whose carried content differs from the working tree now. A
+// path the default branch alone changed carries to exactly what the merge left, so it drops out; what
+// is left is round 1's fixes.
+//
+// **Every failure answers `undefined`**, which round 2 reads as the moved-base refusal it gave before:
+// no recorded blobs, a carry that conflicts, or a git that cannot run one of the reads.
+
+// A path the working tree or a commit does not hold.
+const ABSENT = review_tree.ABSENT_DIGEST
+const SUCCESS_EXIT_CODE = 0
+const NUL = '\0'
+const NEWLINE = '\n'
+const TAB = '\t'
+const SPACE = ' '
+const OID_FIELD = 2
+const WRITE_FLAGS: ReadonlyArray<string> = ['-w']
+const READ_FLAGS: ReadonlyArray<string> = []
+
+interface Move {
+	// The base round 1 was read against, and the base now.
+	from: string | undefined
+	to: string | undefined
+	// The paths to read: for a carry, those changed against the base now.
+	paths: ReadonlyArray<string>
+}
+
+interface CarryInput extends Move {
+	// Round 1's blobs, from the snapshot.
+	blobs: Record<string, string> | undefined
+}
+
+interface Carry {
+	blobs: Record<string, string>
+	from: string
+	to: string
+	paths: ReadonlyArray<string>
+}
+
+interface Readings {
+	blobs: Record<string, string>
+	before: Record<string, string>
+	after: Record<string, string>
+	now: Record<string, string>
+}
+
+interface Sides {
+	base: string
+	round_one: string
+	moved: string
+}
+
+// git's paths are root-relative, so every command runs from the root rather than the caller's cwd.
+function repository_root(): string | undefined {
+	return git_spawn_sync.read(['rev-parse', '--show-toplevel'])
+}
+
+function hash_paths(
+	root: string,
+	paths: ReadonlyArray<string>,
+	flags: ReadonlyArray<string>,
+): Record<string, string> | undefined {
+	const present = paths.filter((relative) => existsSync(path.join(root, relative)))
+	const output =
+		present.length === 0
+			? ''
+			: git_spawn_sync.read(['hash-object', ...flags, '--', ...present], { cwd: root })
+
+	if (output === undefined) return undefined
+
+	const hashes = output.split(NEWLINE)
+	const hashed = new Map(present.map((relative, index) => [relative, hashes[index] ?? ABSENT]))
+
+	return Object.fromEntries(paths.map((relative) => [relative, hashed.get(relative) ?? ABSENT]))
+}
+
+// `<mode> <type> <oid>\t<path>`.
+function parse_entry(entry: string): [string, string] {
+	const tab = entry.indexOf(TAB)
+
+	return [entry.slice(tab + 1), entry.slice(0, tab).split(SPACE)[OID_FIELD] ?? ABSENT]
+}
+
+function blobs_at(
+	commit: string,
+	paths: ReadonlyArray<string>,
+	root: string,
+): Record<string, string> | undefined {
+	const result = git_spawn_sync.run(['ls-tree', '-r', '-z', commit, '--', ...paths], { cwd: root })
+
+	if (result.exit_code !== SUCCESS_EXIT_CODE) return undefined
+
+	return Object.fromEntries(
+		result.stdout
+			.split(NUL)
+			.filter((entry) => entry !== '')
+			.map((entry) => parse_entry(entry)),
+	)
+}
+
+// `git merge-file` exits with the number of conflicts, so only a clean merge answers an oid.
+function merged_blob({ base, round_one, moved }: Sides, root: string): string | undefined {
+	if ([base, round_one, moved].includes(ABSENT)) return undefined
+
+	return git_spawn_sync.read(['merge-file', '--object-id', round_one, base, moved], { cwd: root })
+}
+
+function carried_blob(sides: Sides, root: string): string | undefined {
+	if (sides.round_one === sides.base) return sides.moved
+	if (sides.moved === sides.base || sides.moved === sides.round_one) return sides.round_one
+
+	return merged_blob(sides, root)
+}
+
+// A path round 1 did not list was unchanged against its base, so round 1 held the base's blob.
+function sides_of(relative: string, readings: Readings): Sides {
+	const base = readings.before[relative] ?? ABSENT
+
+	return {
+		base,
+		round_one: readings.blobs[relative] ?? base,
+		moved: readings.after[relative] ?? ABSENT,
+	}
+}
+
+function differing(
+	paths: ReadonlyArray<string>,
+	readings: Readings,
+	root: string,
+): ReadonlyArray<string> | undefined {
+	const carried = paths.map((relative) => carried_blob(sides_of(relative, readings), root))
+
+	if (carried.includes(undefined)) return undefined
+
+	return paths.filter((relative, index) => carried[index] !== readings.now[relative])
+}
+
+function read_readings(
+	input: Carry,
+	paths: ReadonlyArray<string>,
+	root: string,
+): Readings | undefined {
+	const before = blobs_at(input.from, paths, root)
+	const after = blobs_at(input.to, paths, root)
+	const now = hash_paths(root, paths, READ_FLAGS)
+
+	if (before === undefined || after === undefined || now === undefined) return undefined
+
+	return { blobs: input.blobs, before, after, now }
+}
+
+// No paths at all is an empty delta: `ls-tree` given none would list the whole tree.
+function delta_of(input: Carry, root: string): ReadonlyArray<string> | undefined {
+	const paths = [...new Set([...Object.keys(input.blobs), ...input.paths])].toSorted(
+		(left, right) => left.localeCompare(right),
+	)
+	const readings = paths.length === 0 ? undefined : read_readings(input, paths, root)
+
+	if (paths.length === 0) return []
+
+	return readings === undefined ? undefined : differing(paths, readings, root)
+}
+
+function carried_delta(input: CarryInput): ReadonlyArray<string> | undefined {
+	const { blobs, from, to } = input
+	const root = repository_root()
+
+	if (root === undefined || blobs === undefined || from === undefined || to === undefined) {
+		return undefined
+	}
+
+	return delta_of({ blobs, from, to, paths: input.paths }, root)
+}
+
+function unmoved_between(
+	from: string,
+	to: string,
+	paths: ReadonlyArray<string>,
+	root: string,
+): ReadonlyArray<string> | undefined {
+	if (from === to || paths.length === 0) return paths
+	const before = blobs_at(from, paths, root)
+	const after = blobs_at(to, paths, root)
+
+	if (before === undefined || after === undefined) return undefined
+
+	return paths.filter((relative) => (before[relative] ?? ABSENT) === (after[relative] ?? ABSENT))
+}
+
+// The paths the base move left alone: there the carry reproduces round 1's file, so the fix delta on
+// them is round 1 against the working tree, as on an unmoved base. `undefined` when git cannot say.
+function unmoved({ from, to, paths }: Move): ReadonlyArray<string> | undefined {
+	const root = repository_root()
+
+	if (root === undefined || from === undefined || to === undefined) return undefined
+
+	return unmoved_between(from, to, paths, root)
+}
+
+// Each path's blob, written into the object store so a later carry can merge it; `undefined` when git
+// cannot answer, which the record then omits.
+function capture(paths: ReadonlyArray<string>): Record<string, string> | undefined {
+	const root = repository_root()
+
+	return root === undefined ? undefined : hash_paths(root, paths, WRITE_FLAGS)
+}
+
+const review_round_one_blobs = { capture, carried_delta, unmoved }
+
+export { review_round_one_blobs }