@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/review/prose-stale-scan.ts

@@ -0,0 +1,152 @@
+import type { Hit } from '#scripts/git/git-grep-hits'
+import type { Hunk } from '#scripts/test/test-pinned-logic'
+import { review_readers_scan } from './review-readers-scan'
+
+// The words a diff removed that prose may still name (joshuafolkken/kit#5287) — the self-check's
+// "Prose matches the code" (`prompts/review.md`). Pure: `prose-stale-cli.ts` reads the diff and searches.
+//
+// **A removed line names four kinds of word**: a name (a top-level declaration, exported or not — a
+// namespace object's member is a plain `function` — or an `export { … }` entry) and an `UPPER_CASE`
+// constant on a code file's removed line (the declaration reading is `review-readers-scan.ts`'s), a `josh x:y` command
+// on any removed line, and a `.md` file's `#` heading. **A word the diff still writes is not removed**: an
+// identifier or command any added line carries, a heading an added `.md` line still titles, and a command
+// the registry still holds.
+
+type TermKind = 'name' | 'constant' | 'command' | 'heading'
+
+interface Term {
+	kind: TermKind
+	word: string
+}
+
+interface Reference {
+	term: Term
+	hits: ReadonlyArray<Hit>
+	has_failed: boolean
+}
+
+interface Report {
+	text: string
+	exit_code: number
+}
+
+const CODE_FILE = /\.(?:ts|js)$/u
+const MARKDOWN_EXTENSION = '.md'
+const COMMAND = /\bjosh\s+(?<command>[a-z][\w-]*:[\w:-]+)/gu
+const UPPER_CASE = /^[A-Z][A-Z\d_]*[A-Z\d]$/u
+const HEADING = /^#{1,6} (?<text>.+)$/u
+// A command token (`review:stops`) as well as an identifier, so one set answers both kinds.
+const TOKEN = /[\w-]+(?::[\w-]+)*/gu
+// A comment line of a code, shell or YAML file: `//`, `/*`, a block comment's `*`, or `#`.
+const COMMENT_LINE = /^\s*(?:\/[/*]|\*|#)/u
+const OK_LINE = 'ok'
+const FOUND_EXIT = 1
+const FAILED_EXIT = 2
+
+function to_terms(kind: TermKind, words: ReadonlyArray<string>): Array<Term> {
+	return words.map((word) => ({ kind, word }))
+}
+
+function code_terms(source: string): Array<Term> {
+	const declared = review_readers_scan.declarations(source).map((entry) => entry.name)
+	const listed = [...review_readers_scan.exported_names(source)]
+	const constants = declared.filter((name) => UPPER_CASE.test(name))
+	const names = [...declared.filter((name) => !UPPER_CASE.test(name)), ...listed]
+
+	return [...to_terms('name', names), ...to_terms('constant', constants)]
+}
+
+function command_terms(lines: ReadonlyArray<string>): Array<Term> {
+	const commands = lines.flatMap((line) =>
+		[...line.matchAll(COMMAND)].map((match) => match.groups?.['command'] ?? ''),
+	)
+
+	return to_terms('command', commands)
+}
+
+function headings(lines: ReadonlyArray<string>): Array<string> {
+	const texts = lines.map((line) => HEADING.exec(line)?.groups?.['text']?.trim())
+
+	return texts.filter((text): text is string => text !== undefined && text !== '')
+}
+
+function hunk_terms(hunk: Hunk): Array<Term> {
+	const lines = hunk.old_lines
+	const code = CODE_FILE.test(hunk.file) ? code_terms(lines.join('\n')) : []
+	const titled = hunk.file.endsWith(MARKDOWN_EXTENSION) ? to_terms('heading', headings(lines)) : []
+
+	return [...code, ...command_terms(lines), ...titled]
+}
+
+interface Kept {
+	tokens: ReadonlySet<string>
+	titles: ReadonlySet<string>
+	registered: ReadonlySet<string>
+}
+
+function kept_of(hunks: ReadonlyArray<Hunk>, registered: ReadonlySet<string>): Kept {
+	const added = hunks.flatMap((hunk) => hunk.new_lines ?? [])
+	const markdown = hunks.filter((hunk) => hunk.file.endsWith(MARKDOWN_EXTENSION))
+	const titles = headings(markdown.flatMap((hunk) => hunk.new_lines ?? []))
+	const tokens = added.flatMap((line) => [...line.matchAll(TOKEN)].map((match) => match[0]))
+
+	return { tokens: new Set(tokens), titles: new Set(titles), registered }
+}
+
+function is_removed(term: Term, kept: Kept): boolean {
+	if (term.kind === 'heading') return !kept.titles.has(term.word)
+	if (term.kind === 'command' && kept.registered.has(term.word)) return false
+
+	return !kept.tokens.has(term.word)
+}
+
+// Each removed word once, in diff order; `registered` is the command registry's names.
+function stale_terms(hunks: ReadonlyArray<Hunk>, registered: ReadonlySet<string>): Array<Term> {
+	const kept = kept_of(hunks, registered)
+	const unique = new Map(hunks.flatMap((hunk) => hunk_terms(hunk)).map((term) => [term.word, term]))
+
+	return [...unique.values()].filter((term) => is_removed(term, kept))
+}
+
+// A heading is searched quoted, the way a `→ "Heading"` pointer names it; any other word as a whole word.
+function pattern(term: Term): { target: string; flags: ReadonlyArray<string> } {
+	if (term.kind === 'heading') return { target: `"${term.word}"`, flags: [] }
+
+	return { target: term.word, flags: ['-w'] }
+}
+
+// Prose only: a `.md` line, or a comment line of any other searched file.
+function is_prose(hit: Hit): boolean {
+	return hit.path.endsWith(MARKDOWN_EXTENSION) || COMMENT_LINE.test(hit.excerpt)
+}
+
+function reference_lines(reference: Reference): Array<string> {
+	const { kind, word } = reference.term
+
+	if (reference.has_failed) return [`search failed: ${kind} ${word}`]
+
+	return reference.hits
+		.filter((hit) => is_prose(hit))
+		.map((hit) => `${hit.path}:${hit.line} ${kind} ${word}`)
+}
+
+function exit_code_of(references: ReadonlyArray<Reference>, lines: ReadonlyArray<string>): number {
+	if (references.some((reference) => reference.has_failed)) return FAILED_EXIT
+
+	return lines.length > 0 ? FOUND_EXIT : 0
+}
+
+// `ok` only when every search answered and none found prose; a failed search is never read as none.
+function report(references: ReadonlyArray<Reference>): Report {
+	const lines = references.flatMap((reference) => reference_lines(reference))
+
+	return {
+		text: lines.length > 0 ? lines.join('\n') : OK_LINE,
+		exit_code: exit_code_of(references, lines),
+	}
+}
+
+const prose_stale_scan = { FAILED_EXIT, pattern, report, stale_terms }
+
+export type { Reference, Term }
+export { prose_stale_scan }

package/scripts/review/removed-tests-check.ts

@@ -0,0 +1,86 @@
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { change_base } from '#scripts/git/change-base'
+import { changed_paths } from '#scripts/git/changed-paths'
+import { git_command } from '#scripts/git/git-command'
+import { test_declared_logic } from '#scripts/test/test-declared-logic'
+import type { TypeScriptApi } from './comment-ranges'
+import { removed_tests } from './removed-tests'
+import { review_code_tree } from './review-code-tree'
+import { test_titles } from './test-titles'
+
+// The reads behind `removed_tests`: the change base, the test files changed since it, each one's text
+// at the base and in the working tree, and the pull request body. Kept apart so the comparison stays
+// pure.
+//
+// **The base is the tree's, through a merge in progress** (`change_base.resolved_through_merge`): the
+// head side is the work tree, so a stopped merge of the default branch has already removed whatever
+// tests the default branch removed, and measuring from `HEAD`'s older merge-base would list them as
+// this change's own.
+//
+// **A base that cannot be resolved is a refusal, not a pass** — the tests it would have held are
+// exactly what this gate exists to see. A file is read at the base only where the base holds it, so a
+// failed `git show` throws rather than reading as a file that had no tests. TypeScript is an optional
+// peer of this package (`review_code_tree.load_typescript`): a project without it has no titles to
+// compare and merges as before.
+
+const UNREADABLE_MESSAGE =
+	'Merge refused: the change base could not be resolved, so the tests this change removes could not be listed; re-run once `git merge-base` answers.'
+
+function titles_in(api: TypeScriptApi, texts: ReadonlyArray<string>): ReadonlyArray<string> {
+	return texts.flatMap((text) => test_titles.titles_of(api, text))
+}
+
+async function base_texts(
+	base: string,
+	paths: ReadonlyArray<string>,
+): Promise<ReadonlyArray<string>> {
+	const held = await changed_paths.read_held_at(base, paths)
+
+	return await Promise.all(
+		held.map(async (relative) => await git_command.show_file(`${base}:${relative}`)),
+	)
+}
+
+// A test file the change deleted is absent from the tree, and every title it held reads as gone.
+function tree_texts(root: string, paths: ReadonlyArray<string>): ReadonlyArray<string> {
+	return paths
+		.map((relative) => path.join(root, relative))
+		.filter((absolute) => existsSync(absolute))
+		.map((absolute) => readFileSync(absolute, 'utf8'))
+}
+
+async function read(): Promise<ReadonlyArray<string> | undefined> {
+	const base = await change_base.resolved_through_merge()
+
+	if (base === undefined) return undefined
+	const root = await git_command.repository_root()
+	const api = review_code_tree.load_typescript(root)
+
+	if (api === undefined) return []
+	const changed = await changed_paths.read_changed_since(base)
+	const paths = changed.filter((relative) => test_declared_logic.is_test_file(relative))
+	const before = titles_in(api, await base_texts(base, paths))
+
+	return removed_tests.removed(before, titles_in(api, tree_texts(root, paths)))
+}
+
+// `josh ship`'s preflight asks the body it is about to deliver, so a missing disposition stops it
+// before the review rather than at the merge.
+async function body_refusal(pr_body: string | undefined): Promise<string | undefined> {
+	const removed = await read()
+
+	if (removed === undefined) return UNREADABLE_MESSAGE
+	const left = removed_tests.undisposed(removed, pr_body)
+
+	return left.length === 0 ? undefined : removed_tests.refusal_message(left)
+}
+
+async function refusal(branch_name: string): Promise<string | undefined> {
+	return await body_refusal(await git_gh_command.pr_get_body(branch_name))
+}
+
+const removed_tests_check = { body_refusal, read, refusal, UNREADABLE_MESSAGE }
+
+export { removed_tests_check }

package/scripts/review/removed-tests.ts

@@ -0,0 +1,149 @@
+import { markdown_section } from '#scripts/issue/markdown-section'
+import { report_format_reference } from '#scripts/report/report-format-reference'
+import { test_titles } from './test-titles'
+
+// A test is the record of a behavior, and a change that deletes one with no word of what replaced it
+// loses that behavior silently: the gate stays green and the review reads only what is there
+// (joshuafolkken/kit#4287, after #4171 dropped `lane_thresholds()` with the tests that guarded it).
+// **This is the seam where a deleted test has to be accounted for**: every test the base had and the
+// change no longer has is listed in the review brief, and the merge is refused until the pull request
+// body names, for each, the test that replaced it or the Issue that retired its behavior.
+//
+// **A test that moved is not deleted.** Tests are compared by full name across every changed test
+// file, so one moved to another file keeps its name. One moved under another `describe` keeps its own
+// title, so a gone name is matched against an arrived name with the same title, one for one — a common
+// title such as "returns undefined" deleted under one block is still listed when another block keeps
+// its own copy.
+
+const DISPOSITION_HEADING = '## 消えたテストの処置'
+// The heading as a line of its own, never the mention of it inside a format hint.
+const HEADING_LINE = new RegExp(String.raw`^${DISPOSITION_HEADING}[ \t]*$`, 'mu')
+const REPLACED = '置き換え'
+const RETIRED = '廃止'
+const PENDING_SUFFIX = '— 未記入'
+const BRIEF_HEADING = 'Removed tests'
+// The title runs to the first backtick that a disposition follows, so a title holding backticks of its
+// own — `it('reads the \`.each\` table')` — can still be disposed.
+const ROW_PATTERN = new RegExp(
+	String.raw`^[-*]\s+\x60(?<title>.+?)\x60\s+—\s+(?<kind>${REPLACED}|${RETIRED}):\s*(?<rest>\S.*)$`,
+	'u',
+)
+// A retirement names the Issue that decided it first — an Issue or a plan comment on one — then why.
+const RETIREMENT_PATTERN = /^(?:[\w.-]+\/[\w.-]+)?#\d+\s+\S/u
+const ROW_FORMAT = `under ${DISPOSITION_HEADING}, one line per removed test: \`- \`<test>\` — ${REPLACED}: <the test that guards the behavior now>\` or \`- \`<test>\` — ${RETIRED}: #<Issue that retired the behavior> <reason>\``
+
+function unique(titles: ReadonlyArray<string>): ReadonlyArray<string> {
+	return [...new Set(titles)]
+}
+
+function leaf_counts(titles: ReadonlyArray<string>): Map<string, number> {
+	const counts = new Map<string, number>()
+
+	for (const title of titles) {
+		const leaf = test_titles.leaf_of(title)
+
+		counts.set(leaf, (counts.get(leaf) ?? 0) + 1)
+	}
+
+	return counts
+}
+
+// Spends one arrived name with the same title, so each arrival accounts for one departure only.
+function is_moved(arrived: Map<string, number>, title: string): boolean {
+	const leaf = test_titles.leaf_of(title)
+	const left = arrived.get(leaf) ?? 0
+
+	if (left === 0) return false
+	arrived.set(leaf, left - 1)
+
+	return true
+}
+
+function removed(base: ReadonlyArray<string>, head: ReadonlyArray<string>): ReadonlyArray<string> {
+	const base_names = new Set(base)
+	const head_names = new Set(head)
+	const arrived = leaf_counts(unique(head).filter((title) => !base_names.has(title)))
+
+	return unique(base)
+		.filter((title) => !head_names.has(title))
+		.filter((title) => !is_moved(arrived, title))
+}
+
+// A retirement with no Issue is no row at all, so its test reads as undisposed.
+function is_cited(groups: Readonly<Record<string, string>>): boolean {
+	return groups['kind'] === REPLACED || RETIREMENT_PATTERN.test(groups['rest'] ?? '')
+}
+
+function disposed_title(line: string): string | undefined {
+	const groups = ROW_PATTERN.exec(line.trim())?.groups
+
+	if (groups === undefined || !is_cited(groups)) return undefined
+
+	return groups['title']
+}
+
+function undisposed(removed_titles: ReadonlyArray<string>, pr_body = ''): ReadonlyArray<string> {
+	const disposed = new Set(
+		markdown_section
+			.section_lines(pr_body, DISPOSITION_HEADING)
+			.map((line) => disposed_title(line)),
+	)
+
+	return removed_titles.filter((title) => !disposed.has(title))
+}
+
+function pending_rows(titles: ReadonlyArray<string>): ReadonlyArray<string> {
+	return titles.map((title) => `- \`${title}\` ${PENDING_SUFFIX}`)
+}
+
+function has_row(lines: ReadonlyArray<string>, title: string): boolean {
+	return lines.some((line) => line.trim().startsWith(`- \`${title}\` `))
+}
+
+// The pending rows a body still lacks, put under its disposition heading — added at the end when the
+// body has none — so a run fills them in before `josh ship` rather than meeting them at its preflight
+// (joshuafolkken/kit#4563). A title with any row already, pending or filled, is left as it is.
+function with_pending_rows(body: string, titles: ReadonlyArray<string>): string {
+	const lines = markdown_section.section_lines(body, DISPOSITION_HEADING)
+	const rows = pending_rows(titles.filter((title) => !has_row(lines, title))).join('\n')
+
+	if (rows === '') return body
+	if (!HEADING_LINE.test(body)) return `${body.trimEnd()}\n\n${DISPOSITION_HEADING}\n\n${rows}\n`
+
+	return body.replace(HEADING_LINE, () => `${DISPOSITION_HEADING}\n\n${rows}`)
+}
+
+// Nothing when the change removed no test, so an ordinary brief is not one line longer.
+function brief_block(removed_titles: ReadonlyArray<string>): ReadonlyArray<string> {
+	if (removed_titles.length === 0) return []
+
+	return [
+		'',
+		`${BRIEF_HEADING} — these tests existed at the base and are gone from the change. For each, find the test that guards its behavior now, or the Issue that retired the behavior; a removed test with neither is a finding (missing test). The pull request body must dispose of each ${ROW_FORMAT}, or \`josh followup\` refuses the merge:`,
+		...pending_rows(removed_titles),
+	]
+}
+
+function refusal_message(titles: ReadonlyArray<string>): string {
+	return [
+		`Merge refused: this change removes ${String(titles.length)} test(s) the pull request body does not account for.`,
+		`Put these rows into the body's ${DISPOSITION_HEADING} section, replacing each ending with the test that replaced it or the Issue that retired its behavior:`,
+		DISPOSITION_HEADING,
+		'',
+		...pending_rows(titles),
+		`Write ${ROW_FORMAT} — format: ${report_format_reference.pointer(report_format_reference.REMOVED_TESTS_HEADING)}`,
+		'Write it into the `--body-file` before `josh ship`, or update an open PR with `gh api -X PATCH repos/{owner}/{repo}/pulls/<N> -F body=@<path>`, then re-run.',
+	].join('\n')
+}
+
+const removed_tests = {
+	brief_block,
+	DISPOSITION_HEADING,
+	refusal_message,
+	removed,
+	ROW_FORMAT,
+	undisposed,
+	with_pending_rows,
+}
+
+export { removed_tests }

package/scripts/review/review-attest.ts

@@ -32,8 +32,20 @@ import { review_checkout, type ReviewCheckout } from './review-checkout'
 // **Absence is a failure, never a pass.** A fork that ignored the instruction leaves no attestation,
 // and `check` answers `missing` rather than `ok`: the one shape this record must never take is the
 // one the defect already had.
-
-const POINTER_PREFIX = 'josh-review-target-'
+//
+// **One pointer per review slot**: `/code-review` and the interaction review run side by side in a
+// ship (joshuafolkken/kit#4672), so a brief minted for one never drops the other's nonce, and `check`
+// asks every slot against its own nonce. The code slot's pointer is the one the resume narrowing and
+// the issue watch read.
+
+const REVIEW_SLOT = { CODE: 'code', INTERACTION: 'interaction' } as const
+const REVIEW_SLOTS = [REVIEW_SLOT.CODE, REVIEW_SLOT.INTERACTION] as const
+type ReviewSlot = (typeof REVIEW_SLOTS)[number]
+
+const POINTER_PREFIXES: Readonly<Record<ReviewSlot, string>> = {
+	code: 'josh-review-target-',
+	interaction: 'josh-review-interaction-target-',
+}
 const EXPECT_PREFIX = 'josh-review-expect-'
 const ATTEST_PREFIX = 'josh-review-attest-'
 
@@ -64,8 +76,8 @@ interface PointerRecord {
 	taken_at: string
 }
 
-function pointer_path(root: string = PROJECT_ROOT): string {
-	return stamp_file.stamp_path(POINTER_PREFIX, root)
+function pointer_path(root: string = PROJECT_ROOT, slot: ReviewSlot = REVIEW_SLOT.CODE): string {
+	return stamp_file.stamp_path(POINTER_PREFIXES[slot], root)
 }
 
 function expect_path(nonce: string): string {
@@ -114,8 +126,8 @@ function to_pointer(value: unknown): PointerRecord | undefined {
 	return undefined
 }
 
-function read_pointer(root?: string): PointerRecord | undefined {
-	return to_pointer(read_json(pointer_path(root)))
+function read_pointer(root?: string, slot?: ReviewSlot): PointerRecord | undefined {
+	return to_pointer(read_json(pointer_path(root, slot)))
 }
 
 function read_expectation(nonce: string): ReviewCheckout | undefined {
@@ -135,6 +147,13 @@ function drop_records(pointer: PointerRecord | undefined): void {
 	stamp_file.remove_stamp(attest_path(pointer.nonce))
 }
 
+function drop_slot(root: string | undefined, slot: ReviewSlot): void {
+	const pointer = read_pointer(root, slot)
+
+	stamp_file.remove_stamp(pointer_path(root, slot))
+	drop_records(pointer)
+}
+
 // An unparseable timestamp reads as stale rather than as fresh, so a corrupted record drops the
 // requirement instead of wedging every merge in the checkout that holds it.
 function is_stale(taken_at: string, now: number): boolean {
@@ -153,13 +172,23 @@ function is_stale(taken_at: string, now: number): boolean {
 // attestation rather than accepting the one an earlier round already satisfied. Leaving the old pair
 // on disk would only be litter, but an orphaned expectation is also a nonce a fork could still attest
 // against, which is a contract nobody is checking.
-function record_target(checkout: ReviewCheckout, root?: string): string {
+//
+// **A code brief opens a new round, and closes the interaction contract with it.** Only
+// `review:brief --interaction` mints that slot, after the code brief of its round, so a contract
+// left unattested — its reviewer died, or the fix took the change out of the interaction review's
+// paths — would otherwise refuse every later round 2 and merge in the checkout.
+function record_target(
+	checkout: ReviewCheckout,
+	root?: string,
+	slot: ReviewSlot = REVIEW_SLOT.CODE,
+): string {
 	const nonce = randomBytes(NONCE_BYTES).toString('hex')
 	const taken_at = new Date().toISOString()
 
-	drop_records(read_pointer(root))
+	if (slot === REVIEW_SLOT.CODE) drop_slot(root, REVIEW_SLOT.INTERACTION)
+	drop_records(read_pointer(root, slot))
 	stamp_file.write_stamp(expect_path(nonce), { ...checkout, taken_at })
-	stamp_file.write_stamp(pointer_path(root), { nonce, taken_at })
+	stamp_file.write_stamp(pointer_path(root, slot), { nonce, taken_at })
 
 	return nonce
 }
@@ -220,8 +249,8 @@ function verdict_for(nonce: string): AttestVerdict {
 // tree, and evidence does not expire. Checked first, a mismatch older than eight hours would answer
 // `not-required` and the merge would go through on exactly the review this whole record exists to
 // catch — a run that parks, waits on CI or resumes the next morning reaches that state normally.
-function check(now: number = Date.now(), root?: string): AttestVerdict {
-	const pointer = read_pointer(root)
+function check_slot(now: number, root: string | undefined, slot: ReviewSlot): AttestVerdict {
+	const pointer = read_pointer(root, slot)
 
 	if (pointer === undefined) return not_required()
 
@@ -232,6 +261,21 @@ function check(now: number = Date.now(), root?: string): AttestVerdict {
 	return verdict
 }
 
+function is_passing(verdict: AttestVerdict): boolean {
+	return verdict.status === 'ok' || verdict.status === not_required().status
+}
+
+// Every slot answers on its own nonce: the first refusal stands, else an `ok`, else `not-required`.
+function check(now: number = Date.now(), root?: string): AttestVerdict {
+	const verdicts = REVIEW_SLOTS.map((slot) => check_slot(now, root, slot))
+
+	return (
+		verdicts.find((verdict) => !is_passing(verdict)) ??
+		verdicts.find((verdict) => verdict.status === 'ok') ??
+		not_required()
+	)
+}
+
 function is_written_since(source: string, taken_at: string): boolean {
 	try {
 		const stats = lstatSync(source)
@@ -242,6 +286,18 @@ function is_written_since(source: string, taken_at: string): boolean {
 	}
 }
 
+// Whether the brief the pointer names was attested, on this branch — the half of a finished review
+// that does not depend on where its verdict was written down.
+function is_attested_on(checkout: Pick<ReviewCheckout, 'branch'>, root?: string): boolean {
+	const pointer = read_pointer(root)
+
+	if (pointer === undefined) return false
+
+	const verdict = verdict_for(pointer.nonce)
+
+	return verdict.status === 'ok' && verdict.expected?.branch === checkout.branch
+}
+
 // **Whether the last briefed review of this branch finished**. A ship resumed
 // after a stop re-issues round 1, and without this answer it briefed the whole change again — the
 // files the finished review had just read, re-read at full cost. It is asked before `record_target`
@@ -255,11 +311,7 @@ function is_written_since(source: string, taken_at: string): boolean {
 function is_reviewed_on(checkout: ReviewCheckout, findings_path: string, root?: string): boolean {
 	const pointer = read_pointer(root)
 
-	if (pointer === undefined) return false
-
-	const verdict = verdict_for(pointer.nonce)
-
-	if (verdict.status !== 'ok' || verdict.expected?.branch !== checkout.branch) return false
+	if (pointer === undefined || !is_attested_on(checkout, root)) return false
 
 	return is_written_since(findings_path, pointer.taken_at)
 }
@@ -286,10 +338,7 @@ async function check_here(now: number = Date.now()): Promise<AttestVerdict> {
 // contract's lifetime is one run, and a record left behind would be the one the *next* run's check
 // reads. Cleared out of turn it would drop the guard, so it is called from nowhere else.
 function clear(root?: string): void {
-	const pointer = read_pointer(root)
-
-	stamp_file.remove_stamp(pointer_path(root))
-	drop_records(pointer)
+	for (const slot of REVIEW_SLOTS) drop_slot(root, slot)
 }
 
 // The counterpart to `check_here`, keyed the same way and for the same reason.
@@ -328,24 +377,25 @@ function refusal_message(verdict: AttestVerdict): string {
 
 const review_attest = {
 	attest,
-	attest_path,
 	check,
 	check_here,
 	clear,
 	clear_here,
 	expect_path,
+	is_attested_on,
 	is_briefed_since,
 	is_reviewed_on,
 	MISMATCH_VERDICT,
 	MISSING_REASON,
-	pointer_path,
 	read_attestation,
 	read_expectation,
 	read_pointer,
 	record_target,
 	refusal_message,
+	REVIEW_SLOT,
+	REVIEW_SLOTS,
 	STALE_AFTER_MS,
 }
 
-export type { AttestVerdict }
+export type { AttestVerdict, ReviewSlot }
 export { review_attest }