@mailwoman/corpus 8.6.0 → 9.0.0

package/src/tools/index.ts

@@ -17,8 +17,12 @@ export * from "./fetch/download.ts"
 export * from "./fetch/index.ts"
 export * from "./golden-expand.ts"
 export * from "./golden-promote.ts"
+export * from "./golden-relabel-street.ts"
 export * from "./jsonl-to-parquet.ts"
 export * from "./lint-shard.ts"
 export * from "./lint-shard-vocab.ts"
 export * from "./shard-kryptonite.ts"
+export * from "./overture-subvenue.ts"
+export * from "./sub-venue-lexicon.ts"
+export * from "./sub-venue-promotions.ts"
 export * from "./shard-translit.ts"

package/src/tools/jsonl-to-parquet.ts

@@ -36,6 +36,7 @@ import { unlink } from "node:fs/promises"
 import { tmpdir } from "node:os"
 import { join } from "node:path"
 
+import { parseJSONStrict } from "@mailwoman/core/objects"
 import { TextSpliterator } from "spliterator"
 
 const REQUIRED_COLUMNS = [
@@ -168,7 +169,7 @@ export async function jsonlToParquet(
 		let lineNo = 0
 
 		// TextSpliterator, not JSONSpliterator: the staging write below streams the RAW line bytes to
-		// DuckDB verbatim (JSON.parse here only validates), so a re-serialized JSONSpliterator row would
+		// DuckDB verbatim (the parse here only validates), so a re-serialized JSONSpliterator row would
 		// defeat the point. CRLF is handled by the existing `rawLine.trim()` (strips a trailing \r),
 		// same as readline's crlfDelay:Infinity did.
 		for await (const rawLine of TextSpliterator.fromAsync(options.input)) {
@@ -176,7 +177,7 @@ export async function jsonlToParquet(
 			const line = rawLine.trim()
 
 			if (!line) continue
-			const row = JSON.parse(line) as Record<string, unknown>
+			const row = parseJSONStrict<Record<string, unknown>>(line)
 			assertSpanTriple(row, lineNo)
 			// Write the validated line verbatim; DuckDB's `read_json` projects to the explicit `columns`
 			// map below (extra keys dropped, absent keys → NULL — matching the Python `row.get(c)`).

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

@@ -37,6 +37,7 @@
 import { readdirSync } from "node:fs"
 import { join } from "node:path"
 
+import { tryParsingJSON } from "@mailwoman/core/objects"
 import { dataRootPath } from "@mailwoman/core/utils"
 
 /**
@@ -162,8 +163,8 @@ async function readRows(con: DuckDBConnection, path: string): Promise<CorpusRow[
 	const rows: CorpusRow[] = []
 
 	for (const r of raw) {
-		const tokens = JSON.parse(String(r.tokens)) as unknown
-		const labels = JSON.parse(String(r.labels)) as unknown
+		const tokens = tryParsingJSON(String(r.tokens))
+		const labels = tryParsingJSON(String(r.labels))
 
 		if (!Array.isArray(tokens) || !Array.isArray(labels)) continue
 

package/src/tools/lint-shard.ts

@@ -23,7 +23,7 @@
  *        mappings — flagging matches.
  *   5. **Basic sanity.** Truncated rows (tokens.length !== labels.length), all-O rows >90% of shard.
  *
- *   Output: markdown report on stdout, optional JSON sidecar via `outJson`. The command exits 0 if
+ *   Output: markdown report on stdout, optional JSON sidecar via `outJSON`. The command exits 0 if
  *   no errors, 1 if any errors (warnings don't gate). Per the design, the MANIFEST entry for a
  *   flagged shard should require `lint_acknowledged: true` before training consumes it.
  *
@@ -35,10 +35,13 @@
  *   [--out-json /tmp/lint-report.json]
  */
 
-import { execSync } from "node:child_process"
 import { existsSync, readFileSync, writeFileSync } from "node:fs"
 import { fileURLToPath } from "node:url"
 
+import { parseJSONStrict } from "@mailwoman/core/objects"
+
+import { ParquetReader } from "../parquet-wrapper/index.ts"
+
 /**
  * Occurrences of a forbidden label before it is reported — one or two are noise, five is a pattern.
  */
@@ -100,7 +103,7 @@ export interface LintCorpusShardOptions {
 	/**
 	 * Write a JSON sidecar of the flags + summary here.
 	 */
-	outJson?: string
+	outJSON?: string
 }
 
 interface CorpusStats {
@@ -123,31 +126,24 @@ interface LintRulesFile {
 	rules: LintRule[]
 }
 
-interface ShardRow {
+// The reader's `ParquetRecordLike` constraint is `Record<string, unknown>`, and TypeScript gives a type
+// alias an implicit index signature where an interface has none.
+// oxlint-disable-next-line typescript/consistent-type-definitions -- see above
+type ShardRow = {
 	tokens: string[]
 	labels: string[]
 }
 
-function readShard(shardPath: string): ShardRow[] {
-	const py = `
-import pyarrow.parquet as pq
-import json, sys
-t = pq.read_table(${JSON.stringify(shardPath)}, columns=['tokens', 'labels'])
-tokens_col = t['tokens'].to_pylist()
-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[] = []
-
-	for (const line of buf.toString("utf8").split("\n")) {
-		if (!line) continue
-		rows.push(JSON.parse(line))
-	}
+/**
+ * Stream a shard's `tokens`/`labels` columns.
+ *
+ * Projected rather than read whole: parquet is columnar, so the twelve unused columns are never touched. The rows feed
+ * straight into {@link statsFromShard} and are never all resident.
+ */
+async function* streamShard(shardPath: string): AsyncIterable<ShardRow> {
+	await using reader = await ParquetReader.openFile<ShardRow>(shardPath)
 
-	return rows
+	yield* reader.project("tokens", "labels")
 }
 
 interface ShardStats {
@@ -158,16 +154,18 @@ interface ShardStats {
 	allORows: number
 }
 
-function statsFromShard(rows: ShardRow[]): ShardStats {
+async function statsFromShard(rows: AsyncIterable<ShardRow>): Promise<ShardStats> {
 	const out: ShardStats = {
-		rowCount: rows.length,
+		rowCount: 0,
 		tokens: new Map(),
 		bigrams: new Map(),
 		truncatedRows: 0,
 		allORows: 0,
 	}
 
-	for (const row of rows) {
+	for await (const row of rows) {
+		out.rowCount++
+
 		if (row.tokens.length !== row.labels.length) {
 			out.truncatedRows++
 
@@ -474,27 +472,26 @@ function renderReport(
 /**
  * Lint a shard against corpus stats + the anti-pattern rules; print the markdown report to stdout.
  */
-export function lintCorpusShard(
+export async function lintCorpusShard(
 	options: LintCorpusShardOptions,
 	report?: (line: string) => void
-): LintCorpusShardSummary {
+): Promise<LintCorpusShardSummary> {
 	const rulesPath = options.rulesPath ?? defaultRulesPath()
 	report?.(`Reading corpus stats from ${options.statsPath}...`)
-	const corpus: CorpusStats = JSON.parse(readFileSync(options.statsPath, "utf8"))
+	const corpus = parseJSONStrict<CorpusStats>(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`
 	)
 
 	report?.(`Reading shard from ${options.shardPath}...`)
-	const rows = readShard(options.shardPath)
-	report?.(`  ${rows.length} rows`)
 
-	report?.(`Computing shard stats...`)
-	const shard = statsFromShard(rows)
+	const shard = await statsFromShard(streamShard(options.shardPath))
+
+	report?.(`  ${shard.rowCount} rows`)
 
 	report?.(`Loading rules from ${rulesPath}...`)
-	const rulesFile: LintRulesFile = JSON.parse(readFileSync(rulesPath, "utf8"))
+	const rulesFile = parseJSONStrict<LintRulesFile>(readFileSync(rulesPath, "utf8"))
 
 	report?.(`Running checks...`)
 
@@ -514,9 +511,9 @@ export function lintCorpusShard(
 		writeFileSync(options.outMd, rendered)
 	}
 
-	if (options.outJson) {
+	if (options.outJSON) {
 		writeFileSync(
-			options.outJson,
+			options.outJSON,
 			JSON.stringify(
 				{
 					shard: options.shardPath,

package/src/tools/overlay-manifest.ts

@@ -26,6 +26,7 @@
 import { readFileSync, statSync, writeFileSync } from "node:fs"
 import { join } from "node:path"
 
+import { parseJSONStrict } from "@mailwoman/core/objects"
 import { sha256Hex } from "@mailwoman/core/utils"
 
 interface ShardDescriptor {
@@ -96,7 +97,7 @@ export interface OverlayManifestOptions {
 }
 
 export async function assembleOverlayManifest(args: OverlayManifestOptions): Promise<void> {
-	const base = JSON.parse(readFileSync(args.base, "utf8")) as BaseManifest
+	const base = parseJSONStrict<BaseManifest>(readFileSync(args.base, "utf8"))
 
 	if (base.shards.some((s) => s.source === args.source)) {
 		console.log(`WARN: base already contains source '${args.source}' — is this the right base?`)

package/src/tools/overture-subvenue.ts

@@ -0,0 +1,215 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Overture Places source for the sub-venue lexicon (#35 wave 2) — read the sub-venue-bearing
+ *   category slices of `poi.db` (spatial layer #1, `$MAILWOMAN_DATA_ROOT/poi/poi.db`) and yield
+ *   {@link SubVenueHarvestRow}s the lexicon builder consumes exactly like an OSM extract.
+ *
+ *   ── WHY OVERTURE AT ALL, when the OSM extractor already exists ────────────────────────────────────
+ *   Wave 1 measured `concourse` at 21 real Overture rows against 4 in the whole Great Britain OSM
+ *   extract, 3 of which are a street called CONCOURSE WAY. Overture's `airport_terminal` category is
+ *   curated venue-interior naming; OSM's `aeroway=terminal` is a building footprint that usually
+ *   carries the AIRPORT's name. The two sources fail differently, so both are read.
+ *
+ *   ── THE CATEGORY SET IS MEASURED, NOT GUESSED ────────────────────────────────────────────────────
+ *   A full scan of all 13,681,698 rows (2026-08-05, poi.db vintage 2026-05-20.0) counted, per
+ *   category, how many named rows carry a designator token. The ranking is NOT what a category name
+ *   predicts — `gas_station` leads the whole table with 12,996 hits, every one of them the token
+ *   `station` inside "Holiday Station" / "Chevron Station Seward", and `shoe_store` contributes 708
+ *   hits of `wing` because Red Wing sells boots. {@link OVERTURE_SUBVENUE_CATEGORIES} is the four
+ *   categories whose hits survived reading the distribution; the rejects are listed below it so nobody
+ *   re-proposes them.
+ *
+ *   ── poi.db IS FOUR COUNTRIES ─────────────────────────────────────────────────────────────────────
+ *   Measured the same day: US 11,521,612 / CA 794,418 / FR 721,352 / MX 644,316, and nothing else. The
+ *   shipped layer is not a world gazetteer, so Overture can attest en-US, en-CA, fr-FR and es-MX
+ *   surfaces and NOTHING ELSE. Every non-Latin designator the corpus task asks for — `ターミナル`,
+ *   `Halle`, `Flügel` — has to come from the OSM leg. Do not read a zero count here as evidence of
+ *   absence in the world; it is evidence of absence in four countries.
+ *
+ *   ── The row shape fits; the PROVENANCE STAMP did not ─────────────────────────────────────────────
+ *   Wave 1's `OSMSubVenueRow` was written to accept a non-OSM row, and it does: an Overture row is
+ *   `{ designatorID, name }` with no `ref` and no `localizedNames`. What did NOT fit is
+ *   `extractAttestedPhrases`, which hardcoded `osm:name` as the surface's `source`. Feeding Overture
+ *   rows through it unchanged would have labelled every Overture surface as OSM-attested — a
+ *   provenance lie, and under ODbL a consequential one. Hence the `source`/`region` options on that
+ *   function and the source-neutral {@link SubVenueHarvestRow} name.
+ */
+
+import { DatabaseSync } from "node:sqlite"
+
+import { DatabaseClient } from "@mailwoman/core/kysley/client"
+
+import type { SubVenueHarvestRow } from "./sub-venue-lexicon.ts"
+
+/**
+ * Overture Places category → the designator its rows attest.
+ *
+ * Each entry carries the 2026-08-05 full-scan measurement in a comment: `rows` is the category's total, `hits` is how
+ * many of its named rows contain any designator token, and the token list is the top of that distribution.
+ *
+ * REJECTED, with the number that rejected them — do not re-add without a fresh census:
+ *
+ * - `gas_station` (12,996 hits) — all `station` inside a brand name (Holiday Station, Chevron Station Seward).
+ * - `fire_station` (10,377) — same, plus 330 `hall` from fire halls, which are venues rather than sub-venues.
+ * - `town_hall` (5,528) — `City Hall` is a whole building, the `venue` tier, not interior structure.
+ * - `building_supply_store` (4,030) — `building` inside "Allied Building Products".
+ * - `jehovahs_witness_place_of_worship` (2,334) — every hit is "Kingdom Hall of Jehovah's Witnesses".
+ * - `shoe_store` (909, of which 708 `wing`) — Red Wing. This one is a CONFOUND BOARD entry, not a source.
+ * - `college_university` (3,697) — 2,082 `campus`, but the row names the whole institution; `campus_building` is the
+ *   interior slice and is kept instead.
+ * - `airport` (6,000 rows, 4,302 hits) — 4,071 of them are the token `airport` in the aerodrome's own name. Venue tier,
+ *   already covered by OurAirports, and it drowns the interior signal.
+ * - `transport_interchange` (1 row), `rail_facility_or_service` (81 rows, 2 hits) — too small to matter.
+ * - `public_transit_facility_or_service` (2,274 rows, 185 hits) — 161 are `station` naming the station itself.
+ */
+export const OVERTURE_SUBVENUE_CATEGORIES: Readonly<Record<string, string>> = {
+	// 1,022 rows / 669 hits — terminal 266, concourse 19, gate 13, hall 4. The densest interior naming
+	// in the layer and the reason this reader exists.
+	airport_terminal: "terminal",
+	// 7,366 rows / 3,382 hits — hall 2,134, building 1,019, campus 209. US academic halls and numbered
+	// campus buildings: "UAA Cuddy Hall", "UAA Science Building". The row is a building ON a campus, so
+	// `campus` is its CONTEXT designator; the phrase found inside the name decides the record it
+	// attests, which for these rows is mostly `hall`.
+	campus_building: "campus",
+	// 443 rows / 301 hits — pier 282, terminal 17.
+	pier: "pier",
+	// 388 rows / 66 hits — airport 36, terminal 20, concourse 5, gate 3. Small, but the hits are almost
+	// all genuine ("Delta Sky Club Concourse B").
+	airport_lounge: "terminal",
+}
+
+/**
+ * The `poi` and `poi_category_codes` columns this reader touches, declared LOCALLY.
+ *
+ * `@mailwoman/resolver-wof-sqlite` owns the full `POIDatabase` interface, and `@mailwoman/corpus` does not depend on it
+ * — the same dependency-direction call `sub-venue-lexicon.ts` makes for `@mailwoman/osm`'s row type. This is a
+ * read-only projection of four columns; `overture-subvenue.test.ts` builds a fixture with exactly this DDL, so a column
+ * rename upstream fails a test here rather than throwing at runtime against a 3.9 GB database nobody has in CI.
+ */
+interface POIReadDatabase {
+	poi: {
+		category_id: number
+		name: string | null
+		country: string
+	}
+	poi_category_codes: {
+		id: number
+		category: string
+	}
+	layer_manifest: {
+		name: string
+		source_vintage: string
+	}
+}
+
+/**
+ * The layer's `source_vintage` — the Overture release the rows came from (`2026-05-20.0`), for the lexicon's
+ * `sources[]`.
+ *
+ * Read off the database rather than passed in, because a vintage a caller types is a vintage that goes stale silently.
+ * The layer-contract tables are part of every layer database by construction — see `docs/engineering/reference/
+ * layer-contract.mdx` — so there is no version of poi.db where this is absent.
+ */
+export async function readOvertureLayerVintage(databasePath: string): Promise<string> {
+	using kdb = new DatabaseClient<POIReadDatabase>({
+		database: new DatabaseSync(databasePath, { readOnly: true }),
+	})
+
+	const row = await kdb
+		.selectFrom("layer_manifest")
+		.select("source_vintage")
+		.where("name", "=", "poi")
+		.executeTakeFirst()
+
+	return row?.source_vintage ?? ""
+}
+
+export interface ReadOvertureSubVenuesOptions {
+	/**
+	 * Path to `poi.db`. Typically `dataRootPath("poi", "poi.db")`.
+	 */
+	databasePath: string
+	/**
+	 * Category → designator map. Defaults to {@link OVERTURE_SUBVENUE_CATEGORIES}.
+	 */
+	categories?: Readonly<Record<string, string>>
+	/**
+	 * Restrict to these ISO 3166-1 alpha-2 countries. Omit for all four the layer carries.
+	 */
+	countries?: readonly string[]
+}
+
+/**
+ * One Overture row plus the country it came from — {@link SubVenueHarvestRow} widened by the field the layer has and an
+ * OSM extract does not (a Geofabrik extract's country is a property of the invocation, so OSM rows carry `country:
+ * ""`).
+ */
+export interface OvertureSubVenueRow extends SubVenueHarvestRow {
+	/**
+	 * ISO 3166-1 alpha-2, straight off the Overture partition.
+	 */
+	country: string
+	/**
+	 * The Overture category the row was read from, so a surface's provenance survives past the designator.
+	 */
+	category: string
+}
+
+/**
+ * Read the sub-venue-bearing category slices of `poi.db`.
+ *
+ * Cold path, already async, no interface constraint — so Kysely, per the repo's inline-SQL rule.
+ *
+ * `category_id` is the SECOND component of poi.db's clustered `(h3_cell, category_id, …)` primary key, which reads like
+ * a full 13.7M-row scan and is not one: SQLite skip-scans the leading `h3_cell` and the whole four-category read
+ * returned 9,219 rows in **1.4 s** on the shipped layer (2026-08-05). A JS-side scan of every row to survey the same
+ * question took 52 s, which is the number to remember if you are tempted to filter in JS instead.
+ */
+export async function readOvertureSubVenues(options: ReadOvertureSubVenuesOptions): Promise<OvertureSubVenueRow[]> {
+	const categories = options.categories ?? OVERTURE_SUBVENUE_CATEGORIES
+
+	using kdb = new DatabaseClient<POIReadDatabase>({
+		database: new DatabaseSync(options.databasePath, { readOnly: true }),
+	})
+
+	const codes = await kdb
+		.selectFrom("poi_category_codes")
+		.select(["id", "category"])
+		.where("category", "in", Object.keys(categories))
+		.execute()
+
+	if (!codes.length) return []
+
+	const designatorByID = new Map<number, string>()
+	const categoryByID = new Map<number, string>()
+
+	for (const code of codes) {
+		const designator = categories[code.category]
+
+		if (!designator) continue
+		designatorByID.set(code.id, designator)
+		categoryByID.set(code.id, code.category)
+	}
+
+	let query = kdb
+		.selectFrom("poi")
+		.select(["category_id", "name", "country"])
+		.where("category_id", "in", [...designatorByID.keys()])
+		.where("name", "is not", null)
+
+	if (options.countries?.length) {
+		query = query.where("country", "in", [...options.countries])
+	}
+
+	const rows = await query.execute()
+
+	return rows.map((row) => ({
+		designatorID: designatorByID.get(row.category_id)!,
+		name: row.name,
+		country: row.country,
+		category: categoryByID.get(row.category_id)!,
+	}))
+}

package/src/tools/shard-kryptonite.ts

@@ -7,7 +7,7 @@
  *   MANIFEST. corpus-v0.4.0 is a pure adapter-addition revision: it points at every shard from
  *   v0.3.0 plus the new kryptonite shard(s). No v0.3.0 bytes are touched or re-shuffled.
  *
- *   See docs/articles/plan/reference/CORPUS_V0_4_0_GENERATION.md for the why; that doc also pins the
+ *   See docs/engineering/reference/CORPUS_V0_4_0_GENERATION.md for the why; that doc also pins the
  *   DeepSeek model version + prompt versions used to produce the JSONL.
  *
  *   Invoke via `mailwoman corpus shard kryptonite \
@@ -20,7 +20,8 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs"
 import { mkdir } from "node:fs/promises"
 import { join } from "node:path"
 
-import { iterateJSONL } from "@mailwoman/core/utils"
+import { parseJSONStrict } from "@mailwoman/core/objects"
+import { JSONSpliterator } from "spliterator"
 
 import { alignRow } from "../align.ts"
 import type { ShardManifest } from "../parquet.ts"
@@ -42,7 +43,7 @@ export interface ShardKryptoniteOptions {
 }
 
 async function* canonicalRows(jsonl: string, corpusVersion: string): AsyncIterable<CanonicalRow> {
-	for await (const raw of iterateJSONL<Record<string, unknown>>(jsonl)) {
+	for await (const raw of JSONSpliterator.fromAsync<Record<string, unknown>>(jsonl)) {
 		// Strip sidecar underscore-prefixed fields the generator left behind for debugging.
 		const components = raw["components"] as Record<string, string>
 
@@ -111,7 +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 base = parseJSONStrict<ShardManifest>(readFileSync(options.baseManifest, "utf8"))
 
 	const combined: ShardManifest = {
 		corpus_version: corpusVersion,

package/src/tools/shard-translit.ts

@@ -16,10 +16,10 @@
  *   - Each shard is written to `train/part-translit-<slug>.parquet` (distinct from kryptonite's
  *       `part-0000.parquet`, which v0.4.0's first builder already produced).
  *   - Inherits the path-canonicalization fix flagged in Thread B's postmortem: v0.3.0 shard paths are
- *       rewritten from `/mnt/playpen/mailwoman-data/...` to `/data/...` in the combined MANIFEST so
+ *       rewritten from `$MAILWOMAN_DATA_ROOT/...` to `/data/...` in the combined MANIFEST so
  *       all paths share one container-friendly form.
  *
- *   See docs/articles/plan/reference/CORPUS_V0_4_0_GENERATION.md for prompts, model, and the
+ *   See docs/engineering/reference/CORPUS_V0_4_0_GENERATION.md for prompts, model, and the
  *   reproducibility contract.
  *
  *   Invoke via `mailwoman corpus shard translit \
@@ -32,7 +32,9 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs"
 import { mkdir, stat } from "node:fs/promises"
 import { join } from "node:path"
 
-import { iterateJSONL, sha256File } from "@mailwoman/core/utils"
+import { parseJSONStrict } from "@mailwoman/core/objects"
+import { mailwomanDataRoot, sha256File } from "@mailwoman/core/utils"
+import { JSONSpliterator } from "spliterator"
 
 import { alignRow } from "../align.ts"
 import { ParquetWriter } from "../parquet-wrapper/index.ts"
@@ -53,7 +55,10 @@ export interface ShardTranslitOptions {
 	 */
 	canonicalPathPrefix?: string
 	/**
-	 * Default `"/mnt/playpen/mailwoman-data/"`.
+	 * Prefix the base manifest's shard paths currently carry, to be rewritten to
+	 * {@link ShardTranslitOptions.canonicalPathPrefix}. Defaults to `mailwomanDataRoot()` with a trailing slash — the
+	 * root that WROTE those paths. Pass it explicitly when translating a manifest generated under a different
+	 * `$MAILWOMAN_DATA_ROOT` than the one you are running with.
 	 */
 	legacyPathPrefix?: string
 }
@@ -164,7 +169,7 @@ export async function buildTranslitShard(
 ): Promise<void> {
 	const corpusVersion = options.corpusVersion ?? "0.4.0"
 	const canonicalPathPrefix = options.canonicalPathPrefix ?? "/data/"
-	const legacyPathPrefix = options.legacyPathPrefix ?? "/mnt/playpen/mailwoman-data/"
+	const legacyPathPrefix = options.legacyPathPrefix ?? `${mailwomanDataRoot()}/`
 
 	if (!existsSync(options.jsonl)) throw new Error(`jsonl not found: ${options.jsonl}`)
 
@@ -179,7 +184,7 @@ export async function buildTranslitShard(
 	const quarantine: string[] = []
 	let totalIn = 0
 
-	for await (const raw of iterateJSONL<Record<string, unknown>>(options.jsonl)) {
+	for await (const raw of JSONSpliterator.fromAsync<Record<string, unknown>>(options.jsonl)) {
 		totalIn++
 		const canon = toCanonicalRow(raw, corpusVersion)
 		const result = alignRow(canon)
@@ -222,7 +227,7 @@ export async function buildTranslitShard(
 	// Compose final MANIFEST: rewrite base.shards paths from /mnt/playpen/... → /data/... and append
 	// 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 base = parseJSONStrict<ShardManifest>(readFileSync(options.baseManifest, "utf8"))
 
 	const rewrittenBase = base.shards.map((sh) => ({
 		...sh,