@honua/react 0.0.20-alpha.0 → 0.1.1-beta.0

package/query-planner/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `@honua/sdk-js/query-planner` — deterministic query IR, explain plans, and
+ * bounded execution for the protocol-neutral contract.
+ *
+ * Planning is synchronous and side-effect free: it uses a caller-supplied
+ * descriptor/capability snapshot and never fetches metadata or result rows.
+ * Execution is separate and validates the accepted fingerprint and source
+ * context before invoking a `Source`.
+ *
+ * @experimental
+ * @packageDocumentation
+ */
+export { canonicalStringify, sha256, toJsonValue } from "./canonical.js";
+export { compileDuckDbQuery, compileDuckDbQueryV2, compileSemanticDuckDbQuery } from "./duckdb.js";
+export { executeQueryPlan } from "./executor.js";
+export { compileGeoServicesQuery, compileSemanticGeoServicesQuery } from "./geoservices.js";
+export { compileGrpcQuery, compileSemanticGrpcQuery } from "./grpc.js";
+export { compileOgcApiFeaturesQuery, compileSemanticOgcApiFeaturesQuery } from "./ogc-features.js";
+export { compileOdataQuery, compileSemanticOdataQuery } from "./odata.js";
+export { compileSemanticWfsQuery, compileWfsQuery } from "./wfs.js";
+export { canonicalizeQuery, createGeoParquetQueryIr, createQueryIr, hashQueryIr, queryFromCanonical, } from "./ir.js";
+export { explainQuery, hashQueryPlan, migrateGeoParquetQueryPlanV1, parseQueryPlan, queryPlanCacheKey, serializeQueryPlan, } from "./planner.js";
+export { QUERY_RESOURCE_HANDLE_KIND, QUERY_RESOURCE_HANDLE_VERSION, createGeoParquetResourceHandle, createGeoParquetResourceRegistry, hashGeoParquetResourceHandle, parseGeoParquetResourceHandle, resolveGeoParquetResource, } from "./resource.js";
+export { SEMANTIC_QUERY_CANONICAL_KIND, SEMANTIC_QUERY_CANONICAL_VERSION, SEMANTIC_QUERY_HASH_DOMAIN, canonicalSemanticQueryBytes, hashSemanticQuery, serializeCanonicalSemanticQuery, } from "./semantic-canonical.js";
+export { legacyWhereToNativeFilter } from "./semantic-compat.js";
+export type { SemanticCompilationResult, SemanticCompilerDiagnostic, SemanticCompilerFidelity, SemanticCompilerLoss, SemanticCompilerUnsupportedCode, SemanticSqlParameter, } from "./semantic-compiler.js";
+export type { SemanticCompilerFieldMapping } from "./semantic-literals.js";
+export { semanticFilterFromCql2Json, semanticFilterToCql2Json } from "./cql2-json.js";
+export { MAX_SEMANTIC_QUERY_BYTES, MAX_SEMANTIC_QUERY_COLLECTION_ITEMS, MAX_SEMANTIC_QUERY_DEPTH, MAX_SEMANTIC_QUERY_NODES, MAX_SEMANTIC_QUERY_TEXT_BYTES, createSemanticQueryBuilder, defineSemanticQuery, defineSpatialNode, parseSemanticQuery, temporalLiteral, } from "./semantic.js";
+export type { SemanticQueryBuilder } from "./semantic.js";
+export type { AggregateMetric, BuiltInNativeDialect, CanonicalSemanticQueryOptions, Cql2JsonExpression, Cql2JsonInterchangeOptions, ComparisonNode, CountMetric, DistanceOperand, DistanceSpatialPredicate, DistanceUnit, EqualityOperator, ExtremumMetric, FieldName, FirstPageRequest, GeometryFieldName, GeometryProjectionFor, GroupableFieldName, ListNode, LegacyWhereDialectFor, LegacyWhereProtocol, LiteralNode, NativeDialectFor, NativeFilter, NativePayloadFor, NullNode, NumericFieldName, NumericMetric, OffsetPageRequest, OrderableFieldName, OrderedComparisonOperator, OutputCrsFor, ParseSemanticQueryOptions, PatternNode, PropertyNode, QueryFilter, QueryLiteral, RangeNode, ScalarFieldName, SemanticAggregateQuery, SemanticFeatureQuery, SemanticFilter, SemanticPageRequest, SemanticQuery, SemanticSort, SourceSpatiality, SpatialNode, SpatialPredicate, SpatialityForSchema, StringFieldName, TemporalFieldName, TemporalLiteralNode, TemporalNode, TemporalPredicate, TemporalValue, TopologicalSpatialPredicate, } from "./semantic-types.js";
+export type { SemanticOdataCompileOptions, SemanticOdataCompiledQueryV1, SemanticOdataOutputGeometry, SemanticOdataSourceIdentity, SemanticOdataSpatialFunction, } from "./odata.js";
+export type { SemanticDuckDbCompileOptions, SemanticDuckDbCompiledQueryV1, SemanticDuckDbGeometrySource, SemanticDuckDbOutputGeometry, SemanticDuckDbSpatialCompilation, } from "./duckdb.js";
+export type { SemanticGeoServicesCompileOptions, SemanticGeoServicesCompiledQueryV1, SemanticGeoServicesGeometry, SemanticGeoServicesProtocol, SemanticGeoServicesSourceIdentity, SemanticGeoServicesSpatialReference, SemanticGeoServicesSpatialRelationship, } from "./geoservices.js";
+export type { SemanticGrpcCompileOptions, SemanticGrpcCompiledQueryV1, SemanticGrpcCoordinate, SemanticGrpcCoordinateSequence, SemanticGrpcGeometry, SemanticGrpcSourceIdentity, SemanticGrpcSpatialReference, SemanticGrpcSpatialRelationship, } from "./grpc.js";
+export type { Cql2FilterLanguage, OgcApiFeaturesFilterConformanceEvidence, SemanticOgcApiFeaturesCompileOptions, SemanticOgcApiFeaturesCompiledQueryV1, SemanticOgcApiFeaturesSourceIdentity, } from "./ogc-features.js";
+export type { SemanticWfsCompileOptions, SemanticWfsCompiledQueryV1, SemanticWfsSourceIdentity, Wfs20FilterCapabilitiesEvidence, } from "./wfs.js";
+export { COLUMNAR_WORKER_CANCEL_KIND, COLUMNAR_WORKER_ERROR_KIND, COLUMNAR_WORKER_PROGRESS_KIND, COLUMNAR_WORKER_PROTOCOL_VERSION, COLUMNAR_WORKER_REQUEST_KIND, COLUMNAR_WORKER_RESULT_KIND, ColumnarBatchLease, GEOARROW_SPEC_VERSION, HONUA_GEOARROW_LAYOUT_VERSION, HonuaGeoArrowError, HonuaColumnarWorkerError, createColumnarBatch, createColumnarWorkerSession, createGeoArrowBatch, decodeGeoArrowBatch, fromApacheArrowRecordBatch, inspectGeoArrowBatch, inspectColumnarBatch, leaseColumnarBatch, loadApacheArrow, startColumnarWorkerHost, toApacheArrowRecordBatch, } from "../columnar/index.js";
+export { COLUMNAR_BATCH_KIND, COLUMNAR_BATCH_VERSION, COLUMNAR_TRANSFER_KIND, DEFAULT_COLUMNAR_BATCH_MAX_BACKING_BYTES, DEFAULT_COLUMNAR_BATCH_MAX_BUFFER_VIEWS, DEFAULT_COLUMNAR_BATCH_MAX_METADATA_ENTRIES, DEFAULT_COLUMNAR_BATCH_MAX_ROWS, DEFAULT_COLUMNAR_BATCH_MAX_SCHEMA_NODES, DEFAULT_COLUMNAR_BATCH_MAX_STRING_BYTES, HonuaColumnarTransferError, } from "../columnar/index.js";
+export type { ApacheArrowAdapterMetrics, ApacheArrowAdapterOptions, ApacheArrowDataLike, ApacheArrowFieldLike, ApacheArrowModuleImporter, ApacheArrowModuleLike, ApacheArrowRecordBatchLike, ApacheArrowRecordBatchResult, ApacheArrowTypeLike, ApacheArrowVectorLike, ColumnarBatchLeaseState, ColumnarBatchIdentityV1, ColumnarBatchLimits, ColumnarBatchMetrics, ColumnarBatchV1, ColumnarBufferRole, ColumnarBufferV1, ColumnarFieldV1, ColumnarFreshnessV1, ColumnarOrderingKeyV1, ColumnarOrderingV1, ColumnarSchemaV1, ColumnarTransferErrorCode, ColumnarTransferMessageV1, ColumnarTransferOptions, ColumnarTransferReceipt, ColumnarTransferTarget, ColumnarTypeV1, CreateColumnarBatchInput, ColumnarWorkerCancelV1, ColumnarWorkerErrorCode, ColumnarWorkerErrorV1, ColumnarWorkerExecutionProgress, ColumnarWorkerExecutionResult, ColumnarWorkerFactory, ColumnarWorkerFaultEvent, ColumnarWorkerHost, ColumnarWorkerMessageEvent, ColumnarWorkerOperation, ColumnarWorkerOperationContext, ColumnarWorkerProgressV1, ColumnarWorkerRequestV1, ColumnarWorkerResultV1, ColumnarWorkerSession, ColumnarWorkerSessionState, ColumnarWorkerTransport, CreateColumnarWorkerSessionOptions, ExecuteColumnarWorkerOperationOptions, CreateGeoArrowBatchInput, CreatedGeoArrowBatch, DecodedGeoArrowBatch, DecodedGeoArrowRow, GeoArrowBatchInspection, GeoArrowConversionLimits, GeoArrowConversionMetrics, GeoArrowCoordinateLayout, GeoArrowCrs, GeoArrowDictionaryBuffers, GeoArrowDictionaryColumnInput, GeoArrowDimensions, GeoArrowEdges, GeoArrowFeatureIdColumnInput, GeoArrowGeometryBuffers, GeoArrowGeometryColumnInput, GeoArrowGeometryKind, GeoArrowLineString, GeoArrowLineStringColumnInput, GeoArrowPoint, GeoArrowPointColumnInput, GeoArrowPolygon, GeoArrowPolygonColumnInput, GeoArrowPosition, GeoArrowTemporalBuffers, GeoArrowTemporalColumnInput, GeoArrowTimestampUnit, FromApacheArrowRecordBatchOptions, GeoArrowBatchFromApacheResult, HonuaGeoArrowErrorCode, LoadApacheArrowOptions, StartColumnarWorkerHostOptions, } from "../columnar/index.js";
+export { HonuaQueryPlanExecutionError, HonuaQueryPlanningError, MAX_LOCAL_MATERIALIZATION_ROWS, QUERY_IR_KIND, QUERY_IR_VERSION, QUERY_PLAN_KIND, QUERY_PLAN_DIAGNOSTICS_VERSION, QUERY_PLANNER_VERSION, QUERY_PLAN_VERSION, QUERY_IR_V2_VERSION, QUERY_PLAN_V2_VERSION, } from "./types.js";
+export type { CanonicalQuery, CanonicalSpatialFilter, DuckDbCompiledQueryV1, DuckDbCompiledQueryV2, DuckDbGeometryEncoding, ExecuteQueryPlanOptions, ExplainGeoParquetQueryOptions, ExplainQueryOptions, GeoParquetEffectiveSchemaFieldV1, GeoParquetRemoteQueryPlanStepV2, GeoServicesCompiledQueryV1, GrpcCompiledQueryV1, GrpcSpatialRelationship, GrpcStatisticType, JsonPrimitive, JsonValue, LocalAggregatePlanStep, OgcApiFeaturesCompiledQueryV1, OdataCompiledQueryV1, QueryExecutionPlan, QueryExecutionPlanV1, QueryExecutionPlanV2, QueryFallbackPolicy, QueryIrGeoparquetIdentity, QueryIrGeoparquetResourceIdentity, QueryIrSourceIdentity, QueryIrSourceIdentityV2, QueryIrV1, QueryIrV2, QueryPlanExecution, QueryPlanExecutionErrorCode, QueryPlanExecutor, QueryPlanningErrorCode, QueryPlanningEstimates, QueryPlanBoundConfidence, QueryPlanBoundSource, QueryPlanBoundsV1, QueryPlanCacheAction, QueryPlanCacheDecisionV1, QueryPlanCacheFreshness, QueryPlanCacheOptions, QueryPlanCachePolicy, QueryPlanDiscoveryContext, QueryPlanDiscoveryState, QueryPlanExecutionFailureReason, QueryPlanExecutionMode, QueryPlanFidelity, QueryPlanFidelityLoss, QueryPlanProvenanceV1, QueryPlanQuantityBound, QueryPlanStepProvenanceV1, QueryPlanValidatorInput, QueryPlanValidatorKind, QueryPlanValidityV1, QueryPlanWarning, QueryPlanWarningCode, RemoteCompiledQueryV1, QueryPlanStep, QueryPlanStepV2, RemoteQueryPlanStep, WfsCompiledQueryV1, } from "./types.js";
+export type { CreateGeoParquetResourceHandleInput, GeoParquetResolverResourceReferenceV1, GeoParquetResourceHandleV1, GeoParquetResourceRegistry, GeoParquetResourceRegistryOptions, GeoParquetResourceResolutionContext, GeoParquetResourceResolver, RegisterGeoParquetResourceInput, ResolvedGeoParquetResource, } from "./resource.js";
+//# sourceMappingURL=index.d.ts.map

