@mailwoman/soil 9.4.0 → 10.1.0

package/{lib/sdk → sdk}/verify.ts

@@ -2,35 +2,6 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   The two-path agreement check, and its negative half.
- *
- *   POSITIVE HALF. A sample of points is answered from the sealed artifact and then re-asked of Soil Data
- *   Access — the same authority, a different distribution channel, and geometry this package has never
- *   touched. What is compared is the MAP UNIT the two channels put at the point, which is the thing a
- *   conversion can get wrong; comparing the derived capability class instead would let a wrong delineation
- *   agree by accident whenever two neighbouring map units happen to share a class.
- *
- *   NEGATIVE HALF, AND IT MATTERS AS MUCH. A sample of points in states with no rows must come back
- *   `unknown` — no coverage row at all — and never a low-capability reading. The positive half alone would
- *   pass on an artifact that answered class 8 for the whole planet.
- *
- *   A DISAGREEMENT NEAR A DELINEATION EDGE IS NOT A DEFECT, AND THE DISTANCE IS MEASURED TO THE EDGE RATHER
- *   THAN TO THE NEAREST VERTEX. A point a centimetre from a long edge can be metres from every vertex of it
- *   — the flood layer's one near-miss read 1.58 m to vertices and 0.009 m to edges, a 9 mm difference
- *   overstated 175-fold. Measuring vertices makes the boundary tolerance far stricter than it reads, which
- *   is how a rendering difference gets reported as a conversion defect.
- *
- *   THE ARTIFACT'S OWN ANSWER IS THE CELL SUMMARY, AND THE POINT'S MAP UNIT IS UNDER IT. So the comparison
- *   reaches the GEOMETRY — the truth table — rather than the reduction: the reduction is a per-cell
- *   distribution and has no single map unit to compare. That makes this a check on the CONVERSION, which is
- *   what it is for; the reduction is checked by the fixtures and by the share-sum invariant.
- *
- *   IT REACHES IT THROUGH THE CELL INDEX, NOT THROUGH A BOUNDING-BOX SCAN. A `WHERE min_lat <= ? AND …` over
- *   the geometry table reads like a prefilter and is a full table scan: none of those columns is indexed and
- *   every row carries a ring blob, so at the pilot's 2.7 million delineations it reads gigabytes per point.
- *   Naming the point's cell is a primary-key range scan over a `WITHOUT ROWID` table, which is the whole
- *   reason the index exists.
  */
 
 import {
@@ -43,13 +14,15 @@ import {
 } from "@mailwoman/spatial"
 import { DatabaseClient } from "@mailwoman/sqlite/client"
 import { cellToParent, latLngToCell } from "h3-js"
+import type { PathBuilderLike } from "path-ts"
 
 import { SoilCapabilityLookup, SoilReadingKind } from "#index"
 import type { SoilDatabase } from "#schema"
 import type { SoilDataAccessClient } from "#sdk/client"
 
 /**
- * One point, both verdicts, and whether they agree.
+ * One comparison row for a point.
+ * It records both verdicts and whether they agree.
  */
 export interface SoilAgreementRow {
 	label: string
@@ -65,10 +38,10 @@ export interface SoilAgreementRow {
 	serviceMukey: string | null
 	outcome: "agree" | "disagree" | "boundary_tolerance"
 	/**
-	 * Metres from the point to the nearest EDGE of the delineation the artifact matched.
+	 * Meters from the point to the nearest edge of the delineation the artifact matched.
 	 *
-	 * Carried on every row rather than only the tolerated ones, because it is what separates a real defect from two
-	 * channels rendering the same edge differently — and a receipt that omits it forces a re-run.
+	 * Included on every row because it separates a real defect from two channels
+	 * rendering the same edge differently.
 	 */
 	nearestEdgeMetres?: number
 }
@@ -82,7 +55,7 @@ export interface SoilOutsideRow {
 	longitude: number
 	kind: SoilReadingKind
 	/**
-	 * True when the artifact answered `unknown` — the only acceptable reading outside the built survey areas.
+	 * True when the artifact answered `unknown`, the only acceptable reading outside the built survey areas.
 	 */
 	passed: boolean
 }
@@ -97,13 +70,10 @@ export interface VerifySoilResult {
 }
 
 /**
- * Points outside the pilot region, named. Each is a place, not a bare pair of numbers: a coordinate a reader cannot
- * name is a coordinate nobody can check.
+ * Points outside the pilot region.
  *
- * Every neighbouring state is included, because the failure this half catches is a footprint that leaked past the
- * survey-area outlines — and a footprint accidentally clipped to "the Midwest" would pass a one-state check. Two of
- * these sit close to the Iowa border on purpose: the outline test is conservative, so a near-border point must read
- * unknown rather than borrow Iowa's coverage.
+ * Every neighboring state is included because a footprint clipped to "the
+ * Midwest" would pass a one-state check.
  */
 export const OUTSIDE_PILOT_POINTS: ReadonlyArray<{ label: string; latitude: number; longitude: number }> = [
 	{ label: "Lincoln, Nebraska", latitude: 40.8136, longitude: -96.7026 },
@@ -117,21 +87,16 @@ export const OUTSIDE_PILOT_POINTS: ReadonlyArray<{ label: string; latitude: numb
 ]
 
 /**
- * How close to a delineation edge a disagreement is attributed to the channels' differing rendering rather than to the
- * conversion.
- *
- * One metre. The published shapefile carries nine decimals through this package's ingest and Soil Data Access renders
- * its own geometry independently; NRCS's own positional-accuracy statement says the difference between a boundary's
- * field location and its digitized location "is unknown", so this tolerance is about the two RENDERINGS agreeing rather
- * than about ground truth. One metre is far below the median delineation, which is 24,863 m² — about 158 m across.
+ * One meter, far below the median delineation, so a disagreement within it is the two
+ * channels rendering the same edge differently rather than a conversion defect.
  */
 const BOUNDARY_TOLERANCE_METRES = 1
 
 export interface VerifySoilOptions {
-	databasePath: string
+	databasePath: PathBuilderLike
 	client: Pick<SoilDataAccessClient, "mukeyAtPoint">
 	/**
-	 * Points to re-ask the service about. A caller samples them from the artifact — see {@link sampleAgreementPoints}.
+	 * Points to re-ask the service about, sampled from the artifact — see {@link sampleAgreementPoints}.
 	 */
 	points: ReadonlyArray<{ label: string; latitude: number; longitude: number }>
 	outsidePoints?: ReadonlyArray<{ label: string; latitude: number; longitude: number }>
@@ -145,7 +110,7 @@ export async function verifySoilDatabase(options: VerifySoilOptions): Promise<Ve
 	const database = new DatabaseClient<SoilDatabase>(options.databasePath, { readOnly: true })
 	const lookup = new SoilCapabilityLookup({ databasePath: options.databasePath })
 
-	// Read once: the stored index is mixed-resolution because the whole tier is compacted, and a probe that assumed one
+	// Read once: the stored index is mixed-resolution, so a probe that assumed one
 	// resolution would read every row at the others as an absence.
 	const resolutions = (
 		database.prepare("SELECT DISTINCT resolution FROM soil_map_unit_cell ORDER BY resolution").all() as Array<{
@@ -198,16 +163,9 @@ export async function verifySoilDatabase(options: VerifySoilOptions): Promise<Ve
 }
 
 /**
- * The candidate delineations reaching a point, found THROUGH THE CELL INDEX rather than by scanning the geometry table.
- *
- * A bounding-box `WHERE` over `soil_map_unit_area` reads as a prefilter and is a FULL TABLE SCAN: none of those columns
- * is indexed, the rows carry the ring blobs, and at the pilot's scale that is 2.7 million rows and several gigabytes
- * read per point. The cell index exists to make exactly this question cheap — `soil_map_unit_cell` is `WITHOUT ROWID`
- * keyed `(h3_cell, area_id)`, so naming the point's cell is a primary-key range scan.
- *
- * EVERY STORED RESOLUTION IS PROBED, not just the index one. The whole tier is compacted parent-ward, so a delineation
- * that fills a run of cells is stored at a coarser resolution and a probe at the index resolution alone would read it
- * as an absence — the same ancestor walk the reader does, and the same false negative it avoids.
+ * The candidate delineations reaching a point, found through the cell index
+ * because a bounding-box scan over `soil_map_unit_area` is a full table scan. every
+ * stored resolution is probed since the tier is compacted parent-ward.
  */
 function candidateDelineations(
 	database: DatabaseClient<SoilDatabase>,
@@ -233,12 +191,8 @@ function candidateDelineations(
 			mukey: string
 			rings: Uint8Array
 		}>) {
-			// DEDUPE ON THE DELINEATION, NEVER ON ITS MAP UNIT. A delineation reached through two resolutions is one
-			// delineation and must be tested once; two DIFFERENT delineations of the same map unit are two shapes covering
-			// different ground and must both be tested. Keying on the map unit drops the second, and it drops it silently —
-			// the point test simply finds nothing and the row reads as a disagreement with the authority. Measured at Iowa
-			// scale: one point in 60, where the artifact's own geometry does contain the point and the index-driven read
-			// could not reach the delineation that holds it.
+			// Dedupe on the delineation rather than its map unit, since two different delineations
+			// of one map unit cover different ground and both must be tested.
 			if (seen.has(row.area_id)) continue
 
 			seen.add(row.area_id)
@@ -250,11 +204,9 @@ function candidateDelineations(
 }
 
 /**
- * Which map unit the ARTIFACT's own geometry puts at a point, and how far the point is from that delineation's nearest
- * edge.
+ * The map unit that the artifact's geometry places at a point.
  *
- * The cell index narrows; the ray cast decides. The edge distance is measured against every candidate, so a near-miss
- * is reported with a distance rather than with nothing.
+ * Also records the distance to that delineation's nearest edge.
  */
 function localDelineationAt(
 	database: DatabaseClient<SoilDatabase>,
@@ -284,10 +236,9 @@ function localDelineationAt(
 }
 
 /**
- * Metres from a point to the nearest edge of an encoded ring set.
+ * Meters from a point to the nearest edge of an encoded ring set.
  *
- * Decoding here rather than walking the blob directly: this runs a few hundred times in a verification, not per
- * geocode, and the decoded form is what makes the segment walk readable.
+ * This function decodes here because it runs once per verification rather than once per geocode.
  */
 function nearestEdgeDistance(blob: Uint8Array, lon: number, lat: number): number {
 	const { polygons } = decodeRings(blob)
@@ -315,17 +266,11 @@ function nearestEdgeDistance(blob: Uint8Array, lon: number, lat: number): number
 }
 
 /**
- * Draw a reproducible sample of points from the artifact.
- *
- * The draw is a deterministic stride over the primary key, not a random one, so a re-run compares the same points and a
- * disagreement can be looked at rather than re-rolled.
- *
- * ONE ROW IS READ PER SAMPLE POINT AND NO MORE. A `WHERE rowid % stride = 0` scan looks like the same thing and is not:
- * it walks the table itself, which means reading every ring blob to keep a few dozen. `ORDER BY area_id LIMIT 1 OFFSET
- * n` walks the primary-key index to the offset and fetches exactly the row it lands on.
+ * Draw a reproducible sample of points from the artifact, a deterministic stride
+ * over the primary key so a re-run compares the same points.
  */
 export function sampleAgreementPoints(
-	databasePath: string,
+	databasePath: PathBuilderLike,
 	options: { count?: number } = {}
 ): Array<{ label: string; latitude: number; longitude: number }> {
 	const count = options.count ?? 60
@@ -334,9 +279,8 @@ export function sampleAgreementPoints(
 	const total = (database.prepare("SELECT count(*) AS n FROM soil_map_unit_area").get() as { n: number }).n
 	const stride = Math.max(1, Math.floor(total / Math.max(1, count)))
 
-	// One OFFSET probe per sample point rather than one materialized key list. The list looks cheap because it reads
-	// only the primary key, and at the pilot's 2.7 million delineations it is still 2.7 million strings held to keep
-	// sixty of them.
+	// Use one offset probe per sample point instead of materializing a key list.
+	// That list would retain every primary key to select sixty points.
 	const selectByOffset = database.prepare(
 		"SELECT area_id, mukey, min_lat, min_lon, max_lat, max_lon, rings FROM soil_map_unit_area ORDER BY area_id LIMIT 1 OFFSET ?"
 	)

package/lib/sdk/client.ts

@@ -1,184 +0,0 @@
-/**
- * @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, 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 { 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.
- */
-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
-
-/**
- * One published survey area, as the catalogue reports it.
- */
-export interface SurveyAreaCatalogEntry {
-	areasymbol: string
-	areaname: string
-	/**
-	 * The version-established date as an ISO date — what the archive's filename embeds.
-	 */
-	saverest: string
-	saversion: number
-}
-
-/**
- * A client for Soil Data Access.
- */
-export class SoilDataAccessClient extends APIClient<APIClientConfig> {
-	/**
-	 * Run one query and return its rows.
-	 *
-	 * @throws {OGCServiceError} When the service answers with an exception report — including on an HTTP 200, which is
-	 *   what a server-side timeout does.
-	 */
-	public async query(sql: string): Promise<string[][]> {
-		const { data } = await this.fetch<string>({
-			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<{ Table?: unknown }>(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 as unknown[]).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.
-	 */
-	public async readSurveyAreaCatalog(prefix: string): Promise<SurveyAreaCatalogEntry[]> {
-		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.
-	 */
-	public async mukeyAtPoint(latitude: number, longitude: number): Promise<string | undefined> {
-		const rows = await this.query(
-			`SELECT mukey FROM SDA_Get_Mukey_from_intersection_with_WktWgs84('point(${longitude} ${latitude})')`
-		)
-
-		return rows[0]?.[0] || undefined
-	}
-}
-
-export interface CreateSoilDataAccessClientOptions {
-	clock?: ClockLike
-	cacheDirectory?: string
-	minRequestIntervalMs?: number
-}
-
-/**
- * Build a {@link SoilDataAccessClient} with the disk cache and pacing this package's acquisition path expects.
- */
-export function createSoilDataAccessClient(options: CreateSoilDataAccessClientOptions = {}): SoilDataAccessClient {
-	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")),
-			}),
-		},
-	})
-}

package/lib/sdk/download.ts

@@ -1,161 +0,0 @@
-/**
- * @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: string, versionDate: string): string {
-	return `${WSS_SSA_CACHE_URL}/wss_SSA_${areaSymbol}_%5B${versionDate}%5D.zip`
-}
-
-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
-}
-
-/**
- * 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
-
-/**
- * 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 async function downloadSurveyArea(options: DownloadSurveyAreaOptions): Promise<SurveyAreaArchive> {
-	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: string) => 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,
-	}
-}

package/lib/sdk/index.ts

@@ -1,20 +0,0 @@
-/**
- * @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"