@mailwoman/soil 9.2.0

package/out/sdk/ingest-chunk.js

@@ -0,0 +1,98 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The streaming pass — every delineation into `soil_map_unit_area` and into the build's touch table — as a
+ *   unit of work that can run over PART of one survey area.
+ *
+ *   WHY THIS IS A CHUNK RATHER THAN A WHOLE FILE. h3's WASM heap cannot be reset from JavaScript, and it does
+ *   not survive an unbounded number of polyfill calls: over the flood layer's real product, runs died after
+ *   roughly 510,000 and 798,000 features on geometry that classifies in milliseconds in a fresh process. A
+ *   build that completes only when fragmentation happens to stay low is not a reproducible build, so the
+ *   classification is bounded by construction — {@linkcode buildSoilDatabase} runs one of these per range of
+ *   the shapefile's own FIDs, each in its own process, and each therefore against a heap that starts empty.
+ *   Iowa's 99 survey areas hold far more delineations together than any one of them does, which is why the
+ *   bound is per RANGE rather than per area.
+ *
+ *   THE CHUNK OWNS NO ARTIFACT. It appends rows to a database the parent created and will seal, and returns
+ *   counts the parent adds up. Chunks run one at a time against that file, so there is no concurrent writer
+ *   and no locking to reason about.
+ */
+import { addCoverageCells, encodeRings, ringAreaReadings, ringsBoundingBox, shortCellToInt } from "@mailwoman/spatial";
+import { beginBatched } from "@mailwoman/sqlite/batched";
+import { classifyDelineationCells } from "#sdk/cells";
+/**
+ * Rows per bulk-insert transaction. Chosen for the geometry table, whose rows carry a blob: a larger transaction grows
+ * the write-ahead file without improving throughput.
+ */
+const INSERT_TRANSACTION_ROWS = 5000;
+/**
+ * Delineations between progress reports.
+ */
+const PROGRESS_STRIDE = 20_000;
+/**
+ * Stream one chunk of one survey area into `database`.
+ *
+ * @throws {Error} On a delineation the classifier refuses — which includes the allocator's silent zero-cell answer.
+ */
+export async function ingestSoilChunk(database, options) {
+    const insertArea = database.prepare("INSERT INTO soil_map_unit_area (area_id, mukey, areasymbol, min_lat, min_lon, max_lat, max_lon, rings) " +
+        "VALUES (?, ?, ?, ?, ?, ?, ?, ?)");
+    const insertTouch = database.prepare("INSERT INTO build_cell_touch (h3_cell, resolution, area_id, is_full) VALUES (?, ?, ?, ?)");
+    const observedByCoverageCell = new Map();
+    const mappedByCoverageCell = new Map();
+    let delineations = 0;
+    let coarsened = 0;
+    let nestedArea = 0;
+    let allExteriorArea = 0;
+    const batch = beginBatched(database, { rowsPerCommit: INSERT_TRANSACTION_ROWS });
+    try {
+        for await (const delineation of options.source.delineations()) {
+            const bbox = ringsBoundingBox(delineation.polygons);
+            const areas = ringAreaReadings(delineation.polygons);
+            nestedArea += areas.nested;
+            allExteriorArea += areas.allExterior;
+            insertArea.run(delineation.areaID, delineation.mukey, delineation.areasymbol, bbox.minLat, bbox.minLon, bbox.maxLat, bbox.maxLon, encodeRings(delineation.polygons));
+            const classified = classifyDelineationCells(delineation.polygons, options.indexResolution, delineation.areaID);
+            if (classified.resolution !== options.indexResolution) {
+                coarsened++;
+            }
+            const coverageCells = new Set();
+            for (const cell of classified.whole) {
+                insertTouch.run(shortCellToInt(cell), classified.resolution, delineation.areaID, 1);
+                addCoverageCells(coverageCells, cell, classified.resolution, options.coverageResolution);
+            }
+            for (const cell of classified.partial) {
+                insertTouch.run(shortCellToInt(cell), classified.resolution, delineation.areaID, 0);
+                addCoverageCells(coverageCells, cell, classified.resolution, options.coverageResolution);
+            }
+            const hasMapping = !options.noMappingMukeys.has(delineation.mukey);
+            for (const coverageCell of coverageCells) {
+                observedByCoverageCell.set(coverageCell, (observedByCoverageCell.get(coverageCell) ?? 0) + 1);
+                if (hasMapping) {
+                    mappedByCoverageCell.set(coverageCell, (mappedByCoverageCell.get(coverageCell) ?? 0) + 1);
+                }
+            }
+            delineations++;
+            batch.rowWritten();
+            if (delineations % PROGRESS_STRIDE === 0) {
+                options.onProgress?.(`${delineations.toLocaleString()} delineations in this chunk`);
+            }
+        }
+        batch.commit();
+    }
+    catch (error) {
+        batch.rollbackQuietly();
+        throw error;
+    }
+    return {
+        areaSymbol: options.source.areaSymbol,
+        delineations,
+        coarsened,
+        observedByCoverageCell: [...observedByCoverageCell],
+        mappedByCoverageCell: [...mappedByCoverageCell],
+        area: { nestedM2: nestedArea, allExteriorM2: allExteriorArea },
+    };
+}
+//# sourceMappingURL=ingest-chunk.js.map

