@mailwoman/soil 9.4.0 → 10.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (115) hide show
  1. package/README.md +118 -116
  2. package/lib/index.ts +66 -98
  3. package/lib/paths.ts +24 -0
  4. package/lib/schema.ts +188 -120
  5. package/lib/vocabulary.ts +40 -107
  6. package/out/index.d.ts +52 -70
  7. package/out/index.d.ts.map +1 -1
  8. package/out/index.js +24 -72
  9. package/out/index.js.map +1 -1
  10. package/out/paths.d.ts +19 -0
  11. package/out/paths.d.ts.map +1 -0
  12. package/out/paths.js +21 -0
  13. package/out/paths.js.map +1 -0
  14. package/out/schema.d.ts +187 -119
  15. package/out/schema.d.ts.map +1 -1
  16. package/out/schema.js +31 -31
  17. package/out/schema.js.map +1 -1
  18. package/out/sdk/acquire.d.ts +15 -24
  19. package/out/sdk/acquire.d.ts.map +1 -1
  20. package/out/sdk/acquire.js +5 -20
  21. package/out/sdk/acquire.js.map +1 -1
  22. package/out/sdk/build-soil.d.ts +67 -70
  23. package/out/sdk/build-soil.d.ts.map +1 -1
  24. package/out/sdk/build-soil.js +65 -95
  25. package/out/sdk/build-soil.js.map +1 -1
  26. package/out/sdk/cell-tiers.d.ts +7 -19
  27. package/out/sdk/cell-tiers.d.ts.map +1 -1
  28. package/out/sdk/cell-tiers.js +19 -38
  29. package/out/sdk/cell-tiers.js.map +1 -1
  30. package/out/sdk/cells.d.ts +15 -41
  31. package/out/sdk/cells.d.ts.map +1 -1
  32. package/out/sdk/cells.js +11 -38
  33. package/out/sdk/cells.js.map +1 -1
  34. package/out/sdk/client.d.ts +23 -48
  35. package/out/sdk/client.d.ts.map +1 -1
  36. package/out/sdk/client.js +19 -63
  37. package/out/sdk/client.js.map +1 -1
  38. package/out/sdk/download.d.ts +24 -47
  39. package/out/sdk/download.d.ts.map +1 -1
  40. package/out/sdk/download.js +14 -54
  41. package/out/sdk/download.js.map +1 -1
  42. package/out/sdk/ingest/chunk.d.ts +77 -0
  43. package/out/sdk/ingest/chunk.d.ts.map +1 -0
  44. package/out/sdk/{ingest-chunk.js → ingest/chunk.js} +19 -17
  45. package/out/sdk/ingest/chunk.js.map +1 -0
  46. package/out/sdk/ingest/worker.d.ts +9 -0
  47. package/out/sdk/ingest/worker.d.ts.map +1 -0
  48. package/out/{scripts/ingest-chunk.js → sdk/ingest/worker.js} +11 -10
  49. package/out/sdk/ingest/worker.js.map +1 -0
  50. package/out/sdk/ingest.d.ts +40 -52
  51. package/out/sdk/ingest.d.ts.map +1 -1
  52. package/out/sdk/ingest.js +18 -61
  53. package/out/sdk/ingest.js.map +1 -1
  54. package/out/sdk/measure-resolutions.d.ts +5 -16
  55. package/out/sdk/measure-resolutions.d.ts.map +1 -1
  56. package/out/sdk/measure-resolutions.js +3 -15
  57. package/out/sdk/measure-resolutions.js.map +1 -1
  58. package/out/sdk/reduce.d.ts +33 -59
  59. package/out/sdk/reduce.d.ts.map +1 -1
  60. package/out/sdk/reduce.js +47 -78
  61. package/out/sdk/reduce.js.map +1 -1
  62. package/out/sdk/survey-area.d.ts +16 -48
  63. package/out/sdk/survey-area.d.ts.map +1 -1
  64. package/out/sdk/survey-area.js +33 -77
  65. package/out/sdk/survey-area.js.map +1 -1
  66. package/out/sdk/tabular.d.ts +32 -31
  67. package/out/sdk/tabular.d.ts.map +1 -1
  68. package/out/sdk/tabular.js +58 -56
  69. package/out/sdk/tabular.js.map +1 -1
  70. package/out/sdk/test-kit.d.ts +57 -0
  71. package/out/sdk/test-kit.d.ts.map +1 -0
  72. package/out/{test-kit.js → sdk/test-kit.js} +18 -39
  73. package/out/sdk/test-kit.js.map +1 -0
  74. package/out/sdk/verify.d.ts +15 -51
  75. package/out/sdk/verify.d.ts.map +1 -1
  76. package/out/sdk/verify.js +19 -77
  77. package/out/sdk/verify.js.map +1 -1
  78. package/out/vocabulary.d.ts +37 -103
  79. package/out/vocabulary.d.ts.map +1 -1
  80. package/out/vocabulary.js +34 -107
  81. package/out/vocabulary.js.map +1 -1
  82. package/package.json +36 -190
  83. package/{lib/sdk → sdk}/acquire.ts +17 -27
  84. package/{lib/sdk → sdk}/build-soil.ts +114 -128
  85. package/{lib/sdk → sdk}/cell-tiers.ts +20 -39
  86. package/{lib/sdk → sdk}/cells.ts +17 -43
  87. package/sdk/client.ts +147 -0
  88. package/sdk/download.ts +131 -0
  89. package/{lib/sdk/ingest-chunk.ts → sdk/ingest/chunk.ts} +34 -26
  90. package/{lib/scripts/ingest-chunk.ts → sdk/ingest/worker.ts} +10 -9
  91. package/sdk/ingest.ts +253 -0
  92. package/{lib/sdk → sdk}/measure-resolutions.ts +5 -16
  93. package/sdk/reduce.ts +344 -0
  94. package/{lib/sdk → sdk}/survey-area.ts +39 -83
  95. package/{lib/sdk → sdk}/tabular.ts +62 -59
  96. package/{lib → sdk}/test-kit.ts +18 -40
  97. package/{lib/sdk → sdk}/verify.ts +29 -85
  98. package/lib/sdk/client.ts +0 -184
  99. package/lib/sdk/download.ts +0 -161
  100. package/lib/sdk/index.ts +0 -20
  101. package/lib/sdk/ingest.ts +0 -278
  102. package/lib/sdk/reduce.ts +0 -375
  103. package/out/scripts/ingest-chunk.d.ts +0 -11
  104. package/out/scripts/ingest-chunk.d.ts.map +0 -1
  105. package/out/scripts/ingest-chunk.js.map +0 -1
  106. package/out/sdk/index.d.ts +0 -20
  107. package/out/sdk/index.d.ts.map +0 -1
  108. package/out/sdk/index.js +0 -20
  109. package/out/sdk/index.js.map +0 -1
  110. package/out/sdk/ingest-chunk.d.ts +0 -73
  111. package/out/sdk/ingest-chunk.d.ts.map +0 -1
  112. package/out/sdk/ingest-chunk.js.map +0 -1
  113. package/out/test-kit.d.ts +0 -79
  114. package/out/test-kit.d.ts.map +0 -1
  115. package/out/test-kit.js.map +0 -1
