@honua/react 0.1.2-beta.0 → 0.1.4-beta.0

package/query-planner/index.js

@@ -11,13 +11,19 @@
  * @packageDocumentation
  */
 export { canonicalStringify, sha256, toJsonValue } from "./canonical.js";
+export { columnarBatchIdentityFromPlan } from "./columnar-plan.js";
+export { COLUMNAR_REPRESENTATION_ENCODINGS, COLUMNAR_REPRESENTATION_MIN_BYTES, COLUMNAR_REPRESENTATION_MIN_ROWS, createQueryPlanRepresentationDecision, isColumnarRepresentationEncoding, } from "./representation.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 { odataProtocolModule } from "./odata-protocol-module.js";
+export { compileOdataQuery } from "./odata-v1.js";
+export { compileSemanticOdataQuery } from "./odata.js";
+export { HonuaWfsProtocolError, wfsProtocolModule } from "./wfs-protocol-module.js";
+export { compileWfsQuery } from "./wfs-v1.js";
+export { compileSemanticWfsQuery } 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";
@@ -25,6 +31,13 @@ export { SEMANTIC_QUERY_CANONICAL_KIND, SEMANTIC_QUERY_CANONICAL_VERSION, SEMANT
 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_WORKER_CANCEL_KIND, COLUMNAR_WORKER_ERROR_KIND, COLUMNAR_WORKER_PROGRESS_KIND, COLUMNAR_WORKER_PROTOCOL_VERSION, COLUMNAR_WORKER_REQUEST_KIND, COLUMNAR_WORKER_RESULT_KIND, ColumnarBatchLease, DEFAULT_GEOARROW_AGGREGATE_MAX_GROUPS, DEFAULT_GEOARROW_AGGREGATE_YIELD_ROWS, GEOARROW_AGGREGATE_ABORT_CHECK_ROWS, GEOARROW_AGGREGATE_MAX_GRID_CELL_INDEX, GEOARROW_SPEC_VERSION, HONUA_GEOARROW_AGGREGATE_LAYOUT_VERSION, HONUA_GEOARROW_LAYOUT_VERSION, HonuaGeoArrowError, HonuaColumnarWorkerError, createColumnarBatch, createColumnarWorkerSession, createGeoArrowAggregateOperation, createGeoArrowBatch, createGeoArrowReprojectOperation, readGeoArrowAggregateBatch, deserializeGeoArrowBatch, decodeGeoArrowBatch, fromApacheArrowRecordBatch, inspectGeoArrowBatch, inspectColumnarBatch, leaseColumnarBatch, loadApacheArrow, startColumnarWorkerHost, serializeGeoArrowBatch, toApacheArrowRecordBatch, } from "../columnar/index.js";
+// Bounded conversion between a columnar batch and an object `Result` (#942).
+// It shipped documented as part of this entrypoint but was never re-exported
+// here, so it was unreachable through a subpath; the telemetry seam below
+// observes it, which requires a caller able to reach it.
+export { DEFAULT_COLUMNAR_RESULT_MAX_FEATURES, columnarBatchToResult, columnarBatchToResultPages, resultToColumnarBatch, } from "../columnar/index.js";
+export { COLUMNAR_PATCH_ABORT_CHECK_ROWS, COLUMNAR_PATCH_KIND, COLUMNAR_PATCH_VERSION, DEFAULT_COLUMNAR_PATCH_MAX_CAPACITY_UTILIZATION, DEFAULT_COLUMNAR_PATCH_MAX_OPERATIONS, DEFAULT_COLUMNAR_PATCH_MAX_TOMBSTONE_OVERLAY_BYTES, DEFAULT_COLUMNAR_PATCH_MAX_TOMBSTONE_RATIO, DEFAULT_COLUMNAR_PATCH_MAX_VERTEX_GROWTH_RATIO, HONUA_COLUMNAR_PATCH_LAYOUT_VERSION, HonuaColumnarPatchError, applyColumnarPatch, columnarPatchLiveMask, createColumnarPatch, createColumnarPatchOperation, createPatchableGeoArrowBatch, decodePatchedGeoArrowBatch, inspectColumnarPatchState, } from "../columnar/index.js";
+export { COLUMNAR_BATCH_CACHE_CONFORMANCE_CASES, DEFAULT_COLUMNAR_BATCH_CACHE_MAX_AGE_MS, DEFAULT_COLUMNAR_BATCH_CACHE_MAX_RECORDS, DEFAULT_COLUMNAR_BATCH_CACHE_QUOTA_BYTES, GEOARROW_ENVELOPE_MIGRATIONS, HONUA_COLUMNAR_BATCH_CACHE_CONFORMANCE_KIND, HONUA_COLUMNAR_BATCH_CACHE_CONFORMANCE_VERSION, HONUA_COLUMNAR_BATCH_CACHE_FORMAT, HONUA_GEOARROW_ENVELOPE_KIND, HONUA_GEOARROW_ENVELOPE_VERSION, MAX_COLUMNAR_BATCH_CACHE_MAX_AGE_MS, MAX_COLUMNAR_BATCH_CACHE_MAX_RECORDS, MAX_COLUMNAR_BATCH_CACHE_QUOTA_BYTES, columnarAuthorizationScopeDigest, columnarBatchCacheFixtureBatch, columnarBatchCacheFixtureIdentity, columnarBatchCacheKey, columnarBatchCacheLegacyEntry, columnarBatchCacheOrderingDigest, createColumnarBatchCache, createIndexedDbColumnarBatchCacheStorage, createMemoryColumnarBatchCacheStorage, planColumnarBatchCacheAdmission, planGeoArrowEnvelopeMigration, readableGeoArrowEnvelopeVersions, runColumnarBatchCacheConformance, } 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