package/out/sdk/ingest-chunk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest-chunk.js","sourceRoot":"","sources":["../../lib/sdk/ingest-chunk.ts"],"names":[],"mappings":"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"}

package/out/sdk/ingest.d.ts

@@ -0,0 +1,132 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Read a survey area's published shapefiles as a stream of WGS84 delineations, through ogr2ogr.
+ *
+ *   OGR IS BUILD TOOLING, NEVER A SERVE DEPENDENCY (SCOPE invariant 6). It converts the authority's geometry
+ *   into the structure the runtime probes, and nothing downstream of this module knows GDAL exists.
+ *
+ *   THE SOURCE IS ALREADY IN WGS84, AND CHECKING IT IS STILL THE CHECK. Each `.prj` is an ESRI WKT reading
+ *   `GEOGCS["GCS_WGS_1984",…]`, which GDAL resolves to EPSG:4326 — so no reprojection is needed before H3.
+ *   The authority code is asserted anyway before a single feature is read, and the reprojected stream is
+ *   asserted against the layer's own declared extent, which is the check that catches a coordinate-order
+ *   mistake the projection check cannot see.
+ *
+ *   THE DATUM GUARD RUNS EVEN THOUGH THE ANSWER IS THE IDENTITY, AND THAT IS THE POINT. PROJ substitutes a
+ *   ballpark datum shift SILENTLY when the accurate grid is missing — measured on the flood layer at 3.4 m
+ *   over an entire country, visible only as eight disagreements out of 59 against the authority's own
+ *   service. For an EPSG:4326 source `projinfo` answers `Null geographic offset from WGS 84 to WGS 84, 0 m,
+ *   World.` and the guard passes in one process. Skipping it on the reasoning that this source needs no
+ *   shift is how the guard comes to be missing on the day a source arrives that does.
+ *
+ *   THE ID IS THE SHAPEFILE'S OWN FID, AND IT HAS TO BE, because SSURGO publishes no per-delineation key:
+ *   `MUKEY` names the MAP UNIT and one map unit has many delineations — `IA153` holds 17,966 delineations
+ *   across 152 map units. So `area_id` is `<areasymbol>:<fid>`, which is stable across runs and is what makes
+ *   a bounded chunk name the same features every time.
+ */
+import { type MultiPolygonRings } from "@mailwoman/spatial";
+/**
+ * The shapefile holding a survey area's map-unit polygons — the delineations this layer stores.
+ */
+export declare function mapUnitShapefile(spatialDirectory: string, areaSymbol: string): string;
+/**
+ * The shapefile holding a survey area's own OUTLINE. The footprint comes from HERE and never from the union of the
+ * rated polygons — `NOTCOM` and access-denied map units are inside the footprint and carry no rating, so a footprint
+ * derived from the rated set would report them as unmapped when the authority has declared exactly what they are.
+ */
+export declare function surveyAreaShapefile(spatialDirectory: string, areaSymbol: string): string;
+/**
+ * One map-unit delineation, reprojected to WGS84.
+ */
+export interface SoilDelineation {
+    /**
+     * `<areasymbol>:<fid>`.
+     */
+    areaID: string;
+    mukey: string;
+    areasymbol: string;
+    polygons: MultiPolygonRings;
+}
+/**
+ * What a shapefile says about itself, read before any feature is.
+ */
+export interface SoilSourceIdentity {
+    epsg: number;
+    featureCount: number;
+    layer: string;
+    /**
+     * The layer's own declared extent, `[minLon, minLat, maxLon, maxLat]`.
+     */
+    bbox: readonly [number, number, number, number];
+}
+export interface SoilIngestOptions {
+    shapefilePath: string;
+    /**
+     * Layer inside it. Defaults to the shapefile's base name, which is what the ESRI driver reports.
+     */
+    layer?: string;
+    /**
+     * The EPSG code the source must declare.
+     */
+    expectEPSG?: number;
+    /**
+     * Read only the shapefile's own FIDs in `[fidFrom, fidTo]`, inclusive — what makes a bounded chunk possible.
+     */
+    fidFrom?: number;
+    fidTo?: number;
+    /**
+     * Stop after this many features. The fixture and smoke rungs use it; a full build does not set it.
+     */
+    limit?: number;
+}
+/**
+ * Read what the shapefile declares about itself, and refuse a projection this ingest was not written for.
+ *
+ * @throws {Error} When the layer is missing, declares no EPSG authority code, declares one other than `expectEPSG`, or
+ *   reports no feature count.
+ */
+export declare function readSoilSourceIdentity(options: SoilIngestOptions): Promise<SoilSourceIdentity>;
+/**
+ * Stream the map-unit delineations as WGS84 features.
+ *
+ * Every feature is checked against the declared extent as it passes. A swapped coordinate order survives a projection
+ * check — both axes are still numbers in a plausible range — and shows up here immediately.
+ *
+ * @throws {Error} When ogr2ogr fails, when a feature carries no geometry or no `MUKEY`, or when a vertex falls outside
+ *   the declared extent.
+ */
+export declare function readSoilDelineations(options: SoilIngestOptions & {
+    bbox: readonly [number, number, number, number];
+}): AsyncGenerator<SoilDelineation>;
+/**
+ * Where a build's delineations come from, and what the source declares about itself.
+ *
+ * The builder takes ONE of these rather than a path, which is what makes the fixture rung possible: hand-built geometry
+ * with no network and no GDAL still exercises the whole database half — the domain check, the cell classification, the
+ * reduction, the coverage rows, the manifest and the seal.
+ */
+export interface SoilFeatureSource {
+    areaSymbol: string;
+    /**
+     * What the source says it holds. The build compares its own streamed total against this, so a short read throws
+     * instead of building a smaller county.
+     */
+    declaredFeatureCount: number;
+    layer: string;
+    epsg: number;
+    /**
+     * A description of where these delineations came from, for the receipt.
+     */
+    origin: string;
+    delineations: () => AsyncIterable<SoilDelineation>;
+}
+/**
+ * One survey area's map-unit shapefile as a feature source — identity read up front, features streamed on demand.
+ */
+export declare function createShapefileFeatureSource(options: SoilIngestOptions & {
+    areaSymbol: string;
+    declaredFeatureCount?: number;
+}): Promise<SoilFeatureSource>;
+//# sourceMappingURL=ingest.d.ts.map