package/query-planner/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/query-planner/index.ts"],"names":[],"mappings":"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"}

package/query-planner/index.js

@@ -0,0 +1,30 @@
+/**
+ * `@honua/sdk-js/query-planner` — deterministic query IR, explain plans, and
+ * bounded execution for the protocol-neutral contract.
+ *
+ * Planning is synchronous and side-effect free: it uses a caller-supplied
+ * descriptor/capability snapshot and never fetches metadata or result rows.
+ * Execution is separate and validates the accepted fingerprint and source
+ * context before invoking a `Source`.
+ *
+ * @experimental
+ * @packageDocumentation
+ */
+export { canonicalStringify, sha256, toJsonValue } from "./canonical.js";
+export { compileDuckDbQuery, compileDuckDbQueryV2, compileSemanticDuckDbQuery } from "./duckdb.js";
+export { executeQueryPlan } from "./executor.js";
+export { compileGeoServicesQuery, compileSemanticGeoServicesQuery } from "./geoservices.js";
+export { compileGrpcQuery, compileSemanticGrpcQuery } from "./grpc.js";
+export { compileOgcApiFeaturesQuery, compileSemanticOgcApiFeaturesQuery } from "./ogc-features.js";
+export { compileOdataQuery, compileSemanticOdataQuery } from "./odata.js";
+export { compileSemanticWfsQuery, compileWfsQuery } from "./wfs.js";
+export { canonicalizeQuery, createGeoParquetQueryIr, createQueryIr, hashQueryIr, queryFromCanonical, } from "./ir.js";
+export { explainQuery, hashQueryPlan, migrateGeoParquetQueryPlanV1, parseQueryPlan, queryPlanCacheKey, serializeQueryPlan, } from "./planner.js";
+export { QUERY_RESOURCE_HANDLE_KIND, QUERY_RESOURCE_HANDLE_VERSION, createGeoParquetResourceHandle, createGeoParquetResourceRegistry, hashGeoParquetResourceHandle, parseGeoParquetResourceHandle, resolveGeoParquetResource, } from "./resource.js";
+export { SEMANTIC_QUERY_CANONICAL_KIND, SEMANTIC_QUERY_CANONICAL_VERSION, SEMANTIC_QUERY_HASH_DOMAIN, canonicalSemanticQueryBytes, hashSemanticQuery, serializeCanonicalSemanticQuery, } from "./semantic-canonical.js";
+export { legacyWhereToNativeFilter } from "./semantic-compat.js";
+export { semanticFilterFromCql2Json, semanticFilterToCql2Json } from "./cql2-json.js";
+export { MAX_SEMANTIC_QUERY_BYTES, MAX_SEMANTIC_QUERY_COLLECTION_ITEMS, MAX_SEMANTIC_QUERY_DEPTH, MAX_SEMANTIC_QUERY_NODES, MAX_SEMANTIC_QUERY_TEXT_BYTES, createSemanticQueryBuilder, defineSemanticQuery, defineSpatialNode, parseSemanticQuery, temporalLiteral, } from "./semantic.js";
+export { COLUMNAR_WORKER_CANCEL_KIND, COLUMNAR_WORKER_ERROR_KIND, COLUMNAR_WORKER_PROGRESS_KIND, COLUMNAR_WORKER_PROTOCOL_VERSION, COLUMNAR_WORKER_REQUEST_KIND, COLUMNAR_WORKER_RESULT_KIND, ColumnarBatchLease, GEOARROW_SPEC_VERSION, HONUA_GEOARROW_LAYOUT_VERSION, HonuaGeoArrowError, HonuaColumnarWorkerError, createColumnarBatch, createColumnarWorkerSession, createGeoArrowBatch, decodeGeoArrowBatch, fromApacheArrowRecordBatch, inspectGeoArrowBatch, inspectColumnarBatch, leaseColumnarBatch, loadApacheArrow, startColumnarWorkerHost, toApacheArrowRecordBatch, } from "../columnar/index.js";
+export { COLUMNAR_BATCH_KIND, COLUMNAR_BATCH_VERSION, COLUMNAR_TRANSFER_KIND, DEFAULT_COLUMNAR_BATCH_MAX_BACKING_BYTES, DEFAULT_COLUMNAR_BATCH_MAX_BUFFER_VIEWS, DEFAULT_COLUMNAR_BATCH_MAX_METADATA_ENTRIES, DEFAULT_COLUMNAR_BATCH_MAX_ROWS, DEFAULT_COLUMNAR_BATCH_MAX_SCHEMA_NODES, DEFAULT_COLUMNAR_BATCH_MAX_STRING_BYTES, HonuaColumnarTransferError, } from "../columnar/index.js";
+export { HonuaQueryPlanExecutionError, HonuaQueryPlanningError, MAX_LOCAL_MATERIALIZATION_ROWS, QUERY_IR_KIND, QUERY_IR_VERSION, QUERY_PLAN_KIND, QUERY_PLAN_DIAGNOSTICS_VERSION, QUERY_PLANNER_VERSION, QUERY_PLAN_VERSION, QUERY_IR_V2_VERSION, QUERY_PLAN_V2_VERSION, } from "./types.js";

