@mailwoman/soil 9.2.0

package/out/sdk/client.js

@@ -0,0 +1,214 @@
+/**
+ * @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 } from "@mailwoman/core/api";
+import { buildDiskStorage } from "@mailwoman/core/api/disk-storage";
+import { dataRootPath } from "@mailwoman/core/data-root";
+import { parseJSONStrict } from "@mailwoman/core/objects";
+import { decodeXML } from "entities";
+import { saverestToISODate } from "#sdk/tabular";
+// Re-exported so a caller branching on this client's failures needs exactly one import.
+export { isTransientResourceError } from "@mailwoman/core/api";
+export { ResourceError } from "@mailwoman/core/errors";
+/**
+ * The tabular endpoint. Anonymous: no key, no account, and no rate-limit header on any observed response.
+ */
+export const SDA_POST_REST_URL = "https://sdmdataaccess.nrcs.usda.gov/Tabular/post.rest";
+/**
+ * Minimum spacing between Soil Data Access requests, in milliseconds.
+ *
+ * NRCS publishes no rate limit for this service and returned no rate-limit header on any request, so this is courtesy
+ * pacing rather than a published ceiling — stated as such rather than dressed up as a measured limit. It costs an
+ * acquisition run nothing: a whole-state build makes one catalogue call, and the verification's per-point calls are
+ * measured at 1.8 s each anyway.
+ */
+export 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;
+/**
+ * The error a `ServiceExceptionReport` becomes.
+ *
+ * Its own class rather than a bare `Error`, because the three failures it carries need different responses from a
+ * caller: a timeout is worth narrowing the query for, an invalid column is a schema change, and access denied is a
+ * query the service will never run.
+ */
+export class SoilDataAccessError extends Error {
+    serviceException;
+    constructor(serviceException, query) {
+        super(`soil data access: the service returned a ServiceExceptionReport — ${serviceException} (query: ${query.slice(0, 200)})`);
+        this.name = "SoilDataAccessError";
+        this.serviceException = serviceException;
+    }
+    /**
+     * Did the service exceed its own query timeout? There is no published figure for it, so the message is the only
+     * signal — and it arrives on an HTTP 200.
+     */
+    get timedOut() {
+        return /timed out/iu.test(this.serviceException);
+    }
+}
+/**
+ * The `<ServiceException>` text inside an OGC exception report, or `undefined` when the body is not one.
+ *
+ * Split from the request so the detection is testable against captured bodies. Both shapes below were taken from the
+ * live service: the report arrives with an XML declaration and an `xmlns` of `http://www.opengis.net/ogc`.
+ */
+export function readServiceException(body) {
+    if (!body.includes("ServiceExceptionReport"))
+        return undefined;
+    // A report whose exception element cannot be read is still a report, and reporting it as a successful empty answer
+    // is the failure this whole function exists to prevent.
+    return decodeXML((exceptionText(body) ?? "the report carried no readable ServiceException element").trim());
+}
+/**
+ * The opening tag, without its terminator — the prefix `<ServiceExceptionReport …>` unhelpfully shares.
+ */
+const EXCEPTION_OPEN = "<ServiceException";
+/**
+ * The inner text of the first real `<ServiceException>` element.
+ *
+ * INDEX SCANS RATHER THAN A REGEX. The obvious form — `/<ServiceException(?:\s[^>]*)?>([\s\S]*?)<\/ServiceException>/`
+ * — backtracks polynomially on a body whose opening tag has no closing partner, and this body is whatever a network
+ * service returned. Two more things it has to get right, both of which cost nothing here: the tag name must END at the
+ * match, because `<ServiceExceptionReport xmlns="…">` shares the prefix and taking it captures the entire report as the
+ * message; and an unclosed element reads as unreadable rather than as empty.
+ */
+function exceptionText(body) {
+    let cursor = 0;
+    for (;;) {
+        const start = body.indexOf(EXCEPTION_OPEN, cursor);
+        if (start === -1)
+            return undefined;
+        const after = start + EXCEPTION_OPEN.length;
+        cursor = after;
+        // `>` closes a bare tag; whitespace introduces attributes. Anything else continues the tag NAME, which means this
+        // is `ServiceExceptionReport` or a sibling and not the element being read.
+        if (!/^[\s>]/u.test(body.slice(after, after + 1)))
+            continue;
+        const contentStart = body.indexOf(">", after);
+        if (contentStart === -1)
+            return undefined;
+        const end = body.indexOf("</ServiceException>", contentStart);
+        if (end === -1)
+            return undefined;
+        return body.slice(contentStart + 1, end);
+    }
+}
+/**
+ * A client for Soil Data Access.
+ */
+export class SoilDataAccessClient extends APIClient {
+    /**
+     * Run one query and return its rows.
+     *
+     * @throws {SoilDataAccessError} When the service answers with an exception report — including on an HTTP 200, which
+     *   is what a server-side timeout does.
+     */
+    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 },
+        });
+        const exception = readServiceException(data);
+        if (exception)
+            throw new SoilDataAccessError(exception, sql);
+        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)) {
+            throw new TypeError(`soil data access: the service answered with a Table that is not an array (${typeof parsed.Table}) — the response format changed`);
+        }
+        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.
+     *
+     * @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.
+     */
+    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`);
+        }
+        return rows.map((row) => ({
+            areasymbol: row[0],
+            areaname: row[1],
+            saverest: saverestToISODate(row[2]),
+            saversion: Number(row[3]),
+        }));
+    }
+    /**
+     * 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.
+     */
+    async mukeyAtPoint(latitude, longitude) {
+        const rows = await this.query(`SELECT mukey FROM SDA_Get_Mukey_from_intersection_with_WktWgs84('point(${longitude} ${latitude})')`);
+        return rows[0]?.[0] || undefined;
+    }
+}
+/**
+ * Build a {@link SoilDataAccessClient} with the disk cache and pacing this package's acquisition path expects.
+ */
+export function createSoilDataAccessClient(options = {}) {
+    return new SoilDataAccessClient({
+        displayName: "SoilDataAccess",
+        minRequestIntervalMs: options.minRequestIntervalMs ?? SDA_MIN_REQUEST_INTERVAL_MS,
+        retry: true,
+        ...(options.clock ? { clock: options.clock } : {}),
+        caching: {
+            ttl: SDA_CACHE_TTL_MS,
+            storage: buildDiskStorage({
+                directory: options.cacheDirectory ?? String(dataRootPath("soil", "cache", "http")),
+            }),
+        },
+    });
+}
+//# sourceMappingURL=client.js.map

package/out/sdk/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../lib/sdk/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,SAAS,EAAwC,MAAM,qBAAqB,CAAA;AACrF,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAA;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAEpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAEhD,wFAAwF;AACxF,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAEtD;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,uDAAuD,CAAA;AAExF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,GAAG,CAAA;AAE9C;;;;;;;GAOG;AACH,MAAM,gBAAgB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAA;AAE5C;;;;;;GAMG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAC7B,gBAAgB,CAAQ;IAExC,YAAY,gBAAwB,EAAE,KAAa;QAClD,KAAK,CACJ,qEAAqE,gBAAgB,YAAY,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CACvH,CAAA;QAED,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAA;QACjC,IAAI,CAAC,gBAAgB,GAAG,gBAAgB,CAAA;IACzC,CAAC;IAED;;;OAGG;IACH,IAAW,QAAQ;QAClB,OAAO,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAA;IACjD,CAAC;CACD;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAChD,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,wBAAwB,CAAC;QAAE,OAAO,SAAS,CAAA;IAE9D,mHAAmH;IACnH,wDAAwD;IACxD,OAAO,SAAS,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,yDAAyD,CAAC,CAAC,IAAI,EAAE,CAAC,CAAA;AAC5G,CAAC;AAED;;GAEG;AACH,MAAM,cAAc,GAAG,mBAAmB,CAAA;AAE1C;;;;;;;;GAQG;AACH,SAAS,aAAa,CAAC,IAAY;IAClC,IAAI,MAAM,GAAG,CAAC,CAAA;IAEd,SAAS,CAAC;QACT,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,MAAM,CAAC,CAAA;QAElD,IAAI,KAAK,KAAK,CAAC,CAAC;YAAE,OAAO,SAAS,CAAA;QAElC,MAAM,KAAK,GAAG,KAAK,GAAG,cAAc,CAAC,MAAM,CAAA;QAE3C,MAAM,GAAG,KAAK,CAAA;QAEd,kHAAkH;QAClH,2EAA2E;QAC3E,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;YAAE,SAAQ;QAE3D,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;QAE7C,IAAI,YAAY,KAAK,CAAC,CAAC;YAAE,OAAO,SAAS,CAAA;QAEzC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,qBAAqB,EAAE,YAAY,CAAC,CAAA;QAE7D,IAAI,GAAG,KAAK,CAAC,CAAC;YAAE,OAAO,SAAS,CAAA;QAEhC,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,GAAG,CAAC,EAAE,GAAG,CAAC,CAAA;IACzC,CAAC;AACF,CAAC;AAeD;;GAEG;AACH,MAAM,OAAO,oBAAqB,SAAQ,SAA0B;IACnE;;;;;OAKG;IACI,KAAK,CAAC,KAAK,CAAC,GAAW;QAC7B,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAS;YACzC,MAAM,EAAE,MAAM;YACd,GAAG,EAAE,iBAAiB;YACtB,0GAA0G;YAC1G,oGAAoG;YACpG,YAAY,EAAE,MAAM;YACpB,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE;SACtD,CAAC,CAAA;QAEF,MAAM,SAAS,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAA;QAE5C,IAAI,SAAS;YAAE,MAAM,IAAI,mBAAmB,CAAC,SAAS,EAAE,GAAG,CAAC,CAAA;QAE5D,MAAM,MAAM,GAAG,eAAe,CAAsB,IAAI,CAAC,CAAA;QAEzD,mHAAmH;QACnH,0EAA0E;QAC1E,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS;YAAE,OAAO,EAAE,CAAA;QAEzC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,SAAS,CAClB,6EAA6E,OAAO,MAAM,CAAC,KAAK,iCAAiC,CACjI,CAAA;QACF,CAAC;QAED,OAAO,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAE,GAAiB,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IAC3G,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,qBAAqB,CAAC,MAAc;QAChD,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;QAE5C,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,KAAK,CAC5B,0FAA0F,OAAO,wBAAwB,CACzH,CAAA;QAED,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CACd,iFAAiF,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,0EAA0E,CACjL,CAAA;QACF,CAAC;QAED,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YACzB,UAAU,EAAE,GAAG,CAAC,CAAC,CAAE;YACnB,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAE;YACjB,QAAQ,EAAE,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAE,CAAC;YACpC,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;SACzB,CAAC,CAAC,CAAA;IACJ,CAAC;IAED;;;;;OAKG;IACI,KAAK,CAAC,YAAY,CAAC,QAAgB,EAAE,SAAiB;QAC5D,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,KAAK,CAC5B,0EAA0E,SAAS,IAAI,QAAQ,KAAK,CACpG,CAAA;QAED,OAAO,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,SAAS,CAAA;IACjC,CAAC;CACD;AAQD;;GAEG;AACH,MAAM,UAAU,0BAA0B,CAAC,UAA6C,EAAE;IACzF,OAAO,IAAI,oBAAoB,CAAC;QAC/B,WAAW,EAAE,gBAAgB;QAC7B,oBAAoB,EAAE,OAAO,CAAC,oBAAoB,IAAI,2BAA2B;QACjF,KAAK,EAAE,IAAI;QACX,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClD,OAAO,EAAE;YACR,GAAG,EAAE,gBAAgB;YACrB,OAAO,EAAE,gBAAgB,CAAC;gBACzB,SAAS,EAAE,OAAO,CAAC,cAAc,IAAI,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;aAClF,CAAC;SACF;KACD,CAAC,CAAA;AACH,CAAC"}

package/out/sdk/download.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @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`).
+ */
+/**
+ * The download service's survey-area cache. Documented at `https://websoilsurvey.sc.egov.usda.gov/DSD/Download/help`,
+ * which lists `GET /{CacheName}/{FileName}`.
+ */
+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.
+ */
+export declare function surveyAreaArchiveURL(areaSymbol: string, versionDate: string): string;
+export interface DownloadSurveyAreaOptions {
+    areaSymbol: string;
+    /**
+     * The version date from `sacatalog.saverest`, 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.
+     */
+    cacheRoot: string;
+    onProgress?: (message: string) => void;
+}
+/**
+ * What one acquired survey area is, on disk.
+ */
+export interface SurveyAreaArchive {
+    areaSymbol: string;
+    versionDate: string;
+    /**
+     * The extracted `<areasymbol>/` directory, holding `spatial/` and `tabular/`.
+     */
+    root: string;
+    spatialDirectory: string;
+    tabularDirectory: string;
+    /**
+     * The archive as transferred. Kept so a re-run costs nothing and so the bytes are re-checkable.
+     */
+    archivePath: string;
+}
+/**
+ * Download and unzip one survey area, returning where its pieces landed.
+ *
+ * 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.
+ *
+ * @throws {Error} When the host answers anything but 200, or when the extracted tree does not hold the two directories
+ *   every survey area publishes.
+ */
+export declare function downloadSurveyArea(options: DownloadSurveyAreaOptions): Promise<SurveyAreaArchive>;
+//# sourceMappingURL=download.d.ts.map

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