package/out/sdk/ingest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest.d.ts","sourceRoot":"","sources":["../../lib/sdk/ingest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAiD,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAsB1G;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,gBAAgB,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAErF;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,gBAAgB,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAExF;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,iBAAiB,CAAA;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,YAAY,EAAE,MAAM,CAAA;IACpB,KAAK,EAAE,MAAM,CAAA;IACb;;OAEG;IACH,IAAI,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;CAC/C;AAED,MAAM,WAAW,iBAAiB;IACjC,aAAa,EAAE,MAAM,CAAA;IACrB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAepG;AAyBD;;;;;;;;GAQG;AACH,wBAAuB,oBAAoB,CAC1C,OAAO,EAAE,iBAAiB,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAC9E,cAAc,CAAC,eAAe,CAAC,CAqBjC;AAqCD;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IACjC,UAAU,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,oBAAoB,EAAE,MAAM,CAAA;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IACd,YAAY,EAAE,MAAM,aAAa,CAAC,eAAe,CAAC,CAAA;CAClD;AAED;;GAEG;AACH,wBAAsB,4BAA4B,CACjD,OAAO,EAAE,iBAAiB,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAAE,GAChF,OAAO,CAAC,iBAAiB,CAAC,CAa5B"}

package/out/sdk/ingest.js