@@ -13,7 +13,12 @@ export declare function createGeoParquetQueryIr<T>(options: ExplainGeoParquetQue
 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;
+export declare function queryIrSourceIdentity(descriptor: SourceDescriptor, context?: Pick<ExplainQueryOptions, "authorizationScope" | "schemaVersion" | "sourceVersion" | "sourceAuthorityFingerprint">): QueryIrSourceIdentity;
+/**
+ * Derive a stable WFS authority binding without retaining endpoint
+ * credentials, signed-query values, fragments, or authorization material.
+ */
+export declare function queryIrAuthorityFingerprint(rawUrl: string, authorizationScope?: readonly string[]): `sha256:${string}`;
 /** 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;

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

@@ -1 +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"}
+{"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,CA0C/E;AAED,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC,CAAC,CAAC,CAsB3F;AAED,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,gBAAgB,EAC5B,OAAO,GAAE,IAAI,CACX,mBAAmB,EACnB,oBAAoB,GAAG,eAAe,GAAG,eAAe,GAAG,4BAA4B,CACnF,GACL,qBAAqB,CA+CvB;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,MAAM,EACd,kBAAkB,GAAE,SAAS,MAAM,EAAO,GACzC,UAAU,MAAM,EAAE,CAepB;AAED,sFAAsF;AACtF,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,gBAAgB,EAC5B,aAAa,EAAE,OAAO,EACtB,OAAO,GAAE,2BAAgC,GACxC,uBAAuB,CAwDzB;AAiRD,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAMzC"}

package/query-planner/ir.js

@@ -45,6 +45,11 @@ export function canonicalizeQuery(query) {
         assertSafeNativeExpression(query.where);
     const canonical = {
         ...(query.where !== undefined ? { where: { kind: "source-native", expression: query.where } } : {}),
+        // The typed filter and temporal member are identity-bearing: they change
+        // which rows a plan returns, so they belong in the canonical bytes that
+        // `hashQueryIr` / `hashQueryPlan` fingerprint.
+        ...(query.filter !== undefined ? { filter: query.filter } : {}),
+        ...(query.temporalFilter !== undefined ? { temporalFilter: query.temporalFilter } : {}),
         ...(query.spatialFilter
             ? {
                 spatialFilter: {
@@ -81,6 +86,8 @@ export function canonicalizeQuery(query) {
 export function queryFromCanonical(query, signal) {
     return {
         ...(query.where ? { where: query.where.expression } : {}),
+        ...(query.filter !== undefined ? { filter: query.filter } : {}),
+        ...(query.temporalFilter !== undefined ? { temporalFilter: query.temporalFilter } : {}),
         ...(query.spatialFilter
             ? {
                 spatialFilter: {
@@ -104,14 +111,30 @@ export function queryIrSourceIdentity(descriptor, context = {}) {
     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;
+    // WFS names its geometry property per feature type; `locator.geometryName`
+    // carries either the caller's explicit pin or the value the adapter resolved
+    // from DescribeFeatureType, and outranks descriptor schema evidence.
+    const geometryProperty = (descriptor.protocol === "wfs" ? descriptor.locator.geometryName : undefined) ??
+        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");
+    const authorityFingerprint = descriptor.protocol === "wfs"
+        ? context.sourceAuthorityFingerprint === null
+            ? undefined
+            : (context.sourceAuthorityFingerprint ??
+                queryIrAuthorityFingerprint(descriptor.locator.url, authorizationScope))
+        : undefined;
+    if (context.sourceAuthorityFingerprint !== undefined &&
+        context.sourceAuthorityFingerprint !== null &&
+        !/^sha256:[0-9a-f]{64}$/.test(context.sourceAuthorityFingerprint)) {
+        throw new HonuaQueryPlanningError("invalid-query", "source authority fingerprint is invalid");
+    }
     return deepFreeze({
         id: descriptor.id,
         protocol: descriptor.protocol,
         endpoint: credentialFreeEndpoint(descriptor.locator.url),
+        ...(authorityFingerprint ? { authorityFingerprint } : {}),
         ...(descriptor.locator.serviceId !== undefined ? { serviceId: descriptor.locator.serviceId } : {}),
         ...(descriptor.locator.layerId !== undefined ? { layerId: descriptor.locator.layerId } : {}),
         ...(descriptor.locator.collectionId !== undefined ? { collectionId: descriptor.locator.collectionId } : {}),
@@ -126,6 +149,22 @@ export function queryIrSourceIdentity(descriptor, context = {}) {
         capabilities: [...descriptor.capabilities].sort(),
     });
 }
+/**
+ * Derive a stable WFS authority binding without retaining endpoint
+ * credentials, signed-query values, fragments, or authorization material.
+ */
+export function queryIrAuthorityFingerprint(rawUrl, authorizationScope = []) {
+    const scopes = [...new Set(authorizationScope)].sort();
+    if (scopes.some((scope) => !isStableAuthorizationScope(scope))) {
+        throw new HonuaQueryPlanningError("invalid-query", "authorization scope identity is invalid");
+    }
+    const authority = canonicalAuthorityMaterial(rawUrl);
+    return sha256(canonicalStringify(toJsonValue({
+        domain: "honua:wfs-authority:v1",
+        authority,
+        authorizationScope: scopes,
+    })));
+}
 /** Rebuild the exact credential-free source identity used by a GeoParquet v2 plan. */
 export function queryIrSourceIdentityV2(descriptor, resourceValue, context = {}) {
     if (descriptor.protocol !== "geoparquet") {
@@ -317,6 +356,29 @@ function asJsonObject(value, path) {
     }
     return json;
 }
+function canonicalAuthorityMaterial(rawUrl) {
+    if (typeof rawUrl !== "string" || rawUrl.length === 0) {
+        throw new HonuaQueryPlanningError("invalid-query", "source authority endpoint is invalid");
+    }
+    try {
+        const parsed = new URL(rawUrl);
+        parsed.hash = "";
+        const search = parsed.search;
+        parsed.search = "";
+        return `${parsed.toString().replace(/\/$/, "")}${search}`;
+    }
+    catch {
+        const withoutFragment = rawUrl.split("#", 1)[0] ?? rawUrl;
+        const queryIndex = withoutFragment.indexOf("?");
+        const path = queryIndex >= 0 ? withoutFragment.slice(0, queryIndex) : withoutFragment;
+        const search = queryIndex >= 0 ? withoutFragment.slice(queryIndex) : "";
+        const normalized = path === "/" ? "/" : path.replace(/\/$/, "");
+        if (normalized.length === 0 || hasSchemeAuthorityPrefix(rawUrl) || startsWithDoubleSlash(rawUrl)) {
+            throw new HonuaQueryPlanningError("invalid-query", "source authority endpoint is invalid");
+        }
+        return `${normalized}${search}`;
+    }
+}
 function credentialFreeEndpoint(rawUrl) {
     const invalidEndpoint = "[invalid-endpoint]";
     try {

package/query-planner/odata-protocol-module.d.ts

@@ -0,0 +1,54 @@
+/**
+ * First-party OData v4 protocol module.
+ *
+ * The module owns the same typed `HonuaOdataEntitySet` escape hatch exposed by
+ * `Source.protocol("odata")`, the deterministic planner compiler hook, and
+ * canonical query/queryAll wire execution. Runtime authority is the
+ * `HonuaClient` explicitly injected into {@link odataProtocolModule}; compiled
+ * artifacts carry no origin or credentials and cannot redirect a discovered
+ * handle to another entity set.
+ *
+ * @module
+ */
+import type { ProtocolModuleQueryBinding, ProtocolModuleQueryOperation, QueryCapableProtocolModule } from "../contract/protocol-module.js";
+import type { Result, SourceDescriptor } from "../contract/types.js";
+import type { HonuaClient } from "../core/client.js";
+import { HonuaOdataEntitySet, type HonuaOdataPage, type HonuaOdataQueryParams } from "../core/odata.js";
+import type { HonuaFieldInfo } from "../core/types.js";
+import type { CanonicalQuery, OdataProtocolCompiledQueryV1, QueryIrSourceIdentity } from "./types.js";
+/** Runtime-only OData execution context. None of these values enter a plan fingerprint. */
+export interface OdataProtocolExecutionQuery {
+    readonly count: boolean;
+    readonly fields: ReadonlyArray<HonuaFieldInfo>;
+    readonly returnGeometry?: boolean;
+    readonly geometryColumn?: string;
+    readonly limit?: number;
+}
+/** Exact compiler/executor types carried by the OData protocol module. */
+export interface OdataProtocolQueryBinding extends ProtocolModuleQueryBinding {
+    readonly source: QueryIrSourceIdentity;
+    readonly compileQuery: CanonicalQuery;
+    readonly compiled: OdataProtocolCompiledQueryV1;
+    readonly executeQuery: OdataProtocolExecutionQuery;
+}
+export type OdataProtocolModule = QueryCapableProtocolModule<"odata", HonuaOdataEntitySet, OdataProtocolQueryBinding>;
+/**
+ * Project already-negotiated OData query params onto the credential-free
+ * deterministic artifact consumed by the module executor.
+ *
+ * `count` and `signal` are intentionally omitted: count is runtime response
+ * metadata policy, and cancellation can never participate in request identity.
+ */
+export declare function createOdataProtocolCompiledQuery(entitySet: string, operation: ProtocolModuleQueryOperation, params: HonuaOdataQueryParams): OdataProtocolCompiledQueryV1;
+/**
+ * Construct the first-party query-capable OData protocol module.
+ *
+ * Discovery is synchronous and performs no I/O. `$metadata` remains lazy on
+ * the returned `HonuaOdataEntitySet`, exactly as it was before the migration.
+ * The client stays in this module instance's closure; there is no global
+ * protocol registry or ambient authority.
+ */
+export declare function odataProtocolModule(client: HonuaClient): OdataProtocolModule;
+/** Internal shared result projection used by query execution and OData streaming. */
+export declare function odataProtocolResultFromPage<T>(descriptor: SourceDescriptor, page: HonuaOdataPage<Record<string, unknown>>, fields: ReadonlyArray<HonuaFieldInfo>, returnGeometry: boolean | undefined, geometryColumn: string | undefined): Result<T>;
+//# sourceMappingURL=odata-protocol-module.d.ts.map

package/query-planner/odata-protocol-module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"odata-protocol-module.d.ts","sourceRoot":"","sources":["../../../src/query-planner/odata-protocol-module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAEV,0BAA0B,EAE1B,4BAA4B,EAC5B,0BAA0B,EAC3B,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAA0B,MAAM,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAExG,OAAO,KAAK,EAAE,cAAc,EAAqB,MAAM,kBAAkB,CAAC;AAE1E,OAAO,KAAK,EACV,cAAc,EAEd,4BAA4B,EAC5B,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAEpB,2FAA2F;AAC3F,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IAC/C,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,0EAA0E;AAC1E,MAAM,WAAW,yBAA0B,SAAQ,0BAA0B;IAC3E,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,YAAY,EAAE,cAAc,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,4BAA4B,CAAC;IAChD,QAAQ,CAAC,YAAY,EAAE,2BAA2B,CAAC;CACpD;AAED,MAAM,MAAM,mBAAmB,GAAG,0BAA0B,CAAC,OAAO,EAAE,mBAAmB,EAAE,yBAAyB,CAAC,CAAC;AAEtH;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAC9C,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,4BAA4B,EACvC,MAAM,EAAE,qBAAqB,GAC5B,4BAA4B,CAY9B;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,GAAG,mBAAmB,CAwE5E;AA2FD,qFAAqF;AACrF,wBAAgB,2BAA2B,CAAC,CAAC,EAC3C,UAAU,EAAE,gBAAgB,EAC5B,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAC7C,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,EACrC,cAAc,EAAE,OAAO,GAAG,SAAS,EACnC,cAAc,EAAE,MAAM,GAAG,SAAS,GACjC,MAAM,CAAC,CAAC,CAAC,CAUX"}

package/query-planner/odata-protocol-module.js

@@ -0,0 +1,199 @@
+import { PROTOCOL_DEFAULT_CAPABILITIES } from "../contract/types.js";
+import { HonuaCapabilityNotSupportedError } from "../core/errors.js";
+import { HonuaOdataEntitySet } from "../core/odata.js";
+import { trimTrailingSlashes } from "../core/path-utils.js";
+import { bindOdataProtocolQueryOperation, odataProtocolQueryCompiler } from "./odata-v1.js";
+/**
+ * Project already-negotiated OData query params onto the credential-free
+ * deterministic artifact consumed by the module executor.
+ *
+ * `count` and `signal` are intentionally omitted: count is runtime response
+ * metadata policy, and cancellation can never participate in request identity.
+ */
+export function createOdataProtocolCompiledQuery(entitySet, operation, params) {
+    const request = Object.freeze({
+        compiler: "odata-v4-query-v1",
+        entitySet,
+        ...(params.filter !== undefined ? { filter: params.filter } : {}),
+        ...(params.select !== undefined ? { select: Object.freeze([...params.select]) } : {}),
+        ...(params.expand !== undefined ? { expand: Object.freeze([...params.expand]) } : {}),
+        ...(params.orderBy !== undefined ? { orderBy: Object.freeze([...params.orderBy]) } : {}),
+        ...(params.skip !== undefined ? { skip: params.skip } : {}),
+        ...(params.top !== undefined ? { top: params.top } : {}),
+    });
+    return bindOdataProtocolQueryOperation(request, operation);
+}
+/**
+ * Construct the first-party query-capable OData protocol module.
+ *
+ * Discovery is synchronous and performs no I/O. `$metadata` remains lazy on
+ * the returned `HonuaOdataEntitySet`, exactly as it was before the migration.
+ * The client stays in this module instance's closure; there is no global
+ * protocol registry or ambient authority.
+ */
+export function odataProtocolModule(client) {
+    return Object.freeze({
+        kind: "odata",
+        environments: Object.freeze(["browser", "node", "worker"]),
+        capabilities(descriptor) {
+            return descriptor.capabilities ?? PROTOCOL_DEFAULT_CAPABILITIES.odata;
+        },
+        discover(descriptor) {
+            const { entitySet, basePath } = requireOdataLocator(descriptor);
+            const adapter = new HonuaOdataEntitySet({ client, entitySet, basePath });
+            return Object.freeze({
+                descriptor,
+                capabilities: descriptor.capabilities ?? PROTOCOL_DEFAULT_CAPABILITIES.odata,
+                adapter,
+                diagnostics: Object.freeze([]),
+                dispose() {
+                    // HonuaOdataEntitySet retains only settled/in-flight promises and
+                    // opens no persistent handles. Disposal is deterministic and
+                    // synchronous with nothing to release.
+                },
+            });
+        },
+        compile: odataProtocolQueryCompiler.compile,
+        async execute(handle, input) {
+            assertExecutableOdataArtifact(handle.adapter, input.compiled, input.operation);
+            const logicalLimit = input.operation === "queryAll"
+                ? resolveOdataQueryAllLogicalLimit(input.compiled, input.query.limit)
+                : undefined;
+            const params = odataParamsFromCompiled(input.compiled, input.query.count, input.signal);
+            switch (input.operation) {
+                case "query": {
+                    const page = await handle.adapter.query(params);
+                    return odataProtocolResultFromPage(handle.descriptor, page, input.query.fields, input.query.returnGeometry, input.query.geometryColumn);
+                }
+                case "queryAll": {
+                    const drained = await handle.adapter.queryAll(params);
+                    const allFeatures = drained.rows.map((row) => odataRowToFeature(row, handle.descriptor, input.query.returnGeometry, input.query.geometryColumn));
+                    const { features, exceededTransferLimit: collectedExceeded } = applyLimit(allFeatures, logicalLimit);
+                    const countExceeded = typeof drained.totalCount === "number" &&
+                        typeof logicalLimit === "number" &&
+                        drained.totalCount > features.length;
+                    return {
+                        features,
+                        exceededTransferLimit: collectedExceeded || countExceeded,
+                        ...(typeof drained.totalCount === "number"
+                            ? { totalCount: drained.totalCount }
+                            : { totalCount: features.length }),
+                        ...(input.query.fields.length > 0 ? { fields: input.query.fields } : {}),
+                    };
+                }
+                case "queryAggregate":
+                    throw new HonuaCapabilityNotSupportedError("queryAggregate", handle.descriptor.protocol, handle.descriptor.id);
+            }
+        },
+    });
+}
+function requireOdataLocator(descriptor) {
+    const { entitySet, url, layerId } = descriptor.locator;
+    let resolvedEntitySet;
+    if (typeof entitySet === "string" && entitySet !== "") {
+        resolvedEntitySet = entitySet;
+    }
+    else if (typeof layerId === "number" && Number.isFinite(layerId)) {
+        resolvedEntitySet = `Layers(${layerId})/Features`;
+    }
+    if (resolvedEntitySet === undefined) {
+        throw new Error(`createDataset: source "${descriptor.id}" (odata) requires locator.entitySet or locator.layerId`);
+    }
+    const basePath = url ? extractOdataBasePath(url) : "/odata";
+    return { entitySet: resolvedEntitySet, basePath };
+}
+function extractOdataBasePath(url) {
+    try {
+        const parsed = new URL(url);
+        const pathname = trimTrailingSlashes(parsed.pathname);
+        return pathname === "" ? "/odata" : pathname;
+    }
+    catch {
+        return url.startsWith("/") ? trimTrailingSlashes(url) || "/odata" : `/${trimTrailingSlashes(url)}`;
+    }
+}
+function assertExecutableOdataArtifact(adapter, compiled, operation) {
+    if (compiled.compiler !== "odata-v4-protocol-query-v1") {
+        throw new TypeError("odata: protocol module requires an odata-v4-protocol-query-v1 artifact");
+    }
+    if (compiled.entitySet !== adapter.entitySet) {
+        throw new TypeError("odata: compiled entitySet does not match the discovered protocol handle");
+    }
+    if (compiled.operation !== operation) {
+        throw new TypeError("odata: compiled operation does not match the requested protocol operation");
+    }
+}
+/**
+ * Recover the caller-visible queryAll ceiling from the compiler-owned
+ * lookahead row and reject any runtime context that does not describe the
+ * same bounded request. This runs before the adapter performs I/O.
+ */
+function resolveOdataQueryAllLogicalLimit(compiled, requestedLimit) {
+    if (requestedLimit !== undefined && (!Number.isSafeInteger(requestedLimit) || requestedLimit < 0)) {
+        throw new TypeError("odata: queryAll logical limit must be a non-negative safe integer");
+    }
+    if (compiled.top === undefined) {
+        if (requestedLimit !== undefined) {
+            throw new TypeError("odata: queryAll compiled top does not match the logical limit");
+        }
+        return undefined;
+    }
+    if (!Number.isSafeInteger(compiled.top) || compiled.top < 1) {
+        throw new TypeError("odata: queryAll compiled top must contain one lookahead row");
+    }
+    const compiledLogicalLimit = compiled.top - 1;
+    if (requestedLimit !== undefined && requestedLimit !== compiledLogicalLimit) {
+        throw new TypeError("odata: queryAll compiled top does not match the logical limit");
+    }
+    return requestedLimit ?? compiledLogicalLimit;
+}
+function odataParamsFromCompiled(compiled, count, signal) {
+    return {
+        ...(compiled.filter !== undefined ? { filter: compiled.filter } : {}),
+        ...(compiled.select !== undefined ? { select: compiled.select } : {}),
+        ...(compiled.expand !== undefined ? { expand: compiled.expand } : {}),
+        ...(compiled.orderBy !== undefined ? { orderBy: compiled.orderBy } : {}),
+        ...(compiled.skip !== undefined ? { skip: compiled.skip } : {}),
+        ...(compiled.top !== undefined ? { top: compiled.top } : {}),
+        ...(count ? { count: true } : {}),
+        ...(signal ? { signal } : {}),
+    };
+}
+/** Internal shared result projection used by query execution and OData streaming. */
+export function odataProtocolResultFromPage(descriptor, page, fields, returnGeometry, geometryColumn) {
+    const features = page.rows.map((row) => odataRowToFeature(row, descriptor, returnGeometry, geometryColumn));
+    const exceededTransferLimit = typeof page.totalCount === "number" ? features.length < page.totalCount : Boolean(page.nextLink);
+    return {
+        features,
+        exceededTransferLimit,
+        ...(typeof page.totalCount === "number" ? { totalCount: page.totalCount } : {}),
+        ...(fields.length > 0 ? { fields } : {}),
+    };
+}
+function odataRowToFeature(row, descriptor, returnGeometry, geometryColumn) {
+    const geometryKey = geometryColumn ??
+        descriptor.schema?.fields?.find((field) => field.type === "esriFieldTypeGeometry")?.name ??
+        findGeometryKey(row);
+    if (geometryKey && row[geometryKey] !== undefined) {
+        const { [geometryKey]: geometry, ...attributes } = row;
+        return {
+            attributes: attributes,
+            geometry: returnGeometry === false ? null : (geometry ?? null),
+        };
+    }
+    return { attributes: row, geometry: null };
+}
+function findGeometryKey(row) {
+    for (const key of Object.keys(row)) {
+        const lower = key.toLowerCase();
+        if (lower === "geometry" || lower === "geography" || lower === "shape")
+            return key;
+    }
+    return undefined;
+}
+function applyLimit(features, limit) {
+    if (typeof limit !== "number" || limit < 0 || features.length <= limit) {
+        return { features, exceededTransferLimit: false };
+    }
+    return { features: features.slice(0, limit), exceededTransferLimit: true };
+}

package/query-planner/odata-v1.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Lightweight deterministic OData v4 compiler.
+ *
+ * Kept separate from the semantic OData compiler so importing the public
+ * `odataProtocolModule()` does not pull the larger semantic compiler graph
+ * into contract-only bundles.
+ */
+import type { ProtocolModuleQueryCompileInput, ProtocolModuleQueryOperation } from "../contract/protocol-module.js";
+import type { CanonicalQuery, OdataCompiledQueryV1, OdataProtocolCompiledQueryV1, QueryIrSourceIdentity } from "./types.js";
+/** Compile canonical query IR to a deterministic OData v4 entity-set request. */
+export declare function compileOdataQuery(source: QueryIrSourceIdentity, query: CanonicalQuery): OdataCompiledQueryV1;
+/**
+ * The deterministic compiler hook installed on the first-party OData
+ * ProtocolModule. Planner dispatch and module consumers call this exact
+ * object, while runtime authority remains outside the compiler.
+ */
+export declare const odataProtocolQueryCompiler: Readonly<{
+    kind: "odata";
+    compile(input: ProtocolModuleQueryCompileInput<QueryIrSourceIdentity, CanonicalQuery>): OdataProtocolCompiledQueryV1;
+}>;
+/** Bind a legacy wire request to the exact operation authorized to execute it. */
+export declare function bindOdataProtocolQueryOperation(compiled: OdataCompiledQueryV1, operation: ProtocolModuleQueryOperation): OdataProtocolCompiledQueryV1;
+//# sourceMappingURL=odata-v1.d.ts.map

package/query-planner/odata-v1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"odata-v1.d.ts","sourceRoot":"","sources":["../../../src/query-planner/odata-v1.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,+BAA+B,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAIpH,OAAO,KAAK,EACV,cAAc,EACd,oBAAoB,EACpB,4BAA4B,EAC5B,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAGpB,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,qBAAqB,EAAE,KAAK,EAAE,cAAc,GAAG,oBAAoB,CAqH5G;AAED;;;;GAIG;AACH,eAAO,MAAM,0BAA0B;;mBAEtB,+BAA+B,CAAC,qBAAqB,EAAE,cAAc,CAAC,GAAG,4BAA4B;EAGpH,CAAC;AAEH,kFAAkF;AAClF,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,oBAAoB,EAC9B,SAAS,EAAE,4BAA4B,GACtC,4BAA4B,CAsB9B"}