@mailwoman/corpus 8.0.0 → 8.2.0

package/src/tools/lint-shard-vocab.ts

@@ -39,14 +39,18 @@ import { join } from "node:path"
 
 import { dataRootPath } from "@mailwoman/core/utils"
 
-/** A column-projected base/shard row: parallel token + label lists plus the row's country. */
+/**
+ * A column-projected base/shard row: parallel token + label lists plus the row's country.
+ */
 interface CorpusRow {
 	tokens: string[]
 	labels: string[]
 	country: string | null
 }
 
-/** Strip a BIO prefix ("B-"/"I-") off a label, matching the Python `strip_bio`. */
+/**
+ * Strip a BIO prefix ("B-"/"I-") off a label, matching the Python `strip_bio`.
+ */
 function stripBIO(label: string): string {
 	const head = label.slice(0, 2)
 
@@ -77,7 +81,9 @@ function pyRound(x: number): number {
 	return floor % 2 === 0 ? floor : floor + 1
 }
 
-/** Format a fraction as a whole-percent string the way Python's `:.0%` does, e.g. 0.73 -> "73%". */
+/**
+ * Format a fraction as a whole-percent string the way Python's `:.0%` does, e.g. 0.73 -> "73%".
+ */
 function pct(frac: number): string {
 	return `${pyRound(frac * 100)}%`
 }
@@ -91,7 +97,9 @@ function pyFloat(n: number): string {
 	return Number.isInteger(n) ? n.toFixed(1) : String(n)
 }
 
-/** Left-justify to a minimum width with spaces, matching Python's `{value:N}` string field. */
+/**
+ * Left-justify to a minimum width with spaces, matching Python's `{value:N}` string field.
+ */
 function pad(value: string, width: number): string {
 	return value.padEnd(width)
 }
@@ -114,12 +122,14 @@ function dominant(counter: Map<string, number>): [string, number, number] {
 		}
 	}
 
-	if (total === 0) return ["", 0, 0.0]
+	if (total === 0) return ["", 0, 0]
 
 	return [bestTag, total, bestCount / total]
 }
 
-/** Bump a (key -> count) tally, creating the inner counter on first sight. */
+/**
+ * Bump a (key -> count) tally, creating the inner counter on first sight.
+ */
 function bump(table: Map<string, Map<string, number>>, key: string, sub: string): void {
 	let counter = table.get(key)
 
@@ -127,10 +137,13 @@ function bump(table: Map<string, Map<string, number>>, key: string, sub: string)
 		counter = new Map()
 		table.set(key, counter)
 	}
+
 	counter.set(sub, (counter.get(sub) ?? 0) + 1)
 }
 
-/** The DuckDB connection type, without a static dependency on the optional-peer package. */
+/**
+ * The DuckDB connection type, without a static dependency on the optional-peer package.
+ */
 type DuckDBConnection = Awaited<
 	ReturnType<Awaited<ReturnType<(typeof import("@duckdb/node-api"))["DuckDBInstance"]["create"]>>["connect"]>
 >