package/query-planner/ir.d.ts

@@ -0,0 +1,20 @@
+import type { Query, SourceDescriptor } from "../contract/types.js";
+import { type CanonicalQuery, type ExplainGeoParquetQueryOptions, type ExplainQueryOptions, type GeoParquetEffectiveSchemaFieldV1, type QueryIrSourceIdentity, type QueryIrSourceIdentityV2, type QueryIrV1, type QueryIrV2 } from "./types.js";
+/** Context accepted by {@link queryIrSourceIdentityV2}: shared by explain and execute call sites. */
+export interface GeoParquetV2IdentityContext {
+    readonly authorizationScope?: readonly string[];
+    readonly schemaVersion?: string;
+    readonly sourceVersion?: string;
+    readonly effectiveSchema?: readonly GeoParquetEffectiveSchemaFieldV1[];
+}
+export declare function createQueryIr<T>(options: ExplainQueryOptions<T>): QueryIrV1;
+/** Build a GeoParquet v2 IR whose only resource addressing is an opaque handle. */
+export declare function createGeoParquetQueryIr<T>(options: ExplainGeoParquetQueryOptions<T>): QueryIrV2;
+export declare function hashQueryIr(ir: QueryIrV1 | QueryIrV2): `sha256:${string}`;
+export declare function canonicalizeQuery<T>(query?: Readonly<Query<T>>): CanonicalQuery;
+export declare function queryFromCanonical<T>(query: CanonicalQuery, signal?: AbortSignal): Query<T>;
+export declare function queryIrSourceIdentity(descriptor: SourceDescriptor, context?: Pick<ExplainQueryOptions, "authorizationScope" | "schemaVersion" | "sourceVersion">): QueryIrSourceIdentity;
+/** Rebuild the exact credential-free source identity used by a GeoParquet v2 plan. */
+export declare function queryIrSourceIdentityV2(descriptor: SourceDescriptor, resourceValue: unknown, context?: GeoParquetV2IdentityContext): QueryIrSourceIdentityV2;
+export declare function deepFreeze<T>(value: T): T;
+//# sourceMappingURL=ir.d.ts.map