@@ -0,0 +1,163 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Read a survey area's published shapefiles as a stream of WGS84 delineations, through ogr2ogr.
+ *
+ *   OGR IS BUILD TOOLING, NEVER A SERVE DEPENDENCY (SCOPE invariant 6). It converts the authority's geometry
+ *   into the structure the runtime probes, and nothing downstream of this module knows GDAL exists.
+ *
+ *   THE SOURCE IS ALREADY IN WGS84, AND CHECKING IT IS STILL THE CHECK. Each `.prj` is an ESRI WKT reading
+ *   `GEOGCS["GCS_WGS_1984",…]`, which GDAL resolves to EPSG:4326 — so no reprojection is needed before H3.
+ *   The authority code is asserted anyway before a single feature is read, and the reprojected stream is
+ *   asserted against the layer's own declared extent, which is the check that catches a coordinate-order
+ *   mistake the projection check cannot see.
+ *
+ *   THE DATUM GUARD RUNS EVEN THOUGH THE ANSWER IS THE IDENTITY, AND THAT IS THE POINT. PROJ substitutes a
+ *   ballpark datum shift SILENTLY when the accurate grid is missing — measured on the flood layer at 3.4 m
+ *   over an entire country, visible only as eight disagreements out of 59 against the authority's own
+ *   service. For an EPSG:4326 source `projinfo` answers `Null geographic offset from WGS 84 to WGS 84, 0 m,
+ *   World.` and the guard passes in one process. Skipping it on the reasoning that this source needs no
+ *   shift is how the guard comes to be missing on the day a source arrives that does.
+ *
+ *   THE ID IS THE SHAPEFILE'S OWN FID, AND IT HAS TO BE, because SSURGO publishes no per-delineation key:
+ *   `MUKEY` names the MAP UNIT and one map unit has many delineations — `IA153` holds 17,966 delineations
+ *   across 152 map units. So `area_id` is `<areasymbol>:<fid>`, which is stable across runs and is what makes
+ *   a bounded chunk name the same features every time.
+ */
+import { assertRingsInsideExtent, requireArealPolygons } from "@mailwoman/spatial";
+import { readOGRLayerIdentity } from "@mailwoman/spatial/tools/ogr";
+import { ogr2ogrGeoJSONSeq } from "@mailwoman/spatial/tools/ogr-stream";
+import { basename, join } from "path-ts";
+import { SSURGO_SOURCE_EPSG } from "#vocabulary";
+/**
+ * Coordinate decimals ogr2ogr writes into the stream. Nine is well past the source's own precision — the metadata
+ * states compilation to base maps meeting National Map Accuracy Standards at 1 inch = 1,000 feet — and is chosen so the
+ * round trip contributes nothing measurable to the area cross-check.
+ */
+const COORDINATE_PRECISION = 9;
+/**
+ * How far outside the layer's declared extent a vertex may fall before the ingest refuses.
+ *
+ * A tenth of a degree is about 11 km — small enough that an unprojected or axis-swapped read, which lands whole
+ * hemispheres away, still fails, and loose enough that a rounded declared extent is not brittle.
+ */
+const BBOX_MARGIN_DEGREES = 0.1;
+/**
+ * The shapefile holding a survey area's map-unit polygons — the delineations this layer stores.
+ */
+export function mapUnitShapefile(spatialDirectory, areaSymbol) {
+    return join(spatialDirectory, `soilmu_a_${areaSymbol.toLowerCase()}.shp`);
+}
+/**
+ * The shapefile holding a survey area's own OUTLINE. The footprint comes from HERE and never from the union of the
+ * rated polygons — `NOTCOM` and access-denied map units are inside the footprint and carry no rating, so a footprint
+ * derived from the rated set would report them as unmapped when the authority has declared exactly what they are.
+ */
+export function surveyAreaShapefile(spatialDirectory, areaSymbol) {
+    return join(spatialDirectory, `soilsa_a_${areaSymbol.toLowerCase()}.shp`);
+}
+/**
+ * Read what the shapefile declares about itself, and refuse a projection this ingest was not written for.
+ *
+ * @throws {Error} When the layer is missing, declares no EPSG authority code, declares one other than `expectEPSG`, or
+ *   reports no feature count.
+ */
+export async function readSoilSourceIdentity(options) {
+    const identity = await readOGRLayerIdentity({
+        path: options.shapefilePath,
+        layer: options.layer ?? basename(options.shapefilePath, ".shp"),
+        expectEPSG: options.expectEPSG ?? SSURGO_SOURCE_EPSG,
+        context: "soil ingest",
+        requireExtent: true,
+        messages: {
+            noAuthorityCode: "the projection cannot be checked, and reading one datum's coordinates as another's is silent",
+            epsgMismatch: "SSURGO publishes geographic WGS84, so a different code is a product change rather than a variation to absorb",
+        },
+    });
+    return { epsg: identity.epsg, featureCount: identity.featureCount, layer: identity.layer, bbox: identity.extent };
+}
+/**
+ * The ingest's `SELECT`, with the FID range applied when one is asked for.
+ */
+function delineationSelectSQL(layer, options) {
+    const select = `SELECT FID AS fid, MUKEY AS mukey, AREASYMBOL AS areasymbol FROM "${layer}"`;
+    const bounds = [];
+    if (options.fidFrom !== undefined) {
+        bounds.push(`FID >= ${options.fidFrom}`);
+    }
+    if (options.fidTo !== undefined) {
+        bounds.push(`FID <= ${options.fidTo}`);
+    }
+    return bounds.length ? `${select} WHERE ${bounds.join(" AND ")}` : select;
+}
+/**
+ * Stream the map-unit delineations as WGS84 features.
+ *
+ * Every feature is checked against the declared extent as it passes. A swapped coordinate order survives a projection
+ * check — both axes are still numbers in a plausible range — and shows up here immediately.
+ *
+ * @throws {Error} When ogr2ogr fails, when a feature carries no geometry or no `MUKEY`, or when a vertex falls outside
+ *   the declared extent.
+ */
+export async function* readSoilDelineations(options) {
+    const layer = options.layer ?? basename(options.shapefilePath, ".shp");
+    const [minLon, minLat, maxLon, maxLat] = options.bbox;
+    const args = [
+        "-f",
+        "GeoJSONSeq",
+        "/vsistdout/",
+        "-t_srs",
+        `EPSG:${options.expectEPSG ?? SSURGO_SOURCE_EPSG}`,
+        "-lco",
+        `COORDINATE_PRECISION=${COORDINATE_PRECISION}`,
+        ...(options.limit === undefined ? [] : ["-limit", String(options.limit)]),
+        "-sql",
+        delineationSelectSQL(layer, options),
+        options.shapefilePath,
+    ];
+    for await (const raw of ogr2ogrGeoJSONSeq(args, "soil ingest")) {
+        yield toDelineation(raw, { minLon, minLat, maxLon, maxLat });
+    }
+}
+/**
+ * Validate one raw GeoJSON feature and narrow it. Split out so the generator body stays a loop.
+ */
+function toDelineation(raw, extent) {
+    const { properties, geometry } = raw;
+    if (!geometry) {
+        throw new Error(`soil ingest: delineation ${properties.fid} carries no geometry`);
+    }
+    if (properties.mukey === null || properties.mukey === "") {
+        throw new Error(`soil ingest: delineation ${properties.fid} carries no MUKEY — a delineation with no map unit joins to nothing and would read downstream as unmapped ground`);
+    }
+    if (!properties.areasymbol) {
+        throw new Error(`soil ingest: delineation ${properties.fid} carries no AREASYMBOL`);
+    }
+    const polygons = requireArealPolygons(geometry, `delineation ${properties.fid}`, "soil ingest");
+    assertRingsInsideExtent(polygons, `delineation ${properties.fid}`, extent, BBOX_MARGIN_DEGREES, "soil ingest");
+    return {
+        areaID: `${properties.areasymbol}:${properties.fid}`,
+        mukey: String(properties.mukey),
+        areasymbol: properties.areasymbol,
+        polygons,
+    };
+}
+/**
+ * One survey area's map-unit shapefile as a feature source — identity read up front, features streamed on demand.
+ */
+export async function createShapefileFeatureSource(options) {
+    const identity = await readSoilSourceIdentity(options);
+    return {
+        areaSymbol: options.areaSymbol,
+        // A RANGE's own count is supplied by the caller, because `ogrinfo` reports the layer's total and nothing narrower.
+        // The whole-file total is still checked: the builder sums what its chunks streamed and compares that.
+        declaredFeatureCount: options.declaredFeatureCount ?? options.limit ?? identity.featureCount,
+        layer: identity.layer,
+        epsg: identity.epsg,
+        origin: options.shapefilePath,
+        delineations: () => readSoilDelineations({ ...options, bbox: identity.bbox }),
+    };
+}
+//# sourceMappingURL=ingest.js.map

