@mailwoman/soil 9.4.0 → 10.1.0

package/{lib/sdk → sdk}/survey-area.ts

@@ -2,34 +2,11 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   One survey area's attributes, its own metadata, and its mapped footprint.
- *
- *   THE FOOTPRINT IS THE SURVEY-AREA OUTLINE, NEVER THE UNION OF THE RATED POLYGONS. `NOTCOM`,
- *   access-denied and `NOTPUB` map units are INSIDE the footprint and carry no rating, so a footprint taken
- *   from the rated set would report them as unmapped when the authority has declared exactly what they are.
- *   The archive ships the outline as its own shapefile — `soilsa_a_<areasymbol>.shp`, one feature — which is
- *   why this layer never has to reconstruct it.
- *
- *   THE REFRESH DATE IS NOT THE SURVEY DATE, AND CONFLATING THEM IS THE CURRENCY LIE THIS FILE EXISTS TO
- *   PREVENT. `IA153` carries `saverest` 2025-09-09 and version 28, and the FGDC lineage inside the same
- *   archive cites `Soil Survey of Polk County, Iowa`, 1:15,840, **1960**. The dataset's own
- *   time-period-of-content runs 1998-09-22 to 2025-09-09, so a consumer reading that as survey currency
- *   reads it wrong by sixty-five years. Both dates are stored, apart, with the title the older one came
- *   from so it is checkable rather than assertible.
- *
- *   TWO SCALES, ALSO DIFFERENT FACTS. `legend.projectscale` is 12,000 for `IA153` — the scale the map units
- *   were digitized at. The 1960 source citation's own `srcscale` is 15,840 — the scale the ground was
- *   walked at. Storing one as the other would answer the enlargement caveat's question wrongly.
- *
- *   THE LICENCE IS CHECKED PER SURVEY AREA, against the `useconst` element of the metadata that area ships.
- *   An area whose use constraints no longer say "This is public information" is a licence change, and a
- *   build that absorbed one would ship an artifact under terms nobody checked. The text is boilerplate
- *   repeated across SSURGO, which is why asserting it is cheap and why a change in it is loud.
  */
 
-import { parseJSONStrict } from "@mailwoman/core/json"
+import { parseJSONStrict, stringifyJSON } from "@mailwoman/core/json"
 import { runFile } from "@mailwoman/core/process"
+import { normalizeWhitespace } from "@mailwoman/core/strings/format"
 import type { ParsedGeometry } from "@mailwoman/spatial"
 import type { PathBuilderLike } from "path-ts"
 
