@joshuafolkken/kit 1.3044.0 → 1.3099.0

package/scripts/init/init-logic.ts

@@ -1,5 +1,6 @@
 import { json_format } from '#scripts/config-merge/json-format'
 import { vscode_settings_schema } from '#scripts/lib/schemas'
+import { npm_acquisition } from '#scripts/registry-migration/npm-acquisition'
 import { safe_chain_preinstall } from '#scripts/safe-chain/preinstall-command'
 import { distributed_paths } from './distributed-paths'
 import { init_logic_deploy_vps } from './init-logic-deploy-vps'
@@ -89,6 +90,9 @@ const AI_COPY_FILES: ReadonlyArray<string> = [
 	'scripts/gate/change-scope-action.ts',
 	'scripts/gate/path-glob.ts',
 	'scripts/gate/toolchain-inputs.ts',
+	'scripts/gate/change-scope-action.integration.test.ts',
+	'scripts/gate/path-glob.test.ts',
+	'scripts/gate/toolchain-inputs.consumer.test.ts',
 	'.github/pull_request_template.md',
 	'.github/release.yml',
 	'.claude/settings.json',
@@ -263,11 +267,13 @@ function append_missing_lines(existing: string, missing: ReadonlyArray<string>):
 // the credential expanded, and that setting can live in a deploy platform's dashboard — so no
 // reading of the repository tells an inert auth line apart from a live one. Deleting it took down a
 // working production deploy. See docs/authentication.md §4(d).
-function merge_npmrc(content: string): string {
+function merge_npmrc(content: string, root?: string): string {
 	const lines = content.split('\n')
 	const kept = lines.filter((line) => !LEGACY_NPMRC_LINES.has(line.trim()))
 
-	return kept.length === lines.length ? content : kept.join('\n')
+	const merged = kept.length === lines.length ? content : kept.join('\n')
+
+	return root === undefined ? merged : npm_acquisition.merge_npmrc(merged, root)
 }
 
 // A gitignore line worth appending during a union merge: real ignore patterns only.
@@ -361,10 +367,15 @@ function get_suggested_scripts(): Record<string, string> {
 // Drop the suggested `prepare` when the consumer already runs fix-gh-packages in
 // any script, so re-running `josh init` does not re-inject a duplicate hook that
 // fights the consumer's intentional consolidation.
-function get_suggested_scripts_for_content(content: string): Record<string, string> {
-	const scripts = get_suggested_scripts()
+function get_suggested_scripts_for_content(
+	content: string,
+	is_npm = false,
+): Record<string, string> {
+	const scripts = is_npm
+		? { ...get_suggested_scripts(), prepare: `(${GUARDED_LEFTHOOK_CMD} || true)` }
+		: get_suggested_scripts()
 	const has_fix = init_logic_json_merge.has_package_scripts_marker(content, FIX_GH_PACKAGES_MARKER)
-	if (!has_fix) return scripts
+	if (!has_fix || is_npm) return scripts
 
 	return Object.fromEntries(Object.entries(scripts).filter(([key]) => key !== PREPARE_KEY))
 }
@@ -387,11 +398,13 @@ function upgrade_prepare_lefthook_warning(content: string): string {
 // Append the guarded lifecycle commands to an existing `prepare` when no script yet runs
 // fix-gh-packages, so the dev-only hooks land in `prepare` instead of being lost when the
 // suggested-scripts merge skips the already-present `prepare` key.
-function merge_prepare_lifecycle_cmd(content: string): string {
+function merge_prepare_lifecycle_cmd(content: string, is_npm = false): string {
 	const has_fix = init_logic_json_merge.has_package_scripts_marker(content, FIX_GH_PACKAGES_MARKER)
-	if (has_fix) return content
+	if (has_fix && !is_npm) return content
+
+	const command = is_npm ? `(${GUARDED_LEFTHOOK_CMD} || true)` : PREPARE_CMD
 
-	return init_logic_json_merge.merge_package_script_suffix(content, PREPARE_KEY, PREPARE_CMD)
+	return init_logic_json_merge.merge_package_script_suffix(content, PREPARE_KEY, command)
 }
 
 // Migration: remove a kit-managed `postinstall` (one running the fix-gh-packages
@@ -399,6 +412,9 @@ function merge_prepare_lifecycle_cmd(content: string): string {
 // rather than the bare marker avoids stripping a consumer's unrelated postinstall that
 // merely mentions `fix-gh-packages` (e.g. `npm run my-fix-gh-packages-helper`).
 function strip_managed_postinstall(content: string): string {
+	const legacy = `${LEGACY_GUARDED_LEFTHOOK_CMD}; ${GUARDED_FIX_GH_PACKAGES_CMD}; true`
+	if (!npm_acquisition.is_script_value(content, LEGACY_POSTINSTALL_KEY, legacy)) return content
+
 	return init_logic_json_merge.remove_script_with_marker(
 		content,
 		LEGACY_POSTINSTALL_KEY,
@@ -406,6 +422,20 @@ function strip_managed_postinstall(content: string): string {
 	)
 }
 
+function upgrade_npm_lifecycle(content: string, root: string): string {
+	if (!npm_acquisition.is_npm_only(root)) return content
+	const stripped = strip_managed_postinstall(content)
+	const prepared =
+		stripped === content
+			? content
+			: init_logic_json_merge.merge_package_scripts(stripped, {
+					prepare: `(${GUARDED_LEFTHOOK_CMD} || true)`,
+				})
+	const merged = stripped === content ? prepared : merge_prepare_lifecycle_cmd(prepared, true)
+
+	return npm_acquisition.merge_lifecycle(merged, root, GUARDED_FIX_GH_PACKAGES_CMD)
+}
+
 const init_logic = {
 	...init_logic_templates,
 	...init_logic_workspace,
@@ -433,6 +463,7 @@ const init_logic = {
 	VSCODE_EXTENSIONS_FILENAME,
 	SAFE_CHAIN_CMD,
 	GUARDED_LEFTHOOK_CMD,
+	GUARDED_FIX_GH_PACKAGES_CMD,
 	upgrade_prepare_lefthook_warning,
 	get_development_engines_value,
 	get_ai_copy_files,
@@ -442,6 +473,7 @@ const init_logic = {
 	get_suggested_scripts_for_content,
 	merge_prepare_lifecycle_cmd,
 	strip_managed_postinstall,
+	upgrade_npm_lifecycle,
 }
 
 export { init_logic }

package/scripts/init/init.ts

@@ -5,6 +5,7 @@ import { doctor_io } from '#scripts/doctor/doctor-io'
 import { error_text } from '#scripts/lib/error-message'
 import { PACKAGE_JSON } from '#scripts/lib/package-manifest'
 import { package_version_schema, with_package_manager_schema } from '#scripts/lib/schemas'
+import { npm_acquisition } from '#scripts/registry-migration/npm-acquisition'
 import { auto_merge_setting } from '#scripts/repo/auto-merge-setting'
 import { pack_hook } from '#scripts/safe-chain/pack-hook'
 import { security_updates } from '#scripts/security/security-updates'
@@ -78,7 +79,10 @@ function get_kit_self_dependency(): Record<string, string> {
 // the toolchain is added here: without it the first `josh gate` after `pnpm install` fails.
 function apply_dependency_merges(content: string, has_git = true): string {
 	const migrated = init_logic.strip_managed_postinstall(content)
-	const suggested = init_logic.get_suggested_scripts_for_content(migrated)
+	const suggested = init_logic.get_suggested_scripts_for_content(
+		migrated,
+		npm_acquisition.is_npm_only(PROJECT_ROOT),
+	)
 	const merged = init_logic.merge_package_scripts(
 		migrated,
 		has_git
@@ -97,12 +101,16 @@ function apply_dependency_merges(content: string, has_git = true): string {
 function apply_package_json_merges(content: string, has_git = true): string {
 	const with_kit = apply_dependency_merges(content, has_git)
 	const upgraded = has_git ? init_logic.upgrade_prepare_lefthook_warning(with_kit) : with_kit
-	const with_lifecycle = has_git ? init_logic.merge_prepare_lifecycle_cmd(upgraded) : upgraded
+	const with_lifecycle = has_git
+		? init_logic.merge_prepare_lifecycle_cmd(upgraded, npm_acquisition.is_npm_only(PROJECT_ROOT))
+		: upgraded
 	const kit_pm = get_kit_package_manager()
 	const with_pm =
 		kit_pm === undefined ? with_lifecycle : init_logic.merge_package_manager(with_lifecycle, kit_pm)
 	const with_de = init_logic.merge_development_engines(with_pm, get_kit_development_engines())
-	const sorted = init_logic.sort_package_json_keys(with_de)
+	const sorted = init_logic.sort_package_json_keys(
+		init_logic.upgrade_npm_lifecycle(with_de, PROJECT_ROOT),
+	)
 
 	// Pin devEngines.packageManager.version to the packageManager just written so a
 	// freshly scaffolded (or re-initialized) consumer never trips the pnpm

package/scripts/issue/defect-rate-cli.ts

@@ -1,7 +1,9 @@
 import { shared_cache, type CacheSlot } from '#scripts/josh/shared-cache'
+import { run_startup } from '#scripts/run/startup/run-startup'
 import { z } from 'zod'
 import { defect_rate, type DefectRate } from './defect-rate'
 import { issue_search } from './issue-search'
+import { issue_search_count } from './issue-search-count'
 
 const MS_PER_MINUTE = 60_000
 const CACHE_TTL_MINUTES = 15
@@ -25,23 +27,22 @@ async function measure_uncached(
 	repo: string,
 	days: number,
 	since: string,
+	now_ms: number,
 ): Promise<DefectRate | undefined> {
 	const [filed, completed] = await Promise.all([
-		issue_search.search(defect_rate.filed_query(repo, since)),
-		issue_search.search(defect_rate.completed_query(repo, since)),
+		issue_search.search_complete(defect_rate.filed_query(repo, since), now_ms),
+		issue_search_count.count(defect_rate.completed_query(repo, since)),
 	])
 
 	if (filed === undefined || completed === undefined) return undefined
 
-	const is_capped = filed.is_capped || completed.is_capped
-
-	return defect_rate.measure({
+	return {
 		days,
 		since,
-		filed: filed.issues,
-		completed: completed.issues,
-		is_capped,
-	})
+		defects: filed.issues.filter((issue) => defect_rate.is_defect(issue)).length,
+		enhancements: completed,
+		is_capped: filed.is_capped,
+	}
 }
 
 // The rate over a window, or `undefined` when either search could not be read. `backlog:next` asks it.
@@ -54,10 +55,15 @@ async function measure_window(
 	const since = defect_rate.window_start(now_ms, days)
 	const key = [repo, String(days), since].join(' ')
 
-	return await shared_cache.remember(
-		{ slot: RATE_CACHE, key, schema: defect_rate_schema },
-		async () => await measure_uncached(repo, days, since),
-		now_ms,
+	return await run_startup.phase(
+		'defect rate',
+		async () =>
+			await shared_cache.remember(
+				{ slot: RATE_CACHE, key, schema: defect_rate_schema },
+				async () => await measure_uncached(repo, days, since, now_ms),
+				now_ms,
+			),
+		{ edge_of: (value) => (value === undefined ? 'failed' : 'done') },
 	)
 }
 

package/scripts/issue/issue-file-batch.ts

@@ -71,9 +71,13 @@ async function planned_of(
 async function scout_all(
 	planned: ReadonlyArray<Planned>,
 ): Promise<ReadonlyArray<ScoutOutcome | undefined>> {
-	const outcomes = await Promise.all(
-		planned.map(async ({ argv }) => await issue_file_cli.scout(argv)),
-	)
+	const outcomes: Array<ScoutOutcome | undefined> = []
+
+	for (const { argv } of planned) {
+		// eslint-disable-next-line no-await-in-loop -- scouts temporarily share GH_REPO
+		outcomes.push(await issue_file_cli.scout(argv))
+	}
+
 	const sections = planned.map(({ entry }, index) => {
 		const report = outcomes[index]?.report ?? SCOUT_UNANSWERED
 

package/scripts/issue/issue-file-cli.ts

@@ -26,6 +26,7 @@ import { issue_file_pass, type Filing } from './issue-file-pass'
 import { issue_file_worker } from './issue-file-worker'
 import { has_label_name, has_parked_label, RUN_SOLO_LABEL } from './issue-labels'
 import { issue_priority } from './issue-priority'
+import { issue_publication_state } from './issue-publication-state'
 import { issue_release_cli } from './issue-release-cli'
 import { issue_run_verdict } from './issue-run-verdict'
 import type { ScoutOutcome } from './issue-scout-cli'
@@ -79,8 +80,11 @@ async function create(filing: Filing, labels: ReadonlyArray<string>): Promise<st
 	)
 	const request = git_gh_issue_write.issue_create_request({
 		title: filing.args.title,
-		body: filing.body,
-		labels,
+		...issue_publication_state.creation(
+			filing.body,
+			labels,
+			filing.args.is_prepared === true || has_label_name(labels, 'route:split'),
+		),
 		repo: filing.target,
 	})
 
@@ -326,7 +330,9 @@ async function file_issue(
 ): Promise<string | undefined> {
 	const filing = await parsed_filing(argv)
 
-	return filing === undefined ? undefined : await file({ ...filing, scouted })
+	return filing === undefined
+		? undefined
+		: await issue_file_pass.with_repository_restored(async () => await file({ ...filing, scouted }))
 }
 
 // The scout `file_issue` would run, for `issue:file --batch` to run for every filing before the first.
@@ -334,16 +340,23 @@ async function scout(argv: ReadonlyArray<string>): Promise<ScoutOutcome | undefi
 	const args = issue_file.parse(argv)
 	const filing = args === undefined ? undefined : await filing_of(args)
 
-	return typeof filing === 'object' ? await issue_file_pass.scout_filing(filing) : undefined
+	return typeof filing === 'object'
+		? await issue_file_pass.with_repository_restored(
+				async () => await issue_file_pass.scout_filing(filing),
+			)
+		: undefined
 }
 
 async function run(argv: ReadonlyArray<string>): Promise<number> {
 	const filing = await parsed_filing(argv)
 
 	if (filing === undefined) return FAILURE_EXIT_CODE
-	if (filing.args.is_check) return await check(filing)
 
-	return (await file(filing)) === undefined ? FAILURE_EXIT_CODE : SUCCESS_EXIT_CODE
+	return await issue_file_pass.with_repository_restored(async () => {
+		if (filing.args.is_check) return await check(filing)
+
+		return (await file(filing)) === undefined ? FAILURE_EXIT_CODE : SUCCESS_EXIT_CODE
+	})
 }
 
 const issue_file_cli = {

package/scripts/issue/issue-file-main.ts

@@ -2,6 +2,7 @@
 import { fileURLToPath } from 'node:url'
 import { issue_file_batch } from './issue-file-batch'
 import { issue_file_cli } from './issue-file-cli'
+import { issue_publication } from './issue-publication'
 
 // The `josh issue:file` entry, kept apart from `issue-file-cli.ts` because `upstream:interrupt` imports
 // that one: a bundle is one file, so a main guard there would fire for every command that carries it
@@ -13,5 +14,9 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
 	const argv = process.argv.slice(ARGV_OFFSET)
 	const filing = issue_file_batch.is_batch(argv) ? issue_file_batch : issue_file_cli
 
-	process.exitCode = await filing.run(argv)
+	const is_publication = argv.some(
+		(argument) => argument === '--publish' || argument.startsWith('--publish='),
+	)
+
+	process.exitCode = await (is_publication ? issue_publication : filing).run(argv)
 }

package/scripts/issue/issue-file-pass.ts

@@ -25,6 +25,22 @@ import { size_estimate } from './size-estimate'
 // scout and `epic:bundle` make at the target repository rather than at this checkout.
 const GH_REPO_VARIABLE = 'GH_REPO'
 
+function restore_repository(original: string | undefined): void {
+	if (original === undefined) Reflect.deleteProperty(process.env, GH_REPO_VARIABLE)
+	else process.env[GH_REPO_VARIABLE] = original
+}
+
+// Keep the target available through placement, then restore the caller's exact environment.
+async function with_repository_restored<Result>(action: () => Promise<Result>): Promise<Result> {
+	const original = process.env[GH_REPO_VARIABLE]
+
+	try {
+		return await action()
+	} finally {
+		restore_repository(original)
+	}
+}
+
 interface Filing {
 	args: FileArguments
 	body: string
@@ -243,6 +259,7 @@ const issue_file_pass = {
 	GH_REPO_VARIABLE,
 	labels_in_one_pass,
 	scout_filing,
+	with_repository_restored,
 }
 
 export { issue_file_pass }

package/scripts/issue/issue-file.ts

@@ -56,6 +56,7 @@ interface FileArguments {
 	is_blocking_finder: boolean
 	// `--check`: every filing step runs and prints its verdict, and nothing is created on GitHub.
 	is_check: boolean
+	is_prepared?: boolean
 }
 
 const OPTIONS = {
@@ -71,6 +72,7 @@ const OPTIONS = {
 	release: { type: 'boolean' },
 	'blocks-finder': { type: 'boolean' },
 	check: { type: 'boolean' },
+	prepare: { type: 'boolean' },
 } as const
 
 // The label a `--route` value names, or `undefined` when it names none — read against the route
@@ -157,6 +159,7 @@ function arguments_of(values: ParsedValues, title: string | undefined): FileArgu
 		is_release: values.release === true,
 		is_blocking_finder: values['blocks-finder'] === true,
 		is_check: values.check === true,
+		is_prepared: values.prepare === true,
 	}
 }
 

package/scripts/issue/issue-not-before.ts

@@ -1,4 +1,5 @@
 import { issue_body_keys } from './issue-body-keys'
+import { issue_observation_gate } from './issue-observation-gate'
 import { issue_sample_gate } from './issue-sample-gate'
 import { markdown_section } from './markdown-section'
 import { measure_declaration } from './measure-declaration'
@@ -73,7 +74,11 @@ function is_date_due(body: string | undefined, now: number): boolean {
 
 // Whether the issue may start: its declared time has arrived and its declared samples are recorded.
 function is_due(body: string | undefined, now: number = Date.now()): boolean {
-	return is_date_due(body, now) && issue_sample_gate.wait_of(body) === undefined
+	return (
+		is_date_due(body, now) &&
+		issue_sample_gate.wait_of(body) === undefined &&
+		issue_observation_gate.wait_of(body) === undefined
+	)
 }
 
 // The declared time as epoch milliseconds while it is still ahead, or `undefined` when it has arrived —
@@ -97,7 +102,9 @@ function waiting_reason(body: string | undefined, now: number = Date.now()): str
 
 	const wait = issue_sample_gate.wait_of(body)
 
-	return wait === undefined ? undefined : issue_sample_gate.reason_of(wait)
+	return wait === undefined
+		? issue_observation_gate.wait_of(body)?.reason
+		: issue_sample_gate.reason_of(wait)
 }
 
 function stray_heading_problems(body: string): ReadonlyArray<string> {

package/scripts/issue/issue-observation-gate.ts

@@ -0,0 +1,141 @@
+import { lane_early_push_count } from '#scripts/lane/lane-early-push-count'
+import { markdown_section } from './markdown-section'
+
+// The issue pins both the evidence comment and every required key. Removing a task from the
+// comment cannot release it. This is an explicit, evidence-backed attestation, not a stop-text guess.
+const PREFIX = '<!-- josh:observation-wait'
+const DECLARATION =
+	/^<!-- josh:observation-wait:v1 (?<url>https:\/\/github\.com\/(?<repo>[\w.-]+\/[\w.-]+)\/issues\/[1-9]\d*#issuecomment-(?<comment>[1-9]\d*)) (?<keys>[\w-]+(?:,[\w-]+)*) -->$/u
+// An optional ledger condition before the close releases the wait once the ledger holds that many
+// samples (joshuafolkken/kit#7503); any metric but these is an unknown condition.
+const LEDGER = / ledger:(?<metric>[\w-]+)>=(?<minimum>[1-9]\d*)(?= -->$)/u
+const METRICS: ReadonlySet<string> = new Set([lane_early_push_count.MULTI_SLOT_EARLY_PUSH])
+const EVIDENCE_HEADING = '## Observation evidence'
+const TASK = /^- \[(?<checked>[ xX])\] (?<key>[\w-]+): (?<description>.+)$/u
+const EVIDENCE = /\[evidence\]\(https:\/\/github\.com\/[\w./#?=&%-]+\)$/u
+
+interface ObservationSource {
+	url: string
+	repo: string
+	comment: string
+	keys: ReadonlyArray<string>
+	ledger?: LedgerCondition | undefined
+}
+
+interface LedgerCondition {
+	metric: string
+	minimum: number
+}
+
+interface ObservationWait {
+	reason: string
+	url?: string | undefined
+}
+
+const records = new Map<string, string | undefined>()
+const samples = new Map<string, number>()
+
+function is_evidenced(task: Partial<Record<string, string>> | undefined): boolean {
+	return task?.['checked']?.toLowerCase() === 'x' && EVIDENCE.test(task['description'] ?? '')
+}
+
+function declarations(body = ''): ReadonlyArray<string> {
+	return markdown_section.unfenced_lines(body).filter((line) => line.trimStart().startsWith(PREFIX))
+}
+
+function ledger_of(line: string): LedgerCondition | undefined {
+	const groups = LEDGER.exec(line)?.groups
+	if (groups === undefined) return undefined
+
+	return { metric: String(groups['metric']), minimum: Number(groups['minimum']) }
+}
+
+function is_known(ledger: LedgerCondition | undefined): boolean {
+	return ledger === undefined || METRICS.has(ledger.metric)
+}
+
+function source_of(line: string): ObservationSource | undefined {
+	const trimmed = line.trim()
+	const ledger = ledger_of(trimmed)
+	if (!is_known(ledger)) return undefined
+	const groups = DECLARATION.exec(trimmed.replace(LEDGER, ''))?.groups
+	if (groups === undefined) return undefined
+
+	return {
+		url: String(groups['url']),
+		repo: String(groups['repo']),
+		comment: String(groups['comment']),
+		keys: String(groups['keys']).split(','),
+		ledger,
+	}
+}
+
+function is_sampled(ledger: LedgerCondition | undefined): boolean {
+	if (ledger === undefined) return false
+
+	return (samples.get(ledger.metric) ?? 0) >= ledger.minimum
+}
+
+function sources(bodies: ReadonlyArray<string | undefined>): ReadonlyArray<ObservationSource> {
+	return bodies.flatMap((body) => declarations(body).flatMap((line) => source_of(line) ?? []))
+}
+
+function pending(source: ObservationSource, body: string): ReadonlyArray<string> {
+	const lines = markdown_section.section_lines(body, EVIDENCE_HEADING).join('\n')
+	const tasks = markdown_section.unfenced_lines(lines).map((line) => TASK.exec(line)?.groups)
+
+	return source.keys.filter((key) => {
+		const matches = tasks.filter((task) => task?.['key'] === key)
+		const [task] = matches
+
+		return matches.length !== 1 || !is_evidenced(task)
+	})
+}
+
+function wait_for(line: string): ObservationWait | undefined {
+	const source = source_of(line)
+
+	if (source === undefined) {
+		return {
+			reason: 'unknown observation condition; record a v1 evidence comment and required keys',
+		}
+	}
+
+	if (is_sampled(source.ledger)) return undefined
+	const body = records.get(source.url)
+
+	if (body === undefined) {
+		return { reason: `observation evidence unread: ${source.keys.join(', ')}`, url: source.url }
+	}
+
+	const missing = pending(source, body)
+
+	return missing.length === 0
+		? undefined
+		: { reason: `observation evidence required: ${missing.join(', ')}`, url: source.url }
+}
+
+function wait_of(body?: string): ObservationWait | undefined {
+	return declarations(body)
+		.map((line) => wait_for(line))
+		.find((wait) => wait !== undefined)
+}
+
+function record(url: string, body: string | undefined): void {
+	records.set(url, body)
+}
+
+// The ledger's current count of a declared metric, primed with the evidence comments.
+function record_sample(metric: string, count: number): void {
+	samples.set(metric, count)
+}
+
+function reset(): void {
+	records.clear()
+	samples.clear()
+}
+
+const issue_observation_gate = { sources, wait_of, record, record_sample, reset }
+
+export type { LedgerCondition, ObservationSource }
+export { issue_observation_gate }

package/scripts/issue/issue-observation-prime.ts

@@ -0,0 +1,83 @@
+import { gh_author_association } from '#scripts/gh/gh-author-association'
+import { git_gh_api_path } from '#scripts/gh/git-gh-api-path'
+import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { parse_json } from '#scripts/git/parse-json-array'
+import { lane_early_push_count } from '#scripts/lane/lane-early-push-count'
+import { lane_ledger, type LedgerEntry } from '#scripts/lane/lane-ledger'
+import { z } from 'zod'
+import { issue_observation_gate, type ObservationSource } from './issue-observation-gate'
+
+const comment_schema = z.object({
+	...gh_author_association.author_fields_schema,
+	body: z.string(),
+	html_url: z.string(),
+})
+
+type ReadSource = (source: ObservationSource) => Promise<string | undefined>
+type ReadLedger = () => Promise<ReadonlyArray<LedgerEntry>>
+
+// A checkout with no ledger (outside a repository, or a test run) has no samples.
+async function read_ledger(): Promise<ReadonlyArray<LedgerEntry>> {
+	const path = await lane_ledger.target()
+
+	return path === undefined ? [] : lane_ledger.read_entries(path)
+}
+
+async function read(source: ObservationSource): Promise<string | undefined> {
+	const path = `${git_gh_api_path.issues_api_path(source.repo)}/comments/${source.comment}`
+	const raw = await git_gh_exec.exec_gh_api({ path })
+	const comment = parse_json.parse_json_object_or_undefined(raw, comment_schema)
+	if (comment?.html_url !== source.url) return undefined
+	const author = { ...gh_author_association.author_of(comment), repo: source.repo }
+
+	return (await gh_author_association.is_trusted(author)) ? comment.body : undefined
+}
+
+async function remember(source: ObservationSource, read_source: ReadSource): Promise<void> {
+	try {
+		issue_observation_gate.record(source.url, await read_source(source))
+	} catch {
+		issue_observation_gate.record(source.url, undefined)
+	}
+}
+
+// Only a declaration naming a ledger condition reads the ledger; a failed read counts nothing.
+async function sample(
+	sources: ReadonlyArray<ObservationSource>,
+	read_entries: ReadLedger,
+): Promise<void> {
+	if (sources.every((source) => source.ledger === undefined)) return
+	let entries: ReadonlyArray<LedgerEntry> = []
+
+	try {
+		entries = await read_entries()
+	} catch {
+		// An unreadable ledger holds no sample.
+	}
+
+	issue_observation_gate.record_sample(
+		lane_early_push_count.MULTI_SLOT_EARLY_PUSH,
+		lane_early_push_count.multi_slot_pushed(entries),
+	)
+}
+
+// Re-read even a satisfied comment: a later correction or failed read must withhold the next offer.
+async function prime(
+	bodies: ReadonlyArray<string | undefined>,
+	read_source: ReadSource = read,
+	read_entries: ReadLedger = read_ledger,
+): Promise<void> {
+	const sources = issue_observation_gate.sources(bodies)
+	const unique = new Map(sources.map((source) => [source.url, source]))
+
+	await Promise.all([
+		sample(sources, read_entries),
+		...[...unique.values()].map(async (source) => {
+			await remember(source, read_source)
+		}),
+	])
+}
+
+const issue_observation_prime = { prime }
+
+export { issue_observation_prime }