@mailwoman/soil 9.2.0

package/lib/test-kit.ts

@@ -0,0 +1,255 @@
+/**
+ * @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.
+import { rectangleRing } from "@mailwoman/spatial"
+
+import type { SoilComponentTable, SoilMapUnitTable } from "#schema"
+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.
+ */
+export { rectangleRing, reversedRing as holeRing } from "@mailwoman/spatial"
+
+/**
+ * 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.
+ */
+export const FIXTURE_SIDE = 0.015
+
+/**
+ * The fixture map units. Each one exists to exercise exactly one reading.
+ */
+export function fixtureMapUnits(areaSymbol = "XX001"): SoilMapUnitTable[] {
+	return [
+		{
+			mukey: "mu-mixed",
+			areasymbol: areaSymbol,
+			musym: "M1",
+			muname: "Fixture complex, 0 to 2 percent slopes",
+			mukind: "Complex",
+			mustatus: null,
+			farmlndcl: "Prime farmland if drained",
+			farmland_scope: "federal",
+			niccdcd: "2",
+			niccdcdpct: 45,
+			no_mapping: 0,
+		},
+		{
+			mukey: "mu-class8",
+			areasymbol: areaSymbol,
+			musym: "M8",
+			muname: "Fixture badland",
+			mukind: "Consociation",
+			mustatus: null,
+			farmlndcl: "Not prime farmland",
+			farmland_scope: "none",
+			niccdcd: "8",
+			niccdcdpct: 100,
+			no_mapping: 0,
+		},
+		{
+			mukey: "mu-water",
+			areasymbol: areaSymbol,
+			musym: "W",
+			muname: "Water",
+			mukind: "Consociation",
+			mustatus: null,
+			farmlndcl: null,
+			farmland_scope: "none",
+			niccdcd: null,
+			niccdcdpct: null,
+			no_mapping: 0,
+		},
+		{
+			mukey: "mu-unrated",
+			areasymbol: areaSymbol,
+			musym: "U",
+			muname: "Fixture silt loam, unrated",
+			mukind: "Consociation",
+			mustatus: null,
+			farmlndcl: "Farmland of statewide importance",
+			farmland_scope: "state",
+			niccdcd: null,
+			niccdcdpct: null,
+			no_mapping: 0,
+		},
+		{
+			mukey: "mu-notcom",
+			areasymbol: areaSymbol,
+			musym: "NOTCOM",
+			muname: "No Digital Data Available",
+			mukind: null,
+			mustatus: null,
+			farmlndcl: null,
+			farmland_scope: "none",
+			niccdcd: null,
+			niccdcdpct: null,
+			no_mapping: 1,
+		},
+	]
+}
+
+/**
+ * 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.
+ */
+export function fixtureComponents(): SoilComponentTable[] {
+	return [
+		component("co-mixed-1", "mu-mixed", 45, "Series", "2", "e"),
+		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.
+		component("co-water", "mu-water", 100, "Miscellaneous area", null, null),
+		// A named soil 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"),
+	]
+}
+
+function component(
+	cokey: string,
+	mukey: string,
+	comppct: number,
+	compkind: string,
+	nirrcapcl: string | null,
+	nirrcapscl: string | null
+): SoilComponentTable {
+	return {
+		cokey,
+		mukey,
+		comppct_r: comppct,
+		compname: cokey,
+		compkind,
+		nirrcapcl,
+		nirrcapscl,
+		irrcapcl: null,
+		irrcapscl: null,
+		nccpi_v3: null,
+	}
+}
+
+/**
+ * The declared domains a fixture build validates and stores, matching what the real `msdomdet.txt` ships.
+ */
+export function fixtureDomains(): SurveyAreaAttributes["domains"] {
+	const members: SurveyAreaAttributes["domains"] = []
+
+	for (const [index, code] of ["1", "2", "3", "4", "5", "6", "7", "8"].entries()) {
+		members.push({
+			domain: "capability_class",
+			code,
+			sequence: index + 1,
+			definition: `Soils in Class ${code} — fixture definition.`,
+		})
+	}
+
+	for (const [index, code] of ["e", "w", "s", "c"].entries()) {
+		members.push({ domain: "capability_subclass", code, sequence: index + 1, definition: `Fixture subclass ${code}.` })
+	}
+
+	return members
+}
+
+/**
+ * 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.
+ */
+export function fixtureDelineations(areaSymbol = "XX001"): SoilDelineation[] {
+	const { lat, lon } = FIXTURE_ORIGIN
+	const mukeys = ["mu-mixed", "mu-class8", "mu-water", "mu-unrated", "mu-notcom"]
+
+	return mukeys.map((mukey, index) => ({
+		areaID: `${areaSymbol}:${index}`,
+		mukey,
+		areasymbol: areaSymbol,
+		polygons: [[rectangleRing(lon + index * FIXTURE_SIDE, lat, lon + (index + 1) * FIXTURE_SIDE, lat + FIXTURE_SIDE)]],
+	}))
+}
+
+/**
+ * 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.
+ */
+export function fixtureOutline(margin = 0.75): { type: "Polygon"; coordinates: number[][][] } {
+	const { lat, lon } = FIXTURE_ORIGIN
+
+	return {
+		type: "Polygon",
+		coordinates: [
+			rectangleRing(lon - margin, lat - margin, lon + 5 * FIXTURE_SIDE + margin, lat + FIXTURE_SIDE + margin),
+		],
+	}
+}
+
+/**
+ * A feature source over hand-built delineations.
+ */
+export function fixtureSource(delineations: SoilDelineation[], areaSymbol = "XX001"): SoilFeatureSource {
+	return {
+		areaSymbol,
+		declaredFeatureCount: delineations.length,
+		layer: `soilmu_a_${areaSymbol.toLowerCase()}`,
+		epsg: 4326,
+		origin: "fixture",
+		async *delineations() {
+			for (const delineation of delineations) {
+				yield delineation
+			}
+		},
+	}
+}
+
+/**
+ * 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.
+ */
+export function fixtureAttributes(areaSymbol = "XX001"): SurveyAreaAttributes {
+	return {
+		areasymbol: areaSymbol,
+		areaname: "Fixture County, Iowa",
+		saverest: "2025-09-09",
+		saversion: 1,
+		surveySourceDate: "1960",
+		surveySourceTitle: "Soil Survey of Fixture County, Iowa",
+		sourceScale: 15_840,
+		mappingScale: 12_000,
+		areaAcres: null,
+		mapUnits: fixtureMapUnits(areaSymbol),
+		components: fixtureComponents(),
+		domains: fixtureDomains(),
+	}
+}