@@ -45,10 +22,8 @@ import {
 } from "#vocabulary"
 
 /**
- * The declared domains this layer validates against, and stores.
- *
- * `capability_class` is shared by `nirrcapcl`, `irrcapcl` and `muaggatt.niccdcd`, which is why one domain covers three
- * columns.
+ * The declared domains this layer validates against and stores; `capability_class`
+ * covers `nirrcapcl`, `irrcapcl` and `muaggatt.niccdcd`.
  */
 export const STORED_DOMAINS = [
 	"capability_class",
@@ -72,8 +47,8 @@ export interface SurveyAreaAttributes {
 	sourceScale: number | null
 	mappingScale: number | null
 	/**
-	 * The area the authority publishes for this survey area, in acres — the independent witness the ring-area check
-	 * compares against.
+	 * The area the authority publishes for this survey area, in acres —
+	 * the independent witness the ring-area check compares against.
 	 */
 	areaAcres: number | null
 	mapUnits: SoilMapUnitTable[]
@@ -84,8 +59,9 @@ export interface SurveyAreaAttributes {
 /**
  * Read one survey area's tabular export.
  *
- * @throws {Error} When the metadata's use constraints no longer carry the public-information sentence, when a `Choice`
- *   column holds a value outside the authority's own declared domain, or when the export declares no legend row.
+ * @throws {Error} When the metadata's use constraints no longer include the
+ * public-information sentence, when a `Choice` column holds a value outside the
+ * authority's own declared domain, or when the export declares no legend row.
  */
 export async function readSurveyAreaAttributes(
 	tabularDirectory: PathBuilderLike,
@@ -170,8 +146,8 @@ export async function readSurveyAreaAttributes(
 		return {
 			cokey: row.cokey!,
 			mukey: row.mukey!,
-			// A blank `comppct_r` is a component with no declared weight. Zero is the truthful reading — it contributes
-			// nothing to a weighted share — and it is recorded rather than dropped, so the component still appears.
+			// A blank `comppct_r` is a component with no declared weight, recorded as zero
+			// rather than dropped so the component still appears.
 			comppct_r: row.comppct_r ? Number(row.comppct_r) : 0,
 			compname: nullable(row.compname),
 			compkind: nullable(row.compkind),
@@ -225,11 +201,8 @@ export async function readSurveyAreaAttributes(
 /**
  * A polygon the authority drew with no soil mapping behind it.
  *
- * Three signals rather than one, because the source encodes the same fact three ways and each on its own has a gap: the
- * symbol (`NOTCOM`, `NOTPUB`), the name (`Area not surveyed, access denied`), and the structural case of a map unit
- * carrying NO components at all. A map unit with no components has nothing to rate whatever it is called, and reading
- * it as "rated nothing" rather than "no mapping" would put it in `unrated_share` — a claim that the survey looked and
- * declined, when it did not look.
+ * A map unit with no components has no component to rate, so it reads as no mapping
+ * rather than assigned no rating.
  */
 function isNoMapping(musym: string, muname: string, componentCount: number): boolean {
 	if (SSURGO_NO_MAPPING_SYMBOLS.has(musym.toUpperCase())) return true
@@ -242,10 +215,8 @@ function isNoMapping(musym: string, muname: string, componentCount: number): boo
 /**
  * Refuse a value outside the authority's own declared domain.
  *
- * An unknown code is a source-schema change, which is the event a reader most needs to hear about; coercing it to a
- * nearest neighbour or to NULL converts "the source changed" into "there is nothing here". A BLANK is not a violation:
- * NULL is a real state in every one of these columns and means something specific — for `nirrcapcl` it means the survey
- * did not rate the component, which is not class 8.
+ * A blank is a real NULL state rather than a violation, recording that the
+ * survey did not rate the component.
  */
 function assertDeclared(declared: ReadonlySet<string>, value: string | undefined, domain: string, where: string): void {
 	if (!value) return
@@ -253,7 +224,7 @@ function assertDeclared(declared: ReadonlySet<string>, value: string | undefined
 	if (declared.has(value)) return
 
 	throw new Error(
-		`soil survey area: ${where} holds ${JSON.stringify(value)}, which is not in the authority's declared ${domain} domain (${declared.size} members, read from the archive's own msdomdet.txt) — an unknown code is a source-schema change, and coercing it would turn "the source changed" into "there is nothing here"`
+		`soil survey area: ${where} holds ${stringifyJSON(value)}, which is not in the authority's declared ${domain} domain (${declared.size} members, read from the archive's own msdomdet.txt) — an unknown code is a source-schema change, and coercing it would turn "the source changed" into "there is nothing here"`
 	)
 }
 
@@ -262,12 +233,9 @@ function nullable(value: string | undefined): string | null {
 }
 
 /**
- * The NCCPI v3.0 overall index per component.
+ * The nccpi v3.0 overall index per component.
  *
- * `cointerp` is the largest table in the export — 157,063 rows for `IA153`, read in 0.36 s — and the overall rule is
- * one row per component at {@link COINTERP_OVERALL_RULE_DEPTH}: 369 of 369 components on `IA153`, of which 327 carry a
- * value. Sub-rules at greater depths are the submodels (corn, soybeans, small grains, cotton), which this layer does
- * not carry.
+ * Sub-rules at greater depths are submodels this layer does not include.
  */
 async function readNCCPI(
 	tabularDirectory: PathBuilderLike,
@@ -296,15 +264,15 @@ async function readNCCPI(
 }
 
 /**
- * What the shipped FGDC metadata says about this survey area's dates and its licence.
+ * What the shipped FGDC metadata records about this survey area's dates and its license.
  */
 export interface FGDCMetadata {
 	/**
-	 * The citation's own `pubdate`, as an ISO date — the refresh.
+	 * The citation's own `pubdate` as an ISO date — the refresh rather than the survey date.
 	 */
 	publicationDate: string
 	/**
-	 * The OLDEST source citation date in the lineage, as an ISO date or a bare year.
+	 * The oldest source citation date in the lineage, as an ISO date or a bare year.
 	 */
 	oldestSourceDate: string | null
 	oldestSourceTitle: string | null
@@ -312,24 +280,17 @@ export interface FGDCMetadata {
 }
 
 /**
- * Read the metadata NRCS ships inside the archive.
- *
- * Targeted extraction rather than a general XML parse, and NOT for want of a parser — `@mailwoman/core` ships
- * `htmlparser2`. A parser RECOVERS an unclosed element by giving it the rest of the document as its content, and the
- * two values below that throw would then stamp the artifact with that content instead. {@link elementText} answers
- * `undefined` for an element it cannot read, which is what makes the throw reachable. Every value this reader cannot
- * find is reported as `null` EXCEPT the publication date and the licence sentence, which throw — those two decide the
- * artifact's vintage and whether it may be shipped at all, and neither has a safe default.
+ * Read the metadata nrcs ships inside the archive.
  *
- * @throws {Error} When the metadata carries no publication date, or its use constraints no longer carry the
- *   public-information sentence.
+ * @throws {Error} When the metadata has no publication date, or its use constraints
+ * no longer include the public-information sentence.
  */
 export function readFGDCMetadata(xml: string, areaSymbol: string): FGDCMetadata {
 	const useConstraints = elementText(xml, "useconst")
 
 	if (!useConstraints?.includes(SSURGO_PUBLIC_INFORMATION_SENTENCE)) {
 		throw new Error(
-			`soil survey area: ${areaSymbol}'s FGDC use constraints do not carry ${JSON.stringify(SSURGO_PUBLIC_INFORMATION_SENTENCE)} — that sentence is the grant this layer ships on, so a survey area without it must not be built into a distributable artifact`
+			`soil survey area: ${areaSymbol}'s FGDC use constraints do not carry ${stringifyJSON(SSURGO_PUBLIC_INFORMATION_SENTENCE)} — that sentence is the grant this layer ships on, so a survey area without it must not be built into a distributable artifact`
 		)
 	}
 
@@ -353,14 +314,14 @@ export function readFGDCMetadata(xml: string, areaSymbol: string): FGDCMetadata
 }
 
 /**
- * The lineage's source citations: what the polygons rest on, and when each was made.
+ * The lineage's source citations — what the polygons rest on and when each was made.
  */
 function readSourceCitations(xml: string): Array<{ date: string; title: string; scale: number | null }> {
 	const citations: Array<{ date: string; title: string; scale: number | null }> = []
 
 	for (const body of elementBlocks(xml, "srcinfo")) {
-		// `caldate` for a single date, `begdate` for a range. A range's END is when the source stopped being collected;
-		// its BEGINNING is when the ground was first looked at, which is the fact this layer is carrying.
+		// `caldate` stores a single date.
+		// `begdate` stores a range's start date in this layer.
 		const date = elementText(body, "caldate") ?? elementText(body, "begdate")
 
 		if (!date) continue
@@ -369,7 +330,7 @@ function readSourceCitations(xml: string): Array<{ date: string; title: string;
 
 		citations.push({
 			date: date.trim(),
-			title: (elementText(body, "title") ?? "").replaceAll(/\s+/gu, " ").trim(),
+			title: normalizeWhitespace(elementText(body, "title") ?? ""),
 			scale: scale ? Number(scale) : null,
 		})
 	}
@@ -378,13 +339,10 @@ function readSourceCitations(xml: string): Array<{ date: string; title: string;
 }
 
 /**
- * The text of the first `<name>` element, whitespace left alone.
+ * The text of the first `<name>` element, with whitespace preserved.
  *
- * INDEX SCANS RATHER THAN A REGEX, AND THAT IS A CORRECTNESS CHOICE RATHER THAN A SPEED ONE. The obvious form — ``new
- * RegExp(`<${name}>([\\s\\S]*?)</${name}>`)`` — backtracks polynomially on a document whose opening tag has no closing
- * partner: the lazy run re-scans to the end from every candidate start. The input here is a 43,251-character document
- * that arrived over the network inside a downloaded archive, so "a malformed one cannot happen" is not a claim this
- * reader gets to make. Two `indexOf` calls answer the same question in one pass.
+ * Two `indexOf` calls avoid the polynomial backtracking a regex takes on a document
+ * whose opening tag has no closing partner.
  */
 function elementText(xml: string, name: string): string | undefined {
 	const open = `<${name}>`
@@ -395,14 +353,12 @@ function elementText(xml: string, name: string): string | undefined {
 	const from = start + open.length
 	const end = xml.indexOf(`</${name}>`, from)
 
-	// An element with no closing tag is unreadable, not empty — the same answer an absent element gets, because both
-	// mean the value could not be read rather than that it is blank.
+	// An element with no closing tag is unreadable rather than empty, the same answer an absent element gets.
 	return end === -1 ? undefined : xml.slice(from, end)
 }
 
 /**
- * Every `<name>` element's inner text, in document order. The repeating counterpart of {@link elementText}, and linear
- * for the same reason.
+ * Every `<name>` element's inner text in document order, the repeating counterpart of {@link elementText}.
  */
 function elementBlocks(xml: string, name: string): string[] {
 	const open = `<${name}>`
@@ -427,8 +383,8 @@ function elementBlocks(xml: string, name: string): string[] {
 }
 
 /**
- * FGDC dates arrive as `YYYY` or `YYYYMMDD`. Both are kept as they are meant — a bare year is a bare year, and padding
- * it to January 1 would invent a precision the citation does not claim.
+ * A bare year stays bare, since padding it to January 1 would invent a precision
+ * the citation does not claim.
  */
 function normalizeFGDCDate(value: string): string {
 	const trimmed = value.trim()
@@ -440,10 +396,10 @@ function normalizeFGDCDate(value: string): string {
 /**
  * Read the survey area's own outline shapefile as a GeoJSON geometry.
  *
- * @throws {Error} When the shapefile holds anything other than exactly one feature. Taking the first of several would
- *   silently choose which ground the coverage claim is about.
+ * @throws {Error} When the shapefile holds anything other than exactly one feature.
+ * The function would silently choose which ground the coverage claim describes if it took the first feature.
  */
-export async function readSurveyAreaOutline(shapefilePath: string): Promise<ParsedGeometry> {
+export async function readSurveyAreaOutline(shapefilePath: PathBuilderLike): Promise<ParsedGeometry> {
 	const { stdout } = await runFile("ogr2ogr", ["-f", "GeoJSON", "/vsistdout/", "-t_srs", "EPSG:4326", shapefilePath], {
 		maxBuffer: 256 * 1024 * 1024,
 	})

package/{lib/sdk → sdk}/tabular.ts

@@ -3,31 +3,29 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   The pipe-delimited NASIS export inside a survey-area archive: which file holds which table, which
- *   column sits at which position, and the authority's own declared domains.
+ *   Reads the pipe-delimited NASIS export inside a survey-area archive. It maps files to tables and columns to
+ *   positions, then reads the authority's declared domains.
  *
- *   THE FILES CARRY NO HEADER AND THE ARCHIVE SHIPS THE SCHEMA. `mstab.txt` maps a logical table name to
- *   the file base name that holds it (`component` → `comp.txt`, `sacatalog` → `sacatlog.txt` — neither is
- *   guessable), and `mstabcol.txt` gives every column's ordinal position. So the reader looks the positions
- *   up rather than hard-coding them, and {@link readTable} THROWS on a requested column the shipped
- *   dictionary does not declare. A reader that quietly returned `undefined` for a renamed column would turn
- *   "the source changed" into "there is none of it", at exactly the measurement boundary where that lie
- *   costs the most.
+ *   The files have no headers. The archive supplies their schema. `mstab.txt` maps each logical table name to a
+ *   filename (`component` → `comp.txt`, `sacatalog` → `sacatlog.txt`). The filenames cannot be inferred. `mstabcol.txt`
+ *   gives each column's ordinal position. The reader looks up those positions instead of hard-coding them.
+ *   {@link readTable} throws when a requested column is absent from the shipped dictionary. An `undefined` result
+ *   for a renamed column would turn a source change into an apparent absence. That would corrupt the measurement.
  *
- *   QUOTE HANDLING IS NOT OPTIONAL HERE, AND THE MEASUREMENT determines the result. `sacatlog.txt` holds 594 newline
- *   bytes and exactly ONE record: its `fgdcmetadata` column carries a 43,251-character XML document with
- *   embedded newlines. `mstabcol.txt` — the column dictionary itself — holds 913 newlines and 865 records.
- *   A line-splitting reader gets 594 malformed rows from a one-row file, every one of them well-formed
- *   enough to keep going.
+ *   Quote handling affects the parsed result. `sacatlog.txt` contains 594 newline bytes and one record. Its
+ *   `fgdcmetadata` column contains a 43,251-character XML document with embedded newlines. `mstabcol.txt`, the column
+ *   dictionary, contains 913 newlines and 865 records. A line-splitting reader would create 594 malformed rows from
+ *   the one-row `sacatlog.txt` file. Each malformed row would still look valid enough to process.
  *
- *   THE DECLARED DOMAINS COME OUT OF THE ARCHIVE TOO, which is stronger than transcribing them.
- *   `msdomdet.txt` carries every `Choice` column's members WITH the authority's own prose definition —
- *   capability classes 1 through 8, subclasses `c`/`e`/`s`/`w`, the 28 conditional farmland
- *   classifications, the six component kinds. The layer stores them and validates against them.
+ *   The archive also supplies its declared domains. Those values remove the need to transcribe them by hand.
+ *   `msdomdet.txt` lists every `Choice` column's members and the authority's prose definition. It includes
+ *   capability classes 1 through 8, subclasses `c`/`e`/`s`/`w`, 28 conditional farmland classifications and six
+ *   component kinds. The layer stores and validates those values.
  */
 
 import { readLocalBuffer } from "@mailwoman/core/fs/readers"
-import { join, type PathBuilderLike } from "path-ts"
+import { stringifyJSON } from "@mailwoman/core/json"
+import { PathBuilder, type PathBuilderLike, resolvePathBuilder } from "path-ts"
 import { CSVSpliterator } from "spliterator"
 
 /**
@@ -38,30 +36,24 @@ export type TabularRow = ReadonlyArray<string>
 /**
  * Read one pipe-delimited export file into rows.
  *
- * `enableQuoteHandling` is what makes the embedded newlines above survive; `header: false` is what keeps the first
- * record from being eaten, since these files carry none.
+ * Quote-aware parsing preserves embedded newlines; `header: false` keeps the first record
+ * because these files have no header.
  */
 async function readPipeDelimited(path: PathBuilderLike): Promise<TabularRow[]> {
 	const rows: TabularRow[] = []
 
 	for (const row of CSVSpliterator.from(await readLocalBuffer(path), {
-		mode: "array",
 		header: false,
 		columnDelimiter: "|",
-		enableQuoteHandling: true,
 	})) {
-		// `String` ON A DECLARED STRING IS NOT REDUNDANT HERE. The emitter's array mode is TYPED `string[]` and coerces
-		// numeric-looking columns at RUNTIME — measured: `mukey` comes back as the number 412818, not `"412818"` — so a row
-		// passed through untouched stops joining against the shapefile's own `MUKEY`. An empty column arrives as `""`
-		// rather than as null, which is why nothing here has to decide what a missing value means.
-		rows.push(row.map((value) => String(value)))
+		rows.push(row)
 	}
 
 	return rows
 }
 
 /**
- * The archive's own description of itself: table → file, and table → column positions.
+ * Maps each table to a file and to its column positions, as recorded in the archive's dictionary.
  */
 export interface TabularDictionary {
 	/**
@@ -77,9 +69,11 @@ export interface TabularDictionary {
 /**
  * Column positions in `mstab.txt` and `mstabcol.txt` themselves.
  *
- * These two are the ONLY positions this module hard-codes, and they cannot be looked up because they are what the
- * lookup is built from. Both files declare themselves in `mstabcol.txt`, so the assertions below check the bootstrap
- * against the archive's own account of it rather than trusting it.
+ * This module hard-codes only these two positions.
+ * It cannot look them up because they initialize the lookup.
+ *
+ * `mstabcol.txt` declares positions for both files.
+ * The assertions below check the bootstrap against the archive's own dictionary.
  */
 const MSTAB_TABLE_NAME = 0
 const MSTAB_FILE_NAME = 4
@@ -88,9 +82,10 @@ const MSTABCOL_POSITION = 1
 const MSTABCOL_COLUMN_NAME = 2
 
 /**
- * Declared widths of the two bootstrap files, asserted before either is read as a dictionary. A different width means
- * the metadata format changed, and reading positions out of a changed format is how a builder mis-reads every column at
- * once.
+ * Declared widths of the two bootstrap files, asserted before either is read as a dictionary.
+ *
+ * A different width means the metadata format changed.
+ * Changed-format positions could misread every column.
  */
 const MSTAB_WIDTH = 5
 const MSTABCOL_WIDTH = 14
@@ -101,8 +96,9 @@ const MSTABCOL_WIDTH = 14
  * @throws {Error} When either bootstrap file is missing or is not the declared width.
  */
 export async function readTabularDictionary(tabularDirectory: PathBuilderLike): Promise<TabularDictionary> {
-	const mstab = await readPipeDelimited(join(tabularDirectory, "mstab.txt"))
-	const mstabcol = await readPipeDelimited(join(tabularDirectory, "mstabcol.txt"))
+	const directory = PathBuilder.from(tabularDirectory)
+	const mstab = await readPipeDelimited(directory("mstab.txt"))
+	const mstabcol = await readPipeDelimited(directory("mstabcol.txt"))
 
 	assertWidth(mstab, MSTAB_WIDTH, "mstab.txt")
 	assertWidth(mstabcol, MSTABCOL_WIDTH, "mstabcol.txt")
@@ -146,8 +142,9 @@ function assertWidth(rows: ReadonlyArray<TabularRow>, width: number, name: strin
 /**
  * A reader over one logical table, projecting the columns a caller names.
  *
- * The projection is by NAME and a missing name throws, which is the whole point: this is the shape that produced the
- * repository's worst measurement bugs, where a silently dropped column read downstream as an empty world.
+ * The projection selects columns by name and throws when a name is missing.
+ * This prevents a silently dropped column from appearing downstream as an empty dataset,
+ * the failure behind the repository's worst measurement bugs.
  */
 export interface TabularTable {
 	/**
@@ -161,10 +158,10 @@ export interface TabularTable {
 }
 
 /**
- * Read a logical SSURGO table, projecting `wanted` columns.
+ * Read a logical ssurgo table, projecting `wanted` columns.
  *
- * @throws {Error} When the archive declares no file for the table, when a requested column is not in the shipped
- *   dictionary, or when a record is narrower than the position a requested column sits at.
+ * @throws {Error} When the archive declares no file for the table, when a requested column is not in
+ * the shipped dictionary, or when a record is narrower than the position a requested column sits at.
  */
 export async function readTable(
 	tabularDirectory: PathBuilderLike,
@@ -175,13 +172,13 @@ export async function readTable(
 	const file = dictionary.files.get(table)
 
 	if (!file) {
-		throw new Error(`soil tabular: the archive's mstab.txt declares no file for table ${JSON.stringify(table)}`)
+		throw new Error(`soil tabular: the archive's mstab.txt declares no file for table ${stringifyJSON(table)}`)
 	}
 
 	const positions = dictionary.columns.get(table)
 
 	if (!positions) {
-		throw new Error(`soil tabular: the archive's mstabcol.txt declares no columns for table ${JSON.stringify(table)}`)
+		throw new Error(`soil tabular: the archive's mstabcol.txt declares no columns for table ${stringifyJSON(table)}`)
 	}
 
 	const projection: Array<[string, number]> = []
@@ -191,7 +188,7 @@ export async function readTable(
 
 		if (position === undefined) {
 			throw new Error(
-				`soil tabular: table ${table} declares no column ${JSON.stringify(column)} — the shipped dictionary names ${positions.size} columns, and projecting away a column a caller asked for would read downstream as an absence`
+				`soil tabular: table ${table} declares no column ${stringifyJSON(column)} — the shipped dictionary names ${positions.size} columns, and projecting away a column a caller asked for would read downstream as an absence`
 			)
 		}
 
@@ -199,7 +196,7 @@ export async function readTable(
 	}
 
 	const rows: Array<Record<string, string>> = []
-	const raw = await readPipeDelimited(join(tabularDirectory, `${file}.txt`))
+	const raw = await readPipeDelimited(resolvePathBuilder(tabularDirectory, `${file}.txt`))
 
 	for (const [index, row] of raw.entries()) {
 		const record: Record<string, string> = {}
@@ -231,9 +228,12 @@ export interface DomainMember {
 }
 
 /**
- * Column positions in `msdomdet.txt`. Declared in `mstabcol.txt` under table `msdomdet`, so unlike the two bootstrap
- * files above these could be looked up — they are named here because the domain read runs before any dictionary-driven
- * read and the file is five columns wide by its own declaration.
+ * Column positions in `msdomdet.txt`.
+ *
+ * Declared in `mstabcol.txt` under table `msdomdet`, so unlike the two bootstrap
+ * files above these could be looked up.
+ * They are listed here because the domain read runs before any dictionary-driven read
+ * and the file is five columns wide by its own declaration.
  */
 const MSDOMDET_WIDTH = 5
 
@@ -243,7 +243,7 @@ const MSDOMDET_WIDTH = 5
  * @throws {Error} When the file is not the declared width.
  */
 export async function readDeclaredDomains(tabularDirectory: PathBuilderLike): Promise<DomainMember[]> {
-	const rows = await readPipeDelimited(join(tabularDirectory, "msdomdet.txt"))
+	const rows = await readPipeDelimited(resolvePathBuilder(tabularDirectory, "msdomdet.txt"))
 
 	assertWidth(rows, MSDOMDET_WIDTH, "msdomdet.txt")
 
@@ -271,23 +271,26 @@ export function domainCodes(members: ReadonlyArray<DomainMember>, domain: string
 }
 
 /**
- * `M/D/YYYY H:MM:SS` (and the `MM/DD/YYYY HH:MM:SS` the tabular export writes) to an ISO date.
+ * `M/D/yyyy H:MM:SS` (and the `MM/DD/yyyy HH:MM:SS` the tabular export writes) to an ISO date.
+ *
+ * Soil Data Access writes `9/9/2025 1:57:25 PM`.
+ * The shipped `sacatlog.txt` writes the same instant as `09/09/2025 13:57:25`.
  *
- * The two channels spell the same instant differently — Soil Data Access answers `9/9/2025 1:57:25 PM` and the shipped
- * `sacatlog.txt` writes `09/09/2025 13:57:25` — and the download URL needs `2025-09-09`. Parsing to a date rather than
- * slicing the string is what makes both channels agree.
+ * The download URL needs `2025-09-09`.
+ * Both channels agree only when the code parses the value as a date instead of slicing the string.
  *
- * @throws {Error} When the value is not one of those shapes. A freshness date guessed wrong asks the download host for
- *   a file that does not exist, and the host answers 400 rather than 404, which reads as a bad request rather than a
- *   bad date.
+ * @throws {Error} When the value is not one of those shapes.
+ * An incorrect freshness date requests a nonexistent file.
+ * The host returns 400 for the request.
+ * A 404 would identify a missing file.
  */
-// repo-health-ignore export-name-affix -- parses the survey's M/D/YYYY form; `isoDate` formats a Date and reads none.
+// repo-health-ignore export-name-affix -- parses the survey's M/D/yyyy form; `isoDate` formats a Date and reads none.
 export function saverestToISODate(value: string): string {
 	const matched = /^(\d{1,2})\/(\d{1,2})\/(\d{4})/u.exec(value.trim())
 
 	if (!matched) {
 		throw new Error(
-			`soil tabular: cannot read ${JSON.stringify(value)} as a saverest date — expected M/D/YYYY, which is what both Soil Data Access and the shipped sacatlog.txt write`
+			`soil tabular: cannot read ${stringifyJSON(value)} as a saverest date — expected M/D/YYYY, which is what both Soil Data Access and the shipped sacatlog.txt write`
 		)
 	}
 

package/{lib → sdk}/test-kit.ts

@@ -2,24 +2,10 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   Hand-built survey areas for the fixture rung: geometry, attributes and an outline, with no network and
- *   no GDAL in the loop.
- *
- *   A FIXTURE RUNG THAT COULD ONLY RUN THROUGH ogr2ogr WOULD TEST THE CONVERSION ON THE MACHINES THAT HAVE
- *   IT AND NOTHING AT ALL ON THE ONES THAT DO NOT. What these fixtures exercise is the whole database half —
- *   the declared-domain check, the cell classification, the area-weighted reduction, the four absence
- *   shares, the coverage rows, the manifest and the seal.
- *
- *   THE ABSENCE CASES ARE THE POINT, AND IOWA HAS NONE OF THEM. Every Iowa survey area is fully digitized,
- *   so `NOTCOM`, `NOTPUB` and access-denied map units never appear in the live build — which means the only
- *   place `nodata_share` can be exercised is here. The same is true of a component whose rating is NULL for
- *   the not-rateable reason and of a class-8 rating: both exist in Iowa but sparsely, and a fixture pins the
- *   behaviour rather than hoping a county contains one.
  */
 
-// The exterior and hole ring builders live in `@mailwoman/spatial` — a winding convention rather than this
-// product's geometry, and a second copy of it is a second place for a hole to stop being one.
+// The exterior and hole ring builders live in `@mailwoman/spatial`; a second copy
+// is a second place for a hole to stop being one.
 import { rectangleRing } from "@mailwoman/spatial"
 
 import type { SoilComponentTable, SoilMapUnitTable } from "#schema"
@@ -27,22 +13,19 @@ import type { SoilDelineation, SoilFeatureSource } from "#sdk/ingest"
 import type { SurveyAreaAttributes } from "#sdk/survey-area"
 
 /**
- * Re-exported so a fixture in another workspace builds its rings the same way this one does.
- */
-
-/**
- * Where the fixture geometry sits — central Iowa, so the cells it produces are the ones a real build would use.
+ * Where the fixture geometry sits — central Iowa, so the cells it produces
+ * are the ones a real build would use.
  */
 export const FIXTURE_ORIGIN = { lat: 41.6, lon: -93.6 }
 
 /**
- * Degrees per fixture square side. About 1.6 km at this latitude — several resolution-9 cells across, so a fixture
- * square has both an interior and a fringe.
+ * Degrees per fixture square side, about 1.6 km here — several resolution-9 cells across,
+ * so a square has both an interior and a fringe.
  */
 export const FIXTURE_SIDE = 0.015
 
 /**
- * The fixture map units. Each one exists to exercise exactly one reading.
+ * The fixture map units, each exercising exactly one reading.
  */
 export function fixtureMapUnits(areaSymbol = "XX001"): SoilMapUnitTable[] {
 	return [
@@ -115,8 +98,8 @@ export function fixtureMapUnits(areaSymbol = "XX001"): SoilMapUnitTable[] {
 }
 
 /**
- * The fixture components. `mu-mixed` is 45/35/20 across three classes, which is the case a winner-class schema would
- * report as "class 2" and this one reports as a mixture.
+ * The fixture components; `mu-mixed` is 45/35/20 across three classes, the case a
+ * winner-class schema would report as class 2 and this one as a mixture.
  */
 export function fixtureComponents(): SoilComponentTable[] {
 	return [
@@ -124,9 +107,10 @@ export function fixtureComponents(): SoilComponentTable[] {
 		component("co-mixed-2", "mu-mixed", 35, "Series", "3", "e"),
 		component("co-mixed-3", "mu-mixed", 20, "Series", "6", "s"),
 		component("co-class8", "mu-class8", 100, "Series", "8", "s"),
-		// A miscellaneous area with no rating: NOT RATEABLE, which is not the same as unrated and not the same as class 8.
+		// A miscellaneous area with no rating is not rateable.
+		// That differs from unrated soil and class 8.
 		component("co-water", "mu-water", 100, "Miscellaneous area", null, null),
-		// A named soil the survey did not rate: UNRATED.
+		// A soil type the survey did not rate: unrated.
 		component("co-unrated", "mu-unrated", 100, "Series", null, null),
 		// A minority component small enough to fall under the truncation floor once the lattice splits it.
 		component("co-tail", "mu-mixed", 1, "Series", "7", "e"),
@@ -178,8 +162,8 @@ export function fixtureDomains(): SurveyAreaAttributes["domains"] {
 }
 
 /**
- * The fixture delineations: a mixed square, a class-8 square, a water square, an unrated square, and a `NOTCOM` square,
- * laid out left to right so each occupies its own ground.
+ * The fixture delineations include mixed, class-8, water and unrated squares, plus a `notcom` square.
+ * They sit left to right, each on its own ground area.
  */
 export function fixtureDelineations(areaSymbol = "XX001"): SoilDelineation[] {
 	const { lat, lon } = FIXTURE_ORIGIN
@@ -194,12 +178,8 @@ export function fixtureDelineations(areaSymbol = "XX001"): SoilDelineation[] {
 }
 
 /**
- * The outline covering every fixture delineation, with margin — the survey area's own footprint.
- *
- * The margin is nearly a degree because the coverage test is CONSERVATIVE: `interiorCoverageCellSet` keeps only cells
- * lying wholly inside the outline, and a resolution-6 cell is about 36 km across. An outline the size of the fixture
- * squares yields zero interior cells and the build refuses — correctly, since an artifact with no coverage rows answers
- * unknown everywhere while reporting success.
+ * The outline covering every fixture delineation, with margin because the coverage
+ * test keeps only cells lying wholly inside the outline.
  */
 export function fixtureOutline(margin = 0.75): { type: "Polygon"; coordinates: number[][][] } {
 	const { lat, lon } = FIXTURE_ORIGIN
@@ -231,10 +211,8 @@ export function fixtureSource(delineations: SoilDelineation[], areaSymbol = "XX0
 }
 
 /**
- * One fixture survey area's attributes.
- *
- * `areaAcres` is left NULL on purpose: the area cross-check compares against what the AUTHORITY publishes, and a
- * fixture that invented an acreage would be checking this package's arithmetic against itself.
+ * One fixture survey area's attributes; `areaAcres` is left NULL on purpose so the area
+ * cross-check compares against the authority rather than this package's own arithmetic.
  */
 export function fixtureAttributes(areaSymbol = "XX001"): SurveyAreaAttributes {
 	return {