@mailwoman/soil 9.2.0

package/out/sdk/reduce.js

@@ -0,0 +1,266 @@
+/**
+ * @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 { parseJSONStrict } from "@mailwoman/core/objects";
+import { pointInEncodedRings } from "@mailwoman/spatial";
+import { cellToChildren, cellToLatLng } from "h3-js";
+import { SOIL_SHARE_WEIGHTING } from "#vocabulary";
+/**
+ * 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 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 const CLASS_SHARE_FLOOR = 0.01;
+/**
+ * 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 function mapUnitProfile(mapUnit, components) {
+    if (mapUnit.no_mapping) {
+        return { classShares: new Map(), unrated: 0, notRateable: 0, noData: 1 };
+    }
+    let total = 0;
+    for (const component of components) {
+        total += component.comppct_r;
+    }
+    // A map unit whose components carry no weight at all publishes no readable proportion, so nothing can be apportioned
+    // from it. It is marked `no_mapping` upstream for exactly this reason; reaching here with a zero total means the
+    // upstream check and this one disagree, and answering with an empty distribution would silently drop the delineation's
+    // area out of every share.
+    if (total <= 0) {
+        return { classShares: new Map(), unrated: 0, notRateable: 0, noData: 1 };
+    }
+    const classShares = new Map();
+    let unrated = 0;
+    let notRateable = 0;
+    for (const component of components) {
+        const weight = component.comppct_r / total;
+        if (weight <= 0)
+            continue;
+        if (component.nirrcapcl) {
+            classShares.set(component.nirrcapcl, (classShares.get(component.nirrcapcl) ?? 0) + weight);
+            continue;
+        }
+        // A NULL rating means the survey did not rate this component, and WHY it did not is what separates the two buckets.
+        // A miscellaneous area is a non-soil area — rock outcrop, water — that the capability rating does not apply to; a
+        // named soil with no rating is one the survey chose not to rate. Read as one number they would both say "not
+        // arable", which neither of them says.
+        if (component.compkind === "Miscellaneous area") {
+            notRateable += weight;
+        }
+        else {
+            unrated += weight;
+        }
+    }
+    return { classShares, unrated, notRateable, noData: 0 };
+}
+/**
+ * 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 function reduceCell(cell, resolution, candidates, profiles, h3Cell) {
+    const weights = new Map();
+    let sampled = false;
+    let mappedShare = 1;
+    const whole = candidates.length === 1 ? candidates.find((candidate) => candidate.containment === "whole") : undefined;
+    if (whole) {
+        // Exactly one delineation, and it covers the cell entirely. Nothing else can reach it, so the lattice would return
+        // the same answer at 49 times the cost.
+        weights.set(whole.mukey, 1);
+    }
+    else {
+        sampled = true;
+        const children = cellToChildren(cell, resolution + WEIGHT_LATTICE_DEPTH);
+        let covered = 0;
+        for (const child of children) {
+            const [latitude, longitude] = cellToLatLng(child);
+            const owner = candidateAt(candidates, latitude, longitude);
+            if (!owner)
+                continue;
+            covered++;
+            weights.set(owner.mukey, (weights.get(owner.mukey) ?? 0) + 1);
+        }
+        if (!covered) {
+            // Every child centre fell outside every delineation reaching the cell. The cell IS touched — the index says so —
+            // but no lattice point landed inside, which happens when a sliver clips a corner. Reporting shares over nothing
+            // would divide by zero; reporting a mapped share of zero is the truthful answer, and the row is dropped by the
+            // caller rather than stored as an all-zero distribution.
+            return {
+                row: emptyRow(h3Cell, candidates.length),
+                topClassUnderHalf: false,
+                sampled,
+            };
+        }
+        mappedShare = covered / children.length;
+        for (const [mukey, count] of weights) {
+            weights.set(mukey, count / covered);
+        }
+    }
+    return assembleRow(h3Cell, weights, profiles, mappedShare, candidates.length, sampled);
+}
+/**
+ * The delineation covering a point, or `undefined` where none does.
+ *
+ * The bounding box is the prefilter the geometry table stores precisely so the ray cast runs on the few delineations
+ * that could contain the point rather than on every delineation reaching the cell.
+ */
+function candidateAt(candidates, latitude, longitude) {
+    for (const candidate of candidates) {
+        if (longitude < candidate.minLon ||
+            longitude > candidate.maxLon ||
+            latitude < candidate.minLat ||
+            latitude > candidate.maxLat) {
+            continue;
+        }
+        if (pointInEncodedRings(candidate.rings, longitude, latitude))
+            return candidate;
+    }
+    return undefined;
+}
+/**
+ * Fold the per-map-unit weights through their profiles into the stored row.
+ */
+function assembleRow(h3Cell, weights, profiles, mappedShare, delineations, sampled) {
+    const classShares = new Map();
+    let unrated = 0;
+    let notRateable = 0;
+    let noData = 0;
+    for (const [mukey, weight] of weights) {
+        const profile = profiles.get(mukey);
+        if (!profile) {
+            throw new Error(`soil reduce: cell ${h3Cell} names map unit ${mukey}, which the attribute join does not hold — a missing profile means the join is short, and reducing the remaining candidates would report a well-formed distribution over part of the cell`);
+        }
+        for (const [code, share] of profile.classShares) {
+            classShares.set(code, (classShares.get(code) ?? 0) + share * weight);
+        }
+        unrated += profile.unrated * weight;
+        notRateable += profile.notRateable * weight;
+        noData += profile.noData * weight;
+    }
+    // The floor truncates the long tail component percentages create inside a lattice child. The remainder is stored
+    // rather than dropped, so the five shares sum to 1 and a reader can see how much was folded away.
+    let other = 0;
+    const kept = [];
+    for (const [code, share] of classShares) {
+        if (share < CLASS_SHARE_FLOOR) {
+            other += share;
+        }
+        else {
+            kept.push([code, share]);
+        }
+    }
+    kept.sort((left, right) => right[1] - left[1] || (left[0] < right[0] ? -1 : 1));
+    const top = kept[0];
+    return {
+        row: {
+            h3_cell: h3Cell,
+            class_shares: JSON.stringify(Object.fromEntries(kept.map(([code, share]) => [code, round(share)]))),
+            unrated_share: round(unrated),
+            notrateable_share: round(notRateable),
+            nodata_share: round(noData),
+            other_share: round(other),
+            mapped_share: round(mappedShare),
+            top_class: top ? top[0] : null,
+            top_class_share: top ? round(top[1]) : null,
+            weighting: SOIL_SHARE_WEIGHTING,
+            delineations,
+        },
+        topClassUnderHalf: !top || top[1] < 0.5,
+        sampled,
+    };
+}
+/**
+ * A cell no lattice point landed inside. `mapped_share` zero says exactly that, and the caller drops it rather than
+ * storing an all-zero distribution that would read as a surveyed cell holding nothing.
+ */
+function emptyRow(h3Cell, delineations) {
+    return {
+        h3_cell: h3Cell,
+        class_shares: "{}",
+        unrated_share: 0,
+        notrateable_share: 0,
+        nodata_share: 0,
+        other_share: 0,
+        mapped_share: 0,
+        top_class: null,
+        top_class_share: null,
+        weighting: SOIL_SHARE_WEIGHTING,
+        delineations,
+    };
+}
+/**
+ * Six decimals — a millionth of a cell, far below the lattice's own 2% granularity, and enough that the stored shares
+ * still sum to 1 within a rounding error a reader can see is rounding.
+ */
+const SHARE_DECIMALS = 6;
+function round(value) {
+    return Number(value.toFixed(SHARE_DECIMALS));
+}
+/**
+ * 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 function shareTotal(row) {
+    const classes = parseJSONStrict(row.class_shares);
+    let total = row.unrated_share + row.notrateable_share + row.nodata_share + row.other_share;
+    for (const share of Object.values(classes)) {
+        total += share;
+    }
+    return total;
+}
+//# sourceMappingURL=reduce.js.map

package/out/sdk/reduce.js.map

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

package/out/sdk/survey-area.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   One survey area's attributes, its own metadata, and its mapped footprint.
+ *
+ *   THE FOOTPRINT IS THE SURVEY-AREA OUTLINE, NEVER THE UNION OF THE RATED POLYGONS. `NOTCOM`,
+ *   access-denied and `NOTPUB` map units are INSIDE the footprint and carry no rating, so a footprint taken
+ *   from the rated set would report them as unmapped when the authority has declared exactly what they are.
+ *   The archive ships the outline as its own shapefile — `soilsa_a_<areasymbol>.shp`, one feature — which is
+ *   why this layer never has to reconstruct it.
+ *
+ *   THE REFRESH DATE IS NOT THE SURVEY DATE, AND CONFLATING THEM IS THE CURRENCY LIE THIS FILE EXISTS TO
+ *   PREVENT. `IA153` carries `saverest` 2025-09-09 and version 28, and the FGDC lineage inside the same
+ *   archive cites `Soil Survey of Polk County, Iowa`, 1:15,840, **1960**. The dataset's own
+ *   time-period-of-content runs 1998-09-22 to 2025-09-09, so a consumer reading that as survey currency
+ *   reads it wrong by sixty-five years. Both dates are stored, apart, with the title the older one came
+ *   from so it is checkable rather than assertible.
+ *
+ *   TWO SCALES, ALSO DIFFERENT FACTS. `legend.projectscale` is 12,000 for `IA153` — the scale the map units
+ *   were digitized at. The 1960 source citation's own `srcscale` is 15,840 — the scale the ground was
+ *   walked at. Storing one as the other would answer the enlargement caveat's question wrongly.
+ *
+ *   THE LICENCE IS CHECKED PER SURVEY AREA, against the `useconst` element of the metadata that area ships.
+ *   An area whose use constraints no longer say "This is public information" is a licence change, and a
+ *   build that absorbed one would ship an artifact under terms nobody checked. The text is boilerplate
+ *   repeated across SSURGO, which is why asserting it is cheap and why a change in it is loud.
+ */
+import type { ParsedGeometry } from "@mailwoman/spatial";
+import type { PathBuilderLike } from "path-ts";
+import type { SoilComponentTable, SoilMapUnitTable } from "#schema";
+import { type DomainMember } from "#sdk/tabular";
+/**
+ * The declared domains this layer validates against, and stores.
+ *
+ * `capability_class` is shared by `nirrcapcl`, `irrcapcl` and `muaggatt.niccdcd`, which is why one domain covers three
+ * columns.
+ */
+export declare const STORED_DOMAINS: readonly ["capability_class", "capability_subclass", "farmland_classification", "component_kind", "mapunit_kind", "mapunit_status"];
+/**
+ * One survey area's tabular attributes, already joined and validated.
+ */
+export interface SurveyAreaAttributes {
+    areasymbol: string;
+    areaname: string;
+    saverest: string;
+    saversion: number | null;
+    surveySourceDate: string | null;
+    surveySourceTitle: string | null;
+    sourceScale: number | null;
+    mappingScale: number | null;
+    /**
+     * The area the authority publishes for this survey area, in acres — the independent witness the ring-area check
+     * compares against.
+     */
+    areaAcres: number | null;
+    mapUnits: SoilMapUnitTable[];
+    components: SoilComponentTable[];
+    domains: DomainMember[];
+}
+/**
+ * Read one survey area's tabular export.
+ *
+ * @throws {Error} When the metadata's use constraints no longer carry the public-information sentence, when a `Choice`
+ *   column holds a value outside the authority's own declared domain, or when the export declares no legend row.
+ */
+export declare function readSurveyAreaAttributes(tabularDirectory: PathBuilderLike, areaSymbol: string): Promise<SurveyAreaAttributes>;
+/**
+ * What the shipped FGDC metadata says about this survey area's dates and its licence.
+ */
+export interface FGDCMetadata {
+    /**
+     * The citation's own `pubdate`, as an ISO date — the refresh.
+     */
+    publicationDate: string;
+    /**
+     * The OLDEST source citation date in the lineage, as an ISO date or a bare year.
+     */
+    oldestSourceDate: string | null;
+    oldestSourceTitle: string | null;
+    oldestSourceScale: number | null;
+}
+/**
+ * Read the metadata NRCS ships inside the archive.
+ *
+ * Targeted extraction rather than a general XML parse, and NOT for want of a parser — `@mailwoman/core` ships
+ * `htmlparser2`. A parser RECOVERS an unclosed element by giving it the rest of the document as its content, and the
+ * two values below that throw would then stamp the artifact with that content instead. {@link elementText} answers
+ * `undefined` for an element it cannot read, which is what makes the throw reachable. Every value this reader cannot
+ * find is reported as `null` EXCEPT the publication date and the licence sentence, which throw — those two decide the
+ * artifact's vintage and whether it may be shipped at all, and neither has a safe default.
+ *
+ * @throws {Error} When the metadata carries no publication date, or its use constraints no longer carry the
+ *   public-information sentence.
+ */
+export declare function readFGDCMetadata(xml: string, areaSymbol: string): FGDCMetadata;
+/**
+ * Read the survey area's own outline shapefile as a GeoJSON geometry.
+ *
+ * @throws {Error} When the shapefile holds anything other than exactly one feature. Taking the first of several would
+ *   silently choose which ground the coverage claim is about.
+ */
+export declare function readSurveyAreaOutline(shapefilePath: string): Promise<ParsedGeometry>;
+//# sourceMappingURL=survey-area.d.ts.map

package/out/sdk/survey-area.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"survey-area.d.ts","sourceRoot":"","sources":["../../lib/sdk/survey-area.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AACnE,OAAO,EAAsE,KAAK,YAAY,EAAE,MAAM,cAAc,CAAA;AAUpH;;;;;GAKG;AACH,eAAO,MAAM,cAAc,qIAOjB,CAAA;AAEV;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B;;;OAGG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,QAAQ,EAAE,gBAAgB,EAAE,CAAA;IAC5B,UAAU,EAAE,kBAAkB,EAAE,CAAA;IAChC,OAAO,EAAE,YAAY,EAAE,CAAA;CACvB;AAED;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAC7C,gBAAgB,EAAE,eAAe,EACjC,UAAU,EAAE,MAAM,GAChB,OAAO,CAAC,oBAAoB,CAAC,CAkI/B;AA2ED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B;;OAEG;IACH,eAAe,EAAE,MAAM,CAAA;IACvB;;OAEG;IACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAA;CAChC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,YAAY,CA0B9E;AAuFD;;;;;GAKG;AACH,wBAAsB,qBAAqB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAqB1F"}