@mailwoman/corpus 10.3.0 → 10.4.0

package/lib/parquet/span-sql.ts

@@ -7,7 +7,7 @@
  *   A parquet row stores component offsets in `span_starts` and `span_ends` arrays.
  *   A third array, `span_tags`, identifies each component. The text comes from slicing `raw` at those offsets.
  *   A query that groups or filters by a
- *   component performs that slice in SQL instead of decoding every row in the process.
+ *   component takes that substring in SQL instead of decoding every row in the process.
  *
  *   `holdoutComponents` in `#tools/overlay/split-slice` performs the same read in JavaScript.
  *   The SQL and JavaScript operations use different string indexing. The difference is described below.
@@ -24,8 +24,8 @@
  * `alignRow` records a span in UTF-16 code units.
  *
  * DuckDB's `substr` counts characters.
- * The two agree for the Basic Multilingual Plane and diverge by one unit per astral character,
- * so a row carrying one slices late by the number of astral characters before the span.
+ * The two agree for the Basic Multilingual Plane and diverge by one unit per astral character, so in a
+ * row that contains one, the substring starts late by the number of astral characters before the span.
  *
  * In the first 40 train files of `v0.6.0-register-surface`, 6,982 of 40,000,000
  * rows (0.0175%) contain an astral character.
@@ -34,15 +34,17 @@
  * `𐍀𐍂𐍉𐍆𐌹𐌳𐌰𐌹𐌽𐍃, RHODE ISLAND` read its region as `ND`, taken from `ISLAND`.
  *
  * So this is sound for an aggregate over millions of rows and unsound for a decision about one row.
- * A caller that acts per row narrows with this and confirms with `holdoutComponents`, which
- * slices with JavaScript string semantics and therefore reads the offsets as they were written.
+ * A caller that acts per row narrows with this and confirms with `holdoutComponents`.
+ *
+ * That function indexes with JavaScript string semantics and therefore reads
+ * the offsets as they were written.
  */
 export function componentAtSpanSQL(tag: string, rawColumn = "raw"): string {
 	return componentAtIndexSQL(`list_position(span_tags, '${tag}')`, rawColumn)
 }
 
 /**
- * The same slice against a span index the caller already computed.
+ * The same substring against a span index the caller already computed.
  *
  * A query can hoist `list_position(span_tags, …)` into a subquery column and read it by name.
  * A second evaluation in the projection would run the search twice per row.

package/lib/parquet/streams.ts

@@ -63,7 +63,7 @@ export interface ParquetRowStreamOptions {
 	 */
 	columns?: readonly string[]
 	/**
-	 * Stop after this many rows.
+	 * Stop after this number of rows.
 	 */
 	limit?: number
 }

package/lib/parquet/writers.ts

@@ -5,7 +5,7 @@
  * @file Writes Parquet files and the manifest that describes their contents.
  *
  *   This module exposes two writers. {@linkcode writeParquetFile} writes one file from rows already in memory.
- *   {@linkcode writeParquetSplits} streams per-split row iterables into as many files as the row cap requires. It
+ *   {@linkcode writeParquetSplits} streams per-split row iterables into the number of files the row cap requires. It
  *   returns the manifest. Both writers create their parent directory, as `@mailwoman/core/fs` writers do
  *   encode rather than repeat at each call site.
  *
