@honua/react 0.1.0-beta.0 → 0.1.1-beta.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 (315) hide show
  1. package/contract/discovery.d.ts +231 -0
  2. package/contract/discovery.d.ts.map +1 -0
  3. package/contract/discovery.js +554 -0
  4. package/contract/edit-sketch.d.ts +8 -0
  5. package/contract/edit-sketch.d.ts.map +1 -1
  6. package/contract/edit-sketch.js +15 -0
  7. package/contract/edit-snapping.d.ts +160 -0
  8. package/contract/edit-snapping.d.ts.map +1 -0
  9. package/contract/edit-snapping.js +675 -0
  10. package/contract/generated/projjson-v0.7-crs-validator.d.ts +35 -0
  11. package/contract/generated/projjson-v0.7-crs-validator.d.ts.map +1 -0
  12. package/contract/generated/projjson-v0.7-crs-validator.js +3941 -0
  13. package/contract/index.d.ts +11 -2
  14. package/contract/index.d.ts.map +1 -1
  15. package/contract/index.js +4 -1
  16. package/contract/pmtiles.d.ts +31 -0
  17. package/contract/pmtiles.d.ts.map +1 -1
  18. package/contract/pmtiles.js +60 -20
  19. package/contract/protocol-module.d.ts +70 -0
  20. package/contract/protocol-module.d.ts.map +1 -0
  21. package/contract/protocol-module.js +1 -0
  22. package/contract/schema-envelope.d.ts +26 -0
  23. package/contract/schema-envelope.d.ts.map +1 -0
  24. package/contract/schema-envelope.js +25 -0
  25. package/contract/schema.d.ts +582 -0
  26. package/contract/schema.d.ts.map +1 -0
  27. package/contract/schema.js +2483 -0
  28. package/contract/source-capability-support.d.ts +6 -0
  29. package/contract/source-capability-support.d.ts.map +1 -0
  30. package/contract/source-capability-support.js +154 -0
  31. package/contract/source.d.ts +35 -17
  32. package/contract/source.d.ts.map +1 -1
  33. package/contract/source.js +267 -71
  34. package/contract/types.d.ts +140 -4
  35. package/contract/types.d.ts.map +1 -1
  36. package/contract/types.js +6 -14
  37. package/core/bounded-json.d.ts +4 -0
  38. package/core/bounded-json.d.ts.map +1 -0
  39. package/core/bounded-json.js +38 -0
  40. package/core/cache-state.d.ts +9 -0
  41. package/core/cache-state.d.ts.map +1 -1
  42. package/core/cache-state.js +10 -0
  43. package/core/capabilities-xml.d.ts +33 -0
  44. package/core/capabilities-xml.d.ts.map +1 -0
  45. package/core/capabilities-xml.js +331 -0
  46. package/core/client.d.ts +4 -1
  47. package/core/client.d.ts.map +1 -1
  48. package/core/client.js +115 -29
  49. package/core/error-classifications.d.ts +153 -0
  50. package/core/error-classifications.d.ts.map +1 -0
  51. package/core/error-classifications.js +140 -0
  52. package/core/error-code-registry.d.ts +158 -0
  53. package/core/error-code-registry.d.ts.map +1 -0
  54. package/core/error-code-registry.js +143 -0
  55. package/core/error-envelope.d.ts +68 -0
  56. package/core/error-envelope.d.ts.map +1 -0
  57. package/core/error-envelope.js +357 -0
  58. package/core/errors.d.ts +45 -29
  59. package/core/errors.d.ts.map +1 -1
  60. package/core/errors.js +97 -50
  61. package/core/geoparquet-sql.d.ts +30 -2
  62. package/core/geoparquet-sql.d.ts.map +1 -1
  63. package/core/geoparquet-sql.js +38 -3
  64. package/core/odata-key-path.d.ts +12 -0
  65. package/core/odata-key-path.d.ts.map +1 -0
  66. package/core/odata-key-path.js +28 -0
  67. package/core/odata-write-codec.d.ts +66 -0
  68. package/core/odata-write-codec.d.ts.map +1 -0
  69. package/core/odata-write-codec.js +1083 -0
  70. package/core/odata.d.ts +59 -7
  71. package/core/odata.d.ts.map +1 -1
  72. package/core/odata.js +431 -99
  73. package/core/ogc-features.d.ts.map +1 -1
  74. package/core/ogc-features.js +3 -0
  75. package/core/ogc-maps.d.ts +7 -0
  76. package/core/ogc-maps.d.ts.map +1 -1
  77. package/core/ogc-maps.js +46 -7
  78. package/core/ogc-processes.d.ts +2 -1
  79. package/core/ogc-processes.d.ts.map +1 -1
  80. package/core/ogc-processes.js +33 -5
  81. package/core/ogc-records.d.ts +9 -0
  82. package/core/ogc-records.d.ts.map +1 -1
  83. package/core/ogc-records.js +78 -29
  84. package/core/ogc-tiles.d.ts +10 -1
  85. package/core/ogc-tiles.d.ts.map +1 -1
  86. package/core/ogc-tiles.js +56 -17
  87. package/core/path-utils.d.ts +9 -0
  88. package/core/path-utils.d.ts.map +1 -1
  89. package/core/path-utils.js +19 -0
  90. package/core/protocol-transport.d.ts +1 -0
  91. package/core/protocol-transport.d.ts.map +1 -1
  92. package/core/request-pipeline.d.ts.map +1 -1
  93. package/core/request-pipeline.js +1 -1
  94. package/core/spatial-filter.d.ts +8 -4
  95. package/core/spatial-filter.d.ts.map +1 -1
  96. package/core/spatial-filter.js +206 -16
  97. package/core/stac-static.d.ts +6 -2
  98. package/core/stac-static.d.ts.map +1 -1
  99. package/core/stac-static.js +260 -69
  100. package/core/surfaces.d.ts.map +1 -1
  101. package/core/surfaces.js +69 -5
  102. package/core/types.d.ts +125 -7
  103. package/core/types.d.ts.map +1 -1
  104. package/core/wfs-capabilities.d.ts +2 -0
  105. package/core/wfs-capabilities.d.ts.map +1 -1
  106. package/core/wfs-capabilities.js +8 -1
  107. package/core/wfs.d.ts.map +1 -1
  108. package/core/wfs.js +10 -0
  109. package/core/wms-capabilities.d.ts +56 -84
  110. package/core/wms-capabilities.d.ts.map +1 -1
  111. package/core/wms-capabilities.js +212 -509
  112. package/core/wmts-capabilities.d.ts +62 -62
  113. package/core/wmts-capabilities.d.ts.map +1 -1
  114. package/core/wmts-capabilities.js +224 -371
  115. package/esri-compat/editor.d.ts +8 -0
  116. package/esri-compat/editor.d.ts.map +1 -1
  117. package/esri-compat/editor.js +13 -0
  118. package/esri-compat/feature-layer.d.ts +2 -0
  119. package/esri-compat/feature-layer.d.ts.map +1 -1
  120. package/esri-compat/feature-layer.js +1 -0
  121. package/esri-compat/layer-list.d.ts +11 -0
  122. package/esri-compat/layer-list.d.ts.map +1 -1
  123. package/esri-compat/layer-list.js +49 -0
  124. package/esri-compat/legend.d.ts +10 -0
  125. package/esri-compat/legend.d.ts.map +1 -1
  126. package/esri-compat/legend.js +27 -0
  127. package/esri-compat/portal.d.ts +197 -0
  128. package/esri-compat/portal.d.ts.map +1 -0
  129. package/esri-compat/portal.js +251 -0
  130. package/esri-compat/renderer-objects.d.ts +40 -0
  131. package/esri-compat/renderer-objects.d.ts.map +1 -0
  132. package/esri-compat/renderer-objects.js +62 -0
  133. package/esri-compat/sketch.d.ts +43 -0
  134. package/esri-compat/sketch.d.ts.map +1 -1
  135. package/esri-compat/sketch.js +46 -0
  136. package/esri-compat/snapping.d.ts +43 -0
  137. package/esri-compat/snapping.d.ts.map +1 -0
  138. package/esri-compat/snapping.js +45 -0
  139. package/esri-compat/url.d.ts.map +1 -1
  140. package/esri-compat/url.js +1 -1
  141. package/esri-compat/widget-host.d.ts +84 -0
  142. package/esri-compat/widget-host.d.ts.map +1 -0
  143. package/esri-compat/widget-host.js +159 -0
  144. package/filter-registry/index.d.ts +145 -0
  145. package/filter-registry/index.d.ts.map +1 -0
  146. package/filter-registry/index.js +531 -0
  147. package/generated-app/errors.d.ts +18 -2
  148. package/generated-app/errors.d.ts.map +1 -1
  149. package/generated-app/errors.js +44 -11
  150. package/map/automatic-mount-integration.d.ts +134 -0
  151. package/map/automatic-mount-integration.d.ts.map +1 -0
  152. package/map/automatic-mount-integration.js +305 -0
  153. package/map/automatic-source-strategy.d.ts +125 -0
  154. package/map/automatic-source-strategy.d.ts.map +1 -0
  155. package/map/automatic-source-strategy.js +494 -0
  156. package/map/data-to-map-bridge.d.ts +293 -0
  157. package/map/data-to-map-bridge.d.ts.map +1 -0
  158. package/map/data-to-map-bridge.js +817 -0
  159. package/map/geojson-projection.d.ts +33 -0
  160. package/map/geojson-projection.d.ts.map +1 -0
  161. package/map/geojson-projection.js +118 -0
  162. package/map/index.d.ts +14 -0
  163. package/map/index.d.ts.map +1 -1
  164. package/map/index.js +8 -0
  165. package/map/raster-source-spec.d.ts +30 -0
  166. package/map/raster-source-spec.d.ts.map +1 -0
  167. package/map/raster-source-spec.js +190 -0
  168. package/map/raster-source-strategy.d.ts +65 -0
  169. package/map/raster-source-strategy.d.ts.map +1 -0
  170. package/map/raster-source-strategy.js +232 -0
  171. package/map/source-to-maplibre.d.ts +91 -0
  172. package/map/source-to-maplibre.d.ts.map +1 -0
  173. package/map/source-to-maplibre.js +454 -0
  174. package/map/temporal-playback.d.ts +139 -0
  175. package/map/temporal-playback.d.ts.map +1 -0
  176. package/map/temporal-playback.js +247 -0
  177. package/package.json +14 -1
  178. package/query-planner/canonical.d.ts +7 -0
  179. package/query-planner/canonical.d.ts.map +1 -0
  180. package/query-planner/canonical.js +145 -0
  181. package/query-planner/cql2-json.d.ts +17 -0
  182. package/query-planner/cql2-json.d.ts.map +1 -0
  183. package/query-planner/cql2-json.js +646 -0
  184. package/query-planner/diagnostics.d.ts +35 -0
  185. package/query-planner/diagnostics.d.ts.map +1 -0
  186. package/query-planner/diagnostics.js +373 -0
  187. package/query-planner/duckdb.d.ts +79 -0
  188. package/query-planner/duckdb.d.ts.map +1 -0
  189. package/query-planner/duckdb.js +758 -0
  190. package/query-planner/execution-context.d.ts +5 -0
  191. package/query-planner/execution-context.d.ts.map +1 -0
  192. package/query-planner/execution-context.js +50 -0
  193. package/query-planner/executor.d.ts +5 -0
  194. package/query-planner/executor.d.ts.map +1 -0
  195. package/query-planner/executor.js +223 -0
  196. package/query-planner/geoservices.d.ts +91 -0
  197. package/query-planner/geoservices.d.ts.map +1 -0
  198. package/query-planner/geoservices.js +667 -0
  199. package/query-planner/grpc.d.ts +100 -0
  200. package/query-planner/grpc.d.ts.map +1 -0
  201. package/query-planner/grpc.js +736 -0
  202. package/query-planner/index.d.ts +44 -0
  203. package/query-planner/index.d.ts.map +1 -0
  204. package/query-planner/index.js +30 -0
  205. package/query-planner/ir.d.ts +20 -0
  206. package/query-planner/ir.d.ts.map +1 -0
  207. package/query-planner/ir.js +417 -0
  208. package/query-planner/local-aggregate.d.ts +5 -0
  209. package/query-planner/local-aggregate.d.ts.map +1 -0
  210. package/query-planner/local-aggregate.js +126 -0
  211. package/query-planner/odata.d.ts +48 -0
  212. package/query-planner/odata.d.ts.map +1 -0
  213. package/query-planner/odata.js +662 -0
  214. package/query-planner/ogc-compiler.d.ts +55 -0
  215. package/query-planner/ogc-compiler.d.ts.map +1 -0
  216. package/query-planner/ogc-compiler.js +480 -0
  217. package/query-planner/ogc-features.d.ts +53 -0
  218. package/query-planner/ogc-features.d.ts.map +1 -0
  219. package/query-planner/ogc-features.js +617 -0
  220. package/query-planner/planner.d.ts +17 -0
  221. package/query-planner/planner.d.ts.map +1 -0
  222. package/query-planner/planner.js +818 -0
  223. package/query-planner/resource.d.ts +94 -0
  224. package/query-planner/resource.d.ts.map +1 -0
  225. package/query-planner/resource.js +526 -0
  226. package/query-planner/semantic-canonical.d.ts +15 -0
  227. package/query-planner/semantic-canonical.d.ts.map +1 -0
  228. package/query-planner/semantic-canonical.js +62 -0
  229. package/query-planner/semantic-compat.d.ts +10 -0
  230. package/query-planner/semantic-compat.d.ts.map +1 -0
  231. package/query-planner/semantic-compat.js +35 -0
  232. package/query-planner/semantic-compiler.d.ts +64 -0
  233. package/query-planner/semantic-compiler.d.ts.map +1 -0
  234. package/query-planner/semantic-compiler.js +81 -0
  235. package/query-planner/semantic-literals.d.ts +30 -0
  236. package/query-planner/semantic-literals.d.ts.map +1 -0
  237. package/query-planner/semantic-literals.js +133 -0
  238. package/query-planner/semantic-types.d.ts +265 -0
  239. package/query-planner/semantic-types.d.ts.map +1 -0
  240. package/query-planner/semantic-types.js +1 -0
  241. package/query-planner/semantic.d.ts +54 -0
  242. package/query-planner/semantic.d.ts.map +1 -0
  243. package/query-planner/semantic.js +1421 -0
  244. package/query-planner/types.d.ts +560 -0
  245. package/query-planner/types.d.ts.map +1 -0
  246. package/query-planner/types.js +49 -0
  247. package/query-planner/wfs-semantic.d.ts +58 -0
  248. package/query-planner/wfs-semantic.d.ts.map +1 -0
  249. package/query-planner/wfs-semantic.js +547 -0
  250. package/query-planner/wfs.d.ts +6 -0
  251. package/query-planner/wfs.d.ts.map +1 -0
  252. package/query-planner/wfs.js +71 -0
  253. package/react/external-map.d.ts +67 -0
  254. package/react/external-map.d.ts.map +1 -0
  255. package/react/external-map.js +63 -0
  256. package/react/honua-map.d.ts.map +1 -1
  257. package/react/honua-map.js +3 -2
  258. package/react/honua-source-layer.d.ts +110 -0
  259. package/react/honua-source-layer.d.ts.map +1 -0
  260. package/react/honua-source-layer.js +101 -0
  261. package/react/hooks.d.ts +28 -0
  262. package/react/hooks.d.ts.map +1 -1
  263. package/react/hooks.js +26 -4
  264. package/react/index.d.ts +8 -0
  265. package/react/index.d.ts.map +1 -1
  266. package/react/index.js +5 -0
  267. package/react/query-cache.d.ts +26 -4
  268. package/react/query-cache.d.ts.map +1 -1
  269. package/react/query-cache.js +51 -8
  270. package/react/selection.d.ts +177 -0
  271. package/react/selection.d.ts.map +1 -0
  272. package/react/selection.js +0 -0
  273. package/react/use-mounted-source.d.ts +69 -0
  274. package/react/use-mounted-source.d.ts.map +1 -0
  275. package/react/use-mounted-source.js +346 -0
  276. package/runtime/edit-snapping.d.ts +107 -0
  277. package/runtime/edit-snapping.d.ts.map +1 -0
  278. package/runtime/edit-snapping.js +190 -0
  279. package/runtime/errors.d.ts +3 -2
  280. package/runtime/errors.d.ts.map +1 -1
  281. package/runtime/errors.js +19 -2
  282. package/runtime/index.d.ts +6 -0
  283. package/runtime/index.d.ts.map +1 -1
  284. package/runtime/index.js +3 -0
  285. package/runtime/maplibre-renderer.d.ts +41 -0
  286. package/runtime/maplibre-renderer.d.ts.map +1 -0
  287. package/runtime/maplibre-renderer.js +322 -0
  288. package/runtime/query-tiles.d.ts +2 -1
  289. package/runtime/query-tiles.d.ts.map +1 -1
  290. package/runtime/query-tiles.js +6 -2
  291. package/runtime/source-bridge.d.ts +4 -4
  292. package/runtime/source-bridge.d.ts.map +1 -1
  293. package/runtime/source-bridge.js +9 -56
  294. package/runtime/style-interactions.d.ts +3 -2
  295. package/runtime/style-interactions.d.ts.map +1 -1
  296. package/runtime/style-interactions.js +11 -3
  297. package/runtime/terra-draw-sketch.d.ts +275 -0
  298. package/runtime/terra-draw-sketch.d.ts.map +1 -0
  299. package/runtime/terra-draw-sketch.js +404 -0
  300. package/source-capability-registry.d.ts +1 -0
  301. package/source-capability-registry.js +1 -0
  302. package/source-capability-types.d.ts +186 -0
  303. package/source-capability-types.js +7 -0
  304. package/style/index.d.ts +2 -0
  305. package/style/index.d.ts.map +1 -1
  306. package/style/index.js +2 -0
  307. package/style/renderers.d.ts +326 -0
  308. package/style/renderers.d.ts.map +1 -0
  309. package/style/renderers.js +517 -0
  310. package/webmap/convert-renderer.d.ts +24 -3
  311. package/webmap/convert-renderer.d.ts.map +1 -1
  312. package/webmap/convert-renderer.js +93 -112
  313. package/webmap/index.d.ts +1 -1
  314. package/webmap/index.d.ts.map +1 -1
  315. package/webmap/index.js +1 -1