package/query-planner/ir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ir.d.ts","sourceRoot":"","sources":["../../../src/query-planner/ir.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAmB,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAGrF,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,6BAA6B,EAClC,KAAK,mBAAmB,EACxB,KAAK,gCAAgC,EAMrC,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,EAC5B,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,YAAY,CAAC;AAIpB,qGAAqG;AACrG,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,gCAAgC,EAAE,CAAC;CACxE;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,SAAS,CAgB3E;AAED,mFAAmF;AACnF,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,OAAO,EAAE,6BAA6B,CAAC,CAAC,CAAC,GAAG,SAAS,CAgB/F;AAED,wBAAgB,WAAW,CAAC,EAAE,EAAE,SAAS,GAAG,SAAS,GAAG,UAAU,MAAM,EAAE,CAEzE;AAED,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,cAAc,CAqC/E;AAED,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC,CAAC,CAAC,CAoB3F;AAED,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,gBAAgB,EAC5B,OAAO,GAAE,IAAI,CAAC,mBAAmB,EAAE,oBAAoB,GAAG,eAAe,GAAG,eAAe,CAAM,GAChG,qBAAqB,CA2BvB;AAED,sFAAsF;AACtF,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,gBAAgB,EAC5B,aAAa,EAAE,OAAO,EACtB,OAAO,GAAE,2BAAgC,GACxC,uBAAuB,CAwDzB;AA0PD,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAMzC"}

