@mailwoman/soil 9.2.0

package/out/sdk/cell-tiers.js

@@ -0,0 +1,194 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The two phases between the streamed touches and the artifact a consumer reads: the stored containment
+ *   index, and the reduction above it.
+ *
+ *   BOTH READ THE TOUCH TABLE, AND ONLY ONE OF THEM COMPACTS. `resolveCells` writes the tiers a probe walks
+ *   and collapses uniform interiors parent-ward; `reduceCells` reads the UNCOMPACTED touches, because a
+ *   compacted parent no longer names the cells the reduction has to answer.
+ *
+ *   THE REDUCTION IS THE SLOW PHASE AND ITS MEMORY IS BOUNDED BY CONSTRUCTION. A lattice of 49 point tests
+ *   per sampled cell, over a delineation cache that is cleared whole rather than evicted one entry at a
+ *   time — see {@link GEOMETRY_CACHE_ENTRIES}. Memory stays flat in row count, which is the property the poi
+ *   build lost when a reader materialized instead of streaming.
+ */
+import { expandShortCellInt, shortCellToInt } from "@mailwoman/spatial";
+import { beginBatched } from "@mailwoman/sqlite/batched";
+import { compactCells, getResolution } from "h3-js";
+import { SoilCellContainment } from "#schema";
+import { mapUnitProfile, reduceCell } from "#sdk/reduce";
+/**
+ * Resolve the touch table into the stored containment index.
+ *
+ * Compaction happens HERE and only on the whole side. It is expected to yield close to nothing on this layer, which is
+ * the inversion the survey predicts: compaction needs a uniform interior, and 85.4% of `IA153`'s delineations are
+ * smaller than one resolution-9 cell.
+ */
+export function resolveCells(database, indexResolution) {
+    database.exec("CREATE INDEX build_cell_touch_area_cell ON build_cell_touch (area_id, resolution, is_full, h3_cell)");
+    const groups = database
+        .prepare("SELECT DISTINCT area_id, resolution FROM build_cell_touch WHERE is_full = 1")
+        .all();
+    const insertCell = database.prepare("INSERT OR REPLACE INTO soil_map_unit_cell (h3_cell, resolution, area_id, containment) VALUES (?, ?, ?, ?)");
+    const resolutions = new Set();
+    let wholeRows = 0;
+    // One group per (delineation, resolution): `compactCells` takes a single resolution, and an adaptively-indexed layer
+    // has several. Pooling them throws; compacting only the target-resolution group would silently drop every coarsened
+    // delineation's interior.
+    database.exec("BEGIN");
+    for (const { area_id: areaID, resolution } of groups) {
+        const whole = database
+            .prepare("SELECT DISTINCT h3_cell FROM build_cell_touch WHERE area_id = ? AND resolution = ? AND is_full = 1")
+            .all(areaID, resolution);
+        for (const cell of compactCells(whole.map((row) => expandShortCellInt(row.h3_cell, resolution)))) {
+            const cellResolution = getResolution(cell);
+            resolutions.add(cellResolution);
+            insertCell.run(shortCellToInt(cell), cellResolution, areaID, SoilCellContainment.Whole);
+            wholeRows++;
+        }
+    }
+    database.exec("COMMIT");
+    // The partial rows are every touch that is not whole for its own delineation. `INSERT OR REPLACE` above already put
+    // the whole rows in, and the primary key is `(h3_cell, area_id)`, so this insert must skip them explicitly rather
+    // than rely on the key: a partial row replacing a whole one would demote an answered cell to a ray cast.
+    database.exec("INSERT OR IGNORE INTO soil_map_unit_cell (h3_cell, resolution, area_id, containment) " +
+        "SELECT DISTINCT t.h3_cell, t.resolution, t.area_id, 'partial' FROM build_cell_touch t WHERE t.is_full = 0");
+    const partialRows = database.prepare("SELECT count(*) AS n FROM soil_map_unit_cell WHERE containment = 'partial'").get().n;
+    for (const row of database.prepare("SELECT DISTINCT resolution FROM soil_map_unit_cell").all()) {
+        resolutions.add(row.resolution);
+    }
+    resolutions.add(indexResolution);
+    return { wholeRows, partialRows, resolutions: [...resolutions].toSorted((left, right) => left - right) };
+}
+/**
+ * Cells reduced per progress report. The reduction is the slow phase — a lattice of 49 point tests per sampled cell —
+ * so it reports often enough that a long run is visibly alive.
+ */
+const REDUCE_PROGRESS_STRIDE = 50_000;
+/**
+ * How many delineations the reduction keeps in memory at once.
+ *
+ * Sized to bound the phase rather than to hold everything: the pilot region's median delineation encodes to roughly 1.4
+ * kB, so 200,000 of them is a few hundred megabytes — comfortable, and far below the 2.5 million a whole state holds.
+ * Memory stays flat in row count, which is the property the poi build lost when a reader materialized instead of
+ * streaming.
+ */
+const GEOMETRY_CACHE_ENTRIES = 200_000;
+/**
+ * Reduce the touch table into `soil_capability_cell`.
+ *
+ * Reads the touch table rather than `soil_map_unit_cell` on purpose: the stored index is compacted on the whole side,
+ * so a compacted parent no longer names the cells the reduction has to answer. The touch table is the uncompacted truth
+ * about which delineation reaches which cell.
+ */
+export function reduceCells(database, indexResolution, onProgress) {
+    const profiles = readMapUnitProfiles(database);
+    const insert = database.prepare("INSERT OR REPLACE INTO soil_capability_cell (h3_cell, class_shares, unrated_share, notrateable_share, nodata_share, other_share, mapped_share, top_class, top_class_share, weighting, delineations) " +
+        "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)");
+    const selectArea = database.prepare("SELECT mukey, min_lat, min_lon, max_lat, max_lon, rings FROM soil_map_unit_area WHERE area_id = ?");
+    const rows = database
+        .prepare("SELECT h3_cell, resolution, area_id, is_full FROM build_cell_touch ORDER BY resolution, h3_cell, area_id")
+        .iterate();
+    let cells = 0;
+    let sampled = 0;
+    let topClassUnderHalf = 0;
+    let classless = 0;
+    let unsampled = 0;
+    let candidatePairs = 0;
+    let currentCell;
+    let currentResolution = indexResolution;
+    let candidates = [];
+    // A delineation is named by every cell it reaches — 5.35 of them per cell at resolution 9 on the pilot region — so a
+    // naive read fetches each ring blob once per touch. At Iowa's scale that is millions of blob reads of ground already
+    // in memory. The cache is bounded and CLEARED WHOLE when it fills rather than evicted one at a time: h3 cell integers
+    // carry their ancestry in their high bits, so a scan in `h3_cell` order visits neighbours together and a cleared cache
+    // refills with the delineations the next run of cells actually names.
+    const geometry = new Map();
+    const batch = beginBatched(database, { rowsPerCommit: REDUCE_PROGRESS_STRIDE });
+    const flush = () => {
+        if (currentCell === undefined || !candidates.length)
+            return;
+        const cell = expandShortCellInt(currentCell, currentResolution);
+        const reducedCell = reduceCell(cell, currentResolution, candidates, profiles, currentCell);
+        candidatePairs += candidates.length;
+        if (reducedCell.row.mapped_share <= 0) {
+            unsampled++;
+            return;
+        }
+        cells++;
+        if (reducedCell.sampled) {
+            sampled++;
+        }
+        if (reducedCell.topClassUnderHalf) {
+            topClassUnderHalf++;
+        }
+        if (!reducedCell.row.top_class) {
+            classless++;
+        }
+        insertRow(insert, reducedCell.row);
+        if (batch.rowWritten()) {
+            onProgress?.(`${cells.toLocaleString()} cells reduced`);
+        }
+    };
+    for (const row of rows) {
+        if (row.h3_cell !== currentCell || row.resolution !== currentResolution) {
+            flush();
+            currentCell = row.h3_cell;
+            currentResolution = row.resolution;
+            candidates = [];
+        }
+        let area = geometry.get(row.area_id);
+        if (!area) {
+            area = selectArea.get(row.area_id);
+            if (!area) {
+                throw new Error(`soil build: the touch table names delineation ${row.area_id}, which soil_map_unit_area does not hold — the ingest and the reduction disagree about what was written`);
+            }
+            if (geometry.size >= GEOMETRY_CACHE_ENTRIES) {
+                geometry.clear();
+            }
+            geometry.set(row.area_id, area);
+        }
+        candidates.push({
+            areaID: row.area_id,
+            mukey: area.mukey,
+            containment: row.is_full ? SoilCellContainment.Whole : SoilCellContainment.Partial,
+            minLat: area.min_lat,
+            minLon: area.min_lon,
+            maxLat: area.max_lat,
+            maxLon: area.max_lon,
+            rings: area.rings,
+        });
+    }
+    flush();
+    batch.commit();
+    return { cells, sampled, topClassUnderHalf, classless, unsampled, candidatePairs };
+}
+function insertRow(statement, row) {
+    statement.run(row.h3_cell, row.class_shares, row.unrated_share, row.notrateable_share, row.nodata_share, row.other_share, row.mapped_share, row.top_class, row.top_class_share, row.weighting, row.delineations);
+}
+/**
+ * Every map unit's per-unit-area profile, computed once and reused for every cell it reaches.
+ */
+function readMapUnitProfiles(database) {
+    const componentsByMukey = new Map();
+    for (const row of database
+        .prepare("SELECT mukey, comppct_r, compkind, nirrcapcl FROM soil_component")
+        .all()) {
+        const list = componentsByMukey.get(row.mukey);
+        if (list) {
+            list.push(row);
+        }
+        else {
+            componentsByMukey.set(row.mukey, [row]);
+        }
+    }
+    const profiles = new Map();
+    for (const row of database.prepare("SELECT mukey, no_mapping FROM soil_map_unit").all()) {
+        profiles.set(row.mukey, mapUnitProfile(row, componentsByMukey.get(row.mukey) ?? []));
+    }
+    return profiles;
+}
+//# sourceMappingURL=cell-tiers.js.map

