@mailwoman/soil 10.0.0 → 10.1.0

package/lib/schema.ts

@@ -3,36 +3,26 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Typed schema for `soil.db` — the polygon truth table, the containment index above it, and the ONE
- *   reduction both consumers read, plus the layer-contract tables from `@mailwoman/core/layers`.
+ *   Typed schema for `soil.db`. It defines the polygon truth table, its containment index and the shared reduction
+ *   that both consumers read. It also defines the layer-interface tables from `@mailwoman/core/layers`.
  *
- *   THREE CELL-FACING TABLES ARE ONE PIPELINE, NOT THREE SOURCES. {@link SoilMapUnitAreaTable} holds what
- *   the authority drew, unsimplified. {@link SoilMapUnitCellTable} says which cells each delineation
- *   reaches and whether it fills them. {@link SoilCapabilityCellTable} is that index reduced ONCE, at build
- *   time, into a per-cell distribution. A `partial` cell's contribution to the reduction is weighted by the
- *   area it actually covers, which is why the truth table keeps unsimplified rings: simplify them and the
- *   weights change silently.
+ *   {@link SoilMapUnitAreaTable} stores the authority's unsimplified geometry.
+ *   {@link SoilMapUnitCellTable} records which cells each delineation reaches and whether it fills them.
+ *   {@link SoilCapabilityCellTable} is that index reduced once, at build time, into a per-cell
+ *   distribution. A `partial` cell's contribution is weighted by the area it covers. The truth table keeps
+ *   unsimplified rings so simplification cannot change those weights silently.
  *
- *   THE REDUCTION STORES A DISTRIBUTION, NEVER A WINNER, AND THAT IS FORCED BY MEASUREMENT RATHER THAN
- *   PREFERENCE. 84.0% of the 339,191 national map units hold two or more components; in 16.8% the largest
- *   component covers under half the map unit; and 85.4% of `IA153`'s 17,966 delineations are smaller than
- *   one resolution-9 cell, so no affordable cell size removes the mixture. NRCS itself ships
- *   `muaggatt.niccdcd` — its own dominant-condition capability class — beside `niccdcdpct`, the share that
- *   class actually covers, with an observed minimum of 2%. This table reproduces that pattern at cell grain
- *   rather than inventing one.
+ *   The reduction stores a distribution instead of one winning class. Four separate shares record reasons for
+ *   absence. Class 8 is a determination, so it contributes a class share. A fold that places a `notcom` polygon, a water body
+ *   and an unrated series into "not arable" would produce a well-formed but wrong answer. The four shares preserve
+ *   those distinctions.
  *
- *   AN ABSENCE IS NEVER A SMALL NUMBER. Four separate shares name why the rest of a cell carries no class,
- *   and class 8 is NOT among them: class 8 is a determination — the survey looked and rated the land as
- *   precluding commercial plant production — so it is a class share like any other. Folding a `NOTCOM`
- *   polygon, a water body and an unrated series into "not arable" would produce a well-formed wrong answer,
- *   which is what the four shares exist to make impossible.
- *
- *   `WITHOUT ROWID` ON THE CELL TABLES AND NEVER ON THE GEOMETRY TABLE. Small fixed-width rows probed by
- *   their exact primary key belong in the B-tree; a row carrying a geometry blob does not — clustering it
- *   into the B-tree makes every index page a geometry page.
+ *   Cell tables use `without rowid`; the geometry table uses ordinary rowids. Small fixed-width rows are probed by
+ *   their exact primary key, so they fit the B-tree. A geometry blob would make every index page a geometry page if
+ *   stored in that B-tree.
  */
 
-import type { LayerContractDatabase } from "@mailwoman/core/layers"
+import type { layerschemadatabase } from "@mailwoman/core/layers"
 import { addBoundingBoxColumns, addCellIndexColumns, addRingGeometryColumns } from "@mailwoman/sqlite/schema-columns"
 import { sql, type Kysely } from "kysely"
 
@@ -41,11 +31,16 @@ import { sql, type Kysely } from "kysely"
  */
 export const SoilCellContainment = {
 	/**
-	 * Every point in the cell is inside the delineation. Answered from the index alone, with no geometry read.
+	 * Every point in the cell is inside the delineation.
+	 *
+	 * Answered from the index without reading geometry.
 	 */
 	Whole: "whole",
 	/**
-	 * The delineation's boundary crosses the cell. The index has narrowed the candidates; the point test decides.
+	 * The delineation's boundary crosses the cell.
+	 *
+	 * The index has narrowed the candidates.
+	 * The point test decides.
 	 */
 	Partial: "partial",
 } as const
@@ -53,19 +48,29 @@ export const SoilCellContainment = {
 export type SoilCellContainment = (typeof SoilCellContainment)[keyof typeof SoilCellContainment]
 
 /**
- * One map-unit delineation, verbatim. A plain rowid table: it holds a geometry blob, which is the one shape `WITHOUT
- * ROWID` hurts.
+ * One map-unit delineation, verbatim.
+ *
+ * A plain rowid table.
+ * It holds a geometry blob.
+ * `without rowid` stores this shape inefficiently.
  */
 export interface SoilMapUnitAreaTable {
 	/**
-	 * `<areasymbol>:<ordinal>` — the survey area plus this delineation's position in the authority's own shapefile order.
-	 * SSURGO publishes no per-delineation key of its own (`mukey` names the MAP UNIT, and one map unit has many
-	 * delineations), so the ordinal is what makes a row nameable at all. Text, so a source that starts publishing a
-	 * non-numeric id needs no schema change.
+	 * `<areasymbol>:<ordinal>` identifies the survey area and this delineation's
+	 * position in the authority's own shapefile order.
+	 *
+	 * SSURGO publishes no per-delineation key.
+	 * `mukey` identifies the map unit.
+	 *
+	 * Each map unit has many delineations.
+	 * The ordinal distinguishes each delineation row.
+	 *
+	 * Text allows the source to publish a non-numeric ID without a schema change.
 	 */
 	area_id: string
 	/**
-	 * The map unit this delineation belongs to — NRCS's own key, and the join to every attribute.
+	 * The map unit that contains this delineation.
+	 * NRCS uses this key to join every attribute.
 	 */
 	mukey: string
 	areasymbol: string
@@ -74,26 +79,31 @@ export interface SoilMapUnitAreaTable {
 	max_lat: number
 	max_lon: number
 	/**
-	 * The authority's ring coordinates, unsimplified — see `@mailwoman/spatial`'s ring blob for the layout.
+	 * The authority's ring coordinates, unsimplified.
+	 * See `@mailwoman/spatial`'s ring blob for the layout.
 	 */
 	rings: Uint8Array
 }
 
 /**
- * Per (cell, delineation): does the delineation cover the whole cell, or only part of it?
+ * Records whether a delineation covers a whole cell or only part of it.
  *
- * Keyed on the delineation rather than on the map unit, because the reduction weights by the area a DELINEATION covers
- * and two delineations of one map unit reaching the same cell cover different ground.
+ * Rows use the delineation as the key because the reduction weights by covered area.
+ * Two delineations from one map unit can reach the same cell while covering different ground.
  */
 export interface SoilMapUnitCellTable {
 	/**
-	 * 48-bit short H3 cell. Mixed-resolution: `whole` rows are compacted parent-ward, `partial` rows stay at the index
-	 * resolution.
+	 * 48-bit short H3 cell.
+	 *
+	 * Uses mixed resolutions.
+	 * `whole` rows are compacted parent-ward; `partial` rows stay at the index resolution.
 	 */
 	h3_cell: number
 	/**
-	 * The resolution this row's cell was captured at. A short cell does not name its own resolution, and a table that
-	 * mixes them cannot be probed without it.
+	 * The resolution this row's cell was captured at.
+	 *
+	 * A short cell has no resolution of its own.
+	 * A table that mixes resolutions requires this column for probes.
 	 */
 	resolution: number
 	area_id: string
@@ -104,47 +114,61 @@ export interface SoilMapUnitCellTable {
 }
 
 /**
- * One SSURGO map unit — the attribute row every delineation joins to.
+ * One ssurgo map unit, the attribute row every delineation joins to.
  */
 export interface SoilMapUnitTable {
 	mukey: string
 	areasymbol: string
 	/**
-	 * The map unit symbol. `NOTCOM` and `NOTPUB` are MEANINGFUL values here, not codes to skip: they name a polygon the
-	 * authority drew with no soil mapping behind it.
+	 * The map unit symbol.
+	 *
+	 * `notcom` and `notpub` are meaningful values here rather than codes to skip.
+	 * They mark a polygon the authority drew with no soil mapping behind it.
 	 */
 	musym: string
 	muname: string
 	/**
-	 * `Consociation` | `Complex` | `Association` | `Undifferentiated group`, from the authority's declared domain. A
-	 * complex is NRCS's statement that two or more soils are intermingled and cannot be separated at the mapping scale —
-	 * the mixture is the survey's finding rather than this layer's loss.
+	 * `Consociation` | `Complex` | `Association` | `Undifferentiated group`,
+	 * from the authority's declared domain.
+	 *
+	 * A complex is nrcs's statement that two or more soils are intermingled
+	 * and cannot be separated at the mapping scale.
+	 * The mixture is the survey's finding rather than this layer's loss.
 	 */
 	mukind: string | null
 	mustatus: string | null
 	/**
-	 * The full conditional string, verbatim. NULL is not "not prime farmland": `Not prime farmland` is itself a declared
-	 * value, and NULL means the map unit carries no farmland classification at all.
+	 * The full conditional string, verbatim.
+	 *
+	 * `Not prime farmland` is itself a declared value, while NULL means the map
+	 * unit has no farmland classification.
 	 */
 	farmlndcl: string | null
 	/**
-	 * Which of {@link FarmlandScope} `farmlndcl` falls under — federal criteria travel between states, delegated ones do
-	 * not. Derived once at build time so a consumer never has to re-read 7 CFR 657.5 to know whether two rows are
-	 * comparable.
+	 * Which of {@link FarmlandScope} `farmlndcl` falls under.
+	 *
+	 * Federal criteria travel between states, while delegated ones do not.
+	 *
+	 * Derived once at build time so a consumer never has to re-read 7 CFR 657.5 to know
+	 * whether two rows are comparable.
 	 */
 	farmland_scope: string
 	/**
-	 * NRCS's OWN dominant-condition capability class for the map unit, carried rather than recomputed.
+	 * Nrcs's own dominant-condition capability class for the map unit, stored rather than recomputed.
 	 */
 	niccdcd: string | null
 	/**
-	 * And the share that class actually covers. The pair is the pattern this layer's cell reduction reproduces at cell
-	 * grain, so carrying both makes the two comparable.
+	 * The share that class actually covers.
+	 *
+	 * The pair is the pattern this layer's cell reduction reproduces at cell grain,
+	 * so carrying both makes the two comparable.
 	 */
 	niccdcdpct: number | null
 	/**
-	 * Whether this map unit is a polygon with NO soil mapping behind it — `NOTCOM`, `NOTPUB`, access denied, or a map
-	 * unit carrying no components at all. Such a map unit contributes to `nodata_share` and NEVER to a class share.
+	 * Whether this map unit is a polygon with no soil mapping behind it, such as `notcom`,
+	 * `notpub`, access denied, or a map unit carrying no components at all.
+	 *
+	 * Such a map unit contributes to `nodata_share` and never to a class share.
 	 */
 	no_mapping: number
 }
@@ -156,17 +180,20 @@ export interface SoilComponentTable {
 	cokey: string
 	mukey: string
 	/**
-	 * The component's representative percentage of its map unit — the weight the reduction aggregates by.
+	 * The component's representative percentage of its map unit, the weight the reduction aggregates by.
 	 */
 	comppct_r: number
 	compname: string | null
 	/**
-	 * `Miscellaneous area` is what separates NOT-RATEABLE from UNRATED: a rock outcrop or a water body is a component the
-	 * capability rating does not apply to, while an unrated series is one the survey did not rate.
+	 * `Miscellaneous area` is what separates not-rateable from unrated: a rock outcrop
+	 * or a water body is a component the capability rating does not apply to,
+	 * while an unrated series is one the survey did not rate.
 	 */
 	compkind: string | null
 	/**
-	 * Nonirrigated Land Capability Class, `"1"`–`"8"`. NULL means NOT RATED, never class 8.
+	 * Nonirrigated Land Capability Class, `"1"`–`"8"`.
+	 *
+	 * NULL means not rated, never class 8.
 	 */
 	nirrcapcl: string | null
 	/**
@@ -174,38 +201,48 @@ export interface SoilComponentTable {
 	 */
 	nirrcapscl: string | null
 	/**
-	 * The irrigated rating. NULL on 85.1% of national components, because it is populated only where irrigation is a
-	 * considered use — so its absence is a statement about the rating's applicability rather than about the land, and it
-	 * is carried but never reduced.
+	 * The irrigated rating.
+	 *
+	 * Populated only where irrigation is a considered use, so its absence states that
+	 * the rating does not apply rather than anything about the land.
+	 * The build stores it without reducing it.
 	 */
 	irrcapcl: string | null
 	irrcapscl: string | null
 	/**
-	 * The NCCPI v3.0 overall index in [0, 1], under its own rule name. Never blended with the capability class.
+	 * The nccpi v3.0 overall index in [0, 1], under its own rule name.
+	 *
+	 * Never blended with the capability class.
 	 */
 	nccpi_v3: number | null
 }
 
 /**
- * THE SHARED ARTIFACT BOTH CONSUMERS READ: one row per cell, the index reduced once.
+ * The shared artifact both consumers read, one row per cell with the index reduced once.
  *
- * The result-level observation takes {@link SoilCapabilityCellTable.top_class} with the share it rests on; #1683's
- * affordance vector takes `class_shares` plus the four absence shares as its axis. One artifact, one aggregation, one
- * set of provenance rows, and no possibility of the two consumers disagreeing about what the ground is.
+ * The result-level observation takes {@link SoilCapabilityCellTable.top_class} with the share it rests
+ * on, while the affordance vector takes `class_shares` plus the four absence shares as its axis.
+ * One artifact, one aggregation and one set of provenance rows, so the two
+ * consumers cannot disagree about what the ground is.
  */
 export interface SoilCapabilityCellTable {
 	/**
-	 * 48-bit short H3 cell at the declared index resolution. SINGLE-resolution, unlike {@link SoilMapUnitCellTable}: this
-	 * is the table a consumer joins on, and a mixed-resolution join key is not one.
+	 * 48-bit short H3 cell at the declared index resolution.
+	 *
+	 * Single-resolution, unlike {@link SoilMapUnitCellTable}, because a consumer joins
+	 * on this table and a mixed-resolution join key cannot serve that.
 	 */
 	h3_cell: number
 	/**
-	 * JSON: the authority's class codes mapped to their area-weighted share, sorted by descending share. Shares above the
-	 * declared truncation floor only; the remainder is in `other_share`.
+	 * JSON: the authority's class codes mapped to their area-weighted share, sorted by descending share.
+	 *
+	 * Shares above the declared truncation floor only.
+	 * The remainder is in `other_share`.
 	 */
 	class_shares: string
 	/**
-	 * Mapped soil components carrying a NULL rating — the survey did not rate them.
+	 * Mapped soil components carrying a NULL rating.
+	 * The survey did not rate them.
 	 */
 	unrated_share: number
 	/**
@@ -213,82 +250,105 @@ export interface SoilCapabilityCellTable {
 	 */
 	notrateable_share: number
 	/**
-	 * `NOTCOM`, `NOTPUB` and access-denied map units: a polygon the authority drew, with no soil mapping behind it.
+	 * `notcom`, `notpub` and access-denied map units: a polygon the authority drew,
+	 * with no soil mapping behind it.
 	 */
 	nodata_share: number
 	/**
-	 * The truncated minority tail. Stored explicitly so the five shares always sum to 1 and a reader can see how much was
-	 * folded away rather than inferring it from a gap.
+	 * The truncated minority tail.
+	 *
+	 * Stored explicitly so the five shares always sum to 1 and a reader can see how
+	 * much was folded away rather than inferring it from a gap.
 	 */
 	other_share: number
 	/**
-	 * The fraction of the CELL covered by any map-unit delineation at all.
+	 * The fraction of the cell covered by any map-unit delineation at all.
+	 *
+	 * The five shares above are normalized over this value and sum to 1 exactly.
+	 * A cell at a survey-area edge can fall partly outside every delineation.
 	 *
-	 * The five shares above are normalized over this, so they sum to 1 exactly. A cell at the edge of a survey area is
-	 * partly outside every delineation, and without this column that unmapped remainder would silently deflate every
-	 * class share — an absence represented as a small number, which is the one thing this schema exists to prevent. A
-	 * cell wholly inside the mapped area reads 1.
+	 * This column prevents the unmapped remainder from deflating every class share.
+	 *
+	 * This schema prevents an absence from appearing as a small number.
+	 * A cell wholly inside the mapped area reads 1.
 	 */
 	mapped_share: number
 	/**
-	 * The largest class share, and the share it rests on — the result-level consumer's reading, and NRCS's own
-	 * `niccdcd`/`niccdcdpct` pattern at cell grain. NULL when the cell carries no class at all, which is a real answer: a
-	 * cell that is 100% `unrated_share` is complete and holds no capability reading whatsoever.
+	 * Stores the largest class share and its proportion.
+	 *
+	 * This gives consumers an at-cell result and follows NRCS's `niccdcd`/`niccdcdpct` pattern.
+	 *
+	 * NULL when the cell has no class.
+	 * This is a valid result.
+	 *
+	 * A cell that is 100% `unrated_share` is complete and has no capability reading.
 	 */
 	top_class: string | null
 	top_class_share: number | null
 	/**
-	 * Which weighting produced the shares — {@link SOIL_SHARE_WEIGHTING}. Stored per row rather than only in the
-	 * manifest, because a later build at a different weighting must not read as the same claim.
+	 * Which weighting produced the shares, one of {@link SOIL_SHARE_WEIGHTING}.
+	 *
+	 * Stored per row as well as in the manifest.
+	 * A later build with different weighting must have a distinct record.
 	 */
 	weighting: string
 	/**
-	 * How many delineations reached this cell. The denominator behind every share above, and the number that separates a
-	 * confident single-delineation cell from a crowded one.
+	 * How many delineations reached this cell.
+	 *
+	 * Supplies the denominator behind each share above.
+	 * It also distinguishes a single-delineation cell from a crowded cell.
 	 */
 	delineations: number
 }
 
 /**
- * The authority's mapped footprint, one row per published survey area — derived from the survey-area OUTLINE and each
- * area's own metadata, NEVER from the rated polygons.
+ * The authority's mapped footprint, one row per published survey area, derived from the
+ * survey-area outline and each area's own metadata rather than from the rated polygons.
  *
- * Deriving it from the rated polygons is the error §3.2 of the survey describes: `NOTCOM` and access-denied 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 in fact declared exactly what they are.
+ * The survey's §3.2 identifies rated polygons as an invalid source for this footprint.
+ * `notcom` and access-denied map units are inside the footprint and have no rating,
+ * so a footprint taken from the rated set would report them as unmapped even
+ * though the authority has declared exactly what they are.
  */
 export interface SoilSurveyAreaTable {
 	areasymbol: string
 	areaname: string
 	/**
-	 * The version-established date from `sacatalog.saverest` — the refresh, and the manifest's vintage.
+	 * The version-established date from `sacatalog.saverest`, the refresh and the manifest's vintage.
 	 */
 	saverest: string
 	saversion: number | null
 	/**
-	 * The OLDEST source citation date in the area's own FGDC lineage — the field survey the republished polygons rest on.
+	 * The oldest source citation date in the area's own fgdc lineage, the field
+	 * survey the republished polygons rest on.
 	 *
-	 * This is a different fact from `saverest` and keeping them apart is the point: `IA153` carries a 2025-09-09 refresh
-	 * over a field survey published in 1960, and the dataset's own time-period-of-content ends at the refresh, so a
-	 * consumer reading that as survey currency reads it wrong.
+	 * This date differs from `saverest`.
+	 * `IA153` records a 2025-09-09 refresh over a field survey published in 1960.
+	 *
+	 * The dataset's time-period-of-content ends at the refresh, so it does not state
+	 * when the field survey occurred.
 	 */
 	survey_source_date: string | null
 	/**
-	 * The title of the source `survey_source_date` came from, so the date is checkable rather than assertible.
+	 * The title of the source for `survey_source_date`.
+	 * It lets readers check the date against its source.
 	 */
 	survey_source_title: string | null
 	/**
-	 * The scale of that original source — 15840 for `IA153`'s 1960 survey.
+	 * The scale of that original source, 15840 for `IA153`'s 1960 survey.
 	 */
 	source_scale: number | null
 	/**
-	 * The scale the map units were DIGITIZED at, from `legend.projectscale` — 12000 for `IA153`. A different number from
-	 * `source_scale` and a different fact: one is how finely the ground was walked, the other how finely it was drawn.
+	 * The scale the map units were digitized at, from `legend.projectscale`, 12000 for `IA153`.
+	 *
+	 * This differs from `source_scale`.
+	 * `source_scale` describes survey detail; `mapping_scale` describes drawing detail.
 	 */
 	mapping_scale: number | null
 	/**
-	 * The area the authority publishes for the survey area, in acres. The independent witness the ring-area check
-	 * compares against.
+	 * The area the authority publishes for the survey area, in acres.
+	 *
+	 * The independent witness the ring-area check compares against.
 	 */
 	area_acres: number | null
 	min_lat: number
@@ -296,7 +356,7 @@ export interface SoilSurveyAreaTable {
 	max_lat: number
 	max_lon: number
 	/**
-	 * How many `layer_coverage` rows this survey area produced, and at what resolution.
+	 * The number of `layer_coverage` rows this survey area produced and their resolution.
 	 */
 	coverage_cells: number
 	coverage_resolution: number
@@ -305,13 +365,14 @@ export interface SoilSurveyAreaTable {
 /**
  * The authority's declared domain for one `Choice` column, read out of the `msdomdet.txt` the archive ships.
  *
- * Stored so a reader can refuse a code the layer was never built to hold, and so the authority's own prose definition
- * of "capability class 3" travels with the artifact instead of living in a handbook the reader has to go find.
+ * Stored so a reader can refuse a code the layer cannot hold.
+ * The artifact also includes the authority's prose definition of "capability class 3"
+ * instead of requiring a separate handbook.
  */
 export interface SoilVocabularyTable {
 	/**
-	 * The domain name as NRCS spells it — `capability_class`, `capability_subclass`, `farmland_classification`,
-	 * `component_kind`, `mapunit_kind`.
+	 * The domain name as nrcs spells it, such as `capability_class`, `capability_subclass`,
+	 * `farmland_classification`, `component_kind` or `mapunit_kind`.
 	 */
 	domain: string
 	/**
@@ -323,7 +384,7 @@ export interface SoilVocabularyTable {
 	 */
 	definition: string
 	/**
-	 * Ordering within the domain, as the authority declares it.
+	 * Each value's sequence records its order within the authority's domain.
 	 */
 	sequence: number
 }
@@ -331,7 +392,7 @@ export interface SoilVocabularyTable {
 /**
  * Pass to `new DatabaseClient<SoilDatabase>(...)`.
  */
-export interface SoilDatabase extends LayerContractDatabase {
+export interface SoilDatabase extends layerschemadatabase {
 	soil_map_unit_area: SoilMapUnitAreaTable
 	soil_map_unit_cell: SoilMapUnitCellTable
 	soil_map_unit: SoilMapUnitTable
@@ -342,14 +403,18 @@ export interface SoilDatabase extends LayerContractDatabase {
 }
 
 /**
- * The slice of a Kysely handle the DDL touches. Kysely is invariant in its schema parameter, so naming only the members
- * these functions call lets a caller pass its own wider handle.
+ * The subset of a Kysely handle the DDL touches.
+ *
+ * Kysely is invariant in its schema parameter, so naming only the members these
+ * functions call lets a caller pass its own wider handle.
  */
 export type SoilSchemaHandle = Pick<Kysely<SoilDatabase>, "schema">
 
 /**
- * Create `soil_map_unit_area`. A PLAIN rowid table on purpose — the `rings` blob is exactly the payload `WITHOUT ROWID`
- * penalizes.
+ * Create `soil_map_unit_area`.
+ *
+ * A plain rowid table on purpose.
+ * The `rings` blob is exactly the payload `without rowid` penalizes.
  */
 export async function createSoilMapUnitAreaTable(db: SoilSchemaHandle): Promise<void> {
 	const table = db.schema
@@ -362,14 +427,16 @@ export async function createSoilMapUnitAreaTable(db: SoilSchemaHandle): Promise<
 }
 
 /**
- * Create `soil_map_unit_cell` — the containment index. Small fixed-width rows probed by their exact primary key.
+ * Create `soil_map_unit_cell`, the containment index.
+ *
+ * Small fixed-width rows probed by their exact primary key.
  */
 export async function createSoilMapUnitCellTable(db: SoilSchemaHandle): Promise<void> {
 	const table = db.schema.createTable("soil_map_unit_cell")
 
 	await addCellIndexColumns(table, "area_id")
 		.addPrimaryKeyConstraint("soil_map_unit_cell_pk", ["h3_cell", "area_id"])
-		// `WITHOUT ROWID` has no first-class builder; the raw modifier is the idiomatic fallback.
+		// `without rowid` has no first-class builder. The raw modifier is the idiomatic fallback.
 		.modifyEnd(sql`without rowid`)
 		.execute()
 }
@@ -414,7 +481,8 @@ export async function createSoilComponentTable(db: SoilSchemaHandle): Promise<vo
 }
 
 /**
- * Create `soil_capability_cell` — the reduction both consumers read.
+ * Create `soil_capability_cell`.
+ * The reduction both consumers read.
  */
 export async function createSoilCapabilityCellTable(db: SoilSchemaHandle): Promise<void> {
 	await db.schema