package/out/sdk/ingest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest.js","sourceRoot":"","sources":["../../lib/sdk/ingest.ts"],"names":[],"mappings":"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"}

package/out/sdk/measure-resolutions.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The index resolution is a MEASUREMENT this layer takes, not a number argued to.
+ *
+ *   ONE STREAM, EVERY RESOLUTION. Re-reading a survey area's shapefile per candidate buys nothing — the
+ *   classification is per delineation, so every candidate index folds the same delineation in turn. The cost
+ *   is memory: each resolution holds its own cell sets, and the finest candidate dominates.
+ *
+ *   THIS INSTRUMENT REPORTS THE FIRST OF THE TWO NUMBERS §4.7 NAMES — the `partial` cell share, plus the mean
+ *   delineations per cell that drives it. The SECOND number, the share of cells whose top class holds less
+ *   than half the cell, is not measurable here: it needs the attribute join and the area weighting, which
+ *   are the build. So it comes off the SHIPPING ARTIFACT instead — {@linkcode buildSoilDatabase} counts it
+ *   while it writes the rows, and the build receipt reports it. That is the flood layer's lesson applied:
+ *   the number that describes the artifact is the one taken from the artifact.
+ */
+import type { ResolutionMeasurementOptions } from "@mailwoman/core/layers";
+import { type SoilCellIndexMeasurement } from "#sdk/cells";
+import { type SoilIngestOptions } from "#sdk/ingest";
+export interface MeasureSoilResolutionsOptions extends SoilIngestOptions, ResolutionMeasurementOptions {
+}
+export interface SoilResolutionReport {
+    delineations: number;
+    /**
+     * The count the shapefile declares for itself. A run whose streamed total differs read a truncated file.
+     */
+    declaredFeatureCount: number;
+    measurements: SoilCellIndexMeasurement[];
+}
+/**
+ * Measure every candidate resolution over one survey area's real delineations.
+ *
+ * @throws {Error} When the streamed count does not match the count the shapefile declares. A short read produces a
+ *   well-formed table describing a smaller county, which is the partial result that must throw.
+ */
+export declare function measureSoilCellResolutions(options: MeasureSoilResolutionsOptions): Promise<SoilResolutionReport>;
+//# sourceMappingURL=measure-resolutions.d.ts.map