package/out/sdk/cell-tiers.js.map

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

package/out/sdk/cells.d.ts

@@ -0,0 +1,118 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The delineation-keyed cell index, and the two numbers the index resolution is chosen from.
+ *
+ *   THE CLASSIFIER ITSELF LIVES IN `@mailwoman/spatial`, because the traps it guards are properties of
+ *   h3-js rather than of SSURGO: a centre-containment polyfill drops every polygon smaller than a cell, an
+ *   exhausted WASM allocator reports success and returns zeros, and the allocator is sized from the
+ *   bounding box. The layer contract states all three as requirements on every polygon builder. What is
+ *   soil-shaped is the ACCUMULATOR below, which keys on the delineation rather than on a hazard class,
+ *   because the reduction weights by the area a delineation covers.
+ *
+ *   EXPECT THE `partial` SHARE TO INVERT AGAINST THE FLOOD LAYER, AND DO NOT READ THAT AS A DEFECT. Flood
+ *   polygons are large against their cells, so most cells fall wholly inside one zone and `compactCells`
+ *   collapses long uniform interiors. Soil delineations are the opposite: 85.4% of `IA153`'s 17,966 of them
+ *   are smaller than one resolution-9 cell, and the median is 24,863 m² against a 105,333 m² cell. Small
+ *   polygons against large cells means most cells are crossed by a boundary — so the `partial` share should
+ *   be HIGH, `compactCells` should yield close to nothing, and the index alone will rarely answer a point
+ *   probe. That is not an argument against storing the geometry; it is the argument for why this layer
+ *   carries the reduced `soil_capability_cell` alongside the index rather than relying on the index the way
+ *   the flood layer can.
+ *
+ *   TWO NUMBERS GET REPORTED AT EACH CANDIDATE RESOLUTION, AND THEY MOVE IN OPPOSITE DIRECTIONS. The
+ *   `partial` cell share says whether the containment index answers most probes alone. The share of cells
+ *   whose top class holds less than half the cell says whether the layer is answering or hedging — the
+ *   cell-grain analogue of NRCS's own `niccdcdpct` distribution, which reads 3.3% below half nationally.
+ *   Going coarser improves the first and worsens the second, and picking between them is what the
+ *   measurement is for.
+ */
+import { type FeatureCells, type MultiPolygonRings } from "@mailwoman/spatial";
+/**
+ * The label this layer's classifier failures carry.
+ */
+export declare const SOIL_CELL_LABEL = "soil cells";
+/**
+ * Classify one delineation — {@link classifyFeatureCells} with this layer's label bound.
+ */
+export declare function classifyDelineationCells(polygons: MultiPolygonRings, targetResolution: number, areaID: string): FeatureCells;
+/**
+ * What one resolution's index came out as.
+ */
+export interface SoilCellIndexMeasurement {
+    resolution: number;
+    /**
+     * Cells the layer reaches at all.
+     */
+    touchedCells: number;
+    /**
+     * Cells lying wholly inside a single delineation, before compaction.
+     */
+    wholeCells: number;
+    /**
+     * Cells a delineation boundary crosses.
+     */
+    partialCells: number;
+    /**
+     * `partialCells / touchedCells` — the share of in-layer probes that cannot be answered from the index alone.
+     */
+    partialShare: number;
+    /**
+     * Whole cells after `compactCells`. Expected to be close to `wholeCells` here rather than far below it: compaction
+     * needs a uniform interior, and small delineations do not produce one.
+     */
+    compactedWholeCells: number;
+    /**
+     * `(cell, delineation)` pairs the index stores.
+     */
+    cellDelineationPairs: number;
+    /**
+     * The mean number of delineations reaching a cell — the direct measure of how mixed a cell is before any rating is
+     * read, and the number that rises as the resolution coarsens.
+     */
+    meanDelineationsPerCell: number;
+    /**
+     * Delineations whose bounding box forced a coarser resolution than the target.
+     */
+    coarsenedFeatures: number;
+    /**
+     * The resolutions actually present, finest last.
+     */
+    resolutions: number[];
+}
+/**
+ * Accumulate one resolution's cell index over a stream of delineations.
+ *
+ * Held as short-cell STRINGS rather than the integers the tables store, because `compactCells` is an h3-js function
+ * over full indexes and round-tripping through the integer form at every step would cost more than the strings do.
+ */
+export declare class SoilCellIndex {
+    #private;
+    readonly resolution: number;
+    constructor(resolution: number);
+    /**
+     * Fold one delineation's classification in.
+     */
+    add(areaID: string, cells: FeatureCells): void;
+    /**
+     * Compact the whole-cell set and report the measurement.
+     *
+     * Compaction is applied to the WHOLE set only — a partial cell's parent is not partial in any useful sense, and
+     * compacting it would claim the fringe covers ground it does not.
+     */
+    finish(): SoilCellIndexMeasurement;
+}
+/**
+ * The measurement as markdown table ROWS — what a build receipt carries, one line per element so a caller printing them
+ * never has to split a joined string back apart.
+ */
+export declare function formatSoilResolutionRows(measurements: ReadonlyArray<SoilCellIndexMeasurement & {
+    mixedCellShare?: number;
+}>): string[];
+/**
+ * The cell integer a short-cell string stores as.
+ */
+export declare function cellToShortInt(cell: string): number;
+//# sourceMappingURL=cells.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cells.d.ts","sourceRoot":"","sources":["../../lib/sdk/cells.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAIN,KAAK,YAAY,EAEjB,KAAK,iBAAiB,EACtB,MAAM,oBAAoB,CAAA;AAG3B;;GAEG;AACH,eAAO,MAAM,eAAe,eAAe,CAAA;AAE3C;;GAEG;AACH,wBAAgB,wBAAwB,CACvC,QAAQ,EAAE,iBAAiB,EAC3B,gBAAgB,EAAE,MAAM,EACxB,MAAM,EAAE,MAAM,GACZ,YAAY,CAEd;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACxC,UAAU,EAAE,MAAM,CAAA;IAClB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAA;IACpB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAA;IACpB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,mBAAmB,EAAE,MAAM,CAAA;IAC3B;;OAEG;IACH,oBAAoB,EAAE,MAAM,CAAA;IAC5B;;;OAGG;IACH,uBAAuB,EAAE,MAAM,CAAA;IAC/B;;OAEG;IACH,iBAAiB,EAAE,MAAM,CAAA;IACzB;;OAEG;IACH,WAAW,EAAE,MAAM,EAAE,CAAA;CACrB;AAED;;;;;GAKG;AACH,qBAAa,aAAa;;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;gBAYf,UAAU,EAAE,MAAM;IAI9B;;OAEG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI;IA6B9C;;;;;OAKG;IACH,MAAM,IAAI,wBAAwB;CA+BlC;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACvC,YAAY,EAAE,aAAa,CAAC,wBAAwB,GAAG;IAAE,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GACjF,MAAM,EAAE,CAaV;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD"}

