@mailwoman/soil 9.4.0 → 10.1.0

package/lib/index.ts

@@ -3,43 +3,10 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   The `soil.db` reader — what the soil survey assigns at a coordinate, and on what basis.
- *
- *   THREE ANSWERS, AND KEEPING THEM APART IS THE WHOLE JOB.
- *
- *   1. `designated` — the survey mapped this location and the cell's class distribution is the answer.
- *   2. `designated_no_rating` — the survey mapped this location and rated nothing there. A cell that is
- *      100% `unrated_share` or `notrateable_share` is `designated`-complete and carries no capability
- *      reading whatsoever, and that is not a corner case: 17.1% of national components carry no capability
- *      rating.
- *   3. `unknown` — no coverage row. Outside any published survey area, or inside one where the polygon
- *      exists and the soil mapping behind it does not.
- *
- *   READINGS 2 AND 3 LOOK THE SAME FROM A CLASS CODE AND ARE OPPOSITE ANSWERS FROM THE READER. A layer that
- *   could not tell them apart would report unmapped ground as unrated ground, which is one of the four
- *   absences this whole layer exists to keep separate.
- *
- *   THE ANSWER IS A DISTRIBUTION, AND THE TOP CLASS ALWAYS ARRIVES WITH THE SHARE IT RESTS ON. NRCS's own
- *   `muaggatt` ships `niccdcd` beside `niccdcdpct` for exactly this reason, with an observed minimum of 2%.
- *   A caller that wants one class may take `topClass`; it cannot take it without also being handed
- *   `topClassShare`, because a 2% plurality and an 85% majority are different claims.
- *
- *   NEITHER READING IS A STATEMENT ABOUT WHETHER THE LAND CAN BE FARMED. The layer reports what the soil
- *   survey assigns to the map unit covering a location, which is a fact about the map. NRCS states that its
- *   data "do not eliminate the need for onsite sampling, testing, and detailed study of specific sites for
- *   intensive uses" and are "intended for planning purposes only" — so `limits` carries the authority's own
- *   exclusions on every answer.
- *
- *   THE PROBE IS ONE PRIMARY-KEY READ. The reduction is single-resolution and one row per cell, which is
- *   what makes it the spine key: a coordinate becomes a cell, the cell becomes a row, and the geometry tier
- *   underneath is never touched at read time. The unsimplified rings are there for a caller that wants to
- *   re-derive the claim, not for the probe.
- *
- *   THE READER IS SYNCHRONOUS AND USES RAW PREPARED STATEMENTS, matching the resolution ladder's existing
- *   shape. The DDL that created these tables IS Kysely — see `schema.ts`.
+ *   Synchronous reader for `soil.db` that returns the soil survey's capability-class distribution at a coordinate.
  */
 