@@ -0,0 +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"}

package/out/sdk/download.js

@@ -0,0 +1,117 @@
+/**
+ * @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 { tryStat } from "@mailwoman/core/fs/readers";
+import { makeDirectories } from "@mailwoman/core/fs/writers";
+import { runFile } from "@mailwoman/core/process";
+import { streamToDisk } from "@mailwoman/core/utils";
+import { join } 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}`.
+ */
+export 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.
+ */
+export function surveyAreaArchiveURL(areaSymbol, versionDate) {
+    return `${WSS_SSA_CACHE_URL}/wss_SSA_${areaSymbol}_%5B${versionDate}%5D.zip`;
+}
+/**
+ * Bytes between progress reports. Smaller than the shared default because these archives are 13–41 MB, and the default
+ * stride would leave the smallest of them reporting once.
+ */
+const PROGRESS_STRIDE_BYTES = 8 * 1024 * 1024;
+/**
+ * What this host answers for a version date it does not hold. NOT a 404: it reads as a malformed request rather than a
+ * missing file, which is why the message below says so and why the date comes from the catalogue rather than a guess.
+ */
+const UNKNOWN_VERSION_STATUS = 400;
+/**
+ * Download and unzip one survey area, returning where its pieces landed.
+ *
+ * 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.
+ *
+ * @throws {Error} When the host answers anything but 200, or when the extracted tree does not hold the two directories
+ *   every survey area publishes.
+ */
+export async function downloadSurveyArea(options) {
+    const vintageDirectory = join(options.cacheRoot, options.versionDate);
+    const root = join(vintageDirectory, options.areaSymbol);
+    const archivePath = join(vintageDirectory, `wss_SSA_${options.areaSymbol}.zip`);
+    if (!(await tryStat(root))) {
+        await makeDirectories(vintageDirectory);
+        if (await tryStat(archivePath)) {
+            options.onProgress?.(`${options.areaSymbol}: archive for ${options.versionDate} already downloaded`);
+        }
+        else {
+            await streamToDisk({
+                url: surveyAreaArchiveURL(options.areaSymbol, options.versionDate),
+                destination: archivePath,
+                context: "soil download",
+                progressStrideBytes: PROGRESS_STRIDE_BYTES,
+                describeStatus: (status) => status === UNKNOWN_VERSION_STATUS
+                    ? " — this host answers 400 rather than 404 for a version date it does not hold, so check the date against sacatalog.saverest"
+                    : undefined,
+                // Every progress line names the area, because a full acquisition interleaves hundreds of them.
+                ...(options.onProgress
+                    ? { onProgress: (message) => options.onProgress?.(`${options.areaSymbol}: ${message}`) }
+                    : {}),
+            });
+        }
+        // The archive holds its files under an `<AREASYMBOL>/` root already, so it unzips into the vintage directory
+        // rather than into a directory named for itself.
+        await runFile("unzip", ["-o", "-q", archivePath, "-d", vintageDirectory]);
+    }
+    else {
+        options.onProgress?.(`${options.areaSymbol}: already extracted for ${options.versionDate}`);
+    }
+    const spatialDirectory = join(root, "spatial");
+    const tabularDirectory = join(root, "tabular");
+    for (const directory of [spatialDirectory, tabularDirectory]) {
+        if (!(await tryStat(directory))) {
+            throw new Error(`soil download: ${options.areaSymbol} extracted without a ${directory} directory — every survey area publishes both spatial/ and tabular/, so this archive is not the product`);
+        }
+    }
+    return {
+        areaSymbol: options.areaSymbol,
+        versionDate: options.versionDate,
+        root,
+        spatialDirectory,
+        tabularDirectory,
+        archivePath,
+    };
+}
+//# sourceMappingURL=download.js.map

