@joshuafolkken/kit 1.872.0

package/scripts/sync/workflow-pin-logic.ts

@@ -0,0 +1,240 @@
+import { readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { is_workflow_destination } from '#scripts/claude/workflow-destination'
+import { package_path } from '#scripts/init/init-paths'
+
+// .github/workflows is the single source of truth for action SHA pins. The
+// distributed templates/workflows/* intentionally diverge in structure (steps,
+// commands, comment language), so only the `uses:` pins are propagated.
+//
+// The refs committed in templates/workflows/* are NOT authoritative: every consumer
+// workflow is written through apply_pins_for_destination, which resolves the pins from
+// .github/workflows at write time. Dependabot only ever updates .github/workflows (its
+// github-actions ecosystem cannot scan templates/), so a stale template ref must not be
+// able to reach a consumer — and must not fail CI either. `josh sync-workflow-pins`
+// stays available to refresh the committed refs, but nothing depends on it having run.
+const RUNTIME_WORKFLOWS_DIR = '.github/workflows'
+const TEMPLATE_WORKFLOWS_DIR = 'templates/workflows'
+const USES_KEY = 'uses:'
+const YAML_PATTERN = /\.ya?ml$/u
+const SYNC_HINT = '  Run `pnpm josh sync-workflow-pins` to sync template workflow pins.'
+
+interface ActionPin {
+	name: string
+	ref: string
+}
+
+interface PinDrift {
+	template: string
+	line: number
+	action: string
+	from: string
+	to: string
+}
+
+interface WorkflowSource {
+	file: string
+	text: string
+}
+
+interface UnknownAction {
+	template: string
+	line: number
+	action: string
+}
+
+function parse_uses_line(line: string): ActionPin | undefined {
+	const key_index = line.indexOf(USES_KEY)
+	if (key_index === -1 || line.slice(0, key_index).trim() !== '') return undefined
+
+	const value = line.slice(key_index + USES_KEY.length).trim()
+	const at_index = value.indexOf('@')
+	if (at_index === -1) return undefined
+
+	return { name: value.slice(0, at_index), ref: value.slice(at_index + 1) }
+}
+
+function conflict_message(name: string, existing: string, found: string, file: string): string {
+	return `Action ${name} pinned to conflicting refs in .github/workflows: "${existing}" vs "${found}" (${file})`
+}
+
+function add_pin(pins: Map<string, string>, pin: ActionPin, file: string): void {
+	const existing = pins.get(pin.name)
+
+	if (existing !== undefined && existing !== pin.ref) {
+		throw new Error(conflict_message(pin.name, existing, pin.ref, file))
+	}
+
+	pins.set(pin.name, pin.ref)
+}
+
+function collect_into(pins: Map<string, string>, source: WorkflowSource): void {
+	for (const line of source.text.split('\n')) {
+		const pin = parse_uses_line(line)
+		if (pin) add_pin(pins, pin, source.file)
+	}
+}
+
+function collect_canonical(sources: ReadonlyArray<WorkflowSource>): Map<string, string> {
+	const pins = new Map<string, string>()
+	for (const source of sources) collect_into(pins, source)
+
+	return pins
+}
+
+function drift_for_line(
+	template: string,
+	line: string,
+	index: number,
+	canonical: ReadonlyMap<string, string>,
+): PinDrift | undefined {
+	const pin = parse_uses_line(line)
+	if (!pin) return undefined
+
+	const want = canonical.get(pin.name)
+	if (want === undefined || want === pin.ref) return undefined
+
+	return { template, line: index + 1, action: pin.name, from: pin.ref, to: want }
+}
+
+function find_drift_in_text(
+	template: string,
+	text: string,
+	canonical: ReadonlyMap<string, string>,
+): Array<PinDrift> {
+	const drifts: Array<PinDrift> = []
+
+	for (const [index, line] of text.split('\n').entries()) {
+		const drift = drift_for_line(template, line, index, canonical)
+		if (drift) drifts.push(drift)
+	}
+
+	return drifts
+}
+
+function rewrite_line(line: string, canonical: ReadonlyMap<string, string>): string {
+	const pin = parse_uses_line(line)
+	if (!pin) return line
+
+	const want = canonical.get(pin.name)
+	if (want === undefined || want === pin.ref) return line
+
+	const key_index = line.indexOf(USES_KEY)
+
+	return `${line.slice(0, key_index)}${USES_KEY} ${pin.name}@${want}`
+}
+
+function apply_to_text(text: string, canonical: ReadonlyMap<string, string>): string {
+	return text
+		.split('\n')
+		.map((line) => rewrite_line(line, canonical))
+		.join('\n')
+}
+
+function read_source(relative_directory: string, name: string): WorkflowSource {
+	const file = path.join(relative_directory, name)
+
+	return { file, text: readFileSync(package_path(file), 'utf8') }
+}
+
+function list_workflow_sources(relative_directory: string): Array<WorkflowSource> {
+	return readdirSync(package_path(relative_directory))
+		.filter((name) => YAML_PATTERN.test(name))
+		.toSorted((left, right) => left.localeCompare(right))
+		.map((name) => read_source(relative_directory, name))
+}
+
+function build_canonical_pins(): Map<string, string> {
+	return collect_canonical(list_workflow_sources(RUNTIME_WORKFLOWS_DIR))
+}
+
+// An action the templates use but .github/workflows does not: write-time injection has no
+// ref to resolve, so the stale template ref would reach the consumer unnoticed.
+function unknown_actions_in_source(
+	source: WorkflowSource,
+	canonical: ReadonlyMap<string, string>,
+): Array<UnknownAction> {
+	const unknown: Array<UnknownAction> = []
+
+	for (const [index, line] of source.text.split('\n').entries()) {
+		const pin = parse_uses_line(line)
+
+		if (pin && !canonical.has(pin.name)) {
+			unknown.push({ template: source.file, line: index + 1, action: pin.name })
+		}
+	}
+
+	return unknown
+}
+
+function apply_pins_for_destination(destination: string, text: string): string {
+	if (!is_workflow_destination(destination)) return text
+
+	return apply_to_text(text, build_canonical_pins())
+}
+
+function scan_templates<T>(
+	scan: (source: WorkflowSource, canonical: ReadonlyMap<string, string>) => Array<T>,
+): Array<T> {
+	const canonical = build_canonical_pins()
+
+	return list_workflow_sources(TEMPLATE_WORKFLOWS_DIR).flatMap((source) => scan(source, canonical))
+}
+
+function find_pin_drift(): Array<PinDrift> {
+	return scan_templates((source, canonical) =>
+		find_drift_in_text(source.file, source.text, canonical),
+	)
+}
+
+function find_unknown_template_actions(): Array<UnknownAction> {
+	return scan_templates(unknown_actions_in_source)
+}
+
+function write_synced(source: WorkflowSource, canonical: ReadonlyMap<string, string>): void {
+	const synced = apply_to_text(source.text, canonical)
+	if (synced !== source.text) writeFileSync(package_path(source.file), synced)
+}
+
+function sync_pins(): Array<PinDrift> {
+	const canonical = build_canonical_pins()
+	const drifts = find_pin_drift()
+
+	for (const source of list_workflow_sources(TEMPLATE_WORKFLOWS_DIR)) {
+		write_synced(source, canonical)
+	}
+
+	return drifts
+}
+
+function format_drift_message(drifts: ReadonlyArray<PinDrift>): string {
+	const lines = drifts.map(
+		(drift) =>
+			`  - ${drift.template}:${String(drift.line)} ${drift.action}: ${drift.from} → ${drift.to}`,
+	)
+
+	return [
+		'✖ Template workflow action pins drifted from .github/workflows:',
+		...lines,
+		SYNC_HINT,
+	].join('\n')
+}
+
+const workflow_pin_logic = {
+	RUNTIME_WORKFLOWS_DIR,
+	TEMPLATE_WORKFLOWS_DIR,
+	parse_uses_line,
+	collect_canonical,
+	find_drift_in_text,
+	apply_to_text,
+	is_workflow_destination,
+	apply_pins_for_destination,
+	build_canonical_pins,
+	find_pin_drift,
+	find_unknown_template_actions,
+	sync_pins,
+	format_drift_message,
+}
+
+export { workflow_pin_logic }
+export type { PinDrift }

package/scripts/test/classify-isolation.ts

@@ -0,0 +1,149 @@
+#!/usr/bin/env tsx
+import { globSync, readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { VITEST_INCLUDE_GLOBS } from './vitest-include-globs'
+
+// Isolation requirements — a test matching ANY condition below mutates state a sibling test running
+// in the same worker could observe, so it must run with the default isolate:true and must NOT appear
+// in the generated pilot list. The classifier is deliberately conservative: a file it cannot decide
+// is left isolated, because a false "pure" costs a flaky pilot while a false "isolate" costs only a
+// little speed.
+//   1. Module mocks: vi.mock / vi.spyOn / vi.stubEnv / vi.stubGlobal / vi.resetModules /
+//      vi.unstubAllEnvs / vi.unstubAllGlobals
+//   2. Environment variable writes: process.env.X = ... or delete process.env.X
+//   3. Subprocess calls: execSync / spawnSync / spawn / exec / execa / child_process.*
+//   4. Filesystem writes: writeFileSync / mkdirSync / mkdtemp / rmSync / unlinkSync / rimraf
+//   5. Git operations: enforced by condition 3 — every git operation spawns a process, so a file
+//      that runs git already matches the subprocess pattern.
+
+const MOCK_TOKENS: ReadonlyArray<string> = [
+	'mock',
+	'spyOn',
+	'stubEnv',
+	'stubGlobal',
+	'resetModules',
+	'unstubAllEnvs',
+	'unstubAllGlobals',
+]
+// Bare `exec` is deliberately absent: it matches the pure word (`pnpm exec …`, `regex.exec(…)`) more
+// often than the child_process call, which an `execSync` / `child_process` token catches anyway.
+const SUBPROCESS_TOKENS: ReadonlyArray<string> = [
+	'execSync',
+	'execFileSync',
+	'spawnSync',
+	'execaSync',
+	'execa',
+	'spawn',
+	'child_process',
+]
+const FS_WRITE_TOKENS: ReadonlyArray<string> = [
+	'writeFileSync',
+	'writeFile',
+	'appendFileSync',
+	'mkdirSync',
+	'mkdtempSync',
+	'mkdtemp',
+	'rmSync',
+	'rmdirSync',
+	'unlinkSync',
+	'cpSync',
+	'copyFileSync',
+	'renameSync',
+	'rimraf',
+]
+
+function word_pattern(tokens: ReadonlyArray<string>): RegExp {
+	return new RegExp(String.raw`\b(?:${tokens.join('|')})\b`, 'u')
+}
+
+const MODULE_MOCKS = new RegExp(String.raw`\bvi\.(?:${MOCK_TOKENS.join('|')})\b`, 'u')
+const ENV_WRITES =
+	/(?:process\.env\.\w+\s*=(?!=)|process\.env\[[^\]]+\]\s*=(?!=)|delete\s+process\.env)/u
+const SUBPROCESS = word_pattern(SUBPROCESS_TOKENS)
+const FS_WRITES = word_pattern(FS_WRITE_TOKENS)
+
+const ISOLATION_PATTERNS: ReadonlyArray<RegExp> = [MODULE_MOCKS, ENV_WRITES, SUBPROCESS, FS_WRITES]
+
+// Excluded from the main suite in vitest.config.ts (packs and installs the real tarball), so it must
+// never reach the pilot either.
+const MAIN_EXCLUDE = new Set(['scripts/build/packed-consumer.test.ts'])
+const NODE_MODULES = 'node_modules'
+const PILOT_FILES_PATH = 'scripts/test/pilot-files.ts'
+const WRITE_FLAG = '--write'
+const INDENT = '\t'
+const UTF8 = 'utf8'
+
+const GENERATED_HEADER = `/* eslint-disable max-lines */
+// GENERATED FILE — do not edit by hand.
+// Regenerate with: pnpm exec tsx scripts/test/classify-isolation.ts --write
+// Every entry is a test file the classifier judges free of the isolation requirements documented in
+// classify-isolation.ts; these files run with isolate:false in vitest.pilot.config.ts.`
+
+function normalize_path(file: string): string {
+	return file.split(path.sep).join('/')
+}
+
+function is_in_node_modules(entry: string): boolean {
+	return entry.split(/[/\\]/u).includes(NODE_MODULES)
+}
+
+function collect_glob(glob: string): Array<string> {
+	return globSync(glob, { exclude: is_in_node_modules }).map((file) => normalize_path(file))
+}
+
+// Code-point order, never localeCompare: the list is generated on one machine and re-derived in CI,
+// and ICU collation differs across platforms — so localeCompare reorders the list under CI's Linux
+// ICU and fails the drift test on order alone (joshuafolkken/kit#2170).
+function by_code_point(left: string, right: string): number {
+	if (left < right) return -1
+
+	return left > right ? 1 : 0
+}
+
+function all_test_files(): Array<string> {
+	const files = VITEST_INCLUDE_GLOBS.flatMap((glob) => collect_glob(glob))
+
+	return [...new Set(files)].filter((file) => !MAIN_EXCLUDE.has(file)).toSorted(by_code_point)
+}
+
+function requires_isolation(source: string): boolean {
+	return ISOLATION_PATTERNS.some((pattern) => pattern.test(source))
+}
+
+function is_pilot_candidate(file: string): boolean {
+	return !requires_isolation(readFileSync(file, UTF8))
+}
+
+function classify_pilot_files(): Array<string> {
+	return all_test_files().filter((file) => is_pilot_candidate(file))
+}
+
+function render_pilot_files(files: ReadonlyArray<string>): string {
+	const entries = files.map((file) => `${INDENT}'${file}',`).join('\n')
+	const body = `const PILOT_FILES: ReadonlyArray<string> = [\n${entries}\n]`
+
+	return `${GENERATED_HEADER}\n\n${body}\n\nexport { PILOT_FILES }\n`
+}
+
+function write_pilot_files(): void {
+	writeFileSync(PILOT_FILES_PATH, render_pilot_files(classify_pilot_files()))
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	if (process.argv.includes(WRITE_FLAG)) write_pilot_files()
+	else process.stdout.write(`${classify_pilot_files().join('\n')}\n`)
+}
+
+const classify_isolation = {
+	ISOLATION_PATTERNS,
+	all_test_files,
+	by_code_point,
+	classify_pilot_files,
+	is_pilot_candidate,
+	render_pilot_files,
+	requires_isolation,
+	write_pilot_files,
+}
+
+export { classify_isolation }

package/scripts/test/e2e-retry-check.ts

@@ -0,0 +1,150 @@
+#!/usr/bin/env tsx
+import { appendFileSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// Whether the preview server process died during a failed E2E attempt.
+//
+// This command reports a fact and nothing else. Whether that fact should produce a retry is the
+// workflow's decision, and it has to be, because a step that errors publishes no output at all: a
+// default-branch push must retry whatever happens here, so its rule cannot depend on this command
+// succeeding. `templates/workflows/ci.yml` therefore ORs `E2E_RETRY_UNCONDITIONAL` in front of this
+// output rather than passing the flag down — one rule, in the one place that survives a failure.
+//
+// The distinction being drawn is between a suite that failed and a suite that never got to run. A
+// pull request must not retry the first: that is what hides a real flake before it is merged
+// (#872). It may retry the second, because the preview server dying is produced by the CI substrate
+// rather than by the diff under review. The rule lives in a script rather than in the workflow's
+// shell because it is the one part of the chain that can be wrong without anyone noticing — a
+// signature that stops matching silently stops retrying — and here it has unit tests that turn that
+// drift into a red build.
+
+// The crash, spelled as wrangler spells it in the debug log the E2E job already uploads as
+// `e2e-web-server-log`. **Every** string here must be present, not any of them, and the conjunction
+// is the point: each half is individually weaker than it looks. `Network connection lost.` is
+// logged by workerd for any aborted in-flight request — a page closing, a navigation, a timeout —
+// so a suite that merely failed can produce it with the server perfectly healthy. `Error in
+// ProxyController` is the structural marker for a worker that is gone. Requiring both costs
+// nothing — every observed crash carries them together — and each one narrows the other's exposure.
+//
+// Both halves have now been read against logs wrangler actually wrote, which #872 could only
+// assume (#911). Every `e2e-web-server-log` game-kit retains — 8 artifacts across 6 runs — is from
+// a server that genuinely died, and the pair matches all of them. The open worry was the other
+// direction: that wrangler emits `Error in ProxyController` while tearing the proxy down, which
+// happens at the end of every run including a failing one, and would hand a retry to exactly the
+// flake this gate exists to expose. A run of game-kit's own suite against the same preview server,
+// failing on an assertion with the server serving every request throughout, emits neither string
+// anywhere in its log — it ends on a routine heartbeat with nothing logged behind the last request.
+// That is what this rule reads and all it claims: the log of a healthy failing run is clean, so no
+// shutdown path reachable from one puts a signature in front of this check. It is quoted complete
+// in `e2e-retry-check-healthy-fixture.ts`, the crash in `e2e-retry-check-crash-fixture.ts`, and the
+// suite reads this rule against both rather than against the paragraph above.
+//
+// One marker #872 listed is deliberately absent from this list: the bare `✘ [ERROR]` wrangler
+// prints to the console. It is in the healthy log three times over, each an ordinary 404.
+const CRASH_SIGNATURES: ReadonlyArray<string> = [
+	'Error in ProxyController',
+	'Network connection lost.',
+]
+
+// Both are the workflow's values, exported so the guard in `ci-yml-e2e-retry.test.ts` can assert
+// this command reads the log that job actually writes. A rename on one side alone would leave the
+// check reading nothing and quietly reporting "no crash" on every run.
+const LOG_PATH_VARIABLE = 'WRANGLER_LOG_PATH'
+const DEFAULT_LOG_DIRECTORY = 'e2e-web-server-logs'
+const OUTPUT_NAME = 'crashed'
+
+function has_crash_signature(log_text: string): boolean {
+	return CRASH_SIGNATURES.every((signature) => log_text.includes(signature))
+}
+
+function read_file_safe(file_path: string): string {
+	try {
+		return readFileSync(file_path, 'utf8')
+	} catch {
+		return ''
+	}
+}
+
+// Every file under the directory, because wrangler names the debug log after the run and a job that
+// restarted the server leaves more than one. They stay separate rather than being joined, and the
+// verdict below is taken per file: a crash is one process reporting its own death, so both
+// signatures have to be in the same log. Concatenating them first would let `Network connection
+// lost.` from an aborted request in one file meet `Error in ProxyController` in another — the
+// conjunction satisfied by two unrelated events, and a retry handed to exactly the failing pull
+// request suite this rule exists to keep exposed. Every observed crash carries the pair inside one
+// error record, so nothing is lost by requiring it (#911).
+function read_directory_texts(directory: string): ReadonlyArray<string> {
+	return readdirSync(directory, { recursive: true, withFileTypes: true })
+		.filter((entry) => entry.isFile())
+		.map((entry) => read_file_safe(path.join(entry.parentPath, entry.name)))
+}
+
+// Nothing about reading a log may be fatal: this command decides whether to spend one more CI
+// minute, and throwing would fail the job over a diagnostic. Every way the path can disappoint ends
+// at the same answer — it is missing, it is a file rather than the expected directory (a spelling
+// `WRANGLER_LOG_PATH` supports, which is why the workflow strips a trailing slash), or it cannot be
+// read at all. An empty read is then reported as "no crash", which is the safe verdict: a consumer
+// whose preview script is not wrangler writes no log, and reading silence as a crash would retry
+// every failing suite in that project — the masking this rule exists to prevent.
+function read_log_texts(target: string): ReadonlyArray<string> {
+	try {
+		return statSync(target).isDirectory() ? read_directory_texts(target) : [read_file_safe(target)]
+	} catch {
+		return []
+	}
+}
+
+// One file carrying every signature, never the set of them between them — see `read_directory_texts`.
+function has_crashed_log(log_texts: ReadonlyArray<string>): boolean {
+	return log_texts.some((log_text) => has_crash_signature(log_text))
+}
+
+// The one write this command makes, and the only call left that could throw: a full disk, a
+// read-only mount, an output file the runner removed. Nothing here may be fatal — a job must not go
+// red over a step that only decides whether to spend one more CI minute — so the failure is
+// announced and stepped over. A verdict that cannot be published simply does not produce a retry,
+// which for a pull request is the status quo and for the default branch is nothing at all, since
+// the flag there is read ahead of this output.
+function write_github_output(has_crashed: boolean): void {
+	const output_path = process.env['GITHUB_OUTPUT']
+	if (output_path === undefined || output_path === '') return
+
+	try {
+		appendFileSync(output_path, `${OUTPUT_NAME}=${String(has_crashed)}\n`)
+	} catch {
+		console.info('::warning::Could not publish the E2E crash check verdict; no retry will follow.')
+	}
+}
+
+function resolve_log_directory(): string {
+	const configured = process.env[LOG_PATH_VARIABLE] ?? ''
+
+	return configured === '' ? DEFAULT_LOG_DIRECTORY : configured
+}
+
+function run_retry_check(): boolean {
+	const has_crashed = has_crashed_log(read_log_texts(resolve_log_directory()))
+	const verdict = has_crashed
+		? 'the preview server log carries a crash signature'
+		: 'no crash signature in the preview server log, so the suite itself failed'
+
+	console.info(`::notice::E2E preview server crash check: ${verdict}`)
+	write_github_output(has_crashed)
+
+	return has_crashed
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	run_retry_check()
+}
+
+const e2e_retry_check = {
+	has_crash_signature,
+	has_crashed_log,
+	read_log_texts,
+	resolve_log_directory,
+	run_retry_check,
+}
+
+export { e2e_retry_check, CRASH_SIGNATURES, DEFAULT_LOG_DIRECTORY, LOG_PATH_VARIABLE, OUTPUT_NAME }

package/scripts/test/http-fault-injection.ts

@@ -0,0 +1,79 @@
+import { cases } from '#scripts/cases/cases-logic'
+
+// joshuafolkken/kit#2355: the network boundary's abnormal cases were declared and never run. The unit
+// suite blocks the network by construction (`test-network-guard.ts` shims the `gh` and `git`
+// binaries), so `josh cases`' network vocabulary had no way to be *executed* — only named in a test
+// declaration, where the failure mode nobody anticipated is exactly the one that never gets declared
+// (the transport failure of joshuafolkken/kit#2317 was hit before it was foreseen).
+//
+// This makes each of those failure modes injectable as a `fetch` stand-in that produces the failure
+// without opening a connection. It does not weaken the guard: the shims are untouched, no real request
+// leaves the machine, and the stand-in only shapes the `Response` (or rejection) the caller's error
+// path already has to survive. The mode set is single-sourced from `cases`, so the vocabulary the
+// command prints and the failures that can be injected cannot drift apart — `INJECTORS` is asserted
+// exhaustive against it in the colocated test.
+
+// A `fetch` stand-in: the real signature takes an input and an optional init, both ignored here since
+// the failure is fixed by the mode rather than the request.
+type FetchStub = (input?: unknown, init?: unknown) => Promise<Response>
+
+const NON_200_STATUS = 500
+const RATE_LIMIT_STATUS = 429
+const OK_STATUS = 200
+
+// The two rejection failures wear the shapes the platform itself throws, so a caller's `catch` sees
+// what a real timeout or dropped connection would produce: `AbortSignal.timeout` rejects with a
+// `TimeoutError` DOMException, and a transport failure rejects with a `TypeError`.
+const TIMEOUT_MESSAGE = 'The operation timed out.'
+const TIMEOUT_NAME = 'TimeoutError'
+const CONNECTION_DROP_MESSAGE = 'fetch failed'
+// A body that is present but not JSON, told apart from the empty body by having content at all.
+const INVALID_JSON_BODY = '{'
+const EMPTY_BODY = ''
+
+function ok_body(body: string): FetchStub {
+	return async () => new Response(body, { status: OK_STATUS })
+}
+
+function non_ok(code: number): FetchStub {
+	return async () => new Response(EMPTY_BODY, { status: code })
+}
+
+function rejecting(error: Error): FetchStub {
+	return async () => {
+		throw error
+	}
+}
+
+// Keyed by the exact vocabulary term `josh cases` prints for the network boundary. The colocated test
+// proves this key set equals that vocabulary, so a term added there without an injector here fails.
+const INJECTORS: Readonly<Record<string, FetchStub>> = {
+	非200: non_ok(NON_200_STATUS),
+	タイムアウト: rejecting(new DOMException(TIMEOUT_MESSAGE, TIMEOUT_NAME)),
+	接続断: rejecting(new TypeError(CONNECTION_DROP_MESSAGE)),
+	空レスポンス: ok_body(EMPTY_BODY),
+	不正JSON: ok_body(INVALID_JSON_BODY),
+	レート制限: non_ok(RATE_LIMIT_STATUS),
+}
+
+// The failure modes that can be injected — the injector key set, for the correspondence assertion.
+function supported_modes(): ReadonlyArray<string> {
+	return Object.keys(INJECTORS)
+}
+
+// A `fetch` stand-in producing the named failure. An unknown mode throws rather than silently passing:
+// a typo in a test must not degrade into a request that quietly does nothing.
+function faulty_fetch(mode: string): FetchStub {
+	const injector = INJECTORS[mode]
+	if (injector === undefined) throw new Error(`unknown network failure mode: ${mode}`)
+
+	return injector
+}
+
+// The network vocabulary this injector must cover, single-sourced from the command's own definition.
+const NETWORK_MODES: ReadonlyArray<string> = cases.cases_for(['network'])
+
+const http_fault_injection = { NETWORK_MODES, faulty_fetch, supported_modes }
+
+export type { FetchStub }
+export { http_fault_injection }