package/lib/vocabulary.ts CHANGED
@@ -2,80 +2,48 @@
2
2
  * @copyright Sister Software
3
3
  * @license AGPL-3.0
4
4
  * @author Teffen Ellis, et al.
5
- *
6
- * NRCS's own words, as data: the product identity, the licence sentence it ships inside every archive,
7
- * the acknowledgement it asks for, and the caveats that decide what a reading may claim.
8
- *
9
- * THE RATING VOCABULARY IS NOT HERE, BECAUSE THE AUTHORITY SHIPS IT. `msdomdet.txt` inside each survey
10
- * area's tabular export carries the declared domain for every `Choice` column, WITH the authority's own
11
- * prose definition of each member — capability classes 1 through 8, subclasses `c`/`e`/`s`/`w`, the 28
12
- * farmland classifications, the six component kinds. So the layer reads the domain out of the file it
13
- * ingested rather than transcribing it from the National Soil Survey Handbook, and an out-of-domain value
14
- * throws: an unknown code is a source-schema change, which is the event a reader most needs to hear
15
- * about, and coercing it to a nearest neighbour or to NULL converts "the source changed" into "there is
16
- * nothing here".
17
- *
18
- * THE FARMLAND VOCABULARY IS CONDITIONAL AND THE CONDITION IS THE CLAIM. 28 declared values, of which 24
19
- * carry an "if" — `Prime farmland if drained`, `Prime farmland if irrigated and reclaimed of excess salts
20
- * and sodium`. A boolean `arable` column would be this layer's invention rather than the authority's
21
- * statement, so the string is stored whole.
22
- *
23
- * AND TWO OF ITS CATEGORIES TRAVEL WHILE THE OTHERS DO NOT. 7 CFR 657.5 defines prime farmland and unique
24
- * farmland nationally against nine specific criteria; §657.5(c) and (d) hand "additional farmland of
25
- * statewide importance" and "of local importance" to state and local agencies respectively. So
26
- * `Farmland of statewide importance` in Iowa and in Georgia are not the same claim, and a consumer that
27
- * pooled them into one rank would be pooling incompatible vocabularies. {@link FarmlandScope} carries
28
- * that distinction into the artifact rather than leaving it in a document.
29
5
  */