-import { parseJSONStrict } from "@mailwoman/core/json"
+import { parseJSONStrict, stringifyJSON } from "@mailwoman/core/json"
 import {
 	assertCoverageNotEmpty,
 	singleManifestRow,
@@ -51,6 +18,7 @@ import { shortCellToInt, type H3Cell } from "@mailwoman/spatial"
 import { readCoverageAt } from "@mailwoman/spatial/h3/coverage"
 import { DatabaseClient } from "@mailwoman/sqlite/client"
 import { latLngToCell } from "h3-js"
+import type { PathBuilderLike } from "path-ts"
 
 import type { SoilDatabase } from "#schema"
 import { SOIL_LAYER_NAME_PREFIX, SSURGO_PRODUCT_LIMITS } from "#vocabulary"
@@ -58,80 +26,92 @@ import { SOIL_LAYER_NAME_PREFIX, SSURGO_PRODUCT_LIMITS } from "#vocabulary"
 export { FarmlandScope, farmlandScope, SSURGO_PRODUCT_LIMITS } from "#vocabulary"
 
 /**
- * What the layer can say about a coordinate.
+ * The kinds of answer the layer gives for a coordinate, where `DesignatedNoRating`
+ * and `Unknown` must stay apart.
  */
 export const SoilReadingKind = {
 	/**
-	 * The survey mapped this location and assigns at least one capability class here.
+	 * The survey mapped this location and assigns at least one capability class.
 	 */
 	Designated: "designated",
 	/**
-	 * The survey mapped this location and rated nothing here — every share is an absence share.
+	 * The survey mapped this location and assigned no rating.
+	 * Every share is reported as an absence share.
 	 */
 	DesignatedNoRating: "designated_no_rating",
 	/**
-	 * No coverage row. Unmapped by this authority, and never a low-capability reading.
+	 * The layer has no coverage for this location.
+	 * This does not imply low capability.
 	 */
 	Unknown: "unknown",
 } as const
 
+/**
+ * One of the {@link SoilReadingKind} values.
+ */
 export type SoilReadingKind = (typeof SoilReadingKind)[keyof typeof SoilReadingKind]
 
 /**
- * The per-cell distribution, as a caller reads it.
+ * The capability-class distribution of one cell.
  */
 export interface SoilCapabilityDistribution {
 	/**
-	 * The authority's class codes mapped to their area-weighted share, largest first.
+	 * The authority's class codes mapped to their area-weighted shares, largest first.
 	 */
 	classShares: Record<string, number>
 	/**
-	 * Mapped soil components carrying a NULL rating — the survey did not rate them.
+	 * The share of mapped soil components that have a NULL rating.
 	 */
 	unratedShare: number
 	/**
-	 * Miscellaneous areas the rating does not apply to.
+	 * The share of miscellaneous areas that the rating does not apply to.
 	 */
 	notRateableShare: number
 	/**
-	 * Polygons with no soil mapping behind them.
+	 * The share of polygons that have no soil mapping.
 	 */
 	noDataShare: number
 	/**
-	 * The truncated minority tail. The five shares sum to 1.
+	 * The share of the truncated minority classes.
+	 * The class shares and the four other shares sum to 1.
 	 */
 	otherShare: number
 	/**
-	 * How much of the cell any delineation covers. Below 1 at a survey-area edge.
+	 * The fraction of the cell covered by any delineation.
+	 * It falls below 1 at a survey-area edge.
 	 */
 	mappedShare: number
 	/**
-	 * The largest class share, and the share it rests on. Absent when the cell carries no class at all.
+	 * The class with the largest share, absent when the cell has no class.
+	 *
+	 * A caller that reads `topClass` should also report `topClassShare`,
+	 * because the top class can hold a small plurality.
 	 */
 	topClass?: string
 	topClassShare?: number
 	/**
-	 * Which weighting produced these shares.
+	 * The weighting that produced these shares.
 	 */
 	weighting: string
 	/**
-	 * How many delineations reached the cell.
+	 * The number of delineations that reached the cell.
 	 */
 	delineations: number
 }
 
 /**
- * One survey area, as the layer holds it.
+ * One survey area in the layer.
  */
 export interface SoilSurveyAreaRecord {
 	areaSymbol: string
 	areaName: string
 	/**
-	 * The refresh — when this version of the data was established.
+	 * The date on which this version of the survey data was established.
 	 */
 	saverest: string
 	/**
-	 * The FIELD survey date, which is a different fact and is usually much older.
+	 * The field survey date.
+	 * It can be much older than `saverest`.
 	 */
 	surveySourceDate: string | null
 	surveySourceTitle: string | null
@@ -140,69 +120,71 @@ export interface SoilSurveyAreaRecord {
 }
 
 /**
- * One reading, carrying everything a caller needs to re-derive it rather than take it.
+ * One reading at a coordinate, with the provenance a caller needs to check it.
  */
 export interface SoilCapabilityReading {
 	kind: SoilReadingKind
 	/**
-	 * The cell's distribution. Present on both designated readings; absent on `unknown`.
+	 * The cell's distribution, present on both designated kinds and absent on `unknown`.
 	 */
 	distribution?: SoilCapabilityDistribution
 	/**
-	 * The authority's own definition of the top class, from the domain it shipped.
+	 * The authority's definition of the top class, from its vocabulary.
 	 */
 	topClassDefinition?: string
 	/**
-	 * The survey area covering the location, with both its dates.
+	 * The survey area that covers the location.
 	 */
 	surveyArea?: SoilSurveyAreaRecord
 	/**
-	 * The coverage row that licenses the reading, when there is one. Absent on `unknown`, which IS the absence.
+	 * The coverage row that supports the reading, when one exists.
 	 */
 	coverage?: CoverageCell & { h3CellIndex: string; resolution: number }
 	/**
-	 * The index cell probed, for a receipt.
+	 * The H3 index cell that the lookup probed.
 	 */
 	indexCellIndex: string
 	/**
-	 * What the product does not cover, in the authority's own words. Carried on every reading.
+	 * The authority's own statements of what the product does not cover.
+	 *
+	 * Every reading includes them because the survey supports planning only
+	 * and does not replace onsite study.
 	 */
 	limits: ReadonlyArray<string>
 }
 
 /**
- * The layer's identity, read once at open time.
+ * The layer's identity, read once when the database opens.
  */
 export interface SoilLayerIdentity {
 	manifest: LayerManifest
 	indexResolution: number
 	coverageResolution: number
 	/**
-	 * The survey areas the layer covers, in symbol order.
+	 * The survey areas the layer covers, ordered by area symbol.
 	 */
 	surveyAreas: SoilSurveyAreaRecord[]
 	/**
-	 * The class codes the layer's own vocabulary declares.
+	 * The class codes that the layer's vocabulary declares.
 	 */
 	classCodes: string[]
 	/**
-	 * The weighting every stored share was produced under, and the sentence that says what it means.
+	 * The code of the weighting used for every stored share, with its description.
 	 */
 	weighting: { code: string; description: string }
 	databasePath: string
 }
 
+/**
+ * Options for {@link SoilCapabilityLookup}.
+ */
 export interface SoilCapabilityLookupOptions {
-	databasePath: string
+	databasePath: PathBuilderLike
 }
 
 /**
- * Read a sealed `soil.db`.
- *
- * Everything that would make the reader answer a well-formed wrong thing is refused at CONSTRUCTION rather than at
- * query time: a manifest naming a different product, a coverage table with no rows, a vocabulary with no classes. Each
- * of those would otherwise present as a reader that simply always answers `unknown`, which on a receipt is
- * indistinguishable from a region the authority genuinely has not surveyed.
+ * Reads a sealed `soil.db`, throwing at construction on a manifest for a different product,
+ * an empty coverage table, an empty class vocabulary, or a missing share weighting.
  */
 export class SoilCapabilityLookup implements Disposable {
 	readonly identity: SoilLayerIdentity
@@ -240,15 +222,14 @@ export class SoilCapabilityLookup implements Disposable {
 	}
 
 	/**
-	 * What the soil survey assigns at this coordinate.
+	 * Returns what the soil survey assigns at this coordinate.
 	 */
 	public lookup(latitude: number, longitude: number): SoilCapabilityReading {
 		const indexCell = latLngToCell(latitude, longitude, this.identity.indexResolution) as H3Cell
 		const coverage = this.#readCoverage(indexCell)
 
-		// COVERAGE QUALIFIES THE READING, and without it there is nothing to report. Unlike a polygon hit — which is a
-		// determination at a location and needs no coverage row to be true — every answer this layer gives is a per-cell
-		// summary, so a summary row without a coverage row would state a determination outside the authority's footprint.
+		// Every answer is a per-cell summary, so a cell outside the coverage table
+		// is unknown even if a summary row exists.
 		if (!coverage) {
 			return {
 				kind: SoilReadingKind.Unknown,
@@ -273,9 +254,8 @@ export class SoilCapabilityLookup implements Disposable {
 			| undefined
 
 		if (!row) {
-			// A coverage row without a summary row means the coverage cell is designated and this finer cell holds nothing —
-			// the survey-area edge. Unknown rather than "no rating": the authority's statement covers the coverage cell, and
-			// this location may be outside the delineations it covers.
+			// At a survey-area edge the coarser coverage cell is covered and this index cell
+			// has no delineation, so the location may be outside the survey.
 			return {
 				kind: SoilReadingKind.Unknown,
 				coverage,
@@ -315,24 +295,16 @@ export class SoilCapabilityLookup implements Disposable {
 		this.#database.destroy()
 	}
 
-	/**
-	 * The coverage row for the index cell's parent at the coverage resolution.
-	 */
 	#readCoverage(indexCell: H3Cell): (CoverageCell & { h3CellIndex: string; resolution: number }) | undefined {
 		return readCoverageAt(this.#selectCoverage, indexCell, this.identity.coverageResolution)
 	}
 
 	/**
-	 * Which survey area a coordinate falls in, by the delineation bounds each area's row carries.
-	 *
-	 * A rectangle rather than the outline, and that is honest about what it is: the answer names WHICH published survey
-	 * the reading came from, and two neighbouring counties' rectangles overlap at their corners. The reading itself does
-	 * not depend on it — the cell row is the answer — so a corner ambiguity costs a label rather than a determination.
+	 * Returns the first survey area whose bounding rectangle contains the coordinate.
+	 * overlapping rectangles may give the wrong area near a corner.
 	 *
-	 * A LINEAR SCAN, WHICH THE PILOT'S 99 SURVEY AREAS MAKE FREE AND A NATIONAL BUILD WOULD NOT. It returns on the first
-	 * containing rectangle, so the pilot costs a few dozen comparisons per geocode. At the 3,380 survey areas the country
-	 * holds this wants a bounding-box index; it is left as a scan because a structure sized for a set this build does not
-	 * hold would be untested at the size it was built for.
+	 * This affects only the `surveyArea` label.
+	 * A spatial index would be needed to avoid the linear scan for thousands of areas.
 	 */
 	#surveyAreaAt(latitude: number, longitude: number): SoilSurveyAreaRecord | undefined {
 		for (const [index, bounds] of this.#bounds.entries()) {
@@ -350,12 +322,9 @@ export class SoilCapabilityLookup implements Disposable {
 	}
 }
 
-/**
- * Read and check the layer's identity.
- */
 function readIdentity(
 	database: DatabaseClient<SoilDatabase>,
-	databasePath: string
+	databasePath: PathBuilderLike
 ): {
 	identity: SoilLayerIdentity
 	definitions: Map<string, string>
@@ -365,15 +334,14 @@ function readIdentity(
 		Record<string, string | number | null>
 	>
 
-	// The name's SUFFIX names the region a build covers, so the reader checks the prefix rather than a whole name — which
-	// is why it asserts its own identity instead of taking `parseManifestRows`: one authority, one product, one rating
-	// vocabulary per artifact, over whichever survey areas were built.
+	// The layer name ends with the region the build covers, so the reader checks only the prefix
+	// rather than `parseManifestRows`, which compares whole names.
 	const row = singleManifestRow(manifestRows, `soil reader: ${databasePath}`)
 	const name = String(row.name)
 
 	if (!name.startsWith(SOIL_LAYER_NAME_PREFIX)) {
 		throw new Error(
-			`soil reader: ${databasePath} is layer ${JSON.stringify(name)}, which is not a ${JSON.stringify(SOIL_LAYER_NAME_PREFIX)} layer — one authority, one product, one rating vocabulary per artifact`
+			`soil reader: ${databasePath} is layer ${stringifyJSON(name)}, which is not a ${stringifyJSON(SOIL_LAYER_NAME_PREFIX)} layer — one authority, one product, one rating vocabulary per artifact`
 		)
 	}
 
@@ -461,7 +429,7 @@ function readIdentity(
 			})),
 			classCodes: [...definitions.keys()],
 			weighting: { code: weighting.code, description: weighting.definition },
-			databasePath,
+			databasePath: databasePath.toString(),
 		},
 		definitions,
 		bounds: areaRows.map((area) => ({

package/lib/paths.ts

@@ -0,0 +1,24 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Where the soil layer database and its download caches live under the data root's `db/` group.
+ */
+
+import { databaseRootPath, dataRootPath } from "@mailwoman/core/data-root"
+import type { PathBuilder, PathBuilderLike } from "path-ts"
+
+/**
+ * `<dataRoot>/db/soil`.
+ */
+export function soilDatabaseRoot(dataRoot: PathBuilderLike): PathBuilder {
+	return databaseRootPath(dataRoot)("soil")
+}
+
+/**
+ * `$MAILWOMAN_DATA_ROOT/db/soil`, read when a path is requested.
+ *
+ * @see {@link soilDatabaseRoot} for another data root.
+ */
+export const soilDatabasePath: PathBuilder = soilDatabaseRoot(dataRootPath())