@honua/sdk-esri-compat 0.1.12 → 0.1.13

package/query-planner/ir.js

@@ -0,0 +1,479 @@
+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 } } : {}),
+        // 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: {
+                    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.filter !== undefined ? { filter: query.filter } : {}),
+        ...(query.temporalFilter !== undefined ? { temporalFilter: query.temporalFilter } : {}),
+        ...(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");
+    }
+    // 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 } : {}),
+        ...(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(),
+    });
+}
+/**
+ * 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") {
+        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 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 {
+        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"}

package/query-planner/local-aggregate.js

@@ -0,0 +1,126 @@
+import { HonuaAbortError } from "../core/errors.js";
+export function aggregateLocally(features, aggregation, output, signal) {
+    throwIfLocalAggregationAborted(signal);
+    const groupKeys = aggregation.groupBy ?? [];
+    const rows = groupKeys.length === 0
+        ? [computeMetrics(features, aggregation.metrics, signal)]
+        : aggregateGroups(features, groupKeys, aggregation.metrics, signal);
+    throwIfLocalAggregationAborted(signal);
+    const ordered = output.orderBy && output.orderBy.length > 0 ? [...rows].sort(rowComparator(output.orderBy, signal)) : rows;
+    throwIfLocalAggregationAborted(signal);
+    const offset = output.pagination?.offset ?? 0;
+    const limit = output.pagination?.limit;
+    return limit === undefined ? ordered.slice(offset) : ordered.slice(offset, offset + limit);
+}
+function aggregateGroups(features, groupKeys, metrics, signal) {
+    const groups = new Map();
+    for (let index = 0; index < features.length; index += 1) {
+        if ((index & 255) === 0)
+            throwIfLocalAggregationAborted(signal);
+        const feature = features[index];
+        if (!feature)
+            continue;
+        const key = JSON.stringify(groupKeys.map((field) => readField(feature.attributes, field)));
+        const bucket = groups.get(key);
+        if (bucket)
+            bucket.push(feature);
+        else
+            groups.set(key, [feature]);
+    }
+    return Array.from(groups.values(), (bucket, index) => {
+        if ((index & 255) === 0)
+            throwIfLocalAggregationAborted(signal);
+        const row = {};
+        for (const field of groupKeys)
+            row[field] = readField(bucket[0]?.attributes, field);
+        return Object.assign(row, computeMetrics(bucket, metrics, signal));
+    });
+}
+function computeMetrics(features, metrics, signal) {
+    const output = {};
+    for (let metricIndex = 0; metricIndex < metrics.length; metricIndex += 1) {
+        throwIfLocalAggregationAborted(signal);
+        const metric = metrics[metricIndex];
+        if (!metric)
+            continue;
+        const alias = metric.alias ?? `${metric.fn}_${metric.field}`;
+        const values = [];
+        for (let featureIndex = 0; featureIndex < features.length; featureIndex += 1) {
+            if ((featureIndex & 255) === 0)
+                throwIfLocalAggregationAborted(signal);
+            const feature = features[featureIndex];
+            if (!feature)
+                continue;
+            const value = readField(feature.attributes, metric.field);
+            if (typeof value === "number" && Number.isFinite(value))
+                values.push(value);
+        }
+        output[alias] = applyAggregation(metric.fn, values, features.length);
+    }
+    return output;
+}
+function applyAggregation(fn, values, totalRows) {
+    if (fn === "count")
+        return totalRows;
+    if (values.length === 0)
+        return 0;
+    switch (fn) {
+        case "sum":
+            return values.reduce((sum, value) => sum + value, 0);
+        case "avg":
+            return values.reduce((sum, value) => sum + value, 0) / values.length;
+        case "min":
+            return Math.min(...values);
+        case "max":
+            return Math.max(...values);
+        case "stddev":
+        case "var": {
+            const mean = values.reduce((sum, value) => sum + value, 0) / values.length;
+            const variance = values.reduce((sum, value) => sum + (value - mean) ** 2, 0) / values.length;
+            return fn === "var" ? variance : Math.sqrt(variance);
+        }
+    }
+}
+function rowComparator(orderBy, signal) {
+    let comparisons = 0;
+    return (left, right) => {
+        comparisons += 1;
+        if ((comparisons & 255) === 0)
+            throwIfLocalAggregationAborted(signal);
+        for (const sort of orderBy) {
+            const comparison = compareValues(left[sort.field], right[sort.field]);
+            if (comparison !== 0)
+                return sort.direction === "desc" ? -comparison : comparison;
+        }
+        return 0;
+    };
+}
+function throwIfLocalAggregationAborted(signal) {
+    if (!signal)
+        return;
+    try {
+        if (signal.aborted)
+            throw new HonuaAbortError();
+    }
+    catch (error) {
+        if (error instanceof HonuaAbortError)
+            throw error;
+        throw new HonuaAbortError();
+    }
+}
+function compareValues(left, right) {
+    if (left === right)
+        return 0;
+    if (left === null || left === undefined)
+        return -1;
+    if (right === null || right === undefined)
+        return 1;
+    if (typeof left === "number" && typeof right === "number")
+        return left - right;
+    return String(left).localeCompare(String(right));
+}
+function readField(attributes, field) {
+    if (attributes === null || typeof attributes !== "object")
+        return undefined;
+    return attributes[field];
+}

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"}