package/query-planner/ir.js

@@ -0,0 +1,417 @@
+import { canonicalStringify, sha256, toJsonValue } from "./canonical.js";
+import { parseGeoParquetResourceHandle } from "./resource.js";
+import { HonuaQueryPlanningError, QUERY_IR_KIND, QUERY_IR_V2_VERSION, QUERY_IR_VERSION, } from "./types.js";
+const MAX_EFFECTIVE_SCHEMA_FIELDS = 512;
+export function createQueryIr(options) {
+    try {
+        const ir = {
+            kind: QUERY_IR_KIND,
+            version: QUERY_IR_VERSION,
+            source: queryIrSourceIdentity(options.descriptor, options),
+            query: canonicalizeQuery(options.query),
+        };
+        return deepFreeze(ir);
+    }
+    catch (error) {
+        if (error instanceof HonuaQueryPlanningError)
+            throw error;
+        throw new HonuaQueryPlanningError("invalid-query", `Query cannot be represented by ${QUERY_IR_KIND}@${QUERY_IR_VERSION}: ${errorMessage(error)}`);
+    }
+}
+/** Build a GeoParquet v2 IR whose only resource addressing is an opaque handle. */
+export function createGeoParquetQueryIr(options) {
+    try {
+        const ir = {
+            kind: QUERY_IR_KIND,
+            version: QUERY_IR_V2_VERSION,
+            source: queryIrSourceIdentityV2(options.descriptor, options.geoparquetResource, options),
+            query: canonicalizeQuery(options.query),
+        };
+        return deepFreeze(ir);
+    }
+    catch (error) {
+        if (error instanceof HonuaQueryPlanningError)
+            throw error;
+        throw new HonuaQueryPlanningError("invalid-query", `GeoParquet query cannot be represented safely by ${QUERY_IR_KIND}@${QUERY_IR_V2_VERSION}`);
+    }
+}
+export function hashQueryIr(ir) {
+    return sha256(canonicalStringify(toJsonValue(ir)));
+}
+export function canonicalizeQuery(query) {
+    if (!query)
+        return deepFreeze({});
+    if (query.where !== undefined)
+        assertSafeNativeExpression(query.where);
+    const canonical = {
+        ...(query.where !== undefined ? { where: { kind: "source-native", expression: query.where } } : {}),
+        ...(query.spatialFilter
+            ? {
+                spatialFilter: {
+                    geometry: asJsonObject(query.spatialFilter.geometry, "$.query.spatialFilter.geometry"),
+                    geometryType: query.spatialFilter.geometryType,
+                    ...(query.spatialFilter.spatialRel ? { spatialRel: query.spatialFilter.spatialRel } : {}),
+                },
+            }
+            : {}),
+        ...(query.outFields ? { outFields: [...query.outFields] } : {}),
+        ...(query.orderBy
+            ? {
+                orderBy: query.orderBy.map((sort) => ({ field: sort.field, direction: sort.direction ?? "asc" })),
+            }
+            : {}),
+        ...(query.pagination
+            ? {
+                pagination: {
+                    ...(query.pagination.offset !== undefined
+                        ? { offset: checkedInteger(query.pagination.offset, "offset", 0) }
+                        : {}),
+                    ...(query.pagination.limit !== undefined
+                        ? { limit: checkedInteger(query.pagination.limit, "limit", 0) }
+                        : {}),
+                },
+            }
+            : {}),
+        ...(query.aggregation ? { aggregation: canonicalizeAggregation(query.aggregation) } : {}),
+        ...(query.returnGeometry !== undefined ? { returnGeometry: query.returnGeometry } : {}),
+        ...(query.outSr !== undefined ? { outSr: query.outSr } : {}),
+    };
+    return deepFreeze(canonical);
+}
+export function queryFromCanonical(query, signal) {
+    return {
+        ...(query.where ? { where: query.where.expression } : {}),
+        ...(query.spatialFilter
+            ? {
+                spatialFilter: {
+                    geometry: query.spatialFilter.geometry,
+                    geometryType: query.spatialFilter.geometryType,
+                    ...(query.spatialFilter.spatialRel ? { spatialRel: query.spatialFilter.spatialRel } : {}),
+                },
+            }
+            : {}),
+        ...(query.outFields ? { outFields: query.outFields } : {}),
+        ...(query.orderBy ? { orderBy: query.orderBy } : {}),
+        ...(query.pagination ? { pagination: query.pagination } : {}),
+        ...(query.aggregation ? { aggregation: query.aggregation } : {}),
+        ...(query.returnGeometry !== undefined ? { returnGeometry: query.returnGeometry } : {}),
+        ...(query.outSr !== undefined ? { outSr: query.outSr } : {}),
+        ...(signal ? { signal } : {}),
+    };
+}
+export function queryIrSourceIdentity(descriptor, context = {}) {
+    const authorizationScope = [...new Set(context.authorizationScope ?? [])].sort();
+    if (authorizationScope.some((scope) => !isStableAuthorizationScope(scope))) {
+        throw new HonuaQueryPlanningError("invalid-query", "authorization scope identity is invalid");
+    }
+    const geometryProperty = descriptor.schema?.fields?.find((field) => field.type === "esriFieldTypeGeometry")?.name;
+    const geoparquet = descriptor.protocol === "geoparquet" ? geoparquetIdentity(descriptor, geometryProperty) : undefined;
+    const schemaVersion = optionalPlanMetadata(context.schemaVersion, "schema version");
+    const sourceVersion = optionalPlanMetadata(context.sourceVersion, "source version");
+    return deepFreeze({
+        id: descriptor.id,
+        protocol: descriptor.protocol,
+        endpoint: credentialFreeEndpoint(descriptor.locator.url),
+        ...(descriptor.locator.serviceId !== undefined ? { serviceId: descriptor.locator.serviceId } : {}),
+        ...(descriptor.locator.layerId !== undefined ? { layerId: descriptor.locator.layerId } : {}),
+        ...(descriptor.locator.collectionId !== undefined ? { collectionId: descriptor.locator.collectionId } : {}),
+        ...(descriptor.locator.typeName !== undefined ? { typeName: descriptor.locator.typeName } : {}),
+        ...(descriptor.locator.entitySet !== undefined ? { entitySet: descriptor.locator.entitySet } : {}),
+        ...(geometryProperty ? { geometryProperty } : {}),
+        ...(descriptor.locator.srsName !== undefined ? { srsName: String(descriptor.locator.srsName) } : {}),
+        ...(schemaVersion ? { schemaVersion } : {}),
+        ...(sourceVersion ? { sourceVersion } : {}),
+        ...(geoparquet ? { geoparquet } : {}),
+        authorizationScope,
+        capabilities: [...descriptor.capabilities].sort(),
+    });
+}
+/** Rebuild the exact credential-free source identity used by a GeoParquet v2 plan. */
+export function queryIrSourceIdentityV2(descriptor, resourceValue, context = {}) {
+    if (descriptor.protocol !== "geoparquet") {
+        throw new HonuaQueryPlanningError("invalid-query", "Opaque GeoParquet resources require protocol geoparquet");
+    }
+    const resource = parseGeoParquetResourceHandle(resourceValue);
+    const authorizationScope = [...new Set(context.authorizationScope ?? [])].sort();
+    if (authorizationScope.some((scope) => !isStableAuthorizationScope(scope))) {
+        throw new HonuaQueryPlanningError("invalid-query", "GeoParquet authorization scope identity is invalid");
+    }
+    const geometryProperty = descriptor.schema?.fields?.find((field) => field.type === "esriFieldTypeGeometry")?.name;
+    const primaryKey = optionalPlanMetadata(descriptor.schema?.primaryKey, "primary key");
+    const schemaVersion = optionalPlanMetadata(context.schemaVersion, "schema version");
+    const sourceVersion = optionalPlanMetadata(context.sourceVersion, "source version");
+    const geometryColumn = optionalPlanMetadata(descriptor.locator.geoparquet?.geometryColumn ?? geometryProperty, "geometry column");
+    const bboxColumn = optionalPlanMetadata(descriptor.locator.geoparquet?.bboxColumn, "bbox column");
+    const geometryEncoding = descriptor.locator.geoparquet?.geometryEncoding;
+    if (geometryEncoding !== undefined &&
+        geometryEncoding !== "wkb" &&
+        geometryEncoding !== "native" &&
+        geometryEncoding !== "geojson" &&
+        geometryEncoding !== "geoarrow-point" &&
+        geometryEncoding !== "geoarrow-linestring" &&
+        geometryEncoding !== "geoarrow-polygon" &&
+        geometryEncoding !== "geoarrow-multipoint" &&
+        geometryEncoding !== "geoarrow-multilinestring" &&
+        geometryEncoding !== "geoarrow-multipolygon") {
+        throw new HonuaQueryPlanningError("invalid-query", "GeoParquet geometry encoding identity is invalid");
+    }
+    const nativeDimensions = descriptor.locator.geoparquet?.nativeDimensions;
+    if (nativeDimensions !== undefined && nativeDimensions !== "xy" && nativeDimensions !== "xyz") {
+        throw new HonuaQueryPlanningError("invalid-query", "GeoParquet native geometry dimensions identity is invalid");
+    }
+    const effectiveSchema = geoparquetEffectiveSchema(context.effectiveSchema);
+    return deepFreeze({
+        id: resource.resource.id,
+        protocol: "geoparquet",
+        endpoint: "[opaque-resource]",
+        ...(primaryKey ? { primaryKey } : {}),
+        ...(schemaVersion ? { schemaVersion } : {}),
+        ...(sourceVersion ? { sourceVersion } : {}),
+        geoparquet: {
+            resource,
+            ...(geometryColumn ? { geometryColumn } : {}),
+            ...(geometryEncoding ? { geometryEncoding } : {}),
+            ...(bboxColumn ? { bboxColumn } : {}),
+            ...(nativeDimensions ? { nativeDimensions } : {}),
+            ...(effectiveSchema ? { effectiveSchema } : {}),
+        },
+        authorizationScope,
+        capabilities: [...descriptor.capabilities].sort(),
+    });
+}
+/**
+ * Validate and freeze caller-supplied effective GeoParquet schema evidence
+ * (#627). Reuses the same bounded string checks as other plan metadata so
+ * field name/type text can never smuggle credential material or control
+ * characters into a persisted plan.
+ */
+function geoparquetEffectiveSchema(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || value.length === 0 || value.length > MAX_EFFECTIVE_SCHEMA_FIELDS) {
+        throw new HonuaQueryPlanningError("invalid-query", "GeoParquet effective schema identity is invalid");
+    }
+    const names = new Set();
+    const fields = value.map((field, index) => {
+        if (field === null || typeof field !== "object" || Array.isArray(field)) {
+            throw new HonuaQueryPlanningError("invalid-query", `GeoParquet effective schema field ${index} is invalid`);
+        }
+        const keys = Object.keys(field);
+        if (keys.some((key) => key !== "name" && key !== "type" && key !== "nullable")) {
+            throw new HonuaQueryPlanningError("invalid-query", `GeoParquet effective schema field ${index} is invalid`);
+        }
+        const name = requiredPlanMetadata(field.name, `effective schema field ${index} name`);
+        const type = requiredPlanMetadata(field.type, `effective schema field ${index} type`);
+        if (names.has(name)) {
+            throw new HonuaQueryPlanningError("invalid-query", `GeoParquet effective schema field ${index} duplicates name "${name}"`);
+        }
+        names.add(name);
+        const nullable = field.nullable;
+        if (nullable !== undefined && typeof nullable !== "boolean") {
+            throw new HonuaQueryPlanningError("invalid-query", `GeoParquet effective schema field ${index} nullable is invalid`);
+        }
+        return deepFreeze({ name, type, ...(nullable !== undefined ? { nullable } : {}) });
+    });
+    return deepFreeze(fields);
+}
+function requiredPlanMetadata(value, label) {
+    const parsed = optionalPlanMetadata(value, label);
+    if (parsed === undefined) {
+        throw new HonuaQueryPlanningError("invalid-query", `Query plan ${label} identity is invalid`);
+    }
+    return parsed;
+}
+function optionalPlanMetadata(value, label) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        new TextEncoder().encode(value).byteLength > 1_024 ||
+        containsControlCharacter(value) ||
+        containsCredentialMaterial(value)) {
+        throw new HonuaQueryPlanningError("invalid-query", `Query plan ${label} identity is invalid`);
+    }
+    return value;
+}
+const CREDENTIAL_MATERIAL = /(?:\bBearer\s+[A-Za-z0-9._~+/=-]{8,}|\bBasic\s+[A-Za-z0-9+/=]{8,}|\bAKIA[0-9A-Z]{16}\b|[?&;](?:access[-_]?token|id[-_]?token|refresh[-_]?token|x-amz-signature|x-goog-credential|signature|sig|token|api[-_]?key|password|secret)=[^\s&#;]*|\b(?:authorization|password|secret|token|api[-_]?key|account[-_]?key|shared[-_]?access[-_]?signature)\s*(?:=|:)\s*[^\s,;]+|[a-z][a-z0-9+.-]*:\/\/[^/\s"'<>]*@|\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b)/i;
+function containsCredentialMaterial(value) {
+    return CREDENTIAL_MATERIAL.test(value);
+}
+function containsControlCharacter(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code <= 0x1f || code === 0x7f)
+            return true;
+    }
+    return false;
+}
+function isStableAuthorizationScope(value) {
+    return (typeof value === "string" &&
+        value.length > 0 &&
+        value.length <= 256 &&
+        /^[A-Za-z0-9][A-Za-z0-9._:/~-]*$/.test(value) &&
+        !value.endsWith("/") &&
+        !value.includes("//") &&
+        !value.split("/").some((segment) => segment === "." || segment === "..") &&
+        !/^eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}$/.test(value));
+}
+function assertSafeNativeExpression(value) {
+    if (typeof value !== "string" || value.length === 0 || value.length > 65_536 || containsControlCharacter(value)) {
+        throw new HonuaQueryPlanningError("invalid-query", "query.where is invalid");
+    }
+    const sensitive = /(?:\bBearer\s+[A-Za-z0-9._~+/=-]{8,}|\bBasic\s+[A-Za-z0-9+/=]{8,}|\bAKIA[0-9A-Z]{16}\b|\b(?:authorization|password|secret|token|api[-_]?key)\s*(?:=|eq)\s*['"][^'"]{4,}['"]|\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b)/i;
+    if (sensitive.test(value)) {
+        throw new HonuaQueryPlanningError("invalid-query", "query.where contains sensitive native expression material");
+    }
+}
+/**
+ * Derive deterministic DuckDB/GeoParquet addressing from the descriptor so the
+ * SQL compiler never needs a profiling round-trip. Mirrors the live GeoParquet
+ * `Source` addressing (`locator.url` + `locator.geoparquet.urls`).
+ */
+function geoparquetIdentity(descriptor, geometryProperty) {
+    const { url, geoparquet } = descriptor.locator;
+    const sources = [];
+    if (typeof url === "string" && url.length > 0)
+        sources.push(url);
+    if (geoparquet?.urls)
+        sources.push(...geoparquet.urls);
+    const geometryColumn = geoparquet?.geometryColumn ?? geometryProperty;
+    return {
+        sources,
+        ...(geometryColumn ? { geometryColumn } : {}),
+        ...(geoparquet?.geometryEncoding ? { geometryEncoding: geoparquet.geometryEncoding } : {}),
+        ...(geoparquet?.bboxColumn ? { bboxColumn: geoparquet.bboxColumn } : {}),
+        ...(geoparquet?.nativeDimensions ? { nativeDimensions: geoparquet.nativeDimensions } : {}),
+    };
+}
+function canonicalizeAggregation(aggregation) {
+    if (aggregation.metrics.length === 0) {
+        throw new HonuaQueryPlanningError("invalid-query", "aggregation.metrics must contain at least one metric");
+    }
+    return {
+        ...(aggregation.groupBy ? { groupBy: [...aggregation.groupBy] } : {}),
+        metrics: aggregation.metrics.map((metric) => ({
+            fn: metric.fn,
+            field: metric.field,
+            ...(metric.alias !== undefined ? { alias: metric.alias } : {}),
+        })),
+        ...(aggregation.histogram
+            ? { histogram: toJsonValue(aggregation.histogram) }
+            : {}),
+        ...(aggregation.timeSeries
+            ? { timeSeries: toJsonValue(aggregation.timeSeries) }
+            : {}),
+    };
+}
+function checkedInteger(value, name, minimum) {
+    if (!Number.isSafeInteger(value) || value < minimum) {
+        throw new HonuaQueryPlanningError("invalid-query", `pagination.${name} must be a safe integer >= ${minimum}`);
+    }
+    return value;
+}
+function asJsonObject(value, path) {
+    const json = toJsonValue(value, path);
+    if (json === null || Array.isArray(json) || typeof json !== "object") {
+        throw new TypeError(`${path} must be an object`);
+    }
+    return json;
+}
+function credentialFreeEndpoint(rawUrl) {
+    const invalidEndpoint = "[invalid-endpoint]";
+    try {
+        const parsed = new URL(rawUrl);
+        if (!parsed.username && !parsed.password && hasOpaqueSchemeUserInfo(rawUrl))
+            return invalidEndpoint;
+        parsed.username = "";
+        parsed.password = "";
+        parsed.search = "";
+        parsed.hash = "";
+        return parsed.toString().replace(/\/$/, "");
+    }
+    catch {
+        const path = rawUrl.split(/[?#]/, 1)[0] ?? rawUrl;
+        const malformedAuthority = hasSchemeAuthorityPrefix(rawUrl) || startsWithDoubleSlash(rawUrl);
+        const bareUserInfo = hasBareUserInfo(rawUrl);
+        let unsafeCharacters = false;
+        for (const character of rawUrl) {
+            const codePoint = character.codePointAt(0);
+            if (codePoint <= 0x20 || codePoint === 0x7f || character.trim() === "") {
+                unsafeCharacters = true;
+                break;
+            }
+        }
+        return malformedAuthority || bareUserInfo || unsafeCharacters ? invalidEndpoint : path;
+    }
+}
+function hasSchemeAuthorityPrefix(value) {
+    const colon = value.indexOf(":");
+    if (colon < 1 || !asciiAlpha(value.charCodeAt(0)))
+        return false;
+    for (let index = 1; index < colon; index += 1) {
+        const code = value.charCodeAt(index);
+        if (!(asciiAlpha(code) || (code >= 48 && code <= 57) || code === 43 || code === 45 || code === 46)) {
+            return false;
+        }
+    }
+    return isSlash(value.charCodeAt(colon + 1)) && isSlash(value.charCodeAt(colon + 2));
+}
+function startsWithDoubleSlash(value) {
+    return isSlash(value.charCodeAt(0)) && isSlash(value.charCodeAt(1));
+}
+function hasOpaqueSchemeUserInfo(value) {
+    const colon = value.indexOf(":");
+    if (colon < 1 || !asciiAlpha(value.charCodeAt(0)))
+        return false;
+    for (let index = 1; index < colon; index += 1) {
+        const code = value.charCodeAt(index);
+        if (!(asciiAlpha(code) || (code >= 48 && code <= 57) || code === 43 || code === 45 || code === 46)) {
+            return false;
+        }
+    }
+    for (let index = colon + 1; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code === 64)
+            return true;
+        if (endpointDelimiter(code, false))
+            return false;
+    }
+    return false;
+}
+function hasBareUserInfo(value) {
+    let colon = -1;
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (endpointDelimiter(code, true))
+            return false;
+        if (code === 58 && colon === -1) {
+            if (index === 0)
+                return false;
+            colon = index;
+        }
+        else if (code === 64) {
+            return colon !== -1;
+        }
+    }
+    return false;
+}
+function endpointDelimiter(code, backslash) {
+    return code <= 32 || code === 47 || code === 63 || code === 35 || (backslash && code === 92);
+}
+function asciiAlpha(code) {
+    return (code >= 65 && code <= 90) || (code >= 97 && code <= 122);
+}
+function isSlash(code) {
+    return code === 47 || code === 92;
+}
+export function deepFreeze(value) {
+    if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const child of Object.values(value))
+            deepFreeze(child);
+    }
+    return value;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/query-planner/local-aggregate.d.ts

@@ -0,0 +1,5 @@
+import type { AggregationSpec } from "../contract/types.js";
+import type { HonuaTypedFeature } from "../core/types.js";
+import type { CanonicalQuery } from "./types.js";
+export declare function aggregateLocally<T>(features: readonly HonuaTypedFeature<T>[], aggregation: AggregationSpec, output: Pick<CanonicalQuery, "orderBy" | "pagination">, signal?: AbortSignal): readonly Record<string, unknown>[];
+//# sourceMappingURL=local-aggregate.d.ts.map

package/query-planner/local-aggregate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-aggregate.d.ts","sourceRoot":"","sources":["../../../src/query-planner/local-aggregate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAoC,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE9F,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,QAAQ,EAAE,SAAS,iBAAiB,CAAC,CAAC,CAAC,EAAE,EACzC,WAAW,EAAE,eAAe,EAC5B,MAAM,EAAE,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,YAAY,CAAC,EACtD,MAAM,CAAC,EAAE,WAAW,GACnB,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAcpC"}