package/out/sdk/cells.js

@@ -0,0 +1,140 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The delineation-keyed cell index, and the two numbers the index resolution is chosen from.
+ *
+ *   THE CLASSIFIER ITSELF LIVES IN `@mailwoman/spatial`, because the traps it guards are properties of
+ *   h3-js rather than of SSURGO: a centre-containment polyfill drops every polygon smaller than a cell, an
+ *   exhausted WASM allocator reports success and returns zeros, and the allocator is sized from the
+ *   bounding box. The layer contract states all three as requirements on every polygon builder. What is
+ *   soil-shaped is the ACCUMULATOR below, which keys on the delineation rather than on a hazard class,
+ *   because the reduction weights by the area a delineation covers.
+ *
+ *   EXPECT THE `partial` SHARE TO INVERT AGAINST THE FLOOD LAYER, AND DO NOT READ THAT AS A DEFECT. Flood
+ *   polygons are large against their cells, so most cells fall wholly inside one zone and `compactCells`
+ *   collapses long uniform interiors. Soil delineations are the opposite: 85.4% of `IA153`'s 17,966 of them
+ *   are smaller than one resolution-9 cell, and the median is 24,863 m² against a 105,333 m² cell. Small
+ *   polygons against large cells means most cells are crossed by a boundary — so the `partial` share should
+ *   be HIGH, `compactCells` should yield close to nothing, and the index alone will rarely answer a point
+ *   probe. That is not an argument against storing the geometry; it is the argument for why this layer
+ *   carries the reduced `soil_capability_cell` alongside the index rather than relying on the index the way
+ *   the flood layer can.
+ *
+ *   TWO NUMBERS GET REPORTED AT EACH CANDIDATE RESOLUTION, AND THEY MOVE IN OPPOSITE DIRECTIONS. The
+ *   `partial` cell share says whether the containment index answers most probes alone. The share of cells
+ *   whose top class holds less than half the cell says whether the layer is answering or hedging — the
+ *   cell-grain analogue of NRCS's own `niccdcdpct` distribution, which reads 3.3% below half nationally.
+ *   Going coarser improves the first and worsens the second, and picking between them is what the
+ *   measurement is for.
+ */
+import { classifyFeatureCells, compactAcrossResolutions, shortCellToInt, } from "@mailwoman/spatial";
+import { getResolution } from "h3-js";
+/**
+ * The label this layer's classifier failures carry.
+ */
+export const SOIL_CELL_LABEL = "soil cells";
+/**
+ * Classify one delineation — {@link classifyFeatureCells} with this layer's label bound.
+ */
+export function classifyDelineationCells(polygons, targetResolution, areaID) {
+    return classifyFeatureCells(polygons, targetResolution, areaID, SOIL_CELL_LABEL);
+}
+/**
+ * Accumulate one resolution's cell index over a stream of delineations.
+ *
+ * Held as short-cell STRINGS rather than the integers the tables store, because `compactCells` is an h3-js function
+ * over full indexes and round-tripping through the integer form at every step would cost more than the strings do.
+ */
+export class SoilCellIndex {
+    resolution;
+    #whole = new Set();
+    #touched = new Set();
+    /**
+     * `cell → delineation ids`. Every touched cell, so the mean below is over the real population rather than over the
+     * fringe alone.
+     */
+    #byCell = new Map();
+    #coarsened = 0;
+    constructor(resolution) {
+        this.resolution = resolution;
+    }
+    /**
+     * Fold one delineation's classification in.
+     */
+    add(areaID, cells) {
+        if (cells.resolution !== this.resolution) {
+            this.#coarsened++;
+        }
+        for (const cell of cells.whole) {
+            this.#whole.add(cell);
+            this.#record(cell, areaID);
+        }
+        for (const cell of cells.partial) {
+            this.#record(cell, areaID);
+        }
+    }
+    #record(cell, areaID) {
+        this.#touched.add(cell);
+        let areas = this.#byCell.get(cell);
+        if (!areas) {
+            areas = new Set();
+            this.#byCell.set(cell, areas);
+        }
+        areas.add(areaID);
+    }
+    /**
+     * Compact the whole-cell set and report the measurement.
+     *
+     * Compaction is applied to the WHOLE set only — a partial cell's parent is not partial in any useful sense, and
+     * compacting it would claim the fringe covers ground it does not.
+     */
+    finish() {
+        const compacted = compactAcrossResolutions(this.#whole);
+        const resolutions = new Set();
+        for (const cell of this.#touched) {
+            resolutions.add(getResolution(cell));
+        }
+        let pairs = 0;
+        for (const areas of this.#byCell.values()) {
+            pairs += areas.size;
+        }
+        const touched = this.#touched.size;
+        const partial = touched - this.#whole.size;
+        return {
+            resolution: this.resolution,
+            touchedCells: touched,
+            wholeCells: this.#whole.size,
+            partialCells: partial,
+            partialShare: touched ? partial / touched : 0,
+            compactedWholeCells: compacted.length,
+            cellDelineationPairs: pairs,
+            meanDelineationsPerCell: touched ? pairs / touched : 0,
+            coarsenedFeatures: this.#coarsened,
+            resolutions: [...resolutions].toSorted((left, right) => left - right),
+        };
+    }
+}
+/**
+ * The measurement as markdown table ROWS — what a build receipt carries, one line per element so a caller printing them
+ * never has to split a joined string back apart.
+ */
+export function formatSoilResolutionRows(measurements) {
+    return [
+        "| res | touched cells | whole | partial | partial share | whole after compaction | (cell, delineation) pairs | mean delineations/cell | top class under half |",
+        "| --- | ------------- | ----- | ------- | ------------- | ---------------------- | ------------------------- | ---------------------- | -------------------- |",
+        ...measurements.map((m) => `| ${m.resolution} | ${m.touchedCells.toLocaleString()} | ${m.wholeCells.toLocaleString()} | ` +
+            `${m.partialCells.toLocaleString()} | ${(m.partialShare * 100).toFixed(1)}% | ` +
+            `${m.compactedWholeCells.toLocaleString()} | ${m.cellDelineationPairs.toLocaleString()} | ` +
+            `${m.meanDelineationsPerCell.toFixed(2)} | ` +
+            `${m.mixedCellShare === undefined ? "—" : `${(m.mixedCellShare * 100).toFixed(1)}%`} |`),
+    ];
+}
+/**
+ * The cell integer a short-cell string stores as.
+ */
+export function cellToShortInt(cell) {
+    return shortCellToInt(cell);
+}
+//# sourceMappingURL=cells.js.map