@@ -0,0 +1,373 @@
1
+ import { sourceSchemaV2EnvelopeFingerprint } from "../contract/schema-envelope.js";
2
+ import { canonicalStringify, sha256, toJsonValue } from "./canonical.js";
3
+ import { HonuaQueryPlanningError, QUERY_PLANNER_VERSION, QUERY_PLAN_DIAGNOSTICS_VERSION } from "./types.js";
4
+ export function createQueryPlanProvenance(descriptor, source, options) {
5
+ const schema = schemaProvenance(descriptor, options.schemaVersion);
6
+ const discovery = discoveryProvenance(options.discovery);
7
+ const endpointFingerprint = digest("endpoint", source.endpoint);
8
+ const authorizationScope = {
9
+ fingerprint: digest("authorization-scope", [...source.authorizationScope].sort()),
10
+ count: source.authorizationScope.length,
11
+ };
12
+ const descriptorFingerprint = digest("descriptor", {
13
+ source,
14
+ schema,
15
+ });
16
+ const versionFingerprint = source.sourceVersion === undefined
17
+ ? undefined
18
+ : evidenceFingerprint("source-version", stableText(source.sourceVersion, "sourceVersion"));
19
+ return {
20
+ version: QUERY_PLAN_DIAGNOSTICS_VERSION,
21
+ source: {
22
+ id: source.id,
23
+ protocol: source.protocol,
24
+ endpointFingerprint,
25
+ descriptorFingerprint,
26
+ ...(versionFingerprint ? { versionFingerprint } : {}),
27
+ },
28
+ schema,
29
+ discovery,
30
+ authorizationScope,
31
+ };
32
+ }
33
+ export function createStepProvenance(provenance) {
34
+ return {
35
+ version: QUERY_PLAN_DIAGNOSTICS_VERSION,
36
+ sourceFingerprint: provenance.source.descriptorFingerprint,
37
+ ...(provenance.schema.state === "known" ? { schemaFingerprint: provenance.schema.fingerprint } : {}),
38
+ discoveryFingerprint: provenance.discovery.fingerprint,
39
+ authorizationScopeFingerprint: provenance.authorizationScope.fingerprint,
40
+ };
41
+ }
42
+ export function createCacheDecision(options) {
43
+ const policy = options?.policy ?? "bypass";
44
+ if (!["bypass", "prefer-cache", "require-fresh"].includes(policy))
45
+ invalid("cache.policy");
46
+ if (policy === "bypass") {
47
+ return {
48
+ version: QUERY_PLAN_DIAGNOSTICS_VERSION,
49
+ policy,
50
+ action: "bypass",
51
+ freshness: "unknown",
52
+ reason: "policy-bypass",
53
+ };
54
+ }
55
+ const freshness = options?.freshness ?? "unknown";
56
+ if (!["fresh", "stale", "unknown"].includes(freshness))
57
+ invalid("cache.freshness");
58
+ const validator = options?.validator ? normalizeValidator(options.validator, "cache.validator") : undefined;
59
+ if (freshness === "fresh") {
60
+ return {
61
+ version: QUERY_PLAN_DIAGNOSTICS_VERSION,
62
+ policy,
63
+ action: "reuse",
64
+ freshness,
65
+ ...(validator ? { validator } : {}),
66
+ reason: "fresh-entry",
67
+ };
68
+ }
69
+ if (validator) {
70
+ return {
71
+ version: QUERY_PLAN_DIAGNOSTICS_VERSION,
72
+ policy,
73
+ action: "revalidate",
74
+ freshness,
75
+ validator,
76
+ reason: "validator-available",
77
+ };
78
+ }
79
+ return {
80
+ version: QUERY_PLAN_DIAGNOSTICS_VERSION,
81
+ policy,
82
+ action: "refresh",
83
+ freshness,
84
+ reason: freshness === "stale" ? "stale-entry" : "cache-miss",
85
+ };
86
+ }
87
+ export function createStepDiagnostics(step, estimates, provenance) {
88
+ const losses = bboxApproximated(step) ? [spatialEnvelopeLoss()] : [];
89
+ const fidelity = losses.length > 0 ? "approximate" : step.engine === "client" ? "equivalent" : "exact";
90
+ return {
91
+ fidelity,
92
+ losses,
93
+ bounds: stepBounds(step, estimates),
94
+ provenance: createStepProvenance(provenance),
95
+ };
96
+ }
97
+ export function summarizePlanBounds(steps) {
98
+ return {
99
+ version: QUERY_PLAN_DIAGNOSTICS_VERSION,
100
+ requests: summarizeQuantity(steps, "requests", "request"),
101
+ rows: summarizeQuantity(steps, "rows", "row"),
102
+ bytes: summarizeQuantity(steps, "bytes", "byte"),
103
+ transferBytes: summarizeQuantity(steps, "transferBytes", "byte"),
104
+ serializedMaterializationBytes: summarizeQuantity(steps, "serializedMaterializationBytes", "byte"),
105
+ memoryBytes: summarizeQuantity(steps, "memoryBytes", "byte"),
106
+ };
107
+ }
108
+ export function summarizeFidelity(steps) {
109
+ const fidelity = steps.some((step) => step.fidelity === "approximate")
110
+ ? "approximate"
111
+ : steps.some((step) => step.fidelity === "equivalent")
112
+ ? "equivalent"
113
+ : "exact";
114
+ return { fidelity, losses: steps.flatMap((step) => step.losses) };
115
+ }
116
+ export function createPlanWarnings(steps, source) {
117
+ const warnings = [];
118
+ if (steps.some((step) => step.engine === "client")) {
119
+ warnings.push({
120
+ code: "bounded-local-fallback",
121
+ severity: "warning",
122
+ path: "$.steps[1]",
123
+ message: "Execution uses a bounded local fallback and fails closed if its materialization ceiling is exceeded.",
124
+ remediation: "Enable server pushdown or reduce the query input bound.",
125
+ });
126
+ }
127
+ if (source.protocol === "ogc-features" && steps.some((step) => step.engine === "client")) {
128
+ warnings.push({
129
+ code: "geometry-transfer-required",
130
+ severity: "warning",
131
+ path: "$.steps[0].query.returnGeometry",
132
+ message: "OGC API Features may transfer geometry because portable geometry suppression is unavailable.",
133
+ remediation: "Use a server projection that omits geometry when the endpoint supports one.",
134
+ });
135
+ }
136
+ if (steps.some(bboxApproximated)) {
137
+ warnings.push({
138
+ code: "approximate-spatial-filter",
139
+ severity: "warning",
140
+ path: "$.ir.query.spatialFilter",
141
+ message: "A spatial predicate was reduced to its bounding envelope.",
142
+ remediation: "Use an envelope query or an exact spatial compiler.",
143
+ });
144
+ }
145
+ return warnings;
146
+ }
147
+ function bboxApproximated(step) {
148
+ return step.compiled !== undefined && "bboxApproximated" in step.compiled && step.compiled.bboxApproximated === true;
149
+ }
150
+ export function createPlanValidity(ir, provenance, capabilityPolicy, fallback, executionMode) {
151
+ const unsigned = {
152
+ version: QUERY_PLAN_DIAGNOSTICS_VERSION,
153
+ plannerVersion: QUERY_PLANNER_VERSION,
154
+ contractVersion: `${ir.kind}@${ir.version}`,
155
+ executionMode,
156
+ sourceFingerprint: provenance.source.descriptorFingerprint,
157
+ schemaFingerprint: digest("schema-identity", provenance.schema),
158
+ discoveryFingerprint: provenance.discovery.fingerprint,
159
+ authorizationScopeFingerprint: provenance.authorizationScope.fingerprint,
160
+ queryFingerprint: digest("query", ir.query),
161
+ crsFingerprint: digest("crs", crsIdentity(ir)),
162
+ policyFingerprint: digest("policy", { capabilityPolicy, fallback }),
163
+ };
164
+ return { ...unsigned, fingerprint: digest("validity", unsigned) };
165
+ }
166
+ function stepBounds(step, estimates) {
167
+ if (step.engine === "client") {
168
+ return {
169
+ version: QUERY_PLAN_DIAGNOSTICS_VERSION,
170
+ requests: exact("request", 0),
171
+ rows: step.maxRows === undefined ? unknown("row") : bounded("row", 0, step.maxRows, "fallback-policy"),
172
+ bytes: step.maxBytes === undefined ? unknown("byte") : bounded("byte", 0, step.maxBytes, "fallback-policy"),
173
+ transferBytes: exact("byte", 0),
174
+ serializedMaterializationBytes: step.maxBytes === undefined
175
+ ? estimates.bytes === undefined
176
+ ? unknown("byte")
177
+ : estimated("byte", estimates.bytes)
178
+ : bounded("byte", 0, step.maxBytes, "fallback-policy"),
179
+ memoryBytes: unknown("byte"),
180
+ };
181
+ }
182
+ const queryLimit = compiledRowLimit(step.compiled) ?? step.query?.pagination?.limit;
183
+ const queryAll = step.operation === "queryAll";
184
+ const requests = queryAll
185
+ ? estimates.requests === undefined
186
+ ? { ...unknown("request"), lower: 1 }
187
+ : { ...estimated("request", estimates.requests), lower: 1 }
188
+ : exact("request", 1);
189
+ const rows = queryLimit !== undefined
190
+ ? bounded("row", 0, queryLimit, "query-limit")
191
+ : estimates.rows === undefined
192
+ ? unknown("row")
193
+ : estimated("row", estimates.rows);
194
+ const bytes = estimates.bytes === undefined ? unknown("byte") : estimated("byte", estimates.bytes);
195
+ return {
196
+ version: QUERY_PLAN_DIAGNOSTICS_VERSION,
197
+ requests,
198
+ rows,
199
+ bytes,
200
+ transferBytes: bytes,
201
+ serializedMaterializationBytes: exact("byte", 0),
202
+ memoryBytes: unknown("byte"),
203
+ };
204
+ }
205
+ function schemaProvenance(descriptor, schemaVersion) {
206
+ if (descriptor.schemaV2 !== undefined) {
207
+ try {
208
+ return {
209
+ state: "known",
210
+ fingerprint: sourceSchemaV2EnvelopeFingerprint(descriptor.schemaV2),
211
+ basis: "schema-v2",
212
+ };
213
+ }
214
+ catch {
215
+ throw new HonuaQueryPlanningError("invalid-query", "descriptor.schemaV2 identity is invalid");
216
+ }
217
+ }
218
+ if (schemaVersion !== undefined) {
219
+ return {
220
+ state: "known",
221
+ fingerprint: evidenceFingerprint("schema-version", stableText(schemaVersion, "schemaVersion")),
222
+ basis: "version",
223
+ };
224
+ }
225
+ return { state: "unavailable", reason: "not-provided" };
226
+ }
227
+ function discoveryProvenance(context) {
228
+ const state = context?.state ?? "unavailable";
229
+ if (!["metadata", "declared", "inferred", "unavailable"].includes(state))
230
+ invalid("discovery.state");
231
+ if (context?.source !== undefined && context.sourceFingerprint !== undefined)
232
+ invalid("discovery.source");
233
+ const sourceFingerprint = context?.sourceFingerprint
234
+ ? verifiedFingerprint(context.sourceFingerprint, "discovery.sourceFingerprint")
235
+ : context?.source !== undefined
236
+ ? digest("discovery-source", stableText(context.source, "discovery.source"))
237
+ : undefined;
238
+ if (state !== "unavailable" && !sourceFingerprint)
239
+ invalid("discovery.source");
240
+ const validator = context?.validator ? normalizeValidator(context.validator, "discovery.validator") : undefined;
241
+ const unsigned = { state, ...(sourceFingerprint ? { sourceFingerprint } : {}), ...(validator ? { validator } : {}) };
242
+ return { ...unsigned, fingerprint: digest("discovery", unsigned) };
243
+ }
244
+ function normalizeValidator(input, path) {
245
+ if (!["etag", "last-modified", "revision", "fingerprint"].includes(input.kind))
246
+ invalid(`${path}.kind`);
247
+ if ((input.value === undefined) === (input.fingerprint === undefined))
248
+ invalid(path);
249
+ const fingerprint = input.fingerprint
250
+ ? verifiedFingerprint(input.fingerprint, `${path}.fingerprint`)
251
+ : digest("validator", { kind: input.kind, value: stableText(input.value, `${path}.value`) });
252
+ return { kind: input.kind, fingerprint };
253
+ }
254
+ function spatialEnvelopeLoss() {
255
+ return {
256
+ code: "spatial-envelope-reduction",
257
+ path: "$.ir.query.spatialFilter",
258
+ description: "The source evaluates the input geometry's bounding envelope instead of its exact shape.",
259
+ remediation: "Use an envelope query or select a compiler with exact geometry predicate support.",
260
+ };
261
+ }
262
+ function exact(unit, value) {
263
+ return { unit, confidence: "exact", source: "compiler", lower: value, upper: value, estimate: value };
264
+ }
265
+ function bounded(unit, lower, upper, source) {
266
+ return { unit, confidence: "bounded", source, lower, upper };
267
+ }
268
+ function estimated(unit, estimate) {
269
+ return { unit, confidence: "estimated", source: "caller-estimate", estimate };
270
+ }
271
+ function unknown(unit) {
272
+ return { unit, confidence: "unknown", source: "unavailable" };
273
+ }
274
+ function summarizeQuantity(steps, key, unit) {
275
+ const quantities = steps.map((step) => step.bounds[key]);
276
+ if (quantities.length === 0)
277
+ return unknown(unit);
278
+ if (quantities.length === 1)
279
+ return quantities[0];
280
+ const lower = sumWhenComplete(quantities, "lower");
281
+ const upper = sumWhenComplete(quantities, "upper");
282
+ const estimate = sumWhenComplete(quantities, "estimate");
283
+ const fields = {
284
+ ...(lower === undefined ? {} : { lower }),
285
+ ...(upper === undefined ? {} : { upper }),
286
+ ...(estimate === undefined ? {} : { estimate }),
287
+ };
288
+ if (quantities.every((quantity) => quantity.confidence === "exact")) {
289
+ return { unit, confidence: "exact", source: "plan-summary", ...fields };
290
+ }
291
+ if (quantities.some((quantity) => quantity.confidence === "unknown")) {
292
+ return { unit, confidence: "unknown", source: "plan-summary", ...fields };
293
+ }
294
+ if (lower !== undefined && upper !== undefined) {
295
+ return { unit, confidence: "bounded", source: "plan-summary", ...fields };
296
+ }
297
+ if (estimate !== undefined) {
298
+ return { unit, confidence: "estimated", source: "plan-summary", ...fields };
299
+ }
300
+ return { unit, confidence: "unknown", source: "plan-summary", ...fields };
301
+ }
302
+ function sumWhenComplete(quantities, key) {
303
+ if (quantities.some((quantity) => quantity[key] === undefined))
304
+ return undefined;
305
+ const total = quantities.reduce((sum, quantity) => sum + quantity[key], 0);
306
+ return Number.isFinite(total) ? total : undefined;
307
+ }
308
+ function compiledRowLimit(compiled) {
309
+ if (!compiled || !("compiler" in compiled))
310
+ return undefined;
311
+ const artifact = compiled;
312
+ const field = artifact.compiler === "ogc-api-features-query-v1"
313
+ ? "limit"
314
+ : artifact.compiler === "wfs-2.0-get-feature-v1"
315
+ ? "count"
316
+ : artifact.compiler === "odata-v4-query-v1"
317
+ ? "top"
318
+ : artifact.compiler === "geoservices-rest-query-v1" || artifact.compiler === "honua-grpc-query-features-v1"
319
+ ? "resultRecordCount"
320
+ : undefined;
321
+ if (!field)
322
+ return undefined;
323
+ const value = artifact[field];
324
+ return Number.isSafeInteger(value) && value >= 0 ? value : undefined;
325
+ }
326
+ function crsIdentity(ir) {
327
+ const geometry = ir.query.spatialFilter?.geometry;
328
+ const filterBinding = geometry
329
+ ? {
330
+ geometryType: ir.query.spatialFilter?.geometryType,
331
+ spatialReference: geometry.spatialReference ?? null,
332
+ crs: geometry.crs ?? null,
333
+ srsName: geometry.srsName ?? null,
334
+ }
335
+ : null;
336
+ return {
337
+ sourceSrsName: "srsName" in ir.source ? (ir.source.srsName ?? null) : null,
338
+ filter: filterBinding,
339
+ output: ir.query.outSr ?? null,
340
+ transformPolicy: "no-implicit-transform-v1",
341
+ };
342
+ }
343
+ function digest(namespace, value) {
344
+ return sha256(`${namespace}:v1:${canonicalStringify(toJsonValue(value))}`);
345
+ }
346
+ function verifiedFingerprint(value, path) {
347
+ if (!/^sha256:[0-9a-f]{64}$/.test(value))
348
+ invalid(path);
349
+ return value;
350
+ }
351
+ function evidenceFingerprint(namespace, value) {
352
+ return /^sha256:[0-9a-f]{64}$/.test(value) ? value : digest(namespace, value);
353
+ }
354
+ function stableText(value, path) {
355
+ if (typeof value !== "string" ||
356
+ value.length === 0 ||
357
+ new TextEncoder().encode(value).byteLength > 4_096 ||
358
+ containsControlCharacter(value)) {
359
+ invalid(path);
360
+ }
361
+ return value;
362
+ }
363
+ function containsControlCharacter(value) {
364
+ for (let index = 0; index < value.length; index += 1) {
365
+ const code = value.charCodeAt(index);
366
+ if (code <= 0x1f || code === 0x7f)
367
+ return true;
368
+ }
369
+ return false;
370
+ }
371
+ function invalid(path) {
372
+ throw new HonuaQueryPlanningError("invalid-query", `${path} is invalid`);
373
+ }
@@ -0,0 +1,79 @@
1
+ /**
2
+ * Compile canonical query IR to deterministic DuckDB SQL over
3
+ * `read_parquet(...)` for the GeoParquet columnar `Source`, without performing
4
+ * any network, filesystem, or DuckDB metadata I/O.
5
+ *
6
+ * The heavy lifting — identifier/literal escaping, spatial predicate pushdown,
7
+ * GeoJSON projection, and GROUP BY aggregation — is delegated to the
8
+ * dependency-free {@link module:core/geoparquet-sql} SQL builder that the live
9
+ * GeoParquet `Source` already uses, so the planner and the adapter emit the
10
+ * exact same SQL for the same inputs.
11
+ *
12
+ * @module
13
+ */
14
+ import type { ExecutableCrsBinding, SourceSchemaV2 } from "../contract/schema.js";
15
+ import type { GeoParquetResourceHandleV1 } from "./resource.js";
16
+ import { type SemanticCompilationResult, type SemanticSqlParameter } from "./semantic-compiler.js";
17
+ import type { SemanticQuery, SourceSpatiality } from "./semantic-types.js";
18
+ import type { CanonicalQuery, DuckDbCompiledQueryV1, DuckDbCompiledQueryV2, DuckDbGeometryEncoding, QueryIrSourceIdentity, QueryIrSourceIdentityV2 } from "./types.js";
19
+ /** Physical GeoParquet geometry metadata required by the semantic compiler. */
20
+ export interface SemanticDuckDbGeometrySource {
21
+ /** Logical SourceSchemaV2 field carrying the physical geometry column path. */
22
+ readonly field: string;
23
+ readonly encoding: DuckDbGeometryEncoding;
24
+ /** Optional GeoParquet 1.1 bbox-covering struct column. */
25
+ readonly bboxColumn?: string;
26
+ }
27
+ /** Pure, credential-free inputs for semantic DuckDB compilation. */
28
+ export interface SemanticDuckDbCompileOptions<TRecord = Record<string, unknown>, TSpatiality extends SourceSpatiality = SourceSpatiality> {
29
+ readonly query: SemanticQuery<TRecord, "geoparquet", TSpatiality>;
30
+ readonly schema: SourceSchemaV2;
31
+ readonly resource: GeoParquetResourceHandleV1;
32
+ readonly geometry?: SemanticDuckDbGeometrySource;
33
+ /** Exact by default; bbox reduction is opt-in and always reported as approximate. */
34
+ readonly spatialStrategy?: "exact" | "bbox-envelope";
35
+ }
36
+ export interface SemanticDuckDbSpatialCompilation {
37
+ readonly path: string;
38
+ readonly field: string;
39
+ readonly encoding: DuckDbGeometryEncoding;
40
+ readonly strategy: "exact" | "bbox-envelope";
41
+ readonly crs: ExecutableCrsBinding;
42
+ }
43
+ /** Traceable geometry contract for rows returned by the compiled SELECT. */
44
+ export interface SemanticDuckDbOutputGeometry {
45
+ readonly sourceField: string;
46
+ readonly sourceEncoding: DuckDbGeometryEncoding;
47
+ readonly resultField: "geometry";
48
+ readonly resultEncoding: "geojson";
49
+ readonly crs: ExecutableCrsBinding;
50
+ readonly layout: "xy" | "xyz";
51
+ }
52
+ /** Parameterized DuckDB artifact over an opaque #587 resource handle. */
53
+ export interface SemanticDuckDbCompiledQueryV1 {
54
+ readonly compiler: "duckdb-semantic-query-v1";
55
+ readonly dialect: "duckdb-sql";
56
+ readonly schemaFingerprint: SourceSchemaV2["fingerprint"];
57
+ readonly queryFingerprint: `sha256:${string}`;
58
+ readonly resource: GeoParquetResourceHandleV1;
59
+ readonly sqlTemplate: string;
60
+ readonly parameters: readonly SemanticSqlParameter[];
61
+ readonly outputGeometry?: SemanticDuckDbOutputGeometry;
62
+ readonly spatial: readonly SemanticDuckDbSpatialCompilation[];
63
+ readonly usesNativeFilter: boolean;
64
+ }
65
+ /**
66
+ * Compile canonical query IR to a deterministic DuckDB `SELECT`. Reuses the
67
+ * GeoParquet `Source` SQL builder, so the compiled SQL is byte-identical to
68
+ * what the live adapter runs for the same descriptor + query.
69
+ */
70
+ export declare function compileDuckDbQuery(source: QueryIrSourceIdentity, query: CanonicalQuery): DuckDbCompiledQueryV1;
71
+ /** Compile a credential-free template; execution recompiles with ephemeral resolved sources. */
72
+ export declare function compileDuckDbQueryV2(source: QueryIrSourceIdentityV2, query: CanonicalQuery): DuckDbCompiledQueryV2;
73
+ /**
74
+ * Compile the schema-validated semantic AST into parameterized DuckDB SQL.
75
+ * The table address remains the fixed opaque-resource placeholder; only a
76
+ * trusted execution boundary may resolve the attached handle to raw locators.
77
+ */
78
+ export declare function compileSemanticDuckDbQuery<TRecord, TSpatiality extends SourceSpatiality>(options: SemanticDuckDbCompileOptions<TRecord, TSpatiality>): SemanticCompilationResult<SemanticDuckDbCompiledQueryV1>;
79
+ //# sourceMappingURL=duckdb.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"duckdb.d.ts","sourceRoot":"","sources":["../../../src/query-planner/duckdb.ts"],"names":[],"mappings":"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"}