package/out/sdk/download.js.map

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

package/out/sdk/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file The acquisition + build surface for the NRCS SSURGO soil-capability layer. The READER is the
+ *   package root.
+ */
+export * from "#sdk/acquire";
+export * from "#sdk/build-soil";
+export * from "#sdk/cell-tiers";
+export * from "#sdk/cells";
+export * from "#sdk/client";
+export * from "#sdk/download";
+export * from "#sdk/ingest";
+export * from "#sdk/measure-resolutions";
+export * from "#sdk/reduce";
+export * from "#sdk/survey-area";
+export * from "#sdk/tabular";
+export * from "#sdk/verify";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/sdk/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,cAAc,CAAA;AAC5B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,aAAa,CAAA;AAC3B,cAAc,0BAA0B,CAAA;AACxC,cAAc,aAAa,CAAA;AAC3B,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA"}

package/out/sdk/index.js

@@ -0,0 +1,20 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file The acquisition + build surface for the NRCS SSURGO soil-capability layer. The READER is the
+ *   package root.
+ */
+export * from "#sdk/acquire";
+export * from "#sdk/build-soil";
+export * from "#sdk/cell-tiers";
+export * from "#sdk/cells";
+export * from "#sdk/client";
+export * from "#sdk/download";
+export * from "#sdk/ingest";
+export * from "#sdk/measure-resolutions";
+export * from "#sdk/reduce";
+export * from "#sdk/survey-area";
+export * from "#sdk/tabular";
+export * from "#sdk/verify";
+//# sourceMappingURL=index.js.map