@@ -212,7 +212,7 @@ export interface WriteParquetSplitsOptions {
 	 * A descriptor is appended only after its `.parquet` file closes, so each recorded file is complete.
 	 *
 	 * A resumed run rereads each descriptor's size.
-	 * It discards that many rows from the front of each split's iterable and opens the next file index.
+	 * It discards that number of rows from the front of each split's iterable and opens the next file index.
 	 *
 	 * The caller therefore has to supply the same iterables in the same order.
 	 * For `buildCorpus` that means the same labeled files and the same shuffle seed.

package/lib/pl/tools/fetch/emuia.ts

@@ -155,7 +155,7 @@ export interface HarvestEMUiAOptions {
 	 */
 	pageSize?: number
 	/**
-	 * Stop once the manifest holds this many pages, for a probe rather than a full harvest.
+	 * Stop once the manifest holds this number of pages, for a probe rather than a full harvest.
 	 */
 	maxPages?: number
 	/**
@@ -165,7 +165,7 @@ export interface HarvestEMUiAOptions {
 	 * The measurement costs about 2·log2(n) requests — 51 for a register of this size — and the
 	 * harvest does not need it: paging to the first empty page reads the type whole either way.
 	 *
-	 * It buys a denominator for the progress lines and a figure for the manifest,
+	 * It supplies a denominator for the progress lines and a figure for the manifest,
 	 * and it rests on the monotone-presence assumption this module's header states.
 	 */
 	measureCount?: boolean

package/lib/recipes/scaffold.ts

@@ -170,7 +170,7 @@ export interface OATupleFields {
 
 export interface ReadOATuplesOptions<T> {
 	/**
-	 * Stop after this many distinct tuples.
+	 * Stop after this number of distinct tuples.
 	 *
 	 * The `break` closes the reader and releases the archive.
 	 * GB-scale countrywide extracts need this behavior.
@@ -496,7 +496,7 @@ export interface RecipeOptions {
 	 */
 	venueNames?: PathBuilderLike
 	/**
-	 * `venue`: share of locality rows that also carry the tuple's region after the locality.
+	 * `venue`: share of locality rows that also print the tuple's region after the locality.
 	 *
 	 * @defaultValue `0.5`
 	 */

package/lib/recipes/sources.ts

@@ -285,7 +285,7 @@ export const CARRIED_SOURCES: ReadonlyArray<string> = [
 	"osm-bd",
 	// One id per French overseas jurisdiction for the BAN department files,
 	// written by `corpus run ban --source-name`.
-	// Metropolitan rows keep `ban`, so its weight does not decide how often a territory is drawn.
+	// Metropolitan rows keep `ban`, so its weight does not decide the rate at which a territory is drawn.
 	"ban-gp",
 	"ban-mq",
 	"ban-gf",
@@ -371,7 +371,7 @@ export function defaultRecipeSource(retired: string): string {
  *
  * Its `source-names.json` records the mapping applied per file with the row count
  * and the ordered-`source_id` digest verified on both sides.
- * `v0.7.0-de-holdout/corpus-v0.7.0-de-holdout` is assembled from those bytes over 766 slices.
+ * `v0.7.0-de-holdout/corpus-v0.7.0-de-holdout` is assembled from those bytes over 766 recipe-output files.
  *
  * A recipe writing the retired spelling from here on would produce an output
  * disagreeing with the corpus it joins.
@@ -391,7 +391,7 @@ export const WRITE_CURRENT_SOURCE_NAMES = true
  * throw on every row in the corpus.
  *
  * Callers of those two tables resolve the key through this, so a lookup answers under
- * either spelling and a genuinely unknown source still refuses.
+ * either spelling and a source unknown under both spellings still refuses.
  *
  * The value is returned unchanged for a source outside the table — an adapter id,
  * or an overlay source id — because those tables are keyed by whatever the producer emits.

package/lib/recipes/sub/venue/render.ts

@@ -31,7 +31,7 @@ export type Group = Piece[]
 /**
  * The case and punctuation style of a rendered row.
  *
- * Users often type addresses in lowercase, so every recipe output includes lowercase rows.
+ * Some users type addresses in lowercase, so every recipe output includes lowercase rows.
  */
 export const Register = {
 	Canonical: "canonical",

package/lib/recipes/sub/venue/sources.ts

@@ -330,7 +330,7 @@ const MIN_OWN_SHAPE_OBSERVATIONS = 20
 /**
  * Builds a region's identifier model from the lexicon's `identifierShapes`.
  *
- * The pooled fallback combines the gate, terminal and campus distributions.
+ * The pooled fallback combines the airport gate, terminal and campus distributions.
  */
 export function buildIdentifierModel(lexicon: SubVenueLexiconTable, region: string): IdentifierModel {
 	const byDesignator = new Map<string, ShapeBucket[]>()
@@ -515,8 +515,9 @@ const POI_CONFOUND_CATEGORIES: readonly string[] = [
 ]
 
 /**
- * Reads the venue and confound name pools for one country from the Overture place-names file,
- * which holds `name`, `category` and `country` for every country the release covers.
+ * Reads the venue and confound name pools for one country from the Overture place-names file.
+ *
+ * That file holds `name`, `category` and `country` for every country the release covers.
  *
  * The venue categories fill the `venues` pool.
  * Every row of a venue or confound category is tested against the rejected phrases

package/lib/recipes/sub/venue.ts

@@ -52,7 +52,8 @@ export interface SubVenueLeg {
 	/**
 	 * The ISO 3166-1 alpha-2 key into the lexicon's `identifierShapes`.
 	 *
-	 * Gate and terminal numbering differs by country, so each leg samples identifiers from its own region.
+	 * Airport gate and terminal numbering differs by country, so each leg samples
+	 * identifiers from its own region.
 	 */
 	region: string
 	/**
@@ -142,7 +143,7 @@ export const SUBVENUE_LEGS: readonly SubVenueLeg[] = [
  * The region whose identifier distribution the en-US leg uses.
  *
  * The en-US leg has no OSM extract.
- * The Overture names file carries venue names without refs.
+ * The Overture names file holds venue names without refs.
  * The recipe borrows the identifier distribution from GB.
  */
 export const US_IDENTIFIER_REGION_BORROWED_FROM = "GB"
@@ -514,7 +515,7 @@ function emitPositives(
 		const subGroup: Group = [{ text: form.text, tag: "unit" }]
 		const venueGroup: Group = [{ text: venue, tag: "venue" }]
 		const r = random()
-		// Some rows omit the street because venue addresses such as airport terminals often lack one.
+		// Some rows omit the street because venue addresses such as airport terminals can lack one.
 		const body = addressGroups(leg.country, tuple, r >= NO_STREET_SHARE)
 
 		// An empty body means that no address layout covers this country.

package/lib/recipes/venue.ts

@@ -5,11 +5,11 @@
  *
  *   `venue` recipe. A real venue name written as the whole query, and the same name followed by a
  *   locality drawn from the country's admin tuples. The rows teach the model that
- *   `Manchester Art Gallery` is a venue rather than a locality and a region, which the venue-head
- *   prior in `@mailwoman/neural` also asserts, so the model and the prior agree.
+ *   `Manchester Art Gallery` is a venue rather than a locality and a region. The venue-head
+ *   prior in `@mailwoman/neural` asserts the same reading, so the model and the prior agree.
  *
  *   Venue names come from the Overture place-names Parquet file the venue-head table is built
- *   from, which holds `name`, `category` and `country` for every place at confidence 0.85 or
+ *   from. That file holds `name`, `category` and `country` for every place at confidence 0.85 or
  *   higher. The file has no locality column, so the locality row joins a name to a tuple of the
  *   same country and asserts no fact about where the venue stands, so its surface is
  *   `SurfaceOrigin.Composed`. The bare row is the publisher's own string, so its surface is
@@ -25,7 +25,8 @@
 
 import { dataRootPath } from "@mailwoman/core/data-root"
 import { mulberry32 as makeMulberry32 } from "@mailwoman/core/utils"
-import { venueHeadLexicon } from "@mailwoman/poi-taxonomy/venue-heads"
+import { foldCaseWhitespace } from "@mailwoman/normalize/fold"
+import { isSpacelessScriptWord, venueHeadLexicon } from "@mailwoman/poi-taxonomy/venue-heads"
 import type { PathBuilderLike } from "path-ts"
 
 import { normalizeGauntletSurface, readGauntletInputs } from "#gauntlet-inputs"
@@ -59,7 +60,7 @@ export const DEFAULT_VENUE_NAMES: PathBuilderLike = dataRootPath(
 export const DEFAULT_NAMES_PER_COUNTRY = 20_000
 
 /**
- * Share of locality rows that also carry the region when `--venue-region-fraction` is absent.
+ * Share of locality rows that also print the region when `--venue-region-fraction` is absent.
  */
 export const DEFAULT_REGION_FRACTION = 0.5
 
@@ -105,13 +106,12 @@ export interface VenueHeadSuffixLookup {
 	suffix(word: string): number | null
 }
 
-const SPACELESS_SCRIPT_RE = /^[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}\p{Script=Thai}]+$/u
-
 /**
  * Characters a spaceless-script name needs before it is written as a bare query.
  *
- * A two-character name such as `東京` is the length of a city name, and the head the table recognizes is
- * the name's last character, so a name shorter than this is a head with one character of stem.
+ * A two-character name such as `東京` is the length of a city name.
+ * The head the table recognizes is the name's last character, so a name shorter
+ * than this is a head with one character of stem.
  */
 export const MIN_SPACELESS_BARE_CHARACTERS = 3
 
@@ -135,7 +135,7 @@ export function isBareVenueName(name: string, heads?: VenueHeadSuffixLookup): bo
 	return (
 		Boolean(heads) &&
 		[...word].length >= MIN_SPACELESS_BARE_CHARACTERS &&
-		SPACELESS_SCRIPT_RE.test(word) &&
+		isSpacelessScriptWord(word) &&
 		heads!.suffix(word) !== null
 	)
 }
@@ -144,7 +144,7 @@ export function isBareVenueName(name: string, heads?: VenueHeadSuffixLookup): bo
  * The comparison key for a name against the country's localities.
  */
 export function venueNameKey(name: string): string {
-	return name.normalize("NFC").trim().toLowerCase().replaceAll(/\s+/gu, " ")
+	return foldCaseWhitespace(name.normalize("NFC"))
 }
 
 /**

package/lib/ro/adapters/retea-scolara/adapter.ts

@@ -16,7 +16,7 @@
  * The sheet splits the address into `Strada`, `Numar`, `Cod postal` and `Localitate unitate`, so the
  * adapter splits no street line. Measured over the 2025–2026 edition's 18,022 units:
  *
- * - `Strada` is the street name as the school writes it, usually without the street-type word:
+ * - `Strada` is the street name as the school writes it, in most rows without the street-type word:
  *   `REPUBLICII`, `PRINCIPALA`, `Piața 1848`. 198 values begin with `STR.` and 247 with `CALEA`.
  *   The value is copied unchanged, because a street type the publisher did not write is not evidence.
  * - `Numar` holds the house number. `FN` (`fără număr`, "without number") and `-` state that the premise
@@ -36,7 +36,7 @@
  *
  * ## Identity and license
  *
- * The row id is content-addressed over the aligned components. A school and its kindergarten often share
+ * The row id is content-addressed over the aligned components. A school and its kindergarten can share
  * one address under two names, so they are two rows.
  *
  * data.gov.ro publishes the dataset under `CC-BY-4.0`, the license its CKAN record names for the

package/lib/runner.ts

@@ -47,9 +47,9 @@ export interface RunnerProgress {
 export const DEFAULT_DEDUP_SLOTS_LOG2 = 27
 
 /**
- * How many distinct dedup keys a `Set`-backed run holds before it stops adding new ones.
+ * The number of distinct dedup keys a `Set`-backed run holds before it stops adding new ones.
  *
- * A V8 `Set` refuses a 16,777,216th entry outright, so this cap was a real bound rather than a preference.
+ * A V8 `Set` throws on a 16,777,216th entry, so this cap was a real bound rather than a preference.
  * It applies only to a run that opts out of the fingerprint table
  * through {@linkcode RunAdapterOptions.dedupMaxSize}.
  */
@@ -78,7 +78,7 @@ export interface RunAdapterOptions {
 	adapterOptions: AdapterOptions
 
 	/**
-	 * Hold dedup keys in a V8 `Set` capped at this many, rather than in a fingerprint table.
+	 * Hold dedup keys in a V8 `Set` capped at this number of keys, rather than in a fingerprint table.
 	 *
 	 * The cap is what the fingerprint table replaces.
 	 * A run that sets this reproduces the pre-2026-09-28 behavior.

package/lib/sk/tools/fetch/inspire.ts

@@ -237,7 +237,7 @@ export interface HarvestSKInspireTypeOptions {
 	 */
 	pageSize?: number
 	/**
-	 * Stop once the manifest holds this many pages, for a probe rather than a full harvest.
+	 * Stop once the manifest holds this number of pages, for a probe rather than a full harvest.
 	 */
 	maxPages?: number
 	signal?: AbortSignal
@@ -314,7 +314,7 @@ export interface FetchSKInspireOptions extends BaseFetchOptions {
 	 */
 	pageSize?: number
 	/**
-	 * Stop each type once its manifest holds this many pages, for a probe rather than a full harvest.
+	 * Stop each type once its manifest holds this number of pages, for a probe rather than a full harvest.
 	 */
 	maxPages?: number
 	signal?: AbortSignal
@@ -339,7 +339,7 @@ export function skInspireInputPath(outRoot: BaseFetchOptions["outRoot"]): PathBu
  * for `mailwoman corpus fetch sk-inspire`.
  *
  * Each type is reported separately and a type that fails does not stop the rest, because the
- * documents are read together by the adapter and a partial directory is still worth resuming.
+ * documents are read together by the adapter and a resumed run completes a partial directory.
  * Re-runnable per type: a complete harvest whose file still hashes to its manifest's digest
  * makes no request, and an interrupted one resumes at the page after the last that reached disk.
  */

package/lib/source-register/effective-manifest.ts

@@ -278,7 +278,7 @@ export interface EffectiveTrainingManifest {
 	 * Sources the epoch emitted that the corpus's frozen manifest does not name, with their emitted rows.
 	 *
 	 * `freezeTrainingManifest` runs inside `buildCorpus` and records the base build's sources.
-	 * An overlay is merged into the corpus afterwards by `overlay-manifest`,
+	 * A corpus overlay is merged into the corpus afterwards by `overlay-manifest`,
 	 * so its rows are in the corpus and outside that manifest.
 	 *
 	 * Measured over `v0.6.0-register-surface` on 2026-09-28: the frozen manifest names 11 sources
@@ -329,7 +329,7 @@ export interface EpochMixtureAudit {
 		/**
 		 * Per-source detail the audit computes from the corpus files rather than from the corpus manifest.
 		 *
-		 * `rows` is how many rows of that source the corpus holds.
+		 * `rows` is the number of rows of that source the corpus holds.
 		 * It is the only place a source outside the frozen manifest has a corpus row count, so it is what
 		 * lets a reader read a source's rows in the corpus beside the rows one epoch drew and emitted.
 		 */

package/lib/source-register/types.ts

@@ -351,8 +351,8 @@ export interface ElectedLicense {
 	 * Creative Commons permits that.
 	 *
 	 * Where that happens, {@linkcode ElectedLicense.spdx} records the one a build filters on
-	 * and this records what the publisher actually said, so a later reviewer reads
-	 * the conflict rather than one reading presented as settled.
+	 * and this records what the publisher said, so a later reviewer reads the conflict
+	 * rather than one reading presented as settled.
 	 *
 	 * The engineering policy elects the strictest grant for what a released corpus may include.
 	 * It does not establish which grant governs, and `electedBecause` states

package/lib/subvenue/harvest.ts

@@ -71,9 +71,10 @@ export interface SubVenueHarvestRow {
 /**
  * Classify an OSM `ref` into an {@link IdentifierShape} class.
  *
- * The classes are the ones Berlin's gates actually produced, plus the two aviation forms
+ * The classes are the ones Berlin's airport gates produced, plus the two aviation forms
  * the corpus task names (`Terminal 2F` is digit-letter, `Concourse B` is letter).
- * `range` covers both separators OSM uses for a gate serving more than one stand: `16-18` and `0/1`.
+ * `range` covers both separators OSM uses for a boarding gate serving more
+ * than one stand: `16-18` and `0/1`.
  */
 export function classifyIdentifier(ref: string): string {
 	const value = ref.trim()
@@ -92,10 +93,10 @@ export function classifyIdentifier(ref: string): string {
 }
 
 /**
- * How many real `ref` values each {@link IdentifierShape} keeps.
+ * The number of real `ref` values each {@link IdentifierShape} keeps.
  *
  * Eight rather than "all" and not one.
- * The field exists so a recipe author can see what a class actually contains.
+ * The field exists so a recipe author can see what a class contains.
  *
  * GB's `other` class turned out to be semicolon multi-values (`1.2.3`, `13.14`),
  * which one example would have hidden and which the class name does not say.
@@ -128,7 +129,7 @@ export interface HarvestOptions {
 /**
  * Harvest attested phrases and identifier shapes out of a source's rows.
  *
- * `index` gates the name harvest.
+ * `index` decides whether the name harvest runs.
  * A name contributes only when it contains a phrase already in the table.
  *
  * That filter is the whole reason this function is safe to run over raw OSM:

package/lib/subvenue/promotions.ts

@@ -60,8 +60,8 @@ export interface SubVenuePromotion {
  * This ledger is the only input that sets `curated: true` on a machine-derived surface.
  * Rejections stay in the ledger so the system can reject duplicate proposals until new evidence arrives.
  *
- * The span proposer in `packages/neural/lib/venue/structure.ts` ships its English designators
- * without a locale gate, so a rejection here guides recipes only and does not stop the proposer.
+ * The span proposer in `packages/neural/lib/venue/structure.ts` ships its English designators without
+ * a locale restriction, so a rejection here guides recipes only and does not stop the proposer.
  */
 export const SUBVENUE_PROMOTIONS: readonly SubVenuePromotion[] = [
 	// wing
@@ -171,7 +171,7 @@ export const SUBVENUE_PROMOTIONS: readonly SubVenuePromotion[] = [
 		census: "france.jsonl 2026-08-05 (251,260 rows), 40 hits; all 19 shape hits enumerated",
 	},
 
-	// gate: the English surface ships without modifier eligibility.
+	// The airport gate designator: the English surface ships without modifier eligibility.
 	// These entries cover its localized forms.
 	{
 		designatorID: "gate",

package/lib/subvenue/table.ts

@@ -104,13 +104,13 @@ export interface SubVenueSurface {
 	/**
 	 * Whether a human has approved this surface for parsing use in its region.
 	 *
-	 * Machine-derived entries start `false`; only a matching {@link SubVenuePromotion}
-	 * flips it, so a consumer that gates a parse must filter on this.
+	 * Machine-derived entries start `false`; only a matching {@link SubVenuePromotion} flips it,
+	 * so a consumer that accepts or refuses a parse by this table must filter on this.
 	 */
 	curated: boolean
 	/**
-	 * How many source features attested this exact phrase when the source counts (OSM, Overture);
-	 * Vocabulary sources attest phrase existence and use a count of `0`.
+	 * The number of source features that attested this exact phrase when the source counts
+	 * (OSM, Overture); Vocabulary sources attest phrase existence and use a count of `0`.
 	 * OSM and Overture sources count occurrences.
 	 */
 	observations: number
@@ -138,7 +138,7 @@ export interface IdentifierShape {
 	/**
 	 * ISO 3166-1 alpha-2 of the extract this distribution was measured in.
 	 *
-	 * It is per-region because the shapes differ (GB gates are 70% bare digits, Japanese platform
+	 * It is per-region because the shapes differ (GB airport gates are 70% bare digits, Japanese platform
 	 * refs a different range), so a recipe for a French address should sample France's distribution.
 	 */
 	region: string
@@ -190,7 +190,7 @@ export interface SubVenueLexiconTable {
  * below for the module docstring's dependency-direction reason.
  *
  * `tier` is added here: the seven WOF placetypes plus `terminal`/`gate` are all venue-interior,
- * while `campus` and `building` name a whole venue as often as a part of one
+ * while `campus` and `building` name a whole venue about as frequently as a part of one
  * but are marked `subvenue` because that is the role the span proposer uses them in.
  */
 export const SHIPPED_DESIGNATOR_SEED: ReadonlyArray<{

package/lib/surfaces/locale.ts

@@ -156,7 +156,7 @@ function tokenPresent(raw: string, value: string): boolean {
  * Render one tuple into a locale-ordered `{raw, components}` row via OpenCage templates,
  * with light variation (house number and postcode may be dropped).
  *
- * Returns `null` when the tuple is too thin or a component would not align cleanly.
+ * Returns `null` when the tuple is too thin or a component would not align to an exact span.
  *
  * Region handling depends on order:
  * - native omits region for alignment reliability

package/lib/synthesizers/anchor-absorption.ts

@@ -16,7 +16,7 @@ import { sample } from "@mailwoman/core/random"
 /* oxlint-disable sister-software/no-unnamed-threshold -- the bare decimals below are weighted-sampler
    cutoffs rather than thresholds: `const r = random()` followed by a cascade of `r < 0.4` branches defines the
    output distribution. The cascade shows each weight from top to bottom. A separate constant for each cutoff
-   would hide the distribution behind a wall of identifiers. Genuine thresholds in these files are
+   would hide the distribution behind a wall of identifiers. Decision thresholds in these files are
     extracted as constants above. */
 
 /**

package/lib/synthesizers/boundary-stress.ts

@@ -20,7 +20,7 @@ import type { CanonicalRow } from "#types"
 /* oxlint-disable sister-software/no-unnamed-threshold -- the bare decimals below are weighted-sampler
    cutoffs rather than thresholds: `const r = random()` followed by a cascade of `r < 0.4` branches is the
    output distribution. The cascade shows each weight from top to bottom. A separate constant for each cutoff
-   would hide the distribution behind identifiers. The genuine thresholds in these files are
+   would hide the distribution behind identifiers. The decision thresholds in these files are
     extracted as constants above. */
 
 /**
@@ -348,7 +348,8 @@ export function synthesizeBoundaryStressRow(
 
 		// The layout renders the tail in the country's order: `75005 Paris` for FR
 		// and `Boston, MA 02116` for the US.
-		// Dropping the layout's commas is a surface perturbation that applies to any country.
+		// The synthesizer drops the layout's commas.
+		// That is a surface perturbation that applies to any country.
 		const tail = layoutAdminTail(b.country, {
 			locality: b.locality,
 			region: b.region,

package/lib/synthesizers/no-street.ts

@@ -21,7 +21,7 @@ import type { CanonicalRow } from "#types"
 /* oxlint-disable sister-software/no-unnamed-threshold -- the bare decimals below are weighted-sampler
     cutoffs rather than thresholds: `const r = random()` followed by a cascade of `r < 0.4` branches defines the
    output distribution. The cascade shows each weight from top to bottom. A separate constant for each cutoff
-   would hide the distribution behind a wall of identifiers. Genuine thresholds in these files are
+   would hide the distribution behind a wall of identifiers. Decision thresholds in these files are
     extracted as constants above. */
 
 export interface NoStreetBaseTuple {

package/lib/synthesizers/po-box.ts

@@ -21,7 +21,7 @@ const MIN_DIGITS_FOR_HYPHEN_GROUPING = 3
 /* oxlint-disable sister-software/no-unnamed-threshold -- the bare decimals below are weighted-sampler
    cutoffs rather than thresholds. `const r = random()` followed by `r < 0.4` branches defines the
    output distribution. The branches show each weight from top to bottom. A separate constant for each cutoff
-   would hide the distribution behind identifiers. Genuine thresholds in these files are
+   would hide the distribution behind identifiers. Decision thresholds in these files are
    constants defined above. */
 
 /**

package/lib/synthesizers/tail.ts

@@ -7,9 +7,9 @@
  *   synthesizer writes `Chicago, IL 60613`, `75005 Paris`, `London, EC3N 1DE` or
  *   `Maracaibo 4001, Zulia` from one call rather than from a template per country.
  *
- *   The layout decides which parts print: the FR layout prints no region, so a FR tail carries none
+ *   The layout decides which parts print: the FR layout prints no region, so a FR tail holds none
  *   and the returned components say so. The lines the layout writes are joined with the country's
- *   line join, which is the one-line form the corpus rows take.
+ *   line join. The result is the one-line form the corpus rows take.
  */
 
 import { formatAddressRow } from "@mailwoman/codex/address/format"

package/lib/test-kit/corpus-recipe.ts

@@ -70,7 +70,7 @@ export async function scratch(prefix: string, tuples: object[], surfaces: string
 export const TEST_REGISTER = "test-harness"
 
 /**
- * Bind a recipe and its seed to a runner the tests call with just the tuples and reserved surfaces.
+ * Bind a recipe and its seed to a runner the tests call with only the tuples and reserved surfaces.
  *
  * The seed is required because these suites assert on generated distributions.
  */

package/lib/tools/align-canonical.ts

@@ -7,8 +7,9 @@ import { createNewlineWriter, JSONSpliterator } from "spliterator"
  *
  * Most synthetic recipe outputs are generated on demand by a recipe (parametrized by --count),
  * so re-emitting them in a new label format is a re-run.
- * A few are fixed corpora with a hand/DeepSeek-authored canonical source that is never regenerated,
- * notably `deepseek-kryptonite` (the adversarial hard-case set) and the `deepseek-translit-*` variants.
+ * A few are fixed corpora with a hand/DeepSeek-authored canonical source that is never regenerated.
+ *
+ * They include `deepseek-kryptonite` (the adversarial hard-case set) and the `deepseek-translit-*` variants.
  *
  * Their committed parquets use the label format that was current when they were first built.
  *

package/lib/tools/audit.ts

@@ -130,7 +130,7 @@ async function scanParquetFiles(corpusDir: PathBuilderLike, sampleCount: number)
 }
 
 function inferSourceFromFilename(filename: string): string {
-	// Many corpus builds write part-<source>-<n>.parquet or part-<n>.parquet.
+	// Some corpus builds write part-<source>-<n>.parquet or part-<n>.parquet.
 	// The latter (current build at corpus-v0.3.0) gives no source signal in the filename.
 	// See manifestScan() for the authoritative path.
 	// Return "<unknown>" so the caller flags this case.

package/lib/tools/corpus-stats.ts

@@ -57,7 +57,7 @@ export interface CorpusStatsOptions {
 	parquetPath: string
 	outputPath: string
 	/**
-	 * Read at most this many rows per parquet file.
+	 * Read at most this number of rows per parquet file.
 	 */
 	limitPerFile?: number
 }

package/lib/tools/fetch/download/network.ts

@@ -82,7 +82,7 @@ export interface SourceManifest {
 }
 
 /**
- * A status worth retrying: rate limiting or a server-side failure.
+ * A status the download retries: rate limiting or a server-side failure.
  */
 /**
  * An HTTP failure that includes its status, so callers branch on `error.status`

package/lib/tools/fetch/geonames/dump.ts

@@ -116,7 +116,7 @@ const GAZETTEER_DUMP_COLUMNS = 19
  * The capitals builder already holds each country dump as a string.
  *
  * A byte-oriented spliterator would UTF-8 encode that input and allocate up to
- * another 350 MB just to inspect the first non-empty line.
+ * another 350 MB only to inspect the first non-empty line.
  */
 export function looksLikeGazetteerDump(text: string): boolean {
 	let start = 0

package/lib/tools/fetch/gleif.ts

@@ -14,7 +14,7 @@
  *
  * 1. **The API's `size` is the archive's length.** It stated 507,006,221 and the host answered a
  *    `HEAD` with `content-length` 507,006,221 and a one-byte range with `Content-Range: bytes
- *    0-9/507006221`. The transfer is checked against the API's figure, so a body cut short or a
+ *    0-9/507006221`. The transfer is checked against the API's figure, so a truncated body or a
  *    publish replaced mid-transfer is refused rather than recorded.
  * 2. **The host honors `Range`.** An interrupted transfer resumes through
  *    {@linkcode resumableDownload}. The request names `accept-encoding: identity`, because the host

package/lib/tools/fetch/header.ts

@@ -6,7 +6,7 @@
  * This module reads a delimited file's header line and refuses one that drops a column an adapter
  * indexes.
  *
- * A fetch module checks the file it just wrote against the columns its adapter reads by name,
+ * A fetch module checks the file it has written against the columns its adapter reads by name,
  * because a renamed column reaches the adapter as an empty string on every row rather than as an
  * error. The check belongs here rather than in each publisher's module: every caller needs the same
  * two steps, and each one that wrote them again would also be a second answer to how the file is

package/lib/tools/fetch/inspire-addresses.ts

@@ -131,7 +131,7 @@ export interface WFSCapabilities {
 /**
  * A value a GeoServer JSON response uses for a voidable property that holds no value.
  *
- * INSPIRE marks many attributes voidable.
+ * The INSPIRE schema marks a set of attributes voidable.
  * A voidable property must be present with either a value or a void with a reason.
  *
  * GeoServer encodes that void as an object rather than as `null`, so `String(value)`