package/out/sdk/measure-resolutions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"measure-resolutions.d.ts","sourceRoot":"","sources":["../../lib/sdk/measure-resolutions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,wBAAwB,CAAA;AAE1E,OAAO,EAA2C,KAAK,wBAAwB,EAAE,MAAM,YAAY,CAAA;AACnG,OAAO,EAAgD,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAElG,MAAM,WAAW,6BAA8B,SAAQ,iBAAiB,EAAE,4BAA4B;CAAG;AAEzG,MAAM,WAAW,oBAAoB;IACpC,YAAY,EAAE,MAAM,CAAA;IACpB;;OAEG;IACH,oBAAoB,EAAE,MAAM,CAAA;IAC5B,YAAY,EAAE,wBAAwB,EAAE,CAAA;CACxC;AAID;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAC/C,OAAO,EAAE,6BAA6B,GACpC,OAAO,CAAC,oBAAoB,CAAC,CAmC/B"}

package/out/sdk/measure-resolutions.js

@@ -0,0 +1,52 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The index resolution is a MEASUREMENT this layer takes, not a number argued to.
+ *
+ *   ONE STREAM, EVERY RESOLUTION. Re-reading a survey area's shapefile per candidate buys nothing — the
+ *   classification is per delineation, so every candidate index folds the same delineation in turn. The cost
+ *   is memory: each resolution holds its own cell sets, and the finest candidate dominates.
+ *
+ *   THIS INSTRUMENT REPORTS THE FIRST OF THE TWO NUMBERS §4.7 NAMES — the `partial` cell share, plus the mean
+ *   delineations per cell that drives it. The SECOND number, the share of cells whose top class holds less
+ *   than half the cell, is not measurable here: it needs the attribute join and the area weighting, which
+ *   are the build. So it comes off the SHIPPING ARTIFACT instead — {@linkcode buildSoilDatabase} counts it
+ *   while it writes the rows, and the build receipt reports it. That is the flood layer's lesson applied:
+ *   the number that describes the artifact is the one taken from the artifact.
+ */
+import { classifyDelineationCells, SoilCellIndex } from "#sdk/cells";
+import { readSoilDelineations, readSoilSourceIdentity } from "#sdk/ingest";
+const DEFAULT_PROGRESS_EVERY = 5000;
+/**
+ * Measure every candidate resolution over one survey area's real delineations.
+ *
+ * @throws {Error} When the streamed count does not match the count the shapefile declares. A short read produces a
+ *   well-formed table describing a smaller county, which is the partial result that must throw.
+ */
+export async function measureSoilCellResolutions(options) {
+    const identity = await readSoilSourceIdentity(options);
+    const indexes = options.resolutions.map((resolution) => new SoilCellIndex(resolution));
+    const progressEvery = options.progressEvery ?? DEFAULT_PROGRESS_EVERY;
+    let delineations = 0;
+    for await (const delineation of readSoilDelineations({ ...options, bbox: identity.bbox })) {
+        for (const index of indexes) {
+            index.add(delineation.areaID, classifyDelineationCells(delineation.polygons, index.resolution, delineation.areaID));
+        }
+        delineations++;
+        if (delineations % progressEvery === 0) {
+            options.onProgress?.(`${delineations.toLocaleString()} delineations classified`);
+        }
+    }
+    const expected = options.limit ?? identity.featureCount;
+    if (delineations !== expected) {
+        throw new Error(`soil measure: streamed ${delineations} delineations, the shapefile declares ${expected} — a short read reports a smaller survey area rather than failing`);
+    }
+    return {
+        delineations,
+        declaredFeatureCount: identity.featureCount,
+        measurements: indexes.map((index) => index.finish()),
+    };
+}
+//# sourceMappingURL=measure-resolutions.js.map