package/out/sdk/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../lib/sdk/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,cAAc,CAAA;AAC5B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,aAAa,CAAA;AAC3B,cAAc,0BAA0B,CAAA;AACxC,cAAc,aAAa,CAAA;AAC3B,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA"}

package/out/sdk/ingest-chunk.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The streaming pass — every delineation into `soil_map_unit_area` and into the build's touch table — as a
+ *   unit of work that can run over PART of one survey area.
+ *
+ *   WHY THIS IS A CHUNK RATHER THAN A WHOLE FILE. h3's WASM heap cannot be reset from JavaScript, and it does
+ *   not survive an unbounded number of polyfill calls: over the flood layer's real product, runs died after
+ *   roughly 510,000 and 798,000 features on geometry that classifies in milliseconds in a fresh process. A
+ *   build that completes only when fragmentation happens to stay low is not a reproducible build, so the
+ *   classification is bounded by construction — {@linkcode buildSoilDatabase} runs one of these per range of
+ *   the shapefile's own FIDs, each in its own process, and each therefore against a heap that starts empty.
+ *   Iowa's 99 survey areas hold far more delineations together than any one of them does, which is why the
+ *   bound is per RANGE rather than per area.
+ *
+ *   THE CHUNK OWNS NO ARTIFACT. It appends rows to a database the parent created and will seal, and returns
+ *   counts the parent adds up. Chunks run one at a time against that file, so there is no concurrent writer
+ *   and no locking to reason about.
+ */
+import type { DatabaseClient } from "@mailwoman/sqlite/client";
+import type { SoilDatabase } from "#schema";
+import type { SoilFeatureSource } from "#sdk/ingest";
+/**
+ * What one chunk produced. Every field is JSON-serializable, because a chunk normally reports across a process
+ * boundary.
+ */
+export interface SoilChunkResult {
+    areaSymbol: string;
+    delineations: number;
+    /**
+     * Delineations whose bounding box forced a resolution coarser than the target.
+     */
+    coarsened: number;
+    /**
+     * `[coverageCell, delineationsReachingIt]` pairs — an array rather than a `Map` so it survives the process boundary.
+     */
+    observedByCoverageCell: Array<[number, number]>;
+    /**
+     * The same, counting only delineations whose map unit HAS soil mapping behind it.
+     *
+     * Separate from the total because the coverage rule turns on it: a coverage cell reached only by `NOTCOM` and
+     * access-denied polygons is inside a published survey area and carries no digitized soil mapping, and the survey's
+     * §3.2 gives it no row.
+     */
+    mappedByCoverageCell: Array<[number, number]>;
+    /**
+     * Square metres: the encoded rings read WITH their holes, and read without.
+     */
+    area: {
+        nestedM2: number;
+        allExteriorM2: number;
+    };
+}
+export interface IngestSoilChunkOptions {
+    source: SoilFeatureSource;
+    indexResolution: number;
+    coverageResolution: number;
+    /**
+     * The map units with NO soil mapping behind them — `NOTCOM`, `NOTPUB`, access denied, or no readable component
+     * weights. Passed in rather than joined here so the chunk stays a streaming pass over geometry.
+     */
+    noMappingMukeys: ReadonlySet<string>;
+    onProgress?: (message: string) => void;
+}
+/**
+ * Stream one chunk of one survey area into `database`.
+ *
+ * @throws {Error} On a delineation the classifier refuses — which includes the allocator's silent zero-cell answer.
+ */
+export declare function ingestSoilChunk(database: DatabaseClient<SoilDatabase>, options: IngestSoilChunkOptions): Promise<SoilChunkResult>;
+//# sourceMappingURL=ingest-chunk.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ingest-chunk.d.ts","sourceRoot":"","sources":["../../lib/sdk/ingest-chunk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAE9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAE3C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAapD;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC/B,UAAU,EAAE,MAAM,CAAA;IAClB,YAAY,EAAE,MAAM,CAAA;IACpB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,sBAAsB,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAC/C;;;;;;OAMG;IACH,oBAAoB,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAC7C;;OAEG;IACH,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAA;CACjD;AAED,MAAM,WAAW,sBAAsB;IACtC,MAAM,EAAE,iBAAiB,CAAA;IACzB,eAAe,EAAE,MAAM,CAAA;IACvB,kBAAkB,EAAE,MAAM,CAAA;IAC1B;;;OAGG;IACH,eAAe,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACpC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CACtC;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACpC,QAAQ,EAAE,cAAc,CAAC,YAAY,CAAC,EACtC,OAAO,EAAE,sBAAsB,GAC7B,OAAO,CAAC,eAAe,CAAC,CA2F1B"}