@@ -144,6 +157,7 @@ async function readRows(con: DuckDBConnection, path: string): Promise<CorpusRow[
 	const result = await con.runAndReadAll(
 		`SELECT to_json(tokens) AS tokens, to_json(labels) AS labels, country FROM read_parquet('${path}')`
 	)
+
 	const raw = result.getRowObjects() as Array<{ tokens: unknown; labels: unknown; country: unknown }>
 	const rows: CorpusRow[] = []
 
@@ -152,6 +166,7 @@ async function readRows(con: DuckDBConnection, path: string): Promise<CorpusRow[
 		const labels = JSON.parse(String(r.labels)) as unknown
 
 		if (!Array.isArray(tokens) || !Array.isArray(labels)) continue
+
 		rows.push({
 			tokens: tokens as string[],
 			labels: labels as string[],
@@ -162,7 +177,9 @@ async function readRows(con: DuckDBConnection, path: string): Promise<CorpusRow[
 	return rows
 }
 
-/** Read just the first row's `source` value — used to group base parts for a proportional slice. */
+/**
+ * Read just the first row's `source` value — used to group base parts for a proportional slice.
+ */
 async function readSource(con: DuckDBConnection, path: string): Promise<string> {
 	const result = await con.runAndReadAll(`SELECT source FROM read_parquet('${path}') LIMIT 1`)
 	const rows = result.getRowObjects() as Array<{ source: unknown }>
@@ -170,7 +187,9 @@ async function readSource(con: DuckDBConnection, path: string): Promise<string>
 	return rows.length ? String(rows[0]!.source) : ""
 }
 
-/** Non-recursive `*.parquet` glob, sorted lexicographically — the Python `sorted(glob.glob(...))`. */
+/**
+ * Non-recursive `*.parquet` glob, sorted lexicographically — the Python `sorted(glob.glob(...))`.
+ */
 function globParquet(dir: string): string[] {
 	let names: string[]
 
@@ -183,44 +202,68 @@ function globParquet(dir: string): string[] {
 	return names
 		.filter((f) => f.endsWith(".parquet"))
 		.map((f) => join(dir, f))
-		.sort()
+		.toSorted()
 }
 
-/** Options for {@linkcode lintShardVocab}. */
+/**
+ * Options for {@linkcode lintShardVocab}.
+ */
 export interface LintShardVocabOptions {
-	/** The shard parquet to lint. */
+	/**
+	 * The shard parquet to lint.
+	 */
 	shard: string
-	/** Base corpus version. Default `v0.5.0`. */
+	/**
+	 * Base corpus version. Default `v0.5.0`.
+	 */
 	baseVersion?: string
-	/** Base corpus root. Default `$MAILWOMAN_DATA_ROOT/corpus/versioned`. */
+	/**
+	 * Base corpus root. Default `$MAILWOMAN_DATA_ROOT/corpus/versioned`.
+	 */
 	baseRoot?: string
-	/** Base-majority confidence floor for a contradiction. Default 0.7. */
+	/**
+	 * Base-majority confidence floor for a contradiction. Default 0.7.
+	 */
 	threshold?: number
-	/** Minimum base support to judge a token. Default 50. */
+	/**
+	 * Minimum base support to judge a token. Default 50.
+	 */
 	minCount?: number
-	/** Fraction of base parts to scan (proportional per-source slice below 1.0). Default 1.0. */
+	/**
+	 * Fraction of base parts to scan (proportional per-source slice below 1.0). Default 1.0.
+	 */
 	fraction?: number
 }
 
-/** One contradiction row: token, shard tag, base tag, base fraction, base total. */
+/**
+ * One contradiction row: token, shard tag, base tag, base fraction, base total.
+ */
 export type ShardVocabRow = [token: string, shardTag: string, baseTag: string, baseFrac: number, baseTotal: number]
 
-/** Findings summary returned by {@linkcode lintShardVocab}. */
+/**
+ * Findings summary returned by {@linkcode lintShardVocab}.
+ */
 export interface LintShardVocabSummary {
-	/** Real contradictions — the command exits 1 when nonzero. */
+	/**
+	 * Real contradictions — the command exits 1 when nonzero.
+	 */
 	errors: number
-	/** Affix-split rows (EXPECTED — the loader's affix-relabel handles them). */
+	/**
+	 * Affix-split rows (EXPECTED — the loader's affix-relabel handles them).
+	 */
 	warnings: number
 	findings: { contradictions: ShardVocabRow[]; affixSplits: ShardVocabRow[] }
 }
 
-/** Lint a synthetic shard's (token → tag) vocabulary against the base corpus, country-scoped. */
+/**
+ * Lint a synthetic shard's (token → tag) vocabulary against the base corpus, country-scoped.
+ */
 export async function lintShardVocab(options: LintShardVocabOptions): Promise<LintShardVocabSummary> {
 	const baseVersion = options.baseVersion ?? "v0.5.0"
 	const baseRoot = options.baseRoot ?? dataRootPath("corpus", "versioned")
 	const threshold = options.threshold ?? 0.7
 	const minCount = options.minCount ?? 50
-	const fraction = options.fraction ?? 1.0
+	const fraction = options.fraction ?? 1
 
 	// @duckdb/node-api is an optional peer — lazy import (the pipeline convention).
 	const { DuckDBInstance } = await import("@duckdb/node-api")
@@ -247,10 +290,13 @@ export async function lintShardVocab(options: LintShardVocabOptions): Promise<Li
 				set = new Set()
 				shardCountries.set(w, set)
 			}
+
 			set.add(country)
 		}
 	}
+
 	const shardVocab = new Set(shardTags.keys())
+
 	console.log(`shard: ${shardRows.length} rows, ${shardVocab.size} unique tokens`)
 
 	// 2. base parts — FULL by default; fraction<1 takes a proportional per-source slice (still big)
@@ -261,7 +307,7 @@ export async function lintShardVocab(options: LintShardVocabOptions): Promise<Li
 		throw new Error("no base parts found")
 	}
 
-	if (fraction < 1.0) {
+	if (fraction < 1) {
 		const bysrc = new Map<string, string[]>()
 
 		for (const p of parts) {
@@ -272,8 +318,10 @@ export async function lintShardVocab(options: LintShardVocabOptions): Promise<Li
 				list = []
 				bysrc.set(src, list)
 			}
+
 			list.push(p)
 		}
+
 		const sliced: string[] = []
 
 		for (const ps of bysrc.values()) {
@@ -283,8 +331,10 @@ export async function lintShardVocab(options: LintShardVocabOptions): Promise<Li
 				sliced.push(p)
 			}
 		}
+
 		parts = sliced
 	}
+
 	console.log(`base ${baseVersion}: scanning ${parts.length} parts (fraction=${pyFloat(fraction)}), COUNTRY-scoped`)
 
 	// 3. tally each shard token's base tag, SCOPED to the country the shard uses it in
@@ -336,6 +386,7 @@ export async function lintShardVocab(options: LintShardVocabOptions): Promise<Li
 	for (const [label, rows] of sections) {
 		if (!rows.length) continue
 		rows.sort((a, b) => b[4] - a[4] || b[3] - a[3])
+
 		console.log(`\n${label.startsWith("CONTRA") ? "⚠️ " : "· "}${rows.length} ${label}:`)
 
 		for (const [w, sTag, bTag, bFrac, bTotal] of rows) {

package/src/tools/lint-shard.ts

@@ -39,10 +39,22 @@ import { execSync } from "node:child_process"
 import { existsSync, readFileSync, writeFileSync } from "node:fs"
 import { fileURLToPath } from "node:url"
 
+/**
+ * Occurrences of a forbidden label before it is reported — one or two are noise, five is a pattern.
+ */
+const FORBIDDEN_LABEL_REPORT_THRESHOLD = 5
+
+/**
+ * Examples printed per finding before the list is truncated.
+ */
+const MAX_LISTED_EXAMPLES = 20
+
 const SEP = ""
 
-// Calibrated thresholds (DeepSeek turn 9). These can be tuned over time if new failure
-// modes surface that the current numbers miss.
+/**
+ * Calibrated thresholds (DeepSeek turn 9). These can be tuned over time if new failure modes surface that the current
+ * numbers miss.
+ */
 const CORPUS_CONFIDENCE_FLOOR = 0.66
 const SHARD_MIN_COUNT = 50
 const CORPUS_MIN_COUNT = 200
@@ -65,17 +77,29 @@ function defaultRulesPath(): string {
 	return fileURLToPath(new URL("../../../src/tools/lint-rules.json", import.meta.url))
 }
 
-/** Options for {@linkcode lintCorpusShard}. */
+/**
+ * Options for {@linkcode lintCorpusShard}.
+ */
 export interface LintCorpusShardOptions {
-	/** The new shard parquet to lint. */
+	/**
+	 * The new shard parquet to lint.
+	 */
 	shardPath: string
-	/** Pre-computed corpus stats JSON (see `corpus-stats.ts`). */
+	/**
+	 * Pre-computed corpus stats JSON (see `corpus-stats.ts`).
+	 */
 	statsPath: string
-	/** Anti-pattern rules JSON. Default: the `lint-rules.json` beside this module. */
+	/**
+	 * Anti-pattern rules JSON. Default: the `lint-rules.json` beside this module.
+	 */
 	rulesPath?: string
-	/** Write the markdown report here as well as stdout. */
+	/**
+	 * Write the markdown report here as well as stdout.
+	 */
 	outMd?: string
-	/** Write a JSON sidecar of the flags + summary here. */
+	/**
+	 * Write a JSON sidecar of the flags + summary here.
+	 */
 	outJson?: string
 }
 
@@ -114,6 +138,7 @@ labels_col = t['labels'].to_pylist()
 for i in range(len(tokens_col)):
     sys.stdout.write(json.dumps({"tokens": tokens_col[i], "labels": labels_col[i]}) + "\\n")
 `
+
 	const buf = execSync(`python3`, { input: py, maxBuffer: 1024 * 1024 * 1024 })
 	const rows: ShardRow[] = []
 
@@ -145,6 +170,7 @@ function statsFromShard(rows: ShardRow[]): ShardStats {
 	for (const row of rows) {
 		if (row.tokens.length !== row.labels.length) {
 			out.truncatedRows++
+
 			continue
 		}
 
@@ -161,6 +187,7 @@ function statsFromShard(rows: ShardRow[]): ShardStats {
 				labelMap = new Map()
 				out.tokens.set(tk, labelMap)
 			}
+
 			labelMap.set(lb, (labelMap.get(lb) ?? 0) + 1)
 
 			if (i + 1 < row.tokens.length) {
@@ -172,6 +199,7 @@ function statsFromShard(rows: ShardRow[]): ShardStats {
 					bMap = new Map()
 					out.bigrams.set(bigramKey, bMap)
 				}
+
 				bMap.set(bigramLabel, (bMap.get(bigramLabel) ?? 0) + 1)
 			}
 		}
@@ -203,7 +231,9 @@ function majorityLabel(distribution: Map<string, number> | Record<string, number
 	return { label: bestLabel, count: bestCount, total, confidence: total === 0 ? 0 : bestCount / total }
 }
 
-/** One lint flag emitted by a check. */
+/**
+ * One lint flag emitted by a check.
+ */
 export interface LintShardFlag {
 	check: string
 	severity: "error" | "warn"
@@ -217,12 +247,16 @@ export interface LintShardFlag {
 	ruleID?: string
 }
 
-/** Findings summary returned by {@linkcode lintCorpusShard}. */
+/**
+ * Findings summary returned by {@linkcode lintCorpusShard}.
+ */
 export interface LintCorpusShardSummary {
 	errors: number
 	warnings: number
 	findings: LintShardFlag[]
-	/** The rendered markdown report (also printed to stdout). */
+	/**
+	 * The rendered markdown report (also printed to stdout).
+	 */
 	report: string
 }
 
@@ -307,6 +341,7 @@ function checkBigramCollisions(shard: ShardStats, corpus: CorpusStats): LintShar
 			const renderBigram = bigram.split(SEP).join(" ")
 			const renderShardLabel = shardMaj.label.split(SEP).join(" → ")
 			const renderCorpusLabel = corpusMaj.label.split(SEP).join(" → ")
+
 			flags.push({
 				check: "bigram-collision",
 				severity: "error",
@@ -325,6 +360,7 @@ function checkBigramCollisions(shard: ShardStats, corpus: CorpusStats): LintShar
 
 function checkRules(shard: ShardStats, rulesFile: LintRulesFile): LintShardFlag[] {
 	const flags: LintShardFlag[] = []
+
 	const compiled = rulesFile.rules.map((r) => ({
 		rule: r,
 		regex: new RegExp(r.pattern, r.pattern_case_sensitive ? "" : "i"),
@@ -335,7 +371,7 @@ function checkRules(shard: ShardStats, rulesFile: LintRulesFile): LintShardFlag[
 			if (!regex.test(token)) continue
 
 			for (const [label, count] of labelMap) {
-				if (rule.forbidden_labels.includes(label) && count >= 5) {
+				if (rule.forbidden_labels.includes(label) && count >= FORBIDDEN_LABEL_REPORT_THRESHOLD) {
 					flags.push({
 						check: "anti-pattern-rule",
 						severity: rule.severity,
@@ -363,6 +399,7 @@ function checkSanity(shard: ShardStats): LintShardFlag[] {
 			detail: `${shard.truncatedRows} row(s) have tokens.length !== labels.length. Pipeline alignment bug.`,
 		})
 	}
+
 	const allORatio = shard.allORows / Math.max(1, shard.rowCount)
 
 	if (allORatio >= ALL_O_RATIO_CEILING) {
@@ -383,28 +420,29 @@ function renderReport(
 ): string {
 	const errors = flags.filter((f) => f.severity === "error")
 	const warns = flags.filter((f) => f.severity === "warn")
-	const verdict = errors.length === 0 ? "**PASS** ✓" : "**FLAGGED** ⚠"
-	const lines: string[] = []
-	lines.push(`# Corpus Lint: ${verdict}`)
-	lines.push("")
-	lines.push(`- **Shard:** \`${opts.shardPath}\``)
-	lines.push(`- **Corpus stats:** \`${opts.statsPath}\``)
-	lines.push(`- **Rules:** \`${opts.rulesPath}\``)
-	lines.push(`- **Shard rows:** ${shard.rowCount}`)
-	lines.push(`- **Unique tokens:** ${shard.tokens.size}`)
-	lines.push(`- **Unique bigrams:** ${shard.bigrams.size}`)
-	lines.push("")
-	lines.push(
-		`**Errors:** ${errors.length} (gates the shard's inclusion unless MANIFEST sets \`lint_acknowledged: true\`)`
-	)
-	lines.push(`**Warnings:** ${warns.length} (advisory)`)
-	lines.push("")
+	const verdict = !errors.length ? "**PASS** ✓" : "**FLAGGED** ⚠"
+
+	const lines: string[] = [
+		`# Corpus Lint: ${verdict}`,
+		"",
+		`- **Shard:** \`${opts.shardPath}\``,
+		`- **Corpus stats:** \`${opts.statsPath}\``,
+		`- **Rules:** \`${opts.rulesPath}\``,
+		`- **Shard rows:** ${shard.rowCount}`,
+		`- **Unique tokens:** ${shard.tokens.size}`,
+		`- **Unique bigrams:** ${shard.bigrams.size}`,
+		"",
+		`**Errors:** ${errors.length} (gates the shard's inclusion unless MANIFEST sets \`lint_acknowledged: true\`)`,
+		`**Warnings:** ${warns.length} (advisory)`,
+		"",
+	]
 
-	if (flags.length === 0) {
+	if (!flags.length) {
 		lines.push("No anomalies detected.")
 
 		return lines.join("\n")
 	}
+
 	const byCheck = new Map<string, LintShardFlag[]>()
 
 	for (const f of flags) {
@@ -423,16 +461,19 @@ function renderReport(
 			lines.push(`- **[${f.severity.toUpperCase()}]** ${f.detail}`)
 		}
 
-		if (list.length > 20) {
+		if (list.length > MAX_LISTED_EXAMPLES) {
 			lines.push(`- ... and ${list.length - 20} more`)
 		}
+
 		lines.push("")
 	}
 
 	return lines.join("\n")
 }
 
-/** Lint a shard against corpus stats + the anti-pattern rules; print the markdown report to stdout. */
+/**
+ * Lint a shard against corpus stats + the anti-pattern rules; print the markdown report to stdout.
+ */
 export function lintCorpusShard(
 	options: LintCorpusShardOptions,
 	report?: (line: string) => void
@@ -440,6 +481,7 @@ export function lintCorpusShard(
 	const rulesPath = options.rulesPath ?? defaultRulesPath()
 	report?.(`Reading corpus stats from ${options.statsPath}...`)
 	const corpus: CorpusStats = JSON.parse(readFileSync(options.statsPath, "utf8"))
+
 	report?.(
 		`  ${corpus.row_count} rows from ${corpus.shard_paths.length} shard(s); ${Object.keys(corpus.tokens).length} tokens, ${Object.keys(corpus.bigrams).length} bigrams`
 	)
@@ -455,6 +497,7 @@ export function lintCorpusShard(
 	const rulesFile: LintRulesFile = JSON.parse(readFileSync(rulesPath, "utf8"))
 
 	report?.(`Running checks...`)
+
 	const flags: LintShardFlag[] = [
 		...checkDistributionOutliers(shard, corpus),
 		...checkLabelVacuum(shard, corpus),
@@ -464,6 +507,7 @@ export function lintCorpusShard(
 	]
 
 	const rendered = renderReport({ shardPath: options.shardPath, statsPath: options.statsPath, rulesPath }, shard, flags)
+
 	console.log(rendered)
 
 	if (options.outMd) {

package/src/tools/overlay-manifest.ts

@@ -51,9 +51,11 @@ interface BaseManifest {
 	total_rows: number
 }
 
-/** Escape a path for single-quoted SQL string literals. */
+/**
+ * Escape a path for single-quoted SQL string literals.
+ */
 function sqlString(value: string): string {
-	return value.replace(/'/g, "''")
+	return value.replaceAll("'", "''")
 }
 
 async function descriptor(
@@ -78,7 +80,7 @@ async function descriptor(
 		bytes: statSync(localPath).size,
 		sha256: sha256Hex(readFileSync(localPath)),
 		first_source_id: sids[0]!,
-		last_source_id: sids[sids.length - 1]!,
+		last_source_id: sids.at(-1)!,
 		source,
 	}
 }
@@ -103,7 +105,7 @@ export async function assembleOverlayManifest(args: OverlayManifestOptions): Pro
 	const reroot = (p: string): string => {
 		const i = p.indexOf("/corpus/versioned/")
 
-		return i >= 0 ? "/data" + p.slice(i) : p
+		return i !== -1 ? "/data" + p.slice(i) : p
 	}
 
 	const kept = base.shards.map((s) => ({ ...s, path: reroot(s.path) }))
@@ -134,6 +136,7 @@ export async function assembleOverlayManifest(args: OverlayManifestOptions): Pro
 
 	const out = join(args.newDir, "MANIFEST.json")
 	writeFileSync(out, JSON.stringify(manifest, null, 1) + "\n")
+
 	console.log(`wrote ${out}`)
 	console.log(`  shards: ${manifest.shards.length} (${kept.length} base kept, +1 ${args.source})`)
 	console.log(`  counts: ${JSON.stringify(manifest.counts)}  total: ${manifest.total_rows}`)

package/src/tools/shard-kryptonite.ts

@@ -31,9 +31,13 @@ export interface ShardKryptoniteOptions {
 	jsonl: string
 	baseManifest: string
 	outDir: string
-	/** Default `"0.4.0"`. */
+	/**
+	 * Default `"0.4.0"`.
+	 */
 	corpusVersion?: string
-	/** Default `"deepseek-kryptonite"`. */
+	/**
+	 * Default `"deepseek-kryptonite"`.
+	 */
 	source?: string
 }
 
@@ -41,6 +45,7 @@ async function* canonicalRows(jsonl: string, corpusVersion: string): AsyncIterab
 	for await (const raw of iterateJSONL<Record<string, unknown>>(jsonl)) {
 		// Strip sidecar underscore-prefixed fields the generator left behind for debugging.
 		const components = raw["components"] as Record<string, string>
+
 		yield {
 			raw: raw["raw"] as string,
 			components,
@@ -81,6 +86,7 @@ export async function buildKryptoniteShard(
 	await mkdir(options.outDir, { recursive: true })
 
 	const quarantine: string[] = []
+
 	const newManifest = await writeShards(
 		{ train: labeledRows(options.jsonl, corpusVersion, quarantine) },
 		{ outputDir: options.outDir, corpusVersion }
@@ -91,7 +97,7 @@ export async function buildKryptoniteShard(
 			`quarantined ${quarantine.length}`
 	)
 
-	if (quarantine.length > 0) {
+	if (quarantine.length) {
 		const qPath = join(options.outDir, `corpus-v${corpusVersion}`, "quarantine-kryptonite.tsv")
 		writeFileSync(qPath, quarantine.join("\n") + "\n", "utf8")
 		report?.(`quarantine log → ${qPath}`)
@@ -106,6 +112,7 @@ export async function buildKryptoniteShard(
 
 	// Compose the final corpus-v0.4.0 manifest: every shard from base + the new shard(s).
 	const base = JSON.parse(readFileSync(options.baseManifest, "utf8")) as ShardManifest
+
 	const combined: ShardManifest = {
 		corpus_version: corpusVersion,
 		schema: PARQUET_COLUMNS,
@@ -119,6 +126,7 @@ export async function buildKryptoniteShard(
 		},
 		total_rows: base.total_rows + newManifest.total_rows,
 	}
+
 	// Stamp source on the legacy v0.3.0 shards too, so audit's shard.source path is the
 	// authoritative one. v0.3.0 shards mix sources; we use the first_source_id-prefix
 	// inference for them (audit.ts will re-derive on its own when shard.source is absent).

package/src/tools/shard-translit.ts

@@ -44,11 +44,17 @@ export interface ShardTranslitOptions {
 	jsonl: string
 	baseManifest: string
 	outDir: string
-	/** Default `"0.4.0"`. */
+	/**
+	 * Default `"0.4.0"`.
+	 */
 	corpusVersion?: string
-	/** Default `"/data/"`. */
+	/**
+	 * Default `"/data/"`.
+	 */
 	canonicalPathPrefix?: string
-	/** Default `"/mnt/playpen/mailwoman-data/"`. */
+	/**
+	 * Default `"/mnt/playpen/mailwoman-data/"`.
+	 */
 	legacyPathPrefix?: string
 }
 
@@ -106,6 +112,7 @@ async function writeOneShard(
 	const writer = await ParquetWriter.openFile<ParquetRow>(LABELED_ROW_SCHEMA, outPath, {
 		rowGroupSize: ROW_GROUP_SIZE,
 	})
+
 	writer.setMetadata("mailwoman.corpus_version", corpusVersion)
 	writer.setMetadata("mailwoman.split", "train")
 	writer.setMetadata("mailwoman.shard_source", source)
@@ -120,8 +127,10 @@ async function writeOneShard(
 		if (firstSourceID === "") {
 			firstSourceID = row.source_id
 		}
+
 		lastSourceID = row.source_id
 	}
+
 	await writer.close()
 
 	const fileStat = await stat(outPath)
@@ -177,8 +186,10 @@ export async function buildTranslitShard(
 
 		if (result.kind !== "labeled") {
 			quarantine.push(`${canon.source_id}\t${result.row.reason}`)
+
 			continue
 		}
+
 		const bucket = buckets.get(canon.source)
 
 		if (bucket) {
@@ -187,10 +198,11 @@ export async function buildTranslitShard(
 			buckets.set(canon.source, [result.row])
 		}
 	}
+
 	report?.(`read ${totalIn} rows; ${quarantine.length} quarantined; ${buckets.size} script buckets`)
 
 	const newShards: ShardDescriptor[] = []
-	const sortedKeys = [...buckets.keys()].sort()
+	const sortedKeys = [...buckets.keys()].toSorted()
 
 	for (const source of sortedKeys) {
 		const rows = buckets.get(source)!
@@ -201,7 +213,7 @@ export async function buildTranslitShard(
 		report?.(`  ${source}: ${descriptor.rows} rows → ${outPath} (${descriptor.bytes} bytes)`)
 	}
 
-	if (quarantine.length > 0) {
+	if (quarantine.length) {
 		const qPath = join(corpusDir, "quarantine-transliteration.tsv")
 		writeFileSync(qPath, quarantine.join("\n") + "\n", "utf8")
 		report?.(`quarantine log → ${qPath} (${quarantine.length} rows)`)
@@ -211,11 +223,14 @@ export async function buildTranslitShard(
 	// the new translit shards. Kryptonite shard already lives in the base manifest (it was written
 	// there by Thread B).
 	const base = JSON.parse(readFileSync(options.baseManifest, "utf8")) as ShardManifest
+
 	const rewrittenBase = base.shards.map((sh) => ({
 		...sh,
 		path: canonicalizeShardPath(sh.path, legacyPathPrefix, canonicalPathPrefix),
 	}))
+
 	const newTrainRows = newShards.reduce((sum, sh) => sum + sh.rows, 0)
+
 	const combined: ShardManifest = {
 		corpus_version: corpusVersion,
 		schema: PARQUET_COLUMNS,