package/out/sdk/cells.js.map

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

package/out/sdk/client.d.ts

@@ -0,0 +1,120 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Soil Data Access — NRCS's live SQL service, and the two things this layer asks it: which survey areas
+ *   exist with what version date, and which map unit covers a point.
+ *
+ *   THIS IS AN API REQUEST AND IT GOES THROUGH {@linkcode APIClient}. Small bodies, repeated calls, a
+ *   third-party host with a server-side query timeout and no published rate limit — the pacing, bounded
+ *   retry, response caching and `ResourceError` mapping are exactly what it needs. The survey-area
+ *   ARCHIVES are not: they are 13 to 41 MB file transfers, they stream to disk on raw `fetch`, and
+ *   `download.ts` says so in place.
+ *
+ *   FAILURES COME BACK AS XML, INCLUDING ON A TIMEOUT, AND A JSON-ONLY PARSER MIS-READS THEM. A bad column,
+ *   a blocked query and a query that exceeded the server's own timeout all return an OGC
+ *   `ServiceExceptionReport` document. Measured messages: `Invalid query: Invalid column name
+ *   'nosuchcolumn'.` (HTTP 400), `Invalid query - access denied.`, and `Your query timed out.` — and the
+ *   last one arrives on an HTTP 200. So every response is read as TEXT and checked for the report before
+ *   anything tries to parse it as JSON. A client that branched on the status code alone would read a
+ *   timeout as a successful empty answer, which is the exact shape of lie this program keeps writing down.
+ *
+ *   SCHEMA INTROSPECTION IS REFUSED, SO THE COLUMN NAMES ARE THE PUBLISHED DATA DICTIONARY'S.
+ *   `SELECT COLUMN_NAME FROM INFORMATION_SCHEMA.COLUMNS` answers `Invalid query - access denied.` The
+ *   columns this file names were each verified by querying them successfully.
+ *
+ *   FRESHNESS IS `sacatalog.saverest` AND NEVER A LENGTH PROBE. The download host answers `HEAD` with HTTP
+ *   405 and IGNORES `Range` — a request with `Range: bytes=0-0` returned HTTP 200 and transferred the whole
+ *   27,598,377 bytes — so "just check the size" starts a real download. The tabular service answers the
+ *   freshness question directly instead, and the version date it returns is what the archive's filename
+ *   embeds.
+ */
+import { APIClient, type APIClientConfig, type ClockLike } from "@mailwoman/core/api";
+export { isTransientResourceError } from "@mailwoman/core/api";
+export { ResourceError } from "@mailwoman/core/errors";
+/**
+ * The tabular endpoint. Anonymous: no key, no account, and no rate-limit header on any observed response.
+ */
+export declare const SDA_POST_REST_URL = "https://sdmdataaccess.nrcs.usda.gov/Tabular/post.rest";
+/**
+ * Minimum spacing between Soil Data Access requests, in milliseconds.
+ *
+ * NRCS publishes no rate limit for this service and returned no rate-limit header on any request, so this is courtesy
+ * pacing rather than a published ceiling — stated as such rather than dressed up as a measured limit. It costs an
+ * acquisition run nothing: a whole-state build makes one catalogue call, and the verification's per-point calls are
+ * measured at 1.8 s each anyway.
+ */
+export declare const SDA_MIN_REQUEST_INTERVAL_MS = 500;
+/**
+ * The error a `ServiceExceptionReport` becomes.
+ *
+ * Its own class rather than a bare `Error`, because the three failures it carries need different responses from a
+ * caller: a timeout is worth narrowing the query for, an invalid column is a schema change, and access denied is a
+ * query the service will never run.
+ */
+export declare class SoilDataAccessError extends Error {
+    readonly serviceException: string;
+    constructor(serviceException: string, query: string);
+    /**
+     * Did the service exceed its own query timeout? There is no published figure for it, so the message is the only
+     * signal — and it arrives on an HTTP 200.
+     */
+    get timedOut(): boolean;
+}
+/**
+ * The `<ServiceException>` text inside an OGC exception report, or `undefined` when the body is not one.
+ *
+ * Split from the request so the detection is testable against captured bodies. Both shapes below were taken from the
+ * live service: the report arrives with an XML declaration and an `xmlns` of `http://www.opengis.net/ogc`.
+ */
+export declare function readServiceException(body: string): string | undefined;
+/**
+ * One published survey area, as the catalogue reports it.
+ */
+export interface SurveyAreaCatalogEntry {
+    areasymbol: string;
+    areaname: string;
+    /**
+     * The version-established date as an ISO date — what the archive's filename embeds.
+     */
+    saverest: string;
+    saversion: number;
+}
+/**
+ * A client for Soil Data Access.
+ */
+export declare class SoilDataAccessClient extends APIClient<APIClientConfig> {
+    /**
+     * Run one query and return its rows.
+     *
+     * @throws {SoilDataAccessError} When the service answers with an exception report — including on an HTTP 200, which
+     *   is what a server-side timeout does.
+     */
+    query(sql: string): Promise<string[][]>;
+    /**
+     * The published survey areas whose symbol starts with `prefix` — a state code for a state-scoped build, or a whole
+     * symbol for the single-area rung.
+     *
+     * @throws {Error} When the catalogue returns nothing. An empty catalogue for a prefix a caller named is either a typo
+     *   or a service change, and building zero survey areas while reporting success is the shape this refuses.
+     */
+    readSurveyAreaCatalog(prefix: string): Promise<SurveyAreaCatalogEntry[]>;
+    /**
+     * Which map unit the service's OWN geometry assigns at a point, or `undefined` where it assigns none.
+     *
+     * This is the second path the built artifact is checked against: same authority, different distribution channel, and
+     * geometry this package has never touched. Measured at 1.807 s per point, so a few hundred points is minutes.
+     */
+    mukeyAtPoint(latitude: number, longitude: number): Promise<string | undefined>;
+}
+export interface CreateSoilDataAccessClientOptions {
+    clock?: ClockLike;
+    cacheDirectory?: string;
+    minRequestIntervalMs?: number;
+}
+/**
+ * Build a {@link SoilDataAccessClient} with the disk cache and pacing this package's acquisition path expects.
+ */
+export declare function createSoilDataAccessClient(options?: CreateSoilDataAccessClientOptions): SoilDataAccessClient;
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../lib/sdk/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,SAAS,EAAE,KAAK,eAAe,EAAE,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAA;AASrF,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAEtD;;GAEG;AACH,eAAO,MAAM,iBAAiB,0DAA0D,CAAA;AAExF;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,MAAM,CAAA;AAY9C;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC7C,SAAgB,gBAAgB,EAAE,MAAM,CAAA;gBAE5B,gBAAgB,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IASnD;;;OAGG;IACH,IAAW,QAAQ,IAAI,OAAO,CAE7B;CACD;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMrE;AA4CD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACtC,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,SAAS,CAAC,eAAe,CAAC;IACnE;;;;;OAKG;IACU,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;IA8BpD;;;;;;OAMG;IACU,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,EAAE,CAAC;IAqBrF;;;;;OAKG;IACU,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;CAO3F;AAED,MAAM,WAAW,iCAAiC;IACjD,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,GAAE,iCAAsC,GAAG,oBAAoB,CAahH"}