@mailwoman/corpus 10.1.0 → 10.2.1

package/lib/tools/golden/promote.ts

@@ -31,7 +31,9 @@
  *   ```
  */
 
-import { pathExists } from "@mailwoman/core/fs/readers"
+import { layoutForCountry, layoutPrintsPostcodeBeforeLocality } from "@mailwoman/codex/address/layouts"
+import { matchCountry } from "@mailwoman/codex/country"
+import { pathExists } from "@mailwoman/core/fs/readers/stat"
 import { copyFileTo, makeDirectories, writeLocalJSONFile } from "@mailwoman/core/fs/writers"
 import { sha256File } from "@mailwoman/core/hash"
 import { stringifyJSON } from "@mailwoman/core/json"
@@ -78,13 +80,13 @@ export interface PromoteGoldenOptions {
 	/**
 	 * Previous version to forward-copy + dedup against.
 	 *
-	 * Default `v0.1.0`.
+	 * @defaultValue `v0.1.0`
 	 */
 	prior?: string
 	/**
 	 * Golden dir root.
 	 *
-	 * Default `data/eval/golden`.
+	 * @defaultValue `data/eval/golden`
 	 */
 	goldenRoot?: PathBuilderLike
 	/**
@@ -113,16 +115,18 @@ function isComponentsGlued(entry: GoldenEntry): boolean {
 }
 
 /**
- * Heuristic: in US/UK conventions, postcode goes at the END of the address.
+ * Heuristic: where the country's layout prints the postcode after the locality, a postcode in the
+ * first third of a multi-component raw with 4+ components means the LLM reordered the address.
  *
- * If postcode appears in the first third of a multi-component raw and there are 4+
- * components, the LLM probably over-aggressively reordered.
- * FR is exempt (postcode often precedes locality there).
+ * A country whose layout prints the postcode before the locality (FR, DE) is exempt,
+ * as is a country with no layout or a layout that prints one of the two.
  */
 function isPostcodeBadlyLeading(entry: GoldenEntry): boolean {
 	if (Object.keys(entry.components).length < MIN_PROMOTABLE_COMPONENTS) return false
 
-	if (entry.country === "FR" || entry.country === "France") return false
+	const layout = layoutForCountry(matchCountry(entry.country)?.iso2 ?? entry.country)
+
+	if (!layout || layoutPrintsPostcodeBeforeLocality(layout) !== false) return false
 	const postcode = entry.components.postcode
 
 	if (!postcode) return false

package/lib/tools/golden/relabel-street/directory.ts

@@ -5,7 +5,8 @@
  * @file Rewrites a golden-set directory and renders its review deck.
  */
 
-import { pathExists, readLocalBuffer, readLocalTextFile } from "@mailwoman/core/fs/readers"
+import { readLocalBuffer, readLocalTextFile } from "@mailwoman/core/fs/readers"
+import { pathExists } from "@mailwoman/core/fs/readers/stat"
 import {
 	makeDirectories,
 	writeLocalFile,
@@ -65,13 +66,13 @@ export interface RelabelGoldenOptions {
 	/**
 	 * Review-deck jsonl path.
 	 *
-	 * Default `<output>/review-deck.jsonl`.
+	 * @defaultValue `<output>/review-deck.jsonl`
 	 */
 	deck?: string
 	/**
 	 * Parent version label recorded in the manifest.
 	 *
-	 * Default: the input dir's basename.
+	 * @defaultValue the input dir's basename.
 	 */
 	parentLabel?: string
 	/**
@@ -81,13 +82,13 @@ export interface RelabelGoldenOptions {
 	/**
 	 * Passed through to {@linkcode relabelGoldenStreetRow}.
 	 *
-	 * Default true.
+	 * @defaultValue `true`
 	 */
 	splitPrefix?: boolean
 }
 
 /**
- * Aggregate outcome for a whole golden version.
+ * Aggregate result for a whole golden version.
  */
 export interface RelabelGoldenReport {
 	files: Record<
@@ -251,7 +252,7 @@ export async function relabelGoldenDirectory(
 		parent: options.parentLabel ?? basename(input),
 		generated_at: new Date().toISOString(),
 		tool: "corpus/src/tools/golden-relabel-street.ts (mailwoman corpus golden-relabel)",
-		...(options.commit ? { commit: options.commit } : {}),
+		commit: options.commit || null,
 		convention: {
 			street_convention: { US: "split", "*": "folded" },
 			declared:

package/lib/tools/golden/relabel-street/row.ts

@@ -29,7 +29,7 @@ export interface GoldenStreetRow {
 }
 
 /**
- * The relabel outcome class for one row.
+ * The relabel result class for one row.
  */
 export type GoldenRelabelClass =
 	| "split-suffix"
@@ -140,8 +140,9 @@ export interface RelabelStreetRowOptions {
 	/**
 	 * Whether to also move a leading directional into `street_prefix`.
 	 *
-	 * Defaults to `true`; without it `N Desmet Avenue` grades as `street: "N Desmet"`
-	 * against a model that emits a prefix.
+	 * Without it `N Desmet Avenue` grades as `street: "N Desmet"` against a model that emits a prefix.
+	 *
+	 * @defaultValue `true`
 	 */
 	splitPrefix?: boolean
 }
@@ -178,9 +179,9 @@ export function relabelGoldenStreetRow(
 	const flags: GoldenRelabelFlag[] = []
 	let rowClass: GoldenRelabelClass
 	let name = street
-	let suffix: string | undefined
+	let suffix: string | null = null
 	let suffixGap = ""
-	let canonical: USStreetSuffix | undefined
+	let canonical: USStreetSuffix | null = null
 
 	const split = splitLastWord(street)
 
@@ -215,7 +216,7 @@ export function relabelGoldenStreetRow(
 		}
 	}
 
-	let prefix: string | undefined
+	let prefix: string | null = null
 	let prefixGap = ""
 
 	if (splitPrefix && !row.components.street_prefix) {

package/lib/tools/ingest-csv.ts

@@ -30,7 +30,7 @@
  */
 
 import { ByteFormatter } from "@mailwoman/core/fs/formatters"
-import { tryStat, pathExists } from "@mailwoman/core/fs/readers"
+import { tryStat, pathExists } from "@mailwoman/core/fs/readers/stat"
 import { makeDirectories, writeLocalJSONFile } from "@mailwoman/core/fs/writers"
 import type { SQLInputValue } from "@mailwoman/sqlite/client"
 import type { Database } from "@mailwoman/sqlite/database-schema"
@@ -99,7 +99,7 @@ function inferColumnType(samples: (string | null)[]): ColumnInfo {
 	let textCount = 0
 
 	for (const s of samples) {
-		if (s === null) {
+		if (!s) {
 			nullCount++
 
 			continue
@@ -263,7 +263,7 @@ async function runIngest(opts: IngestOptions): Promise<void> {
 		const values = fields.map((f, i) => {
 			const v = normalizeField(f)
 
-			if (v === null) return null
+			if (!v) return null
 			const col = columns[i]
 
 			if (col?.type === "INTEGER" && /^-?\d+$/.test(v)) return Number.parseInt(v, 10)

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

@@ -55,7 +55,7 @@ export interface JSONLToParquetOptions {
 	/**
 	 * Parquet row-group size.
 	 *
-	 * Default 50000.
+	 * @defaultValue `50000`
 	 */
 	rowGroupSize?: number
 }

package/lib/tools/lint/recipe-output/vocab.ts

@@ -167,27 +167,32 @@ export interface LintRecipeVocabOptions {
 	recipeOutputPath: string
 	/**
 	 * Base corpus version.
-	 * Default `v0.5.0`.
+	 *
+	 * @defaultValue `v0.5.0`
 	 */
 	baseVersion?: string
 	/**
 	 * Base corpus root.
-	 * Default `$MAILWOMAN_DATA_ROOT/corpus/versioned`.
+	 *
+	 * @defaultValue `$MAILWOMAN_DATA_ROOT/corpus/versioned`
 	 */
 	baseRoot?: string
 	/**
 	 * Base-majority confidence floor for a contradiction.
-	 * Default 0.7.
+	 *
+	 * @defaultValue `0.7`
 	 */
 	threshold?: number
 	/**
 	 * Minimum base support to judge a token.
-	 * Default 50.
+	 *
+	 * @defaultValue `50`
 	 */
 	minCount?: number
 	/**
 	 * Fraction of base parts to scan, a proportional per-source sample below 1.0.
-	 * Default 1.0.
+	 *
+	 * @defaultValue `1.0`
 	 */
 	fraction?: number
 }

package/lib/tools/lint/recipe-output.ts

@@ -73,7 +73,7 @@ export interface LintRecipeOutputOptions {
 	/**
 	 * Anti-pattern rules JSON.
 	 *
-	 * Default: the `lint-rules.json` beside this module.
+	 * @defaultValue the `lint-rules.json` beside this module.
 	 */
 	rulesPath?: string
 	/**
@@ -173,16 +173,26 @@ function majorityLabel(distribution: Map<string, number> | Record<string, number
 export interface LintFlag {
 	check: string
 	severity: "error" | "warn"
-	token?: string
-	bigram?: string
-	outputLabel?: string
-	corpusLabel?: string
-	outputCount?: number
-	corpusCount?: number
+	token: string | null
+	bigram: string | null
+	outputLabel: string | null
+	corpusLabel: string | null
+	outputCount: number | null
+	corpusCount: number | null
 	detail: string
-	ruleID?: string
+	ruleID: string | null
 }
 
+const EMPTY_FLAG_FIELDS = {
+	token: null,
+	bigram: null,
+	outputLabel: null,
+	corpusLabel: null,
+	outputCount: null,
+	corpusCount: null,
+	ruleID: null,
+} as const satisfies Partial<LintFlag>
+
 /**
  * Findings summary returned by {@linkcode lintRecipeOutput}.
  */
@@ -213,6 +223,7 @@ function checkDistributionOutliers(output: RecipeOutputStats, corpus: CorpusStat
 			corpusMaj.total >= CORPUS_MIN_COUNT
 		) {
 			flags.push({
+				...EMPTY_FLAG_FIELDS,
 				check: "distribution-outlier",
 				severity: "error",
 				token,
@@ -244,6 +255,7 @@ function checkLabelVacuum(output: RecipeOutputStats, corpus: CorpusStats): LintF
 
 			if (corpusLabelMap[label] === undefined || corpusLabelMap[label] === 0) {
 				flags.push({
+					...EMPTY_FLAG_FIELDS,
 					check: "label-vacuum",
 					severity: "error",
 					token,
@@ -279,6 +291,7 @@ function checkBigramCollisions(output: RecipeOutputStats, corpus: CorpusStats):
 			const renderCorpusLabel = corpusMaj.label.split(SEP).join(" → ")
 
 			flags.push({
+				...EMPTY_FLAG_FIELDS,
 				check: "bigram-collision",
 				severity: "error",
 				bigram: renderBigram,
@@ -309,6 +322,7 @@ function checkRules(output: RecipeOutputStats, rulesFile: LintRulesFile): LintFl
 			for (const [label, count] of labelMap) {
 				if (rule.forbidden_labels.includes(label) && count >= FORBIDDEN_LABEL_REPORT_THRESHOLD) {
 					flags.push({
+						...EMPTY_FLAG_FIELDS,
 						check: "anti-pattern-rule",
 						severity: rule.severity,
 						ruleID: rule.id,
@@ -330,6 +344,7 @@ function checkSanity(output: RecipeOutputStats): LintFlag[] {
 
 	if (output.truncatedRows > 0) {
 		flags.push({
+			...EMPTY_FLAG_FIELDS,
 			check: "truncated-rows",
 			severity: "error",
 			detail: `${output.truncatedRows} row(s) have tokens.length !== labels.length. Pipeline alignment bug.`,
@@ -340,6 +355,7 @@ function checkSanity(output: RecipeOutputStats): LintFlag[] {
 
 	if (allORatio >= ALL_O_RATIO_CEILING) {
 		flags.push({
+			...EMPTY_FLAG_FIELDS,
 			check: "all-O-output",
 			severity: "warn",
 			detail: `${output.allORows}/${output.rowCount} rows (${(allORatio * 100).toFixed(0)}%) are entirely O-labeled. The recipe output contributes no signal.`,
@@ -349,6 +365,8 @@ function checkSanity(output: RecipeOutputStats): LintFlag[] {
 	return flags
 }
 
+// repo-health-ignore private-name-shadows-export -- renders a recipe-lint report.
+// The dossier export renders a building dossier, an unrelated document.
 function renderReport(
 	opts: { outputPath: string; statsPath: string; rulesPath: string },
 	output: RecipeOutputStats,

package/lib/tools/overlay/kryptonite.ts

@@ -17,7 +17,8 @@
  */
 
 import { delimitedSource } from "@mailwoman/core/fs/delimited"
-import { pathExists, readLocalJSONFile } from "@mailwoman/core/fs/readers"
+import { readLocalJSONFile } from "@mailwoman/core/fs/readers"
+import { pathExists } from "@mailwoman/core/fs/readers/stat"
 import { writeLocalJSONFile, writeLocalTextFile, makeDirectories } from "@mailwoman/core/fs/writers"
 import { PathBuilder, type PathBuilderLike } from "path-ts"
 import { JSONSpliterator } from "spliterator"
@@ -33,11 +34,11 @@ export interface KryptoniteOverlayOptions {
 	baseManifest: string
 	outDir: PathBuilderLike
 	/**
-	 * Default `"0.4.0"`.
+	 * @defaultValue `"0.4.0"`
 	 */
 	corpusVersion?: string
 	/**
-	 * Default `"deepseek-kryptonite"`.
+	 * @defaultValue `"deepseek-kryptonite"`
 	 */
 	source?: string
 }

package/lib/tools/overlay/manifest.ts

@@ -7,7 +7,8 @@
  */
 
 import { dataRootPath } from "@mailwoman/core/data-root"
-import { readLocalBuffer, readLocalJSONFile, statPath } from "@mailwoman/core/fs/readers"
+import { readLocalBuffer, readLocalJSONFile } from "@mailwoman/core/fs/readers"
+import { statPath } from "@mailwoman/core/fs/readers/stat"
 import { writeLocalJSONFile } from "@mailwoman/core/fs/writers"
 import { sha256Hex } from "@mailwoman/core/hash"
 import { stringifyJSON } from "@mailwoman/core/json"
@@ -91,10 +92,11 @@ export interface OverlayFile {
 	source: string
 	/**
 	 * The split that the file's rows belong to.
-	 * The default is `train`.
 	 *
 	 * `val` and `test` are allowed only for files that `splitOverlaySlice` returned,
 	 * so that the holdout policy chooses held-out rows.
+	 *
+	 * @defaultValue `train`
 	 */
 	split?: SplitName
 }

package/lib/tools/overlay/merge-source.ts

@@ -32,7 +32,8 @@ export interface MergeSourceOptions {
 	output: PathBuilderLike
 	/**
 	 * The number of rows held in memory while shuffling.
-	 * It defaults to the corpus writer's window.
+	 *
+	 * @defaultValue the corpus writer's window.
 	 */
 	windowSize?: number
 	/**

package/lib/tools/overlay/split-slice.ts

@@ -63,7 +63,7 @@ export function holdoutComponents(row: SpannedRow, index: number, input: string)
 	const components: Record<string, string> = {}
 
 	for (const [span, tag] of tags.entries()) {
-		if (!HOLDOUT_TAGS.has(tag) || components[tag] !== undefined) continue
+		if (!HOLDOUT_TAGS.has(tag) || components[tag]) continue
 
 		components[tag] = raw.slice(starts[span]!, ends[span]!)
 	}
@@ -83,7 +83,7 @@ export interface SplitSliceOptions {
 	 */
 	outputDir: PathBuilderLike
 	/**
-	 * Defaults to `defaultHoldouts()`, which is the policy the base build applies.
+	 * @defaultValue `defaultHoldouts()`, which is the policy the base build applies.
 	 */
 	holdouts?: Record<string, CountryHoldout>
 }

package/lib/tools/overlay/translit.ts

@@ -30,7 +30,8 @@
 
 import { dataRootPath } from "@mailwoman/core/data-root"
 import { delimitedSource } from "@mailwoman/core/fs/delimited"
-import { pathExists, readLocalJSONFile, tryStat } from "@mailwoman/core/fs/readers"
+import { readLocalJSONFile } from "@mailwoman/core/fs/readers"
+import { pathExists, tryStat } from "@mailwoman/core/fs/readers/stat"
 import { writeLocalJSONFile, writeLocalTextFile, makeDirectories } from "@mailwoman/core/fs/writers"
 import { sha256File } from "@mailwoman/core/hash"
 import { PathBuilder, type PathBuilderLike } from "path-ts"
@@ -48,20 +49,21 @@ export interface TranslitOverlayOptions {
 	baseManifest: string
 	outDir: PathBuilderLike
 	/**
-	 * Default `"0.4.0"`.
+	 * @defaultValue `"0.4.0"`
 	 */
 	corpusVersion?: string
 	/**
-	 * Default `"/data/"`.
+	 * @defaultValue `"/data/"`
 	 */
 	canonicalPathPrefix?: string
 	/**
 	 * Prefix currently used in the base manifest's file paths, to be rewritten
 	 * to {@link TranslitOverlayOptions.canonicalPathPrefix}.
 	 *
-	 * Defaults to `dataRootPath()` 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.
+	 *
+	 * @defaultValue `dataRootPath()` with a trailing slash — the root that wrote those paths.
 	 */
 	legacyPathPrefix?: string
 }

package/lib/tools/overture-subvenue.ts

@@ -13,7 +13,7 @@
 import { DatabaseClient } from "@mailwoman/sqlite/client"
 import type { PathBuilderLike } from "path-ts"
 
-import type { SubVenueHarvestRow } from "#tools/sub/venue/lexicon"
+import type { SubVenueHarvestRow } from "#subvenue/harvest"
 
 /**
  * Overture categories selected for sub-venue designator evidence.

package/lib/tools/postcode-triples.ts

@@ -11,7 +11,7 @@
 import { officialLanguagesAlpha3, regionLanguagesAlpha3 } from "@mailwoman/codex/country"
 import { foldName } from "@mailwoman/codex/normalize"
 import { dataRootPath } from "@mailwoman/core/data-root"
-import { assertPathExists } from "@mailwoman/core/fs/readers"
+import { assertPathExists } from "@mailwoman/core/fs/readers/stat"
 import { wofDatabasePath } from "@mailwoman/resolver-wof-sqlite/paths"
 import type { WOFDatabase } from "@mailwoman/resolver-wof-sqlite/schema"
 import { DatabaseClient } from "@mailwoman/sqlite/client"
@@ -32,7 +32,7 @@ export interface PostcodeTriple {
 	 *
 	 * A recipe output whose every row begins with the locality teaches that the first segment is the locality.
 	 */
-	dependentLocality?: string
+	dependentLocality: string | null
 	locality: string
 	region: string
 	country: string
@@ -288,6 +288,7 @@ export async function readTriplesFromParentJoin(
 			for (const region of surfaces.region(cc, row.region_id, row.region)) {
 				out.push({
 					postcode: row.postcode,
+					dependentLocality: null,
 					locality,
 					region,
 					country: row.country ?? "",
@@ -429,7 +430,7 @@ export async function readPairsFromAdmin(
 				// The recipe drops that pair, so filtering it here keeps the country budget for rows that remain.
 				if (region === locality) continue
 
-				out.push({ locality, region, country: row.country ?? "", cc, locale })
+				out.push({ dependentLocality: null, locality, region, country: row.country ?? "", cc, locale })
 			}
 		}
 	}
@@ -534,7 +535,7 @@ export async function readTriplesFromGeonames(
 
 		out.push({
 			postcode,
-			...(dep ? { dependentLocality: dep } : {}),
+			dependentLocality: dep || null,
 			locality,
 			region,
 			country: countryName,

package/lib/tools/source-register/build.ts

@@ -8,7 +8,8 @@
  * The second input is mostly not input: the eight global discovery lookups repeat once per jurisdiction and are dropped, because they name a lookup rather than a national source.
  */
 
-import { pathExists, readLocalJSONFile } from "@mailwoman/core/fs/readers"
+import { readLocalJSONFile } from "@mailwoman/core/fs/readers"
+import { pathExists } from "@mailwoman/core/fs/readers/stat"
 import { writeLocalFile } from "@mailwoman/core/fs/writers"
 import { prettyJSON, stringifyJSON } from "@mailwoman/core/json"
 import type { PathBuilderLike } from "path-ts"
@@ -262,7 +263,7 @@ export interface BuildSourceRegisterOptions {
 	sourceVersion?: string
 }
 
-function required(value: string | undefined, field: string, row: number): string {
+function required(value: string | null | undefined, field: string, row: number): string {
 	const trimmed = (value ?? "").trim()
 
 	if (!trimmed) throw new Error(`row ${row}: ${field} is empty, and the register has nowhere to put an unnamed value`)
@@ -543,17 +544,17 @@ async function readSources(
 const UNRESOLVED_COLUMN_PLACEHOLDERS: ReadonlySet<string> = new Set(["varies", "country-specific", "unknown", "n/a"])
 
 /**
- * A column's value, or `undefined` when the research pass left it unresolved.
+ * A column's value, or `null` when the research pass left it unresolved.
  *
  * Every value outside the placeholder set is returned, so a value somebody fills in
  * later reaches the register or fails the build rather than being lost.
  */
-export function readUnresolvedColumn(value: string | undefined, column: string, row: number): string | undefined {
+export function readUnresolvedColumn(value: string | null | undefined, column: string, row: number): string | null {
 	const trimmed = (value ?? "").trim()
 
-	if (!trimmed) return undefined
+	if (!trimmed) return null
 
-	if (UNRESOLVED_COLUMN_PLACEHOLDERS.has(trimmed.toLowerCase())) return undefined
+	if (UNRESOLVED_COLUMN_PLACEHOLDERS.has(trimmed.toLowerCase())) return null
 
 	if (column === "address_role" && !ADDRESS_ROLE_BY_NAME[trimmed.toLowerCase()]) {
 		throw new Error(
@@ -590,8 +591,8 @@ type RecordedDecision = Omit<ElectedLicense, "licenseID"> | Omit<RefusedLicense,
  * One publisher can hold a license over several jurisdictions, and the register
  * scopes a decision to one publisher in one jurisdiction, so reading that publisher's
  * terms once produces several decisions with the same body.
- * Naming the shared body keeps each license id's own decision while the prose behind
- * it has one home, so nine copies cannot drift apart under later editing.
+ * A shared body keeps each license id's own decision while the prose behind it has one home.
+ * Nine copies cannot drift apart under later editing.
  */
 interface SharedDecisionReference {
 	sameAs: string
@@ -613,7 +614,8 @@ function isSharedReference(value: RecordedDecision | SharedDecisionReference): v
 }
 
 /**
- * The source fields a review resolves, which the research CSV records as placeholders.
+ * The source fields a review resolves.
+ * The research CSV records placeholders for them.
  *
  * The CSV holds the research pass's findings and is a working document of that pass,
  * so a later review records its own findings here rather than by editing the pass's record.
@@ -652,7 +654,8 @@ async function readSourceResolutions(
  *
  * @throws When a resolution's source id is absent from the register.
  * Such an entry is a typo or a source that has been removed.
- * Keeping it silently would leave a review whose fields reach no row, which reads as work already done.
+ * An entry kept silently would leave a review whose fields reach no row.
+ * That reads as work already done.
  */
 export function applySourceResolutions(
 	sources: readonly AddressSourceRecord[],
@@ -683,7 +686,7 @@ export function applySourceResolutions(
  * because reading it as empty would silently drop somebody's recorded work.
  * This function validates no decision it reads, because `auditAddressSourceRegister` already does.
  */
-async function readLicenseDecisions(decisionsPath: PathBuilderLike | undefined): Promise<Map<string, LicenseDecision>> {
+async function readLicenseDecisions(decisionsPath: PathBuilderLike | null): Promise<Map<string, LicenseDecision>> {
 	if (!decisionsPath || !(await pathExists(decisionsPath))) return new Map()
 
 	return resolveRecordedDecisions(await readLocalJSONFile<LicenseDecisionsFile>(decisionsPath))
@@ -697,8 +700,8 @@ async function readLicenseDecisions(decisionsPath: PathBuilderLike | undefined):
  * function checks only that the file declares a reading for each reference.
  *
  * @throws When a `sameAs` reads a reading absent from `sharedReadings`.
- * Such a reference would otherwise produce a decision carrying no terms, which the audit
- * would report as an unknown review state rather than as the typo it is.
+ * Such a reference would otherwise produce a decision holding no terms.
+ * The audit would report that as an unknown review state rather than as the typo it is.
  */
 export function resolveRecordedDecisions(file: LicenseDecisionsFile): Map<string, LicenseDecision> {
 	const shared = file.sharedReadings ?? {}
@@ -764,7 +767,7 @@ export async function buildSourceRegister(options: BuildSourceRegisterOptions):
 		})
 		.toSorted((left, right) => left.licenseID.localeCompare(right.licenseID))
 
-	const licenses = applyLicenseDecisions(generated, await readLicenseDecisions(options.decisionsPath))
+	const licenses = applyLicenseDecisions(generated, await readLicenseDecisions(options.decisionsPath ?? null))
 
 	const register: AddressSourceRegister = {
 		registerID: "address-source-register",

package/lib/tools/sub/venue/lexicon.ts

@@ -6,7 +6,8 @@
  *   @file Builds the sub-venue designator lexicon from Wikidata, OSM and Overture fetch outputs.
  */
 
-import { readLocalJSONFile, statPath } from "@mailwoman/core/fs/readers"
+import { readLocalJSONFile } from "@mailwoman/core/fs/readers"
+import { statPath } from "@mailwoman/core/fs/readers/stat"
 import { writeLocalFile } from "@mailwoman/core/fs/writers"
 import { prettyJSON } from "@mailwoman/core/json"
 import { isoDate } from "@mailwoman/core/utils"
@@ -32,12 +33,6 @@ import {
 import { deriveHeadNounSurfaces } from "#tools/sub/venue/head-nouns"
 import { surfacesFromWikidata } from "#tools/sub/venue/wikidata"
 
-export * from "#subvenue/harvest"
-export * from "#tools/sub/venue/head-nouns"
-export * from "#subvenue/surfaces"
-export * from "#subvenue/table"
-export * from "#tools/sub/venue/wikidata"
-
 /**
  * Returns a copy of the surfaces with `curated: true` set on each surface that a promotion matches.
  *
@@ -115,9 +110,10 @@ export interface BuildSubVenueLexiconInput {
 	 */
 	sources: readonly SubVenueLexiconSource[]
 	/**
-	 * Defaults to {@link SUBVENUE_PROMOTIONS}.
 	 *
 	 * An empty array builds the uncurated table.
+	 *
+	 * @defaultValue {@linkcode SUBVENUE_PROMOTIONS}
 	 */
 	promotions?: readonly SubVenuePromotion[]
 }

package/lib/tw/tools/fetch/gcis.ts

@@ -25,7 +25,7 @@
  */
 
 import { BYTES_PER_KIB } from "@mailwoman/core/fs/formatters"
-import { pathExists } from "@mailwoman/core/fs/readers"
+import { pathExists } from "@mailwoman/core/fs/readers/stat"
 import { makeDirectories } from "@mailwoman/core/fs/writers"
 import { sha256File } from "@mailwoman/core/hash"
 import { sleep } from "@mailwoman/core/utils/sleep"
@@ -84,14 +84,14 @@ async function listBulkDatasets(): Promise<Dataset[]> {
 /**
  * The `/od/file?oid=…` link a dataset's detail page hands its download dialog.
  */
-async function fileURLFor(dataset: Dataset): Promise<string | undefined> {
+async function fileURLFor(dataset: Dataset): Promise<string | null> {
 	const res = await fetch(`${PORTAL}${dataset.detailPath}`, { headers: { accept: "text/html" } })
 
-	if (!res.ok) return undefined
+	if (!res.ok) return null
 	const html = await res.text()
 	const path = /showDialog\('(\/od\/file\?oid=[^']+)'\)/.exec(html)?.[1]
 
-	return path ? `${PORTAL}${path}` : undefined
+	return path ? `${PORTAL}${path}` : null
 }
 
 export async function fetchGCISTW(options: FetchGCISTWOptions, report?: (line: string) => void): Promise<FetchSummary> {