package/out/sdk/measure-resolutions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"measure-resolutions.js","sourceRoot":"","sources":["../../lib/sdk/measure-resolutions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,EAAE,wBAAwB,EAAE,aAAa,EAAiC,MAAM,YAAY,CAAA;AACnG,OAAO,EAAE,oBAAoB,EAAE,sBAAsB,EAA0B,MAAM,aAAa,CAAA;AAalG,MAAM,sBAAsB,GAAG,IAAI,CAAA;AAEnC;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC/C,OAAsC;IAEtC,MAAM,QAAQ,GAAG,MAAM,sBAAsB,CAAC,OAAO,CAAC,CAAA;IACtD,MAAM,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,IAAI,aAAa,CAAC,UAAU,CAAC,CAAC,CAAA;IACtF,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,sBAAsB,CAAA;IAErE,IAAI,YAAY,GAAG,CAAC,CAAA;IAEpB,IAAI,KAAK,EAAE,MAAM,WAAW,IAAI,oBAAoB,CAAC,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;QAC3F,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC7B,KAAK,CAAC,GAAG,CACR,WAAW,CAAC,MAAM,EAClB,wBAAwB,CAAC,WAAW,CAAC,QAAQ,EAAE,KAAK,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CACpF,CAAA;QACF,CAAC;QAED,YAAY,EAAE,CAAA;QAEd,IAAI,YAAY,GAAG,aAAa,KAAK,CAAC,EAAE,CAAC;YACxC,OAAO,CAAC,UAAU,EAAE,CAAC,GAAG,YAAY,CAAC,cAAc,EAAE,0BAA0B,CAAC,CAAA;QACjF,CAAC;IACF,CAAC;IAED,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,IAAI,QAAQ,CAAC,YAAY,CAAA;IAEvD,IAAI,YAAY,KAAK,QAAQ,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CACd,0BAA0B,YAAY,yCAAyC,QAAQ,mEAAmE,CAC1J,CAAA;IACF,CAAC;IAED,OAAO;QACN,YAAY;QACZ,oBAAoB,EAAE,QAAQ,CAAC,YAAY;QAC3C,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;KACpD,CAAA;AACF,CAAC"}

package/out/sdk/reduce.d.ts