30
6
 
31
7
  /**
32
- * The layer-name prefix. The suffix names the REGION the build covers, because the manifest's declared extent and the
33
- * coverage rows describe the same set and that set is a list of published survey areas rather than "the United
34
- * States".
8
+ * The prefix of every soil layer name.
9
+ * The reader rejects an artifact whose layer name lacks it.
35
10
  */
36
11
  export const SOIL_LAYER_NAME_PREFIX = "soil-capability-nrcs-ssurgo-"
37
12
 
38
13
  /**
39
- * The layer name for a build over `region`.
14
+ * Returns the layer name for a build over `region`.
40
15
  */
41
16
  export function soilLayerName(region: string): string {
42
17
  return `${SOIL_LAYER_NAME_PREFIX}${region.toLowerCase()}`
43
18
  }
44
19
 
45
20
  /**
46
- * The pilot region — Iowa, whole, built survey area by survey area.
21
+ * The pilot region, Iowa.
47
22
  */
48
23
  export const SOIL_PILOT_REGION = "ia"
49
24
 
50
25
  /**
51
- * The acknowledgement string the shipped FGDC metadata asks for, verbatim as the metadata gives the agency name. This
52
- * is not decoration: the use constraints say the agency "should be acknowledged as the data source in products derived
53
- * from these data", so it rides in `layer_manifest.attribution`.
26
+ * The agency acknowledgement that the SSURGO use constraints require,
27
+ * written to `layer_manifest.attribution`.
54
28
  */
55
29
  export const SSURGO_ATTRIBUTION = "U.S. Department of Agriculture, Natural Resources Conservation Service"
56
30
 
57
31
  /**
58
- * The licence expression written into `layer_manifest.license`.
59
- *
60
- * A public-domain identifier, and the grant behind it is the producing agency's own sentence rather than a catalogue
61
- * field: data.gov's entry points at `usa.gov/publicdomain/label/1.0/`, which redirects to a page that declines a
62
- * blanket grant and tells the reader to check with the agency. The agency was checked at the strongest available place
63
- * — the FGDC metadata NRCS ships inside the archive — and it says {@link SSURGO_PUBLIC_INFORMATION_SENTENCE}.
32
+ * The public-domain license expression written to `layer_manifest.license`, granted by
33
+ * {@link SSURGO_PUBLIC_INFORMATION_SENTENCE} in each archive's FGDC metadata.
64
34
  */
65
35
  export const SSURGO_LICENSE = "LicenseRef-USGov-Public-Domain"
66
36
 
67
37
  /**
68
- * The sentence that makes this layer shippable, verbatim from the `useconst` element of the FGDC metadata inside every
69
- * survey-area archive.
38
+ * The public-information grant quoted from each survey area's FGDC use constraints.
70
39
  *
71
- * The ingest asserts it is present in each area's metadata. A survey area whose use constraints no longer say this is a
72
- * licence change, and a build that absorbed one would ship an artifact under terms nobody checked.
40
+ * The survey-area loader rejects an area whose metadata lacks it, since its
41
+ * absence signals a license change.
73
42
  */
74
43
  export const SSURGO_PUBLIC_INFORMATION_SENTENCE = "This is public information"
75
44
 
76
45
  /**
77
- * The use constraints in full, as the metadata states them. Carried so a reader can check the licence claim against the
78
- * authority's own words rather than against this package's summary of them.
46
+ * The full SSURGO use constraints, quoted from the FGDC metadata.
79
47
  */
80
48
  export const SSURGO_USE_CONSTRAINTS =
81
49
  "The U.S. Department of Agriculture, Natural Resources Conservation Service, should be acknowledged as the data " +
@@ -85,11 +53,10 @@ export const SSURGO_USE_CONSTRAINTS =
85
53
  "responsible for the appropriate application."
86
54
 
87
55
  /**
88
- * What a reading is NOT, in the authority's own words. Carried on every reading, because a caller cannot see from a
89
- * capability class that the survey declines to speak about a specific site.
56
+ * NRCS states these SSURGO limitations verbatim.
90
57
  *
91
- * The first two sentences are why §3.1 of the survey forbids a point-level determination: the map is authoritative
92
- * about an area at its own scale and explicitly declines to be authoritative about a point.
58
+ * Every reading includes them.
59
+ * They describe the map unit covering a point rather than a site-specific determination.
93
60
  */
