@mailwoman/soil 9.4.0 → 10.1.0

package/out/sdk/reduce.js

@@ -3,69 +3,42 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   The reduction: the containment index, read once, into one per-cell distribution both consumers share.
+ *   Reduces the delineations that reach a cell into that cell's capability-class distribution.
  *
- *   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.
+ *   The result is a distribution because most map units mix several soil components.
+ *   The survey cannot separate those components at its mapping scale. Shares are normalized over the mapped part of the cell.
+ *   `mapped_share` records how large that part is. Capability class 8 is a rated class, so it is stored as a
+ *   class share. The unrated share, the no-data share and the not-rateable share each have their own column.
  */
-import { parseJSONStrict } from "@mailwoman/core/json";
+import { parseJSONStrict, stringifyJSON } from "@mailwoman/core/json";
 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.
+ * The number of H3 levels below the index resolution at which the weighting lattice samples.
  *
- * 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.
+ * Children at a finer resolution have equal area, so counting which delineation
+ * covers each child center estimates the covered area.
+ * A depth of 2 gives 49 children, or about 2% per child.
+ *
+ * NRCS publishes component shares no finer than 2%, and each extra level costs seven times as much.
  */
 export const WEIGHT_LATTICE_DEPTH = 2;
 /**
- * Class shares below this are folded into `other_share` rather than stored.
+ * The class share below which a class is added to `other_share` instead of 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.
+ * The floor is below the lattice's 2% step, so it only removes the small shares
+ * that minor components contribute.
+ * The reducer adds them to `other_share` so all shares 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.
+ * Builds the profile of one map unit from its components.
  *
- * 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.
+ * A `no_mapping` map unit contributes only to `noData`, because it has no soil mapping.
  *
- * 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.
+ * Components are weighted by `comppct_r`, the component's representative percentage of its map unit.
+ * The weights are divided by their actual total, because the percentages may not sum to 100.
  */
 export function mapUnitProfile(mapUnit, components) {
     if (mapUnit.no_mapping) {
@@ -75,10 +48,8 @@ export function mapUnitProfile(mapUnit, components) {
     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.
+    // Components with zero total weight give no proportions, so the map unit counts as no data.
+    // An empty distribution would drop the delineation's area from every share.
     if (total <= 0) {
         return { classShares: new Map(), unrated: 0, notRateable: 0, noData: 1 };
     }
@@ -93,10 +64,8 @@ export function mapUnitProfile(mapUnit, components) {
             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.
+        // A miscellaneous area, such as rock outcrop or water, cannot take a capability rating.
+        // Any other component with a NULL rating is a soil that the survey did not rate.
         if (component.compkind === "Miscellaneous area") {
             notRateable += weight;
         }
@@ -107,11 +76,11 @@ export function mapUnitProfile(mapUnit, components) {
     return { classShares, unrated, notRateable, noData: 0 };
 }
 /**
- * Reduce one cell.
+ * Reduces 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.
+ * @throws {Error} When a candidate's map unit has no profile.
+ * A missing profile means the attribute join is incomplete.
+ * The remaining candidates would describe only part of the cell.
  */
 export function reduceCell(cell, resolution, candidates, profiles, h3Cell) {
     const weights = new Map();
@@ -119,8 +88,7 @@ export function reduceCell(cell, resolution, candidates, profiles, h3Cell) {
     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.
+        // A single delineation covers the whole cell, so the lattice would give the same answer.
         weights.set(whole.mukey, 1);
     }
     else {
@@ -136,10 +104,10 @@ export function reduceCell(cell, resolution, candidates, profiles, h3Cell) {
             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.
+            // No child center fell inside a delineation.
+            // A sliver can clip only a corner.
+            // This row has a mapped share of zero.
+            // The caller drops it.
             return {
                 row: emptyRow(h3Cell, candidates.length),
                 topClassUnderHalf: false,
@@ -154,10 +122,10 @@ export function reduceCell(cell, resolution, candidates, profiles, h3Cell) {
     return assembleRow(h3Cell, weights, profiles, mappedShare, candidates.length, sampled);
 }
 /**
- * The delineation covering a point, or `undefined` where none does.
+ * Returns the delineation that covers a point, or `undefined` when 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.
+ * A bounding-box test runs first so that the ray cast runs only on delineations
+ * that could contain the point.
  */
 function candidateAt(candidates, latitude, longitude) {
     for (const candidate of candidates) {
@@ -173,7 +141,7 @@ function candidateAt(candidates, latitude, longitude) {
     return undefined;
 }
 /**
- * Fold the per-map-unit weights through their profiles into the stored row.
+ * Combines the per-map-unit weights with their profiles into the stored row.
  */
 function assembleRow(h3Cell, weights, profiles, mappedShare, delineations, sampled) {
     const classShares = new Map();
@@ -192,8 +160,7 @@ function assembleRow(h3Cell, weights, profiles, mappedShare, delineations, sampl
         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.
+    // Classes below the floor go into `other_share` so that the shares still sum to 1.
     let other = 0;
     const kept = [];
     for (const [code, share] of classShares) {
@@ -209,7 +176,7 @@ function assembleRow(h3Cell, weights, profiles, mappedShare, delineations, sampl
     return {
         row: {
             h3_cell: h3Cell,
-            class_shares: JSON.stringify(Object.fromEntries(kept.map(([code, share]) => [code, round(share)]))),
+            class_shares: stringifyJSON(Object.fromEntries(kept.map(([code, share]) => [code, round(share)]))),
             unrated_share: round(unrated),
             notrateable_share: round(notRateable),
             nodata_share: round(noData),
@@ -225,8 +192,10 @@ function assembleRow(h3Cell, weights, profiles, mappedShare, delineations, sampl
     };
 }
 /**
- * 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.
+ * Returns the row for a cell that no lattice point landed in.
+ *
+ * The caller drops a row with a zero `mapped_share`, because storing it would
+ * look like a surveyed cell with no soil.
  */
 function emptyRow(h3Cell, delineations) {
     return {
@@ -244,16 +213,16 @@ function emptyRow(h3Cell, 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.
+ * The number of decimals kept in a stored share, far finer than the lattice's 2% step.
  */
 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.
+ * Returns the sum of a stored row's class shares and four other shares.
+ *
+ * Tests use it to check that the shares sum to 1.
  */
 export function shareTotal(row) {
     const classes = parseJSONStrict(row.class_shares);

package/out/sdk/reduce.js.map

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

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

@@ -2,40 +2,14 @@
  * @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.
+ * The declared domains this layer validates against and stores; `capability_class`
+ * covers `nirrcapcl`, `irrcapcl` and `muaggatt.niccdcd`.
  */
 export declare const STORED_DOMAINS: readonly ["capability_class", "capability_subclass", "farmland_classification", "component_kind", "mapunit_kind", "mapunit_status"];
 /**
@@ -51,8 +25,8 @@ export interface SurveyAreaAttributes {
     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.
+     * 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[];
@@ -62,44 +36,38 @@ export interface SurveyAreaAttributes {
 /**
  * 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.
+ * @throws {Error} When the metadata's use constraints no longer include 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.
+ * What the shipped FGDC metadata records about this survey area's dates and its license.
  */
 export interface FGDCMetadata {
     /**
-     * The citation's own `pubdate`, as an ISO date — the refresh.
+     * The citation's own `pubdate` as an ISO date — the refresh rather than the survey date.
      */
     publicationDate: string;
     /**
-     * The OLDEST source citation date in the lineage, as an ISO date or a bare year.
+     * 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.
+ * Read the metadata nrcs ships inside the archive.
  *
- * @throws {Error} When the metadata carries no publication date, or its use constraints no longer carry the
- *   public-information sentence.
+ * @throws {Error} When the metadata has no publication date, or its use constraints
+ * no longer include 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.
+ * @throws {Error} When the shapefile holds anything other than exactly one feature.
+ * The function would silently choose which ground the coverage claim describes if it took the first feature.
  */
-export declare function readSurveyAreaOutline(shapefilePath: string): Promise<ParsedGeometry>;
+export declare function readSurveyAreaOutline(shapefilePath: PathBuilderLike): Promise<ParsedGeometry>;
 //# sourceMappingURL=survey-area.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"survey-area.d.ts","sourceRoot":"","sources":["../../sdk/survey-area.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,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;;;GAGG;AACH,eAAO,MAAM,cAAc,YAC1B,kBAAkB,EAClB,qBAAqB,EACrB,yBAAyB,EACzB,gBAAgB,EAChB,cAAc,EACd,gBAAgB,CACP,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;;;;;;GAMG;AACH,wBAAsB,wBAAwB,CAC7C,gBAAgB,EAAE,eAAe,EACjC,UAAU,EAAE,MAAM,GAChB,OAAO,CAAC,oBAAoB,CAAC,CAkI/B;AAmED;;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;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,YAAY,CA0B9E;AAkFD;;;;;GAKG;AACH,wBAAsB,qBAAqB,CAAC,aAAa,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAqBnG"}

package/out/sdk/survey-area.js

@@ -2,40 +2,15 @@
  * @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 { parseJSONStrict } from "@mailwoman/core/json";
+import { parseJSONStrict, stringifyJSON } from "@mailwoman/core/json";
 import { runFile } from "@mailwoman/core/process";
+import { normalizeWhitespace } from "@mailwoman/core/strings/format";
 import { domainCodes, readDeclaredDomains, readTable, readTabularDictionary } from "#sdk/tabular";
 import { COINTERP_OVERALL_RULE_DEPTH, farmlandScope, NCCPI_V3_RULE_NAME, SSURGO_NO_MAPPING_NAMES, SSURGO_NO_MAPPING_SYMBOLS, SSURGO_PUBLIC_INFORMATION_SENTENCE, } from "#vocabulary";
 /**
- * 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.
+ * The declared domains this layer validates against and stores; `capability_class`
+ * covers `nirrcapcl`, `irrcapcl` and `muaggatt.niccdcd`.
  */
 export const STORED_DOMAINS = [
     "capability_class",
@@ -48,8 +23,9 @@ export const STORED_DOMAINS = [
 /**
  * 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.
+ * @throws {Error} When the metadata's use constraints no longer include 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 async function readSurveyAreaAttributes(tabularDirectory, areaSymbol) {
     const dictionary = await readTabularDictionary(tabularDirectory);
@@ -114,8 +90,8 @@ export async function readSurveyAreaAttributes(tabularDirectory, areaSymbol) {
         return {
             cokey: row.cokey,
             mukey: row.mukey,
-            // A blank `comppct_r` is a component with no declared weight. Zero is the truthful reading — it contributes
-            // nothing to a weighted share — and it is recorded rather than dropped, so the component still appears.
+            // A blank `comppct_r` is a component with no declared weight, recorded as zero
+            // rather than dropped so the component still appears.
             comppct_r: row.comppct_r ? Number(row.comppct_r) : 0,
             compname: nullable(row.compname),
             compkind: nullable(row.compkind),
@@ -163,11 +139,8 @@ export async function readSurveyAreaAttributes(tabularDirectory, areaSymbol) {
 /**
  * A polygon the authority drew with no soil mapping behind it.
  *
- * Three signals rather than one, because the source encodes the same fact three ways and each on its own has a gap: the
- * symbol (`NOTCOM`, `NOTPUB`), the name (`Area not surveyed, access denied`), and the structural case of a map unit
- * carrying NO components at all. A map unit with no components has nothing to rate whatever it is called, and reading
- * it as "rated nothing" rather than "no mapping" would put it in `unrated_share` — a claim that the survey looked and
- * declined, when it did not look.
+ * A map unit with no components has no component to rate, so it reads as no mapping
+ * rather than assigned no rating.
  */
 function isNoMapping(musym, muname, componentCount) {
     if (SSURGO_NO_MAPPING_SYMBOLS.has(musym.toUpperCase()))
@@ -179,28 +152,23 @@ function isNoMapping(musym, muname, componentCount) {
 /**
  * Refuse a value outside the authority's own declared domain.
  *
- * An unknown code is a source-schema change, which is the event a reader most needs to hear about; coercing it to a
- * nearest neighbour or to NULL converts "the source changed" into "there is nothing here". A BLANK is not a violation:
- * NULL is a real state in every one of these columns and means something specific — for `nirrcapcl` it means the survey
- * did not rate the component, which is not class 8.
+ * A blank is a real NULL state rather than a violation, recording that the
+ * survey did not rate the component.
  */
 function assertDeclared(declared, value, domain, where) {
     if (!value)
         return;
     if (declared.has(value))
         return;
-    throw new Error(`soil survey area: ${where} holds ${JSON.stringify(value)}, which is not in the authority's declared ${domain} domain (${declared.size} members, read from the archive's own msdomdet.txt) — an unknown code is a source-schema change, and coercing it would turn "the source changed" into "there is nothing here"`);
+    throw new Error(`soil survey area: ${where} holds ${stringifyJSON(value)}, which is not in the authority's declared ${domain} domain (${declared.size} members, read from the archive's own msdomdet.txt) — an unknown code is a source-schema change, and coercing it would turn "the source changed" into "there is nothing here"`);
 }
 function nullable(value) {
     return value || null;
 }
 /**
- * The NCCPI v3.0 overall index per component.
+ * The nccpi v3.0 overall index per component.
  *
- * `cointerp` is the largest table in the export — 157,063 rows for `IA153`, read in 0.36 s — and the overall rule is
- * one row per component at {@link COINTERP_OVERALL_RULE_DEPTH}: 369 of 369 components on `IA153`, of which 327 carry a
- * value. Sub-rules at greater depths are the submodels (corn, soybeans, small grains, cotton), which this layer does
- * not carry.
+ * Sub-rules at greater depths are submodels this layer does not include.
  */
 async function readNCCPI(tabularDirectory, dictionary) {
     const rows = await readTable(tabularDirectory, dictionary, "cointerp", [
@@ -222,22 +190,15 @@ async function readNCCPI(tabularDirectory, dictionary) {
     return byCokey;
 }
 /**
- * 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.
+ * Read the metadata nrcs ships inside the archive.
  *
- * @throws {Error} When the metadata carries no publication date, or its use constraints no longer carry the
- *   public-information sentence.
+ * @throws {Error} When the metadata has no publication date, or its use constraints
+ * no longer include the public-information sentence.
  */
 export function readFGDCMetadata(xml, areaSymbol) {
     const useConstraints = elementText(xml, "useconst");
     if (!useConstraints?.includes(SSURGO_PUBLIC_INFORMATION_SENTENCE)) {
-        throw new Error(`soil survey area: ${areaSymbol}'s FGDC use constraints do not carry ${JSON.stringify(SSURGO_PUBLIC_INFORMATION_SENTENCE)} — that sentence is the grant this layer ships on, so a survey area without it must not be built into a distributable artifact`);
+        throw new Error(`soil survey area: ${areaSymbol}'s FGDC use constraints do not carry ${stringifyJSON(SSURGO_PUBLIC_INFORMATION_SENTENCE)} — that sentence is the grant this layer ships on, so a survey area without it must not be built into a distributable artifact`);
     }
     const publicationDate = elementText(xml, "pubdate");
     if (!publicationDate) {
@@ -253,33 +214,30 @@ export function readFGDCMetadata(xml, areaSymbol) {
     };
 }
 /**
- * The lineage's source citations: what the polygons rest on, and when each was made.
+ * The lineage's source citations — what the polygons rest on and when each was made.
  */
 function readSourceCitations(xml) {
     const citations = [];
     for (const body of elementBlocks(xml, "srcinfo")) {
-        // `caldate` for a single date, `begdate` for a range. A range's END is when the source stopped being collected;
-        // its BEGINNING is when the ground was first looked at, which is the fact this layer is carrying.
+        // `caldate` stores a single date.
+        // `begdate` stores a range's start date in this layer.
         const date = elementText(body, "caldate") ?? elementText(body, "begdate");
         if (!date)
             continue;
         const scale = elementText(body, "srcscale");
         citations.push({
             date: date.trim(),
-            title: (elementText(body, "title") ?? "").replaceAll(/\s+/gu, " ").trim(),
+            title: normalizeWhitespace(elementText(body, "title") ?? ""),
             scale: scale ? Number(scale) : null,
         });
     }
     return citations;
 }
 /**
- * The text of the first `<name>` element, whitespace left alone.
+ * The text of the first `<name>` element, with whitespace preserved.
  *
- * INDEX SCANS RATHER THAN A REGEX, AND THAT IS A CORRECTNESS CHOICE RATHER THAN A SPEED ONE. The obvious form — ``new
- * RegExp(`<${name}>([\\s\\S]*?)</${name}>`)`` — backtracks polynomially on a document whose opening tag has no closing
- * partner: the lazy run re-scans to the end from every candidate start. The input here is a 43,251-character document
- * that arrived over the network inside a downloaded archive, so "a malformed one cannot happen" is not a claim this
- * reader gets to make. Two `indexOf` calls answer the same question in one pass.
+ * Two `indexOf` calls avoid the polynomial backtracking a regex takes on a document
+ * whose opening tag has no closing partner.
  */
 function elementText(xml, name) {
     const open = `<${name}>`;
@@ -288,13 +246,11 @@ function elementText(xml, name) {
         return undefined;
     const from = start + open.length;
     const end = xml.indexOf(`</${name}>`, from);
-    // An element with no closing tag is unreadable, not empty — the same answer an absent element gets, because both
-    // mean the value could not be read rather than that it is blank.
+    // An element with no closing tag is unreadable rather than empty, the same answer an absent element gets.
     return end === -1 ? undefined : xml.slice(from, end);
 }
 /**
- * Every `<name>` element's inner text, in document order. The repeating counterpart of {@link elementText}, and linear
- * for the same reason.
+ * Every `<name>` element's inner text in document order, the repeating counterpart of {@link elementText}.
  */
 function elementBlocks(xml, name) {
     const open = `<${name}>`;
@@ -314,8 +270,8 @@ function elementBlocks(xml, name) {
     }
 }
 /**
- * FGDC dates arrive as `YYYY` or `YYYYMMDD`. Both are kept as they are meant — a bare year is a bare year, and padding
- * it to January 1 would invent a precision the citation does not claim.
+ * A bare year stays bare, since padding it to January 1 would invent a precision
+ * the citation does not claim.
  */
 function normalizeFGDCDate(value) {
     const trimmed = value.trim();
@@ -325,8 +281,8 @@ function normalizeFGDCDate(value) {
 /**
  * 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.
+ * @throws {Error} When the shapefile holds anything other than exactly one feature.
+ * The function would silently choose which ground the coverage claim describes if it took the first feature.
  */
 export async function readSurveyAreaOutline(shapefilePath) {
     const { stdout } = await runFile("ogr2ogr", ["-f", "GeoJSON", "/vsistdout/", "-t_srs", "EPSG:4326", shapefilePath], {