@@ -0,0 +1,122 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The reduction: the containment index, read once, into one per-cell distribution both consumers share.
+ *
+ *   A DISTRIBUTION, NEVER A WINNER, AND THAT IS FORCED BY MEASUREMENT. 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 delineations are smaller than one resolution-9 cell. No affordable cell size removes
+ *   the mixture — it is a property of the survey, whose own `mukind` says so: 128,499 map units (38.0%) are
+ *   complexes, associations or undifferentiated groups, which is NRCS stating that the soils are
+ *   intermingled and cannot be separated at the mapping scale. A winner class would satisfy the result-level
+ *   consumer and starve the signal consumer, which needs a magnitude to vary over.
+ *
+ *   THE WEIGHT IS A UNIFORM-AREA LATTICE OVER THE CELL, AND THE GRAIN IS CHOSEN AGAINST THE AUTHORITY'S OWN.
+ *   A cell's children at {@link WEIGHT_LATTICE_DEPTH} levels finer have equal area by construction, so
+ *   counting which delineation covers each child centre estimates covered area without a polygon clip. At
+ *   depth 2 that is 49 children — 2.04% per child, which is the finest share NRCS's own
+ *   `muaggatt.niccdcdpct` ever reports (observed minimum: 2%). Resolving finer than the authority publishes
+ *   would be precision this layer cannot source.
+ *
+ *   A WHOLE CELL SKIPS THE LATTICE ENTIRELY, and that is exact rather than an optimization: a cell lying
+ *   wholly inside one delineation is covered by that delineation and by nothing else, so its distribution is
+ *   that map unit's component split and its `mapped_share` is 1.
+ *
+ *   `mapped_share` EXISTS BECAUSE A SURVEY-AREA EDGE CELL IS PARTLY OUTSIDE EVERY DELINEATION. Without it,
+ *   the 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. The five shares are normalized over the
+ *   mapped part, so they sum to 1 exactly, and `mapped_share` says how much of the cell that was.
+ *
+ *   CLASS 8 IS A CLASS SHARE, NOT AN ABSENCE. It is a determination — the survey looked and rated the land
+ *   as precluding commercial plant production, and 67,547 national components carry it. Folding it in with
+ *   `NOTCOM`, a water body and an unrated series would produce a well-formed wrong answer, and separating
+ *   the four absences from the one positive negative is the whole reason this table has five columns rather
+ *   than one.
+ */
+import { type H3Cell } from "@mailwoman/spatial";
+import type { SoilCapabilityCellTable, SoilComponentTable, SoilMapUnitTable } from "#schema";
+/**
+ * How many resolution levels finer than the index the weighting lattice runs.
+ *
+ * Two, giving 49 children per cell and a 2.04% share granularity. That is deliberately matched to the finest share the
+ * authority itself publishes — `muaggatt.niccdcdpct`'s observed minimum is 2% — because a lattice finer than the
+ * source's own reporting grain buys precision this layer cannot source, at 7× the cost per level.
+ */
+export declare const WEIGHT_LATTICE_DEPTH = 2;
+/**
+ * Class shares below this are folded into `other_share` rather than stored.
+ *
+ * One percent, which sits BELOW the lattice's own 2.04% granularity, so nothing a single child cell produces is
+ * truncated — what lands here is the long tail that component percentages create inside a child (a 1%-weight component
+ * inside one child cell contributes 0.02%). Truncating a long tail is legitimate; doing it silently is not, which is
+ * why the remainder is stored explicitly and the shares still sum to 1.
+ */
+export declare const CLASS_SHARE_FLOOR = 0.01;
+/**
+ * One delineation reaching a cell, as the reduction needs it.
+ */
+export interface CellCandidate {
+    areaID: string;
+    mukey: string;
+    containment: string;
+    minLat: number;
+    minLon: number;
+    maxLat: number;
+    maxLon: number;
+    rings: Uint8Array;
+}
+/**
+ * What a map unit contributes per unit of area — computed once per map unit and reused for every cell it reaches.
+ */
+export interface MapUnitProfile {
+    /**
+     * Class code → share of the map unit, summing to 1 across classes and the three mapped-absence buckets.
+     */
+    classShares: ReadonlyMap<string, number>;
+    unrated: number;
+    notRateable: number;
+    noData: number;
+}
+/**
+ * Turn one map unit and its components into the per-unit-area profile the reduction folds in.
+ *
+ * A `no_mapping` map unit contributes wholly to `nodata` and NEVER to a class: it is a polygon the authority drew with
+ * no soil mapping behind it, and reading it as a low class would be the reassuring wrong number §3.2 of the survey is
+ * about.
+ *
+ * The split across components is by `comppct_r`, the component's representative percentage of its map unit, normalized
+ * by the total actually present rather than assumed to be 100 — measured on `IA153` all 152 map units sum to exactly
+ * 100, and a national build must not depend on that holding everywhere.
+ */
+export declare function mapUnitProfile(mapUnit: Pick<SoilMapUnitTable, "no_mapping">, components: ReadonlyArray<Pick<SoilComponentTable, "comppct_r" | "compkind" | "nirrcapcl">>): MapUnitProfile;
+/**
+ * What one cell's reduction produced, plus the diagnostics the receipt reports.
+ */
+export interface ReducedCell {
+    row: SoilCapabilityCellTable;
+    /**
+     * True when the top class covers less than half the cell — the §4.7 number, counted here so it comes off the artifact
+     * rather than out of a separate harness.
+     */
+    topClassUnderHalf: boolean;
+    /**
+     * True when the lattice was used rather than the whole-cell fast path.
+     */
+    sampled: boolean;
+}
+/**
+ * Reduce one cell.
+ *
+ * @throws {Error} When a candidate names a map unit the profile map does not hold. A missing profile means the
+ *   attribute join is short, and answering with the remaining candidates would report a well-formed distribution over
+ *   part of the cell.
+ */
+export declare function reduceCell(cell: H3Cell, resolution: number, candidates: ReadonlyArray<CellCandidate>, profiles: ReadonlyMap<string, MapUnitProfile>, h3Cell: number): ReducedCell;
+/**
+ * The sum of a stored row's five shares. Exported because the invariant it checks — that they sum to 1 — is what makes
+ * `other_share` required rather than decorative, and a test that could not state the sum could not pin it.
+ */
+export declare function shareTotal(row: SoilCapabilityCellTable): number;
+//# sourceMappingURL=reduce.d.ts.map

package/out/sdk/reduce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reduce.d.ts","sourceRoot":"","sources":["../../lib/sdk/reduce.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,EAAuB,KAAK,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAGrE,OAAO,KAAK,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAG5F;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,IAAI,CAAA;AAErC;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,OAAO,CAAA;AAErC;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,UAAU,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B;;OAEG;IACH,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACxC,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;CACd;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC7B,OAAO,EAAE,IAAI,CAAC,gBAAgB,EAAE,YAAY,CAAC,EAC7C,UAAU,EAAE,aAAa,CAAC,IAAI,CAAC,kBAAkB,EAAE,WAAW,GAAG,UAAU,GAAG,WAAW,CAAC,CAAC,GACzF,cAAc,CA+ChB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,GAAG,EAAE,uBAAuB,CAAA;IAC5B;;;OAGG;IACH,iBAAiB,EAAE,OAAO,CAAA;IAC1B;;OAEG;IACH,OAAO,EAAE,OAAO,CAAA;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACzB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,aAAa,CAAC,aAAa,CAAC,EACxC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,EAC7C,MAAM,EAAE,MAAM,GACZ,WAAW,CA+Cb;AAkID;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,uBAAuB,GAAG,MAAM,CAU/D"}