94
61
  export const SSURGO_PRODUCT_LIMITS: ReadonlyArray<string> = [
95
62
  "The depicted soil boundaries, interpretations, and analysis derived from them do not eliminate the need for onsite sampling, testing, and detailed study of specific sites for intensive uses. Thus, these data and their interpretations are intended for planning purposes only.",
@@ -100,78 +67,57 @@ export const SSURGO_PRODUCT_LIMITS: ReadonlyArray<string> = [
100
67
  ]
101
68
 
102
69
  /**
103
- * The coverage statement a `designated` basis rests on: what NRCS declares complete inside a published survey area.
104
- *
105
- * It is the mapping at the survey's own scale, NOT a site-specific determination — which is why the observation reports
106
- * what the survey assigns to the map unit covering a location and never whether the land can be farmed.
70
+ * The coverage statement: soil mapping is complete at survey scale inside a
71
+ * published survey area and absent outside one.
107
72
  */
108
73
  export const SSURGO_COVERAGE_STATEMENT =
109
74
  "Soil surveys are published by survey area. Inside a published survey area the soil mapping is complete at the " +
110
75
  "survey's own scale; land outside any published survey area has no soil map unit at all."
111
76
 
112
77
  /**
113
- * Where the product's identity and cadence are published.
78
+ * The page that publishes the product's identity and update schedule.
114
79
  */
115
80
  export const SSURGO_STATEMENT_URL =
116
81
  "https://www.nrcs.usda.gov/conservation-basics/natural-resource-concerns/soil/annual-soils-refresh"
117
82
 
118
83
  /**
119
- * The dataset identifier written into `layer_manifest.source`.
84
+ * The dataset identifier written to `layer_manifest.source`.
120
85
  */
121
86
  export const SSURGO_SOURCE = "nrcs.usda.gov/SSURGO"
122
87
 
123
88
  /**
124
- * The projection every SSURGO survey-area shapefile declares. The `.prj` is an ESRI WKT naming `GCS_WGS_1984`, which
125
- * GDAL resolves to this authority code — so no reprojection is needed before H3, and a survey area declaring anything
126
- * else is a product change rather than a variation to absorb.
89
+ * The EPSG code that every SSURGO survey-area shapefile declares, required by the ingest by default.
127
90
  */
128
91
  export const SSURGO_SOURCE_EPSG = 4326
129
92
 
130
93
  /**
131
- * Whether a farmland classification's criteria are set nationally or by a state or local agency.
132
- *
133
- * 7 CFR 657.5 defines prime and unique farmland against nine national criteria; (c) and (d) delegate statewide and
134
- * local importance. A consumer comparing two states may compare the national categories and must not compare the
135
- * delegated ones.
94
+ * The authorities that can set a farmland classification's criteria; `None` covers
95
+ * not-prime farmland and land with no classification.
136
96
  */
137
97
  export const FarmlandScope = {
138
- /**
139
- * Criteria set by 7 CFR 657.5(a)–(b). Comparable across the country.
140
- */
141
98
  Federal: "federal",
142
- /**
143
- * Criteria "determined by the appropriate State agency or agencies" — 7 CFR 657.5(c).
144
- */
99
+
145
100
  State: "state",
146
- /**
147
- * Criteria "identified by the local agency or agencies concerned" — 7 CFR 657.5(d).
148
- */
101
+
149
102
  Local: "local",
150
- /**
151
- * The value states no farmland importance at all.
152
- */
103
+
153
104
  None: "none",
154
105
  } as const
155
106
 
107
+ /**
108
+ * One {@link FarmlandScope} value, as stored in the `farmland_scope` column.
109
+ */
156
110
  export type FarmlandScope = (typeof FarmlandScope)[keyof typeof FarmlandScope]
157
111
 
158
112
  /**
159
- * Which scope a declared `farmlndcl` value falls under, decided on the phrase the regulation itself uses.
160
- *
161
- * Matching on the phrase rather than on an enumerated list of the 28 values is deliberate: the domain grows — the
162
- * conditional tail is generated by combining a base category with a condition — and a new `Farmland of statewide
163
- * importance, if …` must land in {@link FarmlandScope.State} on the day it appears rather than silently defaulting to
164
- * the comparable bucket.
113
+ * Classifies a `farmlndcl` value into a {@link FarmlandScope} by the phrase the regulation uses,
114
+ * so a conditional value such as `Farmland of statewide importance, if …` still gets the right scope.
165
115
  */
166
116
  export function farmlandScope(value: string | null | undefined): FarmlandScope {
167
117
  if (!value) return FarmlandScope.None
168
118
 
169
119
  const lowered = value.toLowerCase()
170
120
 
171
- // FIRST, because it CONTAINS the phrase the federal test looks for. `Not prime farmland` is a declared value stating
172
- // no farmland importance at all, and a substring test that ran the other way round would call it federally comparable
173
- // prime farmland — which it is the exact negation of. It is also the most common value in the domain: 192,120 of the
174
- // 339,191 national map units carry it.
175
121
  if (lowered.startsWith("not prime farmland")) return FarmlandScope.None
176
122
 
177
123
  if (lowered.includes("statewide importance")) return FarmlandScope.State
@@ -184,21 +130,14 @@ export function farmlandScope(value: string | null | undefined): FarmlandScope {
184
130
  }
185
131
 
186
132
  /**
187
- * Map-unit symbols NRCS uses for a delineation it has drawn and has no soil mapping behind.
188
- *
189
- * These are polygons rather than holes — the same wall-to-wall discipline that makes them separable from land outside a
190
- * survey area entirely. Measured nationally through Soil Data Access: 37 map units carry `NOTCOM` (`No Digital Data
191
- * Available`) and 7 carry `NOTPUB` (`Not Public Information`).
133
+ * The upper-case map-unit symbols that NRCS gives a delineation it drew without soil mapping.
192
134
  */
193
135
  export const SSURGO_NO_MAPPING_SYMBOLS: ReadonlySet<string> = new Set(["NOTCOM", "NOTPUB"])
194
136
 
195
137
  /**
196
- * Map-unit names for the same case, where the symbol does not carry it. Measured nationally: 72 map units are named
197
- * `Area not surveyed, access denied`.
138
+ * The lower-case map-unit names that mark a delineation without soil mapping when its symbol does not.
198
139
  *
199
- * Matched case-insensitively on the whole name. A prefix match would catch a future `Area not surveyed, access denied —
200
- * pending` and would also catch nothing else, but it would equally catch a real soil name beginning with those words,
201
- * and there is no such thing to be gained by guessing.
140
+ * The match uses the whole name, since a prefix could also match a real soil name.
202
141
  */
203
142
  export const SSURGO_NO_MAPPING_NAMES: ReadonlySet<string> = new Set([
204
143
  "area not surveyed, access denied",
@@ -207,32 +146,26 @@ export const SSURGO_NO_MAPPING_NAMES: ReadonlySet<string> = new Set([
207
146
  ])
208
147
 
209
148
  /**
210
- * The interpretation rule whose overall value this layer carries, exactly as `cointerp.mrulename` spells it.
211
- *
212
- * Its `interphr` is an index in [0, 1] — measured 0.001 to 0.991 nationally, 0.022 to 0.990 on `IA153` — and it is
213
- * never blended with the capability class: they are two ratings from one authority answering different questions, and
214
- * combining them would produce a number NRCS does not publish.
149
+ * The `cointerp.mrulename` of the productivity index this layer stores, kept apart from the capability
150
+ * class because a combination of the two would be a number NRCS does not publish.
215
151
  */
216
152
  export const NCCPI_V3_RULE_NAME = "NCCPI - National Commodity Crop Productivity Index (Ver 3.0)"
217
153
 
218
154
  /**
219
- * The interpretation depth at which a rule reports its own overall value. Sub-rules sit at greater depths and are the
220
- * submodels (corn, soybeans, small grains, cotton), which this layer does not carry.
155
+ * The `cointerp.ruledepth` at which a rule reports its overall value instead of a crop submodel.
221
156
  */
222
157
  export const COINTERP_OVERALL_RULE_DEPTH = "0"
223
158
 
224
159
  /**
225
- * How the per-cell shares were produced, recorded on every row.
160
+ * The code of the area-times-component-percentage weighting that produced the per-cell shares.
226
161
  *
227
- * The survey names this as a required record because the weighting mixes two different things — polygon geometry, which
228
- * the survey does know, and component percentages, which are a proportion without a location. "60% of this cell's area
229
- * lies in map units whose components are class 2" and "the components in this cell sum to 60% class 2" are different
230
- * claims, and a reader holding only a share cannot tell which one it is holding.
162
+ * Component percentages have no location, so a share indicates how much of a cell
163
+ * lies in rated map units and not where the rating applies.
231
164
  */
232
165
  export const SOIL_SHARE_WEIGHTING = "cell_area_x_comppct_r"
233
166
 
234
167
  /**
235
- * The one-sentence expansion of {@link SOIL_SHARE_WEIGHTING}, stored beside it so the artifact explains itself.
168
+ * The prose description of {@link SOIL_SHARE_WEIGHTING}, stored beside it in the artifact.
236
169
  */
237
170
  export const SOIL_SHARE_WEIGHTING_DESCRIPTION =
238
171
  "Each map-unit delineation contributes the area of the cell it covers; that area is split across the delineation's " +
package/out/index.d.ts CHANGED
@@ -3,115 +3,95 @@
3
3
  * @license AGPL-3.0
4
4
  * @author Teffen Ellis, et al.
5
5
  *
6
- * The `soil.db` reader — what the soil survey assigns at a coordinate, and on what basis.
7
- *
8
- * THREE ANSWERS, AND KEEPING THEM APART IS THE WHOLE JOB.
9
- *
10
- * 1. `designated` — the survey mapped this location and the cell's class distribution is the answer.
11
- * 2. `designated_no_rating` — the survey mapped this location and rated nothing there. A cell that is
12
- * 100% `unrated_share` or `notrateable_share` is `designated`-complete and carries no capability
13
- * reading whatsoever, and that is not a corner case: 17.1% of national components carry no capability
14
- * rating.
15
- * 3. `unknown` — no coverage row. Outside any published survey area, or inside one where the polygon
16
- * exists and the soil mapping behind it does not.
17
- *
18
- * READINGS 2 AND 3 LOOK THE SAME FROM A CLASS CODE AND ARE OPPOSITE ANSWERS FROM THE READER. A layer that
19
- * could not tell them apart would report unmapped ground as unrated ground, which is one of the four
20
- * absences this whole layer exists to keep separate.
21
- *
22
- * THE ANSWER IS A DISTRIBUTION, AND THE TOP CLASS ALWAYS ARRIVES WITH THE SHARE IT RESTS ON. NRCS's own
23
- * `muaggatt` ships `niccdcd` beside `niccdcdpct` for exactly this reason, with an observed minimum of 2%.
24
- * A caller that wants one class may take `topClass`; it cannot take it without also being handed
25
- * `topClassShare`, because a 2% plurality and an 85% majority are different claims.
26
- *
27
- * NEITHER READING IS A STATEMENT ABOUT WHETHER THE LAND CAN BE FARMED. The layer reports what the soil
28
- * survey assigns to the map unit covering a location, which is a fact about the map. NRCS states that its
29
- * data "do not eliminate the need for onsite sampling, testing, and detailed study of specific sites for
30
- * intensive uses" and are "intended for planning purposes only" — so `limits` carries the authority's own
31
- * exclusions on every answer.
32
- *
33
- * THE PROBE IS ONE PRIMARY-KEY READ. The reduction is single-resolution and one row per cell, which is
34
- * what makes it the spine key: a coordinate becomes a cell, the cell becomes a row, and the geometry tier
35
- * underneath is never touched at read time. The unsimplified rings are there for a caller that wants to
36
- * re-derive the claim, not for the probe.
37
- *
38
- * THE READER IS SYNCHRONOUS AND USES RAW PREPARED STATEMENTS, matching the resolution ladder's existing
39
- * shape. The DDL that created these tables IS Kysely — see `schema.ts`.
6
+ * Synchronous reader for `soil.db` that returns the soil survey's capability-class distribution at a coordinate.
40
7
  */
41
8
  import { type CoverageCell, type LayerManifest } from "@mailwoman/core/layers";
9
+ import type { PathBuilderLike } from "path-ts";
42
10
  export { FarmlandScope, farmlandScope, SSURGO_PRODUCT_LIMITS } from "#vocabulary";
43
11
  /**
44
- * What the layer can say about a coordinate.
12
+ * The kinds of answer the layer gives for a coordinate, where `DesignatedNoRating`
13
+ * and `Unknown` must stay apart.
45
14
  */
46
15
  export declare const SoilReadingKind: {
47
16
  /**
48
- * The survey mapped this location and assigns at least one capability class here.
17
+ * The survey mapped this location and assigns at least one capability class.
49
18
  */
50
19
  readonly Designated: "designated";
51
20
  /**
52
- * The survey mapped this location and rated nothing here — every share is an absence share.
21
+ * The survey mapped this location and assigned no rating.
22
+ * Every share is reported as an absence share.
53
23
  */
54
24
  readonly DesignatedNoRating: "designated_no_rating";
55
25
  /**
56
- * No coverage row. Unmapped by this authority, and never a low-capability reading.
26
+ * The layer has no coverage for this location.
27
+ * This does not imply low capability.
57
28
  */
58
29
  readonly Unknown: "unknown";
59
30
  };
31
+ /**
32
+ * One of the {@link SoilReadingKind} values.
33
+ */
60
34
  export type SoilReadingKind = (typeof SoilReadingKind)[keyof typeof SoilReadingKind];
61
35
  /**
62
- * The per-cell distribution, as a caller reads it.
36
+ * The capability-class distribution of one cell.
63
37
  */
64
38
  export interface SoilCapabilityDistribution {
65
39
  /**
66
- * The authority's class codes mapped to their area-weighted share, largest first.
40
+ * The authority's class codes mapped to their area-weighted shares, largest first.
67
41
  */
68
42
  classShares: Record<string, number>;
69
43
  /**
70
- * Mapped soil components carrying a NULL rating — the survey did not rate them.
44
+ * The share of mapped soil components that have a NULL rating.
71
45
  */
72
46
  unratedShare: number;
73
47
  /**
74
- * Miscellaneous areas the rating does not apply to.
48
+ * The share of miscellaneous areas that the rating does not apply to.
75
49
  */
76
50
  notRateableShare: number;
77
51
  /**
78
- * Polygons with no soil mapping behind them.
52
+ * The share of polygons that have no soil mapping.
79
53
  */
80
54
  noDataShare: number;
81
55
  /**
82
- * The truncated minority tail. The five shares sum to 1.
56
+ * The share of the truncated minority classes.
57
+ * The class shares and the four other shares sum to 1.
83
58
  */
84
59
  otherShare: number;
85
60
  /**
86
- * How much of the cell any delineation covers. Below 1 at a survey-area edge.
61
+ * The fraction of the cell covered by any delineation.
62
+ * It falls below 1 at a survey-area edge.
87
63
  */
88
64
  mappedShare: number;
89
65
  /**
90
- * The largest class share, and the share it rests on. Absent when the cell carries no class at all.
66
+ * The class with the largest share, absent when the cell has no class.
67
+ *
68
+ * A caller that reads `topClass` should also report `topClassShare`,
69
+ * because the top class can hold a small plurality.
91
70
  */
92
71
  topClass?: string;
93
72
  topClassShare?: number;
94
73
  /**
95
- * Which weighting produced these shares.
74
+ * The weighting that produced these shares.
96
75
  */
97
76
  weighting: string;
98
77
  /**
99
- * How many delineations reached the cell.
78
+ * The number of delineations that reached the cell.
100
79
  */
101
80
  delineations: number;
102
81
  }
103
82
  /**
104
- * One survey area, as the layer holds it.
83
+ * One survey area in the layer.
105
84
  */
106
85
  export interface SoilSurveyAreaRecord {
107
86
  areaSymbol: string;
108
87
  areaName: string;
109
88
  /**
110
- * The refresh — when this version of the data was established.
89
+ * The date on which this version of the survey data was established.
111
90
  */
112
91
  saverest: string;
113
92
  /**
114
- * The FIELD survey date, which is a different fact and is usually much older.
93
+ * The field survey date.
94
+ * It can be much older than `saverest`.
115
95
  */
116
96
  surveySourceDate: string | null;
117
97
  surveySourceTitle: string | null;
@@ -119,55 +99,58 @@ export interface SoilSurveyAreaRecord {
119
99
  mappingScale: number | null;
120
100
  }
121
101
  /**
122
- * One reading, carrying everything a caller needs to re-derive it rather than take it.
102
+ * One reading at a coordinate, with the provenance a caller needs to check it.
123
103
  */
124
104
  export interface SoilCapabilityReading {
125
105
  kind: SoilReadingKind;
126
106
  /**
127
- * The cell's distribution. Present on both designated readings; absent on `unknown`.
107
+ * The cell's distribution, present on both designated kinds and absent on `unknown`.
128
108
  */
129
109
  distribution?: SoilCapabilityDistribution;
130
110
  /**
131
- * The authority's own definition of the top class, from the domain it shipped.
111
+ * The authority's definition of the top class, from its vocabulary.
132
112
  */
133
113
  topClassDefinition?: string;
134
114
  /**
135
- * The survey area covering the location, with both its dates.
115
+ * The survey area that covers the location.
136
116
  */
137
117
  surveyArea?: SoilSurveyAreaRecord;
138
118
  /**
139
- * The coverage row that licenses the reading, when there is one. Absent on `unknown`, which IS the absence.
119
+ * The coverage row that supports the reading, when one exists.
140
120
  */
141
121
  coverage?: CoverageCell & {
142
122
  h3CellIndex: string;
143
123
  resolution: number;
144
124
  };
145
125
  /**
146
- * The index cell probed, for a receipt.
126
+ * The H3 index cell that the lookup probed.
147
127
  */
148
128
  indexCellIndex: string;
149
129
  /**
150
- * What the product does not cover, in the authority's own words. Carried on every reading.
130
+ * The authority's own statements of what the product does not cover.
131
+ *
132
+ * Every reading includes them because the survey supports planning only
133
+ * and does not replace onsite study.
151
134
  */
152
135
  limits: ReadonlyArray<string>;
153
136
  }
154
137
  /**
155
- * The layer's identity, read once at open time.
138
+ * The layer's identity, read once when the database opens.
156
139
  */
157
140
  export interface SoilLayerIdentity {
158
141
  manifest: LayerManifest;
159
142
  indexResolution: number;
160
143
  coverageResolution: number;
161
144
  /**
162
- * The survey areas the layer covers, in symbol order.
145
+ * The survey areas the layer covers, ordered by area symbol.
163
146
  */
164
147
  surveyAreas: SoilSurveyAreaRecord[];
165
148
  /**
166
- * The class codes the layer's own vocabulary declares.
149
+ * The class codes that the layer's vocabulary declares.
167
150
  */
168
151
  classCodes: string[];
169
152
  /**
170
- * The weighting every stored share was produced under, and the sentence that says what it means.
153
+ * The code of the weighting used for every stored share, with its description.
171
154
  */
172
155
  weighting: {
173
156
  code: string;
@@ -175,23 +158,22 @@ export interface SoilLayerIdentity {
175
158
  };
176
159
  databasePath: string;
177
160
  }
161
+ /**
162
+ * Options for {@link SoilCapabilityLookup}.
163
+ */
178
164
  export interface SoilCapabilityLookupOptions {
179
- databasePath: string;
165
+ databasePath: PathBuilderLike;
180
166
  }
181
167
  /**
182
- * Read a sealed `soil.db`.
183
- *
184
- * Everything that would make the reader answer a well-formed wrong thing is refused at CONSTRUCTION rather than at
185
- * query time: a manifest naming a different product, a coverage table with no rows, a vocabulary with no classes. Each
186
- * of those would otherwise present as a reader that simply always answers `unknown`, which on a receipt is
187
- * indistinguishable from a region the authority genuinely has not surveyed.
168
+ * Reads a sealed `soil.db`, throwing at construction on a manifest for a different product,
169
+ * an empty coverage table, an empty class vocabulary, or a missing share weighting.
188
170
  */
189
171
  export declare class SoilCapabilityLookup implements Disposable {
190
172
  #private;
191
173
  readonly identity: SoilLayerIdentity;
192
174
  constructor(options: SoilCapabilityLookupOptions);
193
175
  /**
194
- * What the soil survey assigns at this coordinate.
176
+ * Returns what the soil survey assigns at this coordinate.
195
177
  */
196
178
  lookup(latitude: number, longitude: number): SoilCapabilityReading;
197
179
  [Symbol.dispose](): void;
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAGH,OAAO,EAIN,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,MAAM,wBAAwB,CAAA;AAS/B,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAEjF;;GAEG;AACH,eAAO,MAAM,eAAe;IAC3B;;OAEG;;IAEH;;OAEG;;IAEH;;OAEG;;CAEM,CAAA;AAEV,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,OAAO,eAAe,CAAC,CAAA;AAEpF;;GAEG;AACH,MAAM,WAAW,0BAA0B;IAC1C;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACnC;;OAEG;IACH,YAAY,EAAE,MAAM,CAAA;IACpB;;OAEG;IACH,gBAAgB,EAAE,MAAM,CAAA;IACxB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAA;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACrC,IAAI,EAAE,eAAe,CAAA;IACrB;;OAEG;IACH,YAAY,CAAC,EAAE,0BAA0B,CAAA;IACzC;;OAEG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B;;OAEG;IACH,UAAU,CAAC,EAAE,oBAAoB,CAAA;IACjC;;OAEG;IACH,QAAQ,CAAC,EAAE,YAAY,GAAG;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAA;IACrE;;OAEG;IACH,cAAc,EAAE,MAAM,CAAA;IACtB;;OAEG;IACH,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IACjC,QAAQ,EAAE,aAAa,CAAA;IACvB,eAAe,EAAE,MAAM,CAAA;IACvB,kBAAkB,EAAE,MAAM,CAAA;IAC1B;;OAEG;IACH,WAAW,EAAE,oBAAoB,EAAE,CAAA;IACnC;;OAEG;IACH,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB;;OAEG;IACH,SAAS,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAA;IAChD,YAAY,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,2BAA2B;IAC3C,YAAY,EAAE,MAAM,CAAA;CACpB;AAED;;;;;;;GAOG;AACH,qBAAa,oBAAqB,YAAW,UAAU;;IACtD,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAA;gBASxB,OAAO,EAAE,2BAA2B;IAyBhD;;OAEG;IACI,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,qBAAqB;IAqElE,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAqC/B"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"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"}