package/lib/vocabulary.ts

@@ -0,0 +1,241 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   NRCS's own words, as data: the product identity, the licence sentence it ships inside every archive,
+ *   the acknowledgement it asks for, and the caveats that decide what a reading may claim.
+ *
+ *   THE RATING VOCABULARY IS NOT HERE, BECAUSE THE AUTHORITY SHIPS IT. `msdomdet.txt` inside each survey
+ *   area's tabular export carries the declared domain for every `Choice` column, WITH the authority's own
+ *   prose definition of each member — capability classes 1 through 8, subclasses `c`/`e`/`s`/`w`, the 28
+ *   farmland classifications, the six component kinds. So the layer reads the domain out of the file it
+ *   ingested rather than transcribing it from the National Soil Survey Handbook, and an out-of-domain value
+ *   throws: an unknown code is a source-schema change, which is the event a reader most needs to hear
+ *   about, and coercing it to a nearest neighbour or to NULL converts "the source changed" into "there is
+ *   nothing here".
+ *
+ *   THE FARMLAND VOCABULARY IS CONDITIONAL AND THE CONDITION IS THE CLAIM. 28 declared values, of which 24
+ *   carry an "if" — `Prime farmland if drained`, `Prime farmland if irrigated and reclaimed of excess salts
+ *   and sodium`. A boolean `arable` column would be this layer's invention rather than the authority's
+ *   statement, so the string is stored whole.
+ *
+ *   AND TWO OF ITS CATEGORIES TRAVEL WHILE THE OTHERS DO NOT. 7 CFR 657.5 defines prime farmland and unique
+ *   farmland nationally against nine specific criteria; §657.5(c) and (d) hand "additional farmland of
+ *   statewide importance" and "of local importance" to state and local agencies respectively. So
+ *   `Farmland of statewide importance` in Iowa and in Georgia are not the same claim, and a consumer that
+ *   pooled them into one rank would be pooling incompatible vocabularies. {@link FARMLAND_SCOPE} carries
+ *   that distinction into the artifact rather than leaving it in a document.
+ */
+
+/**
+ * The layer-name prefix. The suffix names the REGION the build covers, because the manifest's declared extent and the
+ * coverage rows describe the same set and that set is a list of published survey areas rather than "the United
+ * States".
+ */
+export const SOIL_LAYER_NAME_PREFIX = "soil-capability-nrcs-ssurgo-"
+
+/**
+ * The layer name for a build over `region`.
+ */
+export function soilLayerName(region: string): string {
+	return `${SOIL_LAYER_NAME_PREFIX}${region.toLowerCase()}`
+}
+
+/**
+ * The pilot region — Iowa, whole, built survey area by survey area.
+ */
+export const SOIL_PILOT_REGION = "ia"
+
+/**
+ * The acknowledgement string the shipped FGDC metadata asks for, verbatim as the metadata gives the agency name. This
+ * is not decoration: the use constraints say the agency "should be acknowledged as the data source in products derived
+ * from these data", so it rides in `layer_manifest.attribution`.
+ */
+export const SSURGO_ATTRIBUTION = "U.S. Department of Agriculture, Natural Resources Conservation Service"
+
+/**
+ * The licence expression written into `layer_manifest.license`.
+ *
+ * A public-domain identifier, and the grant behind it is the producing agency's own sentence rather than a catalogue
+ * field: data.gov's entry points at `usa.gov/publicdomain/label/1.0/`, which redirects to a page that declines a
+ * blanket grant and tells the reader to check with the agency. The agency was checked at the strongest available place
+ * — the FGDC metadata NRCS ships inside the archive — and it says {@link SSURGO_PUBLIC_INFORMATION_SENTENCE}.
+ */
+export const SSURGO_LICENSE = "PDDL-1.0-USGov-NRCS"
+
+/**
+ * The sentence that makes this layer shippable, verbatim from the `useconst` element of the FGDC metadata inside every
+ * survey-area archive.
+ *
+ * The ingest asserts it is present in each area's metadata. A survey area whose use constraints no longer say this is a
+ * licence change, and a build that absorbed one would ship an artifact under terms nobody checked.
+ */
+export const SSURGO_PUBLIC_INFORMATION_SENTENCE = "This is public information"
+
+/**
+ * The use constraints in full, as the metadata states them. Carried so a reader can check the licence claim against the
+ * authority's own words rather than against this package's summary of them.
+ */
+export const SSURGO_USE_CONSTRAINTS =
+	"The U.S. Department of Agriculture, Natural Resources Conservation Service, should be acknowledged as the data " +
+	"source in products derived from these data. This data set is not designed for use as a primary regulatory tool " +
+	"in permitting or citing decisions, but may be used as a reference source. This is public information and may be " +
+	"interpreted by organizations, agencies, units of government, or others based on needs; however, they are " +
+	"responsible for the appropriate application."
+
+/**
+ * What a reading is NOT, in the authority's own words. Carried on every reading, because a caller cannot see from a
+ * capability class that the survey declines to speak about a specific site.
+ *
+ * The first two sentences are why §3.1 of the survey forbids a point-level determination: the map is authoritative
+ * about an area at its own scale and explicitly declines to be authoritative about a point.
+ */
+export const SSURGO_PRODUCT_LIMITS: ReadonlyArray<string> = [
+	"The depicted soil boundaries, interpretations, and analysis derived from them do not eliminate the need for onsite sampling, testing, and detailed study of specific sites for intensive uses. Thus, these data and their interpretations are intended for planning purposes only.",
+	"Photographic or digital enlargement of these maps to scales greater than at which they were originally mapped can cause misinterpretation of the data. If enlarged, maps do not show the small areas of contrasting soils that could have been shown at a larger scale.",
+	"This data set is not designed for use as a primary regulatory tool in permitting or citing decisions, but may be used as a reference source.",
+	"Digital data files are periodically updated. Files are dated, and users are responsible for obtaining the latest version of the data.",
+	"The difference in positional accuracy between the soil boundaries and special soil features locations in the field and their digitized map locations is unknown.",
+]
+
+/**
+ * The coverage statement a `designated` basis rests on: what NRCS declares complete inside a published survey area.
+ *
+ * It is the mapping at the survey's own scale, NOT a site-specific determination — which is why the observation reports
+ * what the survey assigns to the map unit covering a location and never whether the land can be farmed.
+ */
+export const SSURGO_COVERAGE_STATEMENT =
+	"Soil surveys are published by survey area. Inside a published survey area the soil mapping is complete at the " +
+	"survey's own scale; land outside any published survey area has no soil map unit at all."
+
+/**
+ * Where the product's identity and cadence are published.
+ */
+export const SSURGO_STATEMENT_URL =
+	"https://www.nrcs.usda.gov/conservation-basics/natural-resource-concerns/soil/annual-soils-refresh"
+
+/**
+ * The dataset identifier written into `layer_manifest.source`.
+ */
+export const SSURGO_SOURCE = "nrcs.usda.gov/SSURGO"
+
+/**
+ * The projection every SSURGO survey-area shapefile declares. The `.prj` is an ESRI WKT naming `GCS_WGS_1984`, which
+ * GDAL resolves to this authority code — so no reprojection is needed before H3, and a survey area declaring anything
+ * else is a product change rather than a variation to absorb.
+ */
+export const SSURGO_SOURCE_EPSG = 4326
+
+/**
+ * Whether a farmland classification's criteria are set nationally or by a state or local agency.
+ *
+ * 7 CFR 657.5 defines prime and unique farmland against nine national criteria; (c) and (d) delegate statewide and
+ * local importance. A consumer comparing two states may compare the national categories and must not compare the
+ * delegated ones.
+ */
+export const FarmlandScope = {
+	/**
+	 * Criteria set by 7 CFR 657.5(a)–(b). Comparable across the country.
+	 */
+	Federal: "federal",
+	/**
+	 * Criteria "determined by the appropriate State agency or agencies" — 7 CFR 657.5(c).
+	 */
+	State: "state",
+	/**
+	 * Criteria "identified by the local agency or agencies concerned" — 7 CFR 657.5(d).
+	 */
+	Local: "local",
+	/**
+	 * The value states no farmland importance at all.
+	 */
+	None: "none",
+} as const
+
+export type FarmlandScope = (typeof FarmlandScope)[keyof typeof FarmlandScope]
+
+/**
+ * Which scope a declared `farmlndcl` value falls under, decided on the phrase the regulation itself uses.
+ *
+ * Matching on the phrase rather than on an enumerated list of the 28 values is deliberate: the domain grows — the
+ * conditional tail is generated by combining a base category with a condition — and a new `Farmland of statewide
+ * importance, if …` must land in {@link FarmlandScope.State} on the day it appears rather than silently defaulting to
+ * the comparable bucket.
+ */
+export function farmlandScope(value: string | null | undefined): FarmlandScope {
+	if (!value) return FarmlandScope.None
+
+	const lowered = value.toLowerCase()
+
+	// FIRST, because it CONTAINS the phrase the federal test looks for. `Not prime farmland` is a declared value stating
+	// no farmland importance at all, and a substring test that ran the other way round would call it federally comparable
+	// prime farmland — which it is the exact negation of. It is also the most common value in the domain: 192,120 of the
+	// 339,191 national map units carry it.
+	if (lowered.startsWith("not prime farmland")) return FarmlandScope.None
+
+	if (lowered.includes("statewide importance")) return FarmlandScope.State
+
+	if (lowered.includes("local importance")) return FarmlandScope.Local
+
+	if (lowered.includes("prime farmland") || lowered.includes("unique importance")) return FarmlandScope.Federal
+
+	return FarmlandScope.None
+}
+
+/**
+ * Map-unit symbols NRCS uses for a delineation it has drawn and has no soil mapping behind.
+ *
+ * These are polygons rather than holes — the same wall-to-wall discipline that makes them separable from land outside a
+ * survey area entirely. Measured nationally through Soil Data Access: 37 map units carry `NOTCOM` (`No Digital Data
+ * Available`) and 7 carry `NOTPUB` (`Not Public Information`).
+ */
+export const SSURGO_NO_MAPPING_SYMBOLS: ReadonlySet<string> = new Set(["NOTCOM", "NOTPUB"])
+
+/**
+ * Map-unit names for the same case, where the symbol does not carry it. Measured nationally: 72 map units are named
+ * `Area not surveyed, access denied`.
+ *
+ * Matched case-insensitively on the whole name. A prefix match would catch a future `Area not surveyed, access denied —
+ * pending` and would also catch nothing else, but it would equally catch a real soil name beginning with those words,
+ * and there is no such thing to be gained by guessing.
+ */
+export const SSURGO_NO_MAPPING_NAMES: ReadonlySet<string> = new Set([
+	"area not surveyed, access denied",
+	"not public information",
+	"no digital data available",
+])
+
+/**
+ * The interpretation rule whose overall value this layer carries, exactly as `cointerp.mrulename` spells it.
+ *
+ * Its `interphr` is an index in [0, 1] — measured 0.001 to 0.991 nationally, 0.022 to 0.990 on `IA153` — and it is
+ * never blended with the capability class: they are two ratings from one authority answering different questions, and
+ * combining them would produce a number NRCS does not publish.
+ */
+export const NCCPI_V3_RULE_NAME = "NCCPI - National Commodity Crop Productivity Index (Ver 3.0)"
+
+/**
+ * The interpretation depth at which a rule reports its own overall value. Sub-rules sit at greater depths and are the
+ * submodels (corn, soybeans, small grains, cotton), which this layer does not carry.
+ */
+export const COINTERP_OVERALL_RULE_DEPTH = "0"
+
+/**
+ * How the per-cell shares were produced, recorded on every row.
+ *
+ * The survey names this as a required record because the weighting mixes two different things — polygon geometry, which
+ * the survey does know, and component percentages, which are a proportion without a location. "60% of this cell's area
+ * lies in map units whose components are class 2" and "the components in this cell sum to 60% class 2" are different
+ * claims, and a reader holding only a share cannot tell which one it is holding.
+ */
+export const SOIL_SHARE_WEIGHTING = "cell_area_x_comppct_r"
+
+/**
+ * The one-sentence expansion of {@link SOIL_SHARE_WEIGHTING}, stored beside it so the artifact explains itself.
+ */
+export const SOIL_SHARE_WEIGHTING_DESCRIPTION =
+	"Each map-unit delineation contributes the area of the cell it covers; that area is split across the delineation's " +
+	"components in proportion to comppct_r, the component's representative percentage of its map unit. Component " +
+	"percentages are a proportion without a location, so a share states how much of the cell's area lies in map units " +
+	"whose components carry a rating — not where within the cell that rating applies."

