@mailwoman/soil 9.4.0 → 10.1.0

package/out/sdk/cells.d.ts

@@ -3,35 +3,11 @@
  * @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.
+ *   The delineation-keyed cell index, plus the partial-cell and mixed-top-class shares that choose its resolution.
  */
 import { type FeatureCells, type MultiPolygonRings } from "@mailwoman/spatial";
 /**
- * The label this layer's classifier failures carry.
+ * The label assigned to this layer's classifier failures.
  */
 export declare const SOIL_CELL_LABEL = "soil cells";
 /**
@@ -56,12 +32,13 @@ export interface SoilCellIndexMeasurement {
      */
     partialCells: number;
     /**
-     * `partialCells / touchedCells` — the share of in-layer probes that cannot be answered from the index alone.
+     * `partialCells / touchedCells`, the share of in-layer probes that cannot
+     * be answered using only the index.
      */
     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.
+     * Whole cells after `compactCells`, expected to be close to `wholeCells` here
+     * because small delineations do not produce a uniform interior.
      */
     compactedWholeCells: number;
     /**
@@ -69,8 +46,8 @@ export interface SoilCellIndexMeasurement {
      */
     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.
+     * The mean number of delineations reaching a cell measures how mixed a cell is
+     * before any rating is read and rises as the resolution coarsens.
      */
     meanDelineationsPerCell: number;
     /**
@@ -83,10 +60,9 @@ export interface SoilCellIndexMeasurement {
     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.
+ * Accumulates one resolution's cell index over a stream of delineations,
+ * held as short-cell strings because `compactCells` needs full h3-js indexes
+ * and round-tripping through the integer form would cost more.
  */
 export declare class SoilCellIndex {
     #private;
@@ -97,16 +73,14 @@ export declare class SoilCellIndex {
      */
     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.
+     * Compacts the whole-cell set and reports the measurement, applying compaction to the
+     * whole set only because a partial cell's parent would claim fringe ground.
      */
     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.
+ * The measurement as markdown table rows, one line per element so a caller never
+ * has to split a joined string back apart.
  */
 export declare function formatSoilResolutionRows(measurements: ReadonlyArray<SoilCellIndexMeasurement & {
     mixedCellShare?: number;

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

@@ -1 +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"}
+{"version":3,"file":"cells.d.ts","sourceRoot":"","sources":["../../sdk/cells.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;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;;;OAGG;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;;;;GAIG;AACH,qBAAa,aAAa;;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAY3B,YAAY,UAAU,EAAE,MAAM,EAE7B;IAED;;OAEG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI,CAa7C;IAgBD;;;OAGG;IACH,MAAM,IAAI,wBAAwB,CA8BjC;CACD;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

@@ -3,36 +3,12 @@
  * @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.
+ *   The delineation-keyed cell index, plus the partial-cell and mixed-top-class shares that choose its resolution.
  */
 import { classifyFeatureCells, compactAcrossResolutions, shortCellToInt, } from "@mailwoman/spatial";
 import { getResolution } from "h3-js";
 /**
- * The label this layer's classifier failures carry.
+ * The label assigned to this layer's classifier failures.
  */
 export const SOIL_CELL_LABEL = "soil cells";
 /**
@@ -42,18 +18,17 @@ 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.
+ * Accumulates one resolution's cell index over a stream of delineations,
+ * held as short-cell strings because `compactCells` needs full h3-js indexes
+ * and round-tripping through the integer form would cost more.
  */
 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.
+     * `cell → delineation ids` for every touched cell, so the mean is over the
+     * real population rather than only the fringe.
      */
     #byCell = new Map();
     #coarsened = 0;
@@ -85,10 +60,8 @@ export class SoilCellIndex {
         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.
+     * Compacts the whole-cell set and reports the measurement, applying compaction to the
+     * whole set only because a partial cell's parent would claim fringe ground.
      */
     finish() {
         const compacted = compactAcrossResolutions(this.#whole);
@@ -117,8 +90,8 @@ export class SoilCellIndex {
     }
 }
 /**
- * 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.
+ * The measurement as markdown table rows, one line per element so a caller never
+ * has to split a joined string back apart.
  */
 export function formatSoilResolutionRows(measurements) {
     return [

package/out/sdk/cells.js.map

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

package/out/sdk/client.d.ts

@@ -2,46 +2,17 @@
  * @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";
+import type { PathBuilderLike } from "path-ts";
 /**
- * The tabular endpoint. Anonymous: no key, no account, and no rate-limit header on any observed response.
+ * Sends anonymous requests to the Soil Data Access tabular query endpoint.
+ * Requests need no key or account.
  */
 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.
+ * Sets the minimum spacing between Soil Data Access requests.
+ * NRCS publishes no rate limit for the service.
  */
 export declare const SDA_MIN_REQUEST_INTERVAL_MS = 500;
 /**
@@ -51,7 +22,8 @@ export interface SurveyAreaCatalogEntry {
     areasymbol: string;
     areaname: string;
     /**
-     * The version-established date as an ISO date — what the archive's filename embeds.
+     * The version-established date as an ISO date.
+     * The survey area's archive filename embeds it.
      */
     saverest: string;
     saversion: number;
@@ -61,35 +33,38 @@ export interface SurveyAreaCatalogEntry {
  */
 export declare class SoilDataAccessClient extends APIClient<APIClientConfig> {
     /**
-     * Run one query and return its rows.
+     * Runs one SQL query and returns its rows as strings, with NULL as an empty string.
      *
-     * @throws {OGCServiceError} When the service answers with an exception report — including on an HTTP 200, which is
-     *   what a server-side timeout does.
+     * @throws {OGCServiceError} When the service answers with an exception report,
+     * including an HTTP 200 response.
+     * A server-side timeout uses that status.
      */
     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.
+     * Returns the published survey areas whose symbol starts with `prefix`,
+     * such as a state code or one whole area symbol.
      *
-     * @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.
+     * @throws {Error} When no survey area matches, because a build over an empty set
+     * would otherwise report success having written no rows.
      */
     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.
+     * Returns the map unit key the service's own geometry assigns at a point, or `undefined`,
+     * as a cross-check against the authority through a channel this package never processed.
      */
     mukeyAtPoint(latitude: number, longitude: number): Promise<string | undefined>;
 }
+/**
+ * Overrides the clock, the HTTP cache directory and the request spacing used
+ * by {@link createSoilDataAccessClient}.
+ */
 export interface CreateSoilDataAccessClientOptions {
     clock?: ClockLike;
-    cacheDirectory?: string;
+    cacheDirectory?: PathBuilderLike;
     minRequestIntervalMs?: number;
 }
 /**
- * Build a {@link SoilDataAccessClient} with the disk cache and pacing this package's acquisition path expects.
+ * Creates a {@link SoilDataAccessClient} with retries, a 12-hour disk cache and the default request pacing.
  */
 export declare function createSoilDataAccessClient(options?: CreateSoilDataAccessClientOptions): SoilDataAccessClient;
 //# sourceMappingURL=client.d.ts.map

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

@@ -1 +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,EAA+B,MAAM,qBAAqB,CAAA;AASlH;;GAEG;AACH,eAAO,MAAM,iBAAiB,0DAA0D,CAAA;AAExF;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,MAAM,CAAA;AAY9C;;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;IA4BpD;;;;;;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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../sdk/client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,KAAK,eAAe,EAAE,KAAK,SAAS,EAA+B,MAAM,qBAAqB,CAAA;AAGlH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAK9C;;;GAGG;AACH,eAAO,MAAM,iBAAiB,0DAA0D,CAAA;AAExF;;;GAGG;AACH,eAAO,MAAM,2BAA2B,MAAM,CAAA;AAI9C;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACtC,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAEhB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,SAAS,CAAC,eAAe,CAAC;IACnE;;;;;;OAMG;IACU,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAuBnD;IAED;;;;;;OAMG;IACU,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAmBpF;IAED;;;OAGG;IACU,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAM1F;CACD;AAED;;;GAGG;AACH,MAAM,WAAW,iCAAiC;IACjD,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,cAAc,CAAC,EAAE,eAAe,CAAA;IAChC,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,GAAE,iCAAsC,GAAG,oBAAoB,CAahH"}

package/out/sdk/client.js

@@ -2,86 +2,44 @@
  * @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, assertNoOGCServiceException } from "@mailwoman/core/api";
 import { buildDiskStorage } from "@mailwoman/core/api/disk-storage";
-import { dataRootPath } from "@mailwoman/core/data-root";
-import { parseJSONStrict } from "@mailwoman/core/json";
+import { parseJSONStrict, stringifyJSON } from "@mailwoman/core/json";
+import { soilDatabasePath } from "#paths";
 import { saverestToISODate } from "#sdk/tabular";
-// Re-exported so a caller branching on this client's failures needs exactly one import.
 /**
- * The tabular endpoint. Anonymous: no key, no account, and no rate-limit header on any observed response.
+ * Sends anonymous requests to the Soil Data Access tabular query endpoint.
+ * Requests need no key or account.
  */
 export 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.
+ * Sets the minimum spacing between Soil Data Access requests.
+ * NRCS publishes no rate limit for the service.
  */
 export const SDA_MIN_REQUEST_INTERVAL_MS = 500;
-/**
- * How long a cached Soil Data Access response stays fresh.
- *
- * Twelve hours, chosen against the product's cadence rather than a wall-clock intuition: NRCS performs ONE coordinated
- * Annual Soils Refresh, on October 1. Grouping `sacatalog` by year of `saverest` returns 2016: 1, 2025: 3,323, 2026: 56
- * — 98.3% of survey areas carry a single version date from one refresh rather than a per-area drift. A shorter TTL buys
- * nothing.
- */
 const SDA_CACHE_TTL_MS = 12 * 60 * 60 * 1000;
 /**
  * A client for Soil Data Access.
  */
 export class SoilDataAccessClient extends APIClient {
     /**
-     * Run one query and return its rows.
+     * Runs one SQL query and returns its rows as strings, with NULL as an empty string.
      *
-     * @throws {OGCServiceError} When the service answers with an exception report — including on an HTTP 200, which is
-     *   what a server-side timeout does.
+     * @throws {OGCServiceError} When the service answers with an exception report,
+     * including an HTTP 200 response.
+     * A server-side timeout uses that status.
      */
     async query(sql) {
         const { data } = await this.fetch({
             method: "POST",
             url: SDA_POST_REST_URL,
-            // TEXT, not JSON, and that is the whole trap. A JSON response type hands a failure body to a JSON parser,
-            // which either throws something unrelated to what went wrong or — on a 200 — yields nothing at all.
             responseType: "text",
             headers: { "Content-Type": "application/json" },
             data: { SERVICE: "query", FORMAT: "JSON", QUERY: sql },
         });
         assertNoOGCServiceException(data, `soil data access (query: ${sql.slice(0, 200)})`);
         const parsed = parseJSONStrict(data);
-        // An answer with NO rows is `{}` rather than `{"Table":[]}`, so an absent `Table` is a real empty result and not a
-        // read failure — the exception check above has already separated the two.
         if (parsed.Table === undefined)
             return [];
         if (!Array.isArray(parsed.Table)) {
@@ -90,17 +48,17 @@ export class SoilDataAccessClient extends APIClient {
         return parsed.Table.map((row) => row.map((value) => (value === null ? "" : String(value))));
     }
     /**
-     * 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.
+     * Returns the published survey areas whose symbol starts with `prefix`,
+     * such as a state code or one whole area symbol.
      *
-     * @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.
+     * @throws {Error} When no survey area matches, because a build over an empty set
+     * would otherwise report success having written no rows.
      */
     async readSurveyAreaCatalog(prefix) {
         const escaped = prefix.replaceAll("'", "''");
         const rows = await this.query(`SELECT areasymbol, areaname, saverest, saversion FROM sacatalog WHERE areasymbol LIKE '${escaped}%' ORDER BY areasymbol`);
         if (!rows.length) {
-            throw new Error(`soil data access: the catalogue holds no survey area whose symbol starts with ${JSON.stringify(prefix)} — a build over an empty set would report success having written nothing`);
+            throw new Error(`soil data access: the catalogue holds no survey area whose symbol starts with ${stringifyJSON(prefix)} — a build over an empty set would report success having written nothing`);
         }
         return rows.map((row) => ({
             areasymbol: row[0],
@@ -110,10 +68,8 @@ export class SoilDataAccessClient extends APIClient {
         }));
     }
     /**
-     * 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.
+     * Returns the map unit key the service's own geometry assigns at a point, or `undefined`,
+     * as a cross-check against the authority through a channel this package never processed.
      */
     async mukeyAtPoint(latitude, longitude) {
         const rows = await this.query(`SELECT mukey FROM SDA_Get_Mukey_from_intersection_with_WktWgs84('point(${longitude} ${latitude})')`);
@@ -121,7 +77,7 @@ export class SoilDataAccessClient extends APIClient {
     }
 }
 /**
- * Build a {@link SoilDataAccessClient} with the disk cache and pacing this package's acquisition path expects.
+ * Creates a {@link SoilDataAccessClient} with retries, a 12-hour disk cache and the default request pacing.
  */
 export function createSoilDataAccessClient(options = {}) {
     return new SoilDataAccessClient({
@@ -132,7 +88,7 @@ export function createSoilDataAccessClient(options = {}) {
         caching: {
             ttl: SDA_CACHE_TTL_MS,
             storage: buildDiskStorage({
-                directory: options.cacheDirectory ?? String(dataRootPath("soil", "cache", "http")),
+                directory: (options.cacheDirectory ?? soilDatabasePath("cache", "http")).toString(),
             }),
         },
     });

package/out/sdk/client.js.map

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

package/out/sdk/download.d.ts

@@ -2,56 +2,32 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   Acquire one survey area's published archive — 13 to 41 MB streamed to disk and unzipped.
- *
- *   THE TRANSFER ITSELF LIVES IN `@mailwoman/core/utils`, and `streamToDisk` carries why a file transfer of
- *   this size keeps raw `fetch` instead of going through `APIClient`, plus the `.part`-rename rule. What is
- *   soil's, and stays here, is the URL shape, the cache key, and the two facts below that the shared
- *   transfer is told rather than assumes: the progress stride and what a 400 means. The METADATA reads
- *   around this one do go through `APIClient` — see `client.ts`.
- *
- *   FRESHNESS IS `sacatalog.saverest`, NEVER A LENGTH PROBE, AND THE HOST LEAVES NO CHOICE. It answers `HEAD`
- *   with HTTP 405 (`allow: GET`) and IGNORES `Range`: a request with `Range: bytes=0-0` returned HTTP 200 and
- *   transferred the whole 27,598,377 bytes in 7.23 s. So "check the size first" starts a real download. The
- *   cache is keyed on the version date the tabular service reports instead, and a vintage already on disk is
- *   never re-fetched. The `Range` behaviour is PATH-SPECIFIC rather than host-wide — `/DataAvailability/`
- *   does answer 206 — so a client must probe per path rather than conclude from one.
- *
- *   THE FILENAME EMBEDS THE VERSION DATE AND A WRONG ONE IS AN HTTP 400. Not a 404: asking for a date the
- *   host does not hold reads as a malformed request rather than a missing file, which is why the date comes
- *   from the catalogue rather than from a guess. The square brackets must be sent literally, so the URL is
- *   built with them percent-encoded.
- *
- *   TWO CACHE VARIANTS EXIST AND THE BARE ONE IS WANTED. `wss_SSA_IA153_[2025-09-09].zip` is 25,474,922 bytes;
- *   `wss_SSA_IA153_soildb_IA_2003_[2025-09-09].zip` is 27,598,377 and differs only by an EMPTY Microsoft Access
- *   template container for a workflow this program does not use. Confirmed on a second area (`IA015`:
- *   38,981,269 against 41,104,724 bytes) and on a third that ships no template at all (`TX299`, 13,455,641
- *   bytes, 97 files, no `.mdb`).
  */
+import { PathBuilder, type PathBuilderLike } from "path-ts";
 /**
- * The download service's survey-area cache. Documented at `https://websoilsurvey.sc.egov.usda.gov/DSD/Download/help`,
- * which lists `GET /{CacheName}/{FileName}`.
+ * Points to the Web Soil Survey download cache that serves survey-area archives.
  */
 export declare const WSS_SSA_CACHE_URL = "https://websoilsurvey.sc.egov.usda.gov/DSD/Download/Cache/SSA";
 /**
- * The archive URL for one survey area at one version date.
- *
- * The brackets are percent-encoded rather than sent raw: they are not valid in a URL path, and a client that sends them
- * literally depends on the fetcher tolerating them.
+ * Returns the archive URL for one survey area at one version date, with the brackets
+ * around the date percent-encoded because they are not valid in a URL path.
  */
 export declare function surveyAreaArchiveURL(areaSymbol: string, versionDate: string): string;
+/**
+ * Configures {@link downloadSurveyArea}, which caches the archive and its
+ * extracted tree under `cacheRoot/<versionDate>`.
+ */
 export interface DownloadSurveyAreaOptions {
     areaSymbol: string;
     /**
-     * The version date from `sacatalog.saverest`, as `YYYY-MM-DD`.
+     * The survey area's version date from `sacatalog.saverest`, formatted as `YYYY-MM-DD`.
      */
     versionDate: string;
     /**
-     * Where vintages are kept. Each version date gets its own directory, so a new refresh never overwrites the old one in
-     * place and a re-run against the same vintage never re-transfers.
+     * The cache directory, where each version date gets its own subdirectory so a new
+     * vintage never overwrites an old one and a repeat run downloads no file.
      */
-    cacheRoot: string;
+    cacheRoot: PathBuilderLike;
     onProgress?: (message: string) => void;
 }
 /**
@@ -61,24 +37,25 @@ export interface SurveyAreaArchive {
     areaSymbol: string;
     versionDate: string;
     /**
-     * The extracted `<areasymbol>/` directory, holding `spatial/` and `tabular/`.
+     * The extracted `<areasymbol>/` directory.
+     * It contains `spatial/` and `tabular/`.
      */
-    root: string;
-    spatialDirectory: string;
-    tabularDirectory: string;
+    root: PathBuilder;
+    spatialDirectory: PathBuilder;
+    tabularDirectory: PathBuilder;
     /**
-     * The archive as transferred. Kept so a re-run costs nothing and so the bytes are re-checkable.
+     * The downloaded ZIP archive, kept so a repeat run skips the transfer and the bytes can be rechecked.
      */
-    archivePath: string;
+    archivePath: PathBuilder;
 }
 /**
- * Download and unzip one survey area, returning where its pieces landed.
+ * Downloads and unzips one survey area into the cache, skipping completed steps.
+ * Returns the paths to its files.
  *
- * Downloads to a `.part` file and renames only on a clean finish, so an interrupted transfer never presents as a
- * complete archive — the same discipline the database build uses, for the same reason.
+ * The download goes through a `.part` file so an interrupted transfer never looks like a complete archive.
  *
- * @throws {Error} When the host answers anything but 200, or when the extracted tree does not hold the two directories
- *   every survey area publishes.
+ * @throws {Error} When the host answers anything but 200, or when the extracted
+ * tree lacks the `spatial` or `tabular` directory.
  */
 export declare function downloadSurveyArea(options: DownloadSurveyAreaOptions): Promise<SurveyAreaArchive>;
 //# sourceMappingURL=download.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"download.d.ts","sourceRoot":"","sources":["../../lib/sdk/download.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAQH;;;GAGG;AACH,eAAO,MAAM,iBAAiB,kEAAkE,CAAA;AAEhG;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAEpF;AAED,MAAM,WAAW,yBAAyB;IACzC,UAAU,EAAE,MAAM,CAAA;IAClB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CACtC;AAcD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IACjC,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ,gBAAgB,EAAE,MAAM,CAAA;IACxB,gBAAgB,EAAE,MAAM,CAAA;IACxB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAqDvG"}
+{"version":3,"file":"download.d.ts","sourceRoot":"","sources":["../../sdk/download.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,SAAS,CAAA;AAE3D;;GAEG;AACH,eAAO,MAAM,iBAAiB,kEAAkE,CAAA;AAEhG;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAEpF;AAED;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACzC,UAAU,EAAE,MAAM,CAAA;IAElB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;IAEnB;;;OAGG;IACH,SAAS,EAAE,eAAe,CAAA;IAC1B,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CACtC;AAMD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IACjC,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IAEnB;;;OAGG;IACH,IAAI,EAAE,WAAW,CAAA;IACjB,gBAAgB,EAAE,WAAW,CAAA;IAC7B,gBAAgB,EAAE,WAAW,CAAA;IAE7B;;OAEG;IACH,WAAW,EAAE,WAAW,CAAA;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAmDvG"}