package/out/index.d.ts

@@ -0,0 +1,199 @@
+/**
+ * @copyright Sister Software
+ * @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`.
+ */
+import { type CoverageCell, type LayerManifest } from "@mailwoman/core/layers";
+export { FarmlandScope, farmlandScope, SSURGO_PRODUCT_LIMITS } from "#vocabulary";
+/**
+ * What the layer can say about a coordinate.
+ */
+export declare const SoilReadingKind: {
+    /**
+     * The survey mapped this location and assigns at least one capability class here.
+     */
+    readonly Designated: "designated";
+    /**
+     * The survey mapped this location and rated nothing here — every share is an absence share.
+     */
+    readonly DesignatedNoRating: "designated_no_rating";
+    /**
+     * No coverage row. Unmapped by this authority, and never a low-capability reading.
+     */
+    readonly Unknown: "unknown";
+};
+export type SoilReadingKind = (typeof SoilReadingKind)[keyof typeof SoilReadingKind];
+/**
+ * The per-cell distribution, as a caller reads it.
+ */
+export interface SoilCapabilityDistribution {
+    /**
+     * The authority's class codes mapped to their area-weighted share, largest first.
+     */
+    classShares: Record<string, number>;
+    /**
+     * Mapped soil components carrying a NULL rating — the survey did not rate them.
+     */
+    unratedShare: number;
+    /**
+     * Miscellaneous areas the rating does not apply to.
+     */
+    notRateableShare: number;
+    /**
+     * Polygons with no soil mapping behind them.
+     */
+    noDataShare: number;
+    /**
+     * The truncated minority tail. The five shares sum to 1.
+     */
+    otherShare: number;
+    /**
+     * How much of the cell any delineation covers. 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.
+     */
+    topClass?: string;
+    topClassShare?: number;
+    /**
+     * Which weighting produced these shares.
+     */
+    weighting: string;
+    /**
+     * How many delineations reached the cell.
+     */
+    delineations: number;
+}
+/**
+ * One survey area, as the layer holds it.
+ */
+export interface SoilSurveyAreaRecord {
+    areaSymbol: string;
+    areaName: string;
+    /**
+     * The refresh — when this version of the data was established.
+     */
+    saverest: string;
+    /**
+     * The FIELD survey date, which is a different fact and is usually much older.
+     */
+    surveySourceDate: string | null;
+    surveySourceTitle: string | null;
+    sourceScale: number | null;
+    mappingScale: number | null;
+}
+/**
+ * One reading, carrying everything a caller needs to re-derive it rather than take it.
+ */
+export interface SoilCapabilityReading {
+    kind: SoilReadingKind;
+    /**
+     * The cell's distribution. Present on both designated readings; absent on `unknown`.
+     */
+    distribution?: SoilCapabilityDistribution;
+    /**
+     * The authority's own definition of the top class, from the domain it shipped.
+     */
+    topClassDefinition?: string;
+    /**
+     * The survey area covering the location, with both its dates.
+     */
+    surveyArea?: SoilSurveyAreaRecord;
+    /**
+     * The coverage row that licenses the reading, when there is one. Absent on `unknown`, which IS the absence.
+     */
+    coverage?: CoverageCell & {
+        h3CellIndex: string;
+        resolution: number;
+    };
+    /**
+     * The index cell probed, for a receipt.
+     */
+    indexCellIndex: string;
+    /**
+     * What the product does not cover, in the authority's own words. Carried on every reading.
+     */
+    limits: ReadonlyArray<string>;
+}
+/**
+ * The layer's identity, read once at open time.
+ */
+export interface SoilLayerIdentity {
+    manifest: LayerManifest;
+    indexResolution: number;
+    coverageResolution: number;
+    /**
+     * The survey areas the layer covers, in symbol order.
+     */
+    surveyAreas: SoilSurveyAreaRecord[];
+    /**
+     * The class codes the layer's own vocabulary declares.
+     */
+    classCodes: string[];
+    /**
+     * The weighting every stored share was produced under, and the sentence that says what it means.
+     */
+    weighting: {
+        code: string;
+        description: string;
+    };
+    databasePath: string;
+}
+export interface SoilCapabilityLookupOptions {
+    databasePath: string;
+}
+/**
+ * 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.
+ */
+export declare class SoilCapabilityLookup implements Disposable {
+    #private;
+    readonly identity: SoilLayerIdentity;
+    constructor(options: SoilCapabilityLookupOptions);
+    /**
+     * What the soil survey assigns at this coordinate.
+     */
+    lookup(latitude: number, longitude: number): SoilCapabilityReading;
+    [Symbol.dispose](): void;
+}
+//# sourceMappingURL=index.d.ts.map