@honua/sdk-esri-compat 0.1.12 → 0.1.13

package/query-planner/ogc-features.js

@@ -0,0 +1,639 @@
+import { compileQueryFilterToCql2Text, compileTemporalFilterToOgcDatetime, } from "../contract/query-filter.js";
+import { geometryToWkt as esriGeometryToWkt } from "../core/odata.js";
+import { canonicalFilterParts } from "./canonical-filter.js";
+import { canonicalStringify, toJsonValue } from "./canonical.js";
+import { bboxInDefinitionOrder, compiledRequestFingerprint, compilerEvidenceFingerprint, compilerField, cql2FieldName, cql2Identifier, cql2StringLiteral, geometryInDefinitionOrder, geometryToWkt, hasConformanceClass, normalizeConformanceUris, normalizeIdentifierUris, ogcAxisPlan, ogcCrsUri, ogcNumber, sharedFilterCrs, } from "./ogc-compiler.js";
+import { hashSemanticQuery } from "./semantic-canonical.js";
+import { prepareSemanticCompilerQuery, runSemanticCompiler, semanticUnsupported, } from "./semantic-compiler.js";
+import { HonuaQueryPlanningError } from "./types.js";
+const OGC_CAPABILITY_FINGERPRINT_DOMAIN = "honua.ogc-features.filter-capabilities.v1";
+const OGC_REQUEST_FINGERPRINT_DOMAIN = "honua.ogc-features.semantic-request.v1";
+const CQL2_DATE = /^\d{4}-\d{2}-\d{2}$/;
+const CQL2_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;
+const EXACT_NUMERIC_TEXT = /^-?(?:0|[1-9]\d*)(?:\.\d+)?$/;
+const COMPARISON_TEXT = {
+    eq: "=",
+    ne: "<>",
+    lt: "<",
+    lte: "<=",
+    gt: ">",
+    gte: ">=",
+};
+const SPATIAL_TEXT = {
+    equals: "S_EQUALS",
+    intersects: "S_INTERSECTS",
+    within: "S_WITHIN",
+    contains: "S_CONTAINS",
+    disjoint: "S_DISJOINT",
+    touches: "S_TOUCHES",
+    overlaps: "S_OVERLAPS",
+    crosses: "S_CROSSES",
+};
+const SPATIAL_JSON = {
+    equals: "s_equals",
+    intersects: "s_intersects",
+    within: "s_within",
+    contains: "s_contains",
+    disjoint: "s_disjoint",
+    touches: "s_touches",
+    overlaps: "s_overlaps",
+    crosses: "s_crosses",
+};
+const TEMPORAL_TEXT = {
+    before: "T_BEFORE",
+    after: "T_AFTER",
+    during: "T_DURING",
+    "time-intersects": "T_INTERSECTS",
+};
+const TEMPORAL_JSON = {
+    before: "t_before",
+    after: "t_after",
+    during: "t_during",
+    "time-intersects": "t_intersects",
+};
+/**
+ * Compile canonical query IR to an OGC API Features `/items` request. The
+ * compiler is side-effect free and deliberately supports only semantics the
+ * first-party OGC adapter can preserve exactly.
+ */
+export function compileOgcApiFeaturesQuery(source, query) {
+    if (source.protocol !== "ogc-features") {
+        throw new HonuaQueryPlanningError("unsupported-compiler", `ogc-api-features-query-v1 does not compile protocol "${source.protocol}"`);
+    }
+    if (source.collectionId === undefined || source.collectionId === "") {
+        throw new HonuaQueryPlanningError("invalid-query", `Source "${source.id}" requires locator.collectionId for OGC API Features planning`);
+    }
+    if (query.aggregation) {
+        throw new HonuaQueryPlanningError("unsupported-query", "OGC API Features does not provide remote aggregation; use degraded policy with an explicit bounded-local fallback");
+    }
+    if (query.returnGeometry === false) {
+        throw new HonuaQueryPlanningError("unsupported-query", "OGC API Features /items has no portable geometry-suppression parameter; omit returnGeometry or select another protocol");
+    }
+    const ctx = {
+        protocol: source.protocol,
+        sourceId: source.id,
+        geometryProperty: source.geometryProperty ?? "geometry",
+    };
+    const parts = canonicalFilterParts(query, ctx);
+    const typedFilter = parts.expression
+        ? compileQueryFilterToCql2Text(parts.expression, ctx, esriGeometryToWkt)
+        : undefined;
+    const filterParts = [
+        ...(query.where ? [query.where.expression] : []),
+        ...(typedFilter !== undefined ? [typedFilter] : []),
+    ];
+    const filter = filterParts.length === 0
+        ? undefined
+        : filterParts.length === 1
+            ? filterParts[0]
+            : filterParts.map((part) => `(${part})`).join(" AND ");
+    return {
+        compiler: "ogc-api-features-query-v1",
+        collectionId: source.collectionId,
+        ...(filter !== undefined ? { filter, filterLang: "cql2-text" } : {}),
+        ...(parts.protocolTime ? { datetime: compileTemporalFilterToOgcDatetime(parts.protocolTime, ctx) } : {}),
+        ...(query.outFields && query.outFields.length > 0 ? { properties: query.outFields } : {}),
+        ...(query.orderBy && query.orderBy.length > 0
+            ? { sortby: query.orderBy.map((sort) => `${sort.direction === "desc" ? "-" : ""}${sort.field}`).join(",") }
+            : {}),
+        ...(query.spatialFilter ? { bbox: compileBbox(query.spatialFilter, source.id) } : {}),
+        ...(query.outSr !== undefined ? { crs: String(query.outSr) } : {}),
+        ...(query.pagination?.offset !== undefined ? { offset: query.pagination.offset } : {}),
+        ...(query.pagination?.limit !== undefined ? { limit: query.pagination.limit } : {}),
+    };
+}
+/** Compile a typed semantic query using only explicitly discovered OGC/CQL2 support. */
+export function compileSemanticOgcApiFeaturesQuery(options) {
+    return runSemanticCompiler(() => {
+        const { query, schema } = prepareSemanticCompilerQuery(options.query, options.schema, "ogc-features");
+        const source = verifiedSemanticOgcSource(options.source);
+        const conformance = normalizeOgcConformance(options.conformance);
+        const language = query.filter
+            ? selectCql2Language(query.filter, conformance, options.preferredFilterLanguage)
+            : undefined;
+        const state = language
+            ? { schema, conformance, language, usesNativeFilter: false }
+            : undefined;
+        const filter = state && query.filter ? compileCql2Filter(query.filter, state, "$.filter") : undefined;
+        const filterCrs = state?.filterCrs
+            ? compiledOgcFilterCrs(state.filterCrs, conformance, "$.filter")
+            : options.nativeFilterCrs && query.filter?.kind === "native"
+                ? compiledOgcFilterCrs(options.nativeFilterCrs, conformance, "options.nativeFilterCrs")
+                : undefined;
+        validateOgcSemanticProjection(query, schema);
+        rejectOgcSemanticSort(query);
+        const page = query.page;
+        if (page?.kind === "offset") {
+            semanticUnsupported("unsupported-node", "$.page.offset", "OGC API Features Core does not define a client-supplied offset parameter");
+        }
+        const crs = query.outputCrs ? compiledOgcOutputCrs(query.outputCrs, conformance, "$.outputCrs") : undefined;
+        const queryFingerprint = hashSemanticQuery(query, { schema, protocol: "ogc-features" });
+        const preimage = {
+            compiler: "ogc-api-features-semantic-query-v1",
+            ...(language ? { dialect: language } : {}),
+            schemaFingerprint: schema.fingerprint,
+            queryFingerprint,
+            capabilityFingerprint: conformance.fingerprint,
+            collectionId: source.collectionId,
+            ...(filter !== undefined ? { filter, filterLang: language } : {}),
+            ...(filterCrs ? { filterCrs } : {}),
+            ...(crs ? { crs } : {}),
+            ...(page?.limit !== undefined ? { limit: page.limit } : {}),
+            usesNativeFilter: state?.usesNativeFilter ?? false,
+        };
+        const artifact = {
+            ...preimage,
+            requestFingerprint: compiledRequestFingerprint(OGC_REQUEST_FINGERPRINT_DOMAIN, toJsonValue(preimage)),
+        };
+        return { artifact };
+    });
+}
+function verifiedSemanticOgcSource(value) {
+    if (!value || typeof value !== "object") {
+        throw new HonuaQueryPlanningError("invalid-query", "Semantic OGC source identity is invalid");
+    }
+    if ((typeof value.collectionId !== "string" && typeof value.collectionId !== "number") ||
+        (typeof value.collectionId === "string" &&
+            (value.collectionId.length === 0 || value.collectionId.length > 1_024 || hasControl(value.collectionId))) ||
+        (typeof value.collectionId === "number" && (!Number.isSafeInteger(value.collectionId) || value.collectionId < 0))) {
+        throw new HonuaQueryPlanningError("invalid-query", "options.source.collectionId is invalid");
+    }
+    return { collectionId: value.collectionId };
+}
+function normalizeOgcConformance(value) {
+    if (!value || typeof value !== "object") {
+        throw new HonuaQueryPlanningError("invalid-query", "options.conformance is invalid");
+    }
+    const conformsTo = normalizeConformanceUris(value.conformsTo, "options.conformance.conformsTo");
+    const supportedFilterCrs = normalizeIdentifierUris(value.supportedFilterCrs, "options.conformance.supportedFilterCrs");
+    const supportedOutputCrs = normalizeIdentifierUris(value.supportedOutputCrs, "options.conformance.supportedOutputCrs");
+    return {
+        conformsTo,
+        supportedFilterCrs,
+        supportedOutputCrs,
+        fingerprint: compilerEvidenceFingerprint(OGC_CAPABILITY_FINGERPRINT_DOMAIN, toJsonValue({ conformsTo, supportedFilterCrs, supportedOutputCrs })),
+    };
+}
+function selectCql2Language(filter, conformance, preferred) {
+    requireCqlConformance(conformance, "ogcapi-features-3/1.0", "features-filter", "$.filter");
+    requireCqlConformance(conformance, "cql2/1.0", "basic-cql2", "$.filter");
+    const advertised = ["cql2-json", "cql2-text"].filter((language) => hasConformanceClass(conformance.conformsTo, "cql2/1.0", language));
+    if (filter.kind === "native") {
+        const language = filter.dialect;
+        if (language !== "cql2-json" && language !== "cql2-text") {
+            semanticUnsupported("unsupported-native-filter", "$.filter.dialect", `unsupported native dialect ${language}`);
+        }
+        if (!advertised.includes(language)) {
+            semanticUnsupported("unsupported-native-filter", "$.filter.dialect", `native ${language} requires matching discovered conformance`);
+        }
+        return language;
+    }
+    if (preferred !== undefined && preferred !== "cql2-json" && preferred !== "cql2-text") {
+        throw new HonuaQueryPlanningError("invalid-query", "options.preferredFilterLanguage is invalid");
+    }
+    if (preferred !== undefined) {
+        if (!advertised.includes(preferred)) {
+            semanticUnsupported("unsupported-source", "options.preferredFilterLanguage", `${preferred} was not present in discovered conformance`);
+        }
+        return preferred;
+    }
+    const selected = advertised[0];
+    if (!selected) {
+        semanticUnsupported("unsupported-source", "options.conformance.conformsTo", "OGC filtering requires explicitly discovered cql2-json or cql2-text conformance");
+    }
+    return selected;
+}
+function compileCql2Filter(filter, state, path) {
+    if (filter.kind === "native") {
+        state.usesNativeFilter = true;
+        if (filter.dialect !== state.language) {
+            semanticUnsupported("unsupported-native-filter", `${path}.dialect`, `native ${filter.dialect} cannot compile as ${state.language}`);
+        }
+        return filter.payload.format === "json" ? canonicalStringify(filter.payload.value) : filter.payload.text;
+    }
+    if (state.language === "cql2-json") {
+        return canonicalStringify(compileCql2JsonNode(filter, state, path));
+    }
+    return compileCql2TextNode(filter, state, path);
+}
+function compileCql2JsonNode(filter, state, path) {
+    switch (filter.kind) {
+        case "comparison": {
+            const field = compilerField(state.schema, filter.left.name, `${path}.left.name`);
+            return {
+                op: COMPARISON_TEXT[filter.operator],
+                args: [
+                    { property: cql2FieldName(state.schema, filter.left.name, `${path}.left.name`) },
+                    cql2JsonLiteral(filter.right.value, field, `${path}.right.value`),
+                ],
+            };
+        }
+        case "boolean":
+            if (filter.args.length === 1) {
+                return compileCql2JsonNode(filter.args[0], state, `${path}.args[0]`);
+            }
+            return {
+                op: filter.operator,
+                args: filter.args.map((entry, index) => compileCql2JsonNode(entry, state, `${path}.args[${index}]`)),
+            };
+        case "not":
+            return { op: "not", args: [compileCql2JsonNode(filter.arg, state, `${path}.arg`)] };
+        case "null": {
+            const node = {
+                op: "isNull",
+                args: [{ property: cql2FieldName(state.schema, filter.operand.name, `${path}.operand.name`) }],
+            };
+            return filter.operator === "is-null" ? node : { op: "not", args: [node] };
+        }
+        case "list": {
+            requireCqlConformance(state.conformance, "cql2/1.0", "advanced-comparison-operators", path);
+            const field = compilerField(state.schema, filter.operand.name, `${path}.operand.name`);
+            return {
+                op: "in",
+                args: [
+                    { property: cql2FieldName(state.schema, filter.operand.name, `${path}.operand.name`) },
+                    filter.values.map((entry, index) => cql2JsonLiteral(entry.value, field, `${path}.values[${index}].value`)),
+                ],
+            };
+        }
+        case "range": {
+            requireCqlConformance(state.conformance, "cql2/1.0", "advanced-comparison-operators", path);
+            const field = compilerField(state.schema, filter.operand.name, `${path}.operand.name`);
+            return {
+                op: "between",
+                args: [
+                    { property: cql2FieldName(state.schema, filter.operand.name, `${path}.operand.name`) },
+                    cql2JsonLiteral(filter.lower.value, field, `${path}.lower.value`),
+                    cql2JsonLiteral(filter.upper.value, field, `${path}.upper.value`),
+                ],
+            };
+        }
+        case "pattern": {
+            requireCqlConformance(state.conformance, "cql2/1.0", "advanced-comparison-operators", path);
+            const property = {
+                property: cql2FieldName(state.schema, filter.operand.name, `${path}.operand.name`),
+            };
+            if (filter.caseSensitive === false) {
+                requireCqlConformance(state.conformance, "cql2/1.0", "case-insensitive-comparison", path);
+                return {
+                    op: "like",
+                    args: [
+                        { op: "casei", args: [property] },
+                        { op: "casei", args: [filter.pattern] },
+                    ],
+                };
+            }
+            return { op: "like", args: [property, filter.pattern] };
+        }
+        case "spatial":
+            return compileCql2JsonSpatial(filter, state, path);
+        case "temporal":
+            rejectCql2During(filter.operator, path);
+            requireCqlConformance(state.conformance, "cql2/1.0", "temporal-functions", path);
+            return {
+                op: TEMPORAL_JSON[filter.operator],
+                args: [
+                    { property: cql2FieldName(state.schema, filter.operand.name, `${path}.operand.name`) },
+                    cql2JsonTemporal(filter.value, `${path}.value`),
+                ],
+            };
+    }
+}
+function compileCql2TextNode(filter, state, path) {
+    switch (filter.kind) {
+        case "comparison": {
+            const field = compilerField(state.schema, filter.left.name, `${path}.left.name`);
+            const property = cql2TextProperty(state.schema, filter.left.name, `${path}.left.name`);
+            return `${property} ${COMPARISON_TEXT[filter.operator]} ${cql2TextLiteral(filter.right.value, field, `${path}.right.value`)}`;
+        }
+        case "boolean":
+            if (filter.args.length === 1) {
+                return compileCql2TextNode(filter.args[0], state, `${path}.args[0]`);
+            }
+            return `(${filter.args
+                .map((entry, index) => compileCql2TextNode(entry, state, `${path}.args[${index}]`))
+                .join(` ${filter.operator.toUpperCase()} `)})`;
+        case "not":
+            return `NOT (${compileCql2TextNode(filter.arg, state, `${path}.arg`)})`;
+        case "null": {
+            const property = cql2TextProperty(state.schema, filter.operand.name, `${path}.operand.name`);
+            return `${property} IS ${filter.operator === "is-not-null" ? "NOT " : ""}NULL`;
+        }
+        case "list": {
+            requireCqlConformance(state.conformance, "cql2/1.0", "advanced-comparison-operators", path);
+            const field = compilerField(state.schema, filter.operand.name, `${path}.operand.name`);
+            const values = filter.values
+                .map((entry, index) => cql2TextLiteral(entry.value, field, `${path}.values[${index}].value`))
+                .join(", ");
+            return `${cql2TextProperty(state.schema, filter.operand.name, `${path}.operand.name`)} IN (${values})`;
+        }
+        case "range": {
+            requireCqlConformance(state.conformance, "cql2/1.0", "advanced-comparison-operators", path);
+            const field = compilerField(state.schema, filter.operand.name, `${path}.operand.name`);
+            return `${cql2TextProperty(state.schema, filter.operand.name, `${path}.operand.name`)} BETWEEN ${cql2TextLiteral(filter.lower.value, field, `${path}.lower.value`)} AND ${cql2TextLiteral(filter.upper.value, field, `${path}.upper.value`)}`;
+        }
+        case "pattern": {
+            requireCqlConformance(state.conformance, "cql2/1.0", "advanced-comparison-operators", path);
+            const property = cql2TextProperty(state.schema, filter.operand.name, `${path}.operand.name`);
+            const pattern = cql2StringLiteral(filter.pattern, `${path}.pattern`);
+            if (filter.caseSensitive === false) {
+                requireCqlConformance(state.conformance, "cql2/1.0", "case-insensitive-comparison", path);
+                return `CASEI(${property}) LIKE CASEI(${pattern})`;
+            }
+            return `${property} LIKE ${pattern}`;
+        }
+        case "spatial":
+            return compileCql2TextSpatial(filter, state, path);
+        case "temporal":
+            rejectCql2During(filter.operator, path);
+            requireCqlConformance(state.conformance, "cql2/1.0", "temporal-functions", path);
+            return `${TEMPORAL_TEXT[filter.operator]}(${cql2TextProperty(state.schema, filter.operand.name, `${path}.operand.name`)}, ${cql2TextTemporal(filter.value, `${path}.value`)})`;
+    }
+}
+function compileCql2JsonSpatial(filter, state, path) {
+    const property = {
+        property: cql2FieldName(state.schema, spatialProperty(filter, state.schema, path), `${path}.property.name`),
+    };
+    if (filter.operator === "within-distance" || filter.operator === "beyond-distance") {
+        semanticUnsupported("unsupported-distance", `${path}.operator`, "distance predicates are outside CQL2 1.0");
+    }
+    if (filter.operator === "bbox-intersects") {
+        requireCqlConformance(state.conformance, "cql2/1.0", "basic-spatial-functions", path);
+        state.filterCrs = sharedFilterCrs(state.filterCrs, filter.bbox.crs, path);
+        return { op: "s_intersects", args: [property, { bbox: bboxInDefinitionOrder(filter.bbox, `${path}.bbox`) }] };
+    }
+    requireCqlSpatialClass(state.conformance, filter.operator, filter.geometry.geometry.type, path);
+    state.filterCrs = sharedFilterCrs(state.filterCrs, filter.geometry.crs, path);
+    if (filter.geometry.layout !== "xy" && filter.geometry.layout !== "xyz") {
+        semanticUnsupported("unsupported-geometry", `${path}.geometry.layout`, "CQL2 JSON cannot preserve measured coordinate layouts");
+    }
+    const geometry = geometryInDefinitionOrder(filter.geometry, `${path}.geometry`);
+    assertCql2JsonGeometry(geometry, `${path}.geometry.geometry`);
+    return { op: SPATIAL_JSON[filter.operator], args: [property, toJsonValue(geometry)] };
+}
+function compileCql2TextSpatial(filter, state, path) {
+    const property = cql2TextProperty(state.schema, spatialProperty(filter, state.schema, path), `${path}.property.name`);
+    if (filter.operator === "within-distance" || filter.operator === "beyond-distance") {
+        semanticUnsupported("unsupported-distance", `${path}.operator`, "distance predicates are outside CQL2 1.0");
+    }
+    if (filter.operator === "bbox-intersects") {
+        requireCqlConformance(state.conformance, "cql2/1.0", "basic-spatial-functions", path);
+        state.filterCrs = sharedFilterCrs(state.filterCrs, filter.bbox.crs, path);
+        const bounds = bboxInDefinitionOrder(filter.bbox, `${path}.bbox`)
+            .map((entry, index) => ogcNumber(entry, `${path}.bbox.box.bounds[${index}]`))
+            .join(", ");
+        return `S_INTERSECTS(${property}, BBOX(${bounds}))`;
+    }
+    requireCqlSpatialClass(state.conformance, filter.operator, filter.geometry.geometry.type, path);
+    state.filterCrs = sharedFilterCrs(state.filterCrs, filter.geometry.crs, path);
+    if (filter.geometry.layout !== "xy" && filter.geometry.layout !== "xyz") {
+        semanticUnsupported("unsupported-geometry", `${path}.geometry.layout`, "CQL2 text cannot preserve measured coordinate layouts");
+    }
+    const geometry = geometryInDefinitionOrder(filter.geometry, `${path}.geometry`);
+    return `${SPATIAL_TEXT[filter.operator]}(${property}, ${geometryToWkt(geometry, filter.geometry.layout, `${path}.geometry.geometry`)})`;
+}
+function cql2JsonLiteral(value, field, path) {
+    requireCql2ScalarField(field, path);
+    if (field.type.kind === "date") {
+        if (typeof value !== "string" || !CQL2_DATE.test(value)) {
+            semanticUnsupported("unsupported-field-type", path, "CQL2 date comparisons require a full-date string");
+        }
+        return { date: value };
+    }
+    if (field.type.kind === "timestamp") {
+        if (typeof value !== "string" || !CQL2_TIMESTAMP.test(value)) {
+            semanticUnsupported("unsupported-field-type", path, "CQL2 timestamp comparisons require a UTC Z instant");
+        }
+        return { timestamp: value };
+    }
+    if ((field.type.kind === "integer" || field.type.kind === "decimal") && field.type.jsonEncoding === "string") {
+        semanticUnsupported("unsupported-field-type", path, "CQL2 JSON cannot preserve string-encoded numeric precision; use discovered cql2-text");
+    }
+    if (value === null || Array.isArray(value) || typeof value === "object") {
+        semanticUnsupported("unsupported-field-type", path, "CQL2 scalar literals must be string, number, or boolean");
+    }
+    return value;
+}
+function cql2TextLiteral(value, field, path) {
+    requireCql2ScalarField(field, path);
+    if (field.type.kind === "date") {
+        if (typeof value !== "string" || !CQL2_DATE.test(value)) {
+            semanticUnsupported("unsupported-field-type", path, "CQL2 date comparisons require a full-date string");
+        }
+        return `DATE(${cql2StringLiteral(value, path)})`;
+    }
+    if (field.type.kind === "timestamp") {
+        if (typeof value !== "string" || !CQL2_TIMESTAMP.test(value)) {
+            semanticUnsupported("unsupported-field-type", path, "CQL2 timestamp comparisons require a UTC Z instant");
+        }
+        return `TIMESTAMP(${cql2StringLiteral(value, path)})`;
+    }
+    if ((field.type.kind === "integer" || field.type.kind === "decimal") && field.type.jsonEncoding === "string") {
+        if (typeof value !== "string" || !EXACT_NUMERIC_TEXT.test(value)) {
+            semanticUnsupported("unsupported-field-type", path, "CQL2 numeric text is not an exact decimal token");
+        }
+        return value;
+    }
+    if (typeof value === "string")
+        return cql2StringLiteral(value, path);
+    if (typeof value === "number")
+        return ogcNumber(value, path);
+    if (typeof value === "boolean")
+        return value ? "TRUE" : "FALSE";
+    semanticUnsupported("unsupported-field-type", path, "CQL2 scalar literals must be string, number, or boolean");
+}
+function requireCql2ScalarField(field, path) {
+    switch (field.type.kind) {
+        case "boolean":
+        case "integer":
+        case "float":
+        case "decimal":
+        case "string":
+        case "uuid":
+        case "date":
+        case "timestamp":
+            return;
+        default:
+            semanticUnsupported("unsupported-field-type", path, `CQL2 has no exact scalar representation for logical field type ${field.type.kind}`);
+    }
+}
+function cql2JsonTemporal(value, path) {
+    if (value.valueType === "date") {
+        requireCql2Date(value.value, `${path}.value`);
+        return { date: value.value };
+    }
+    if (value.valueType === "instant") {
+        requireCql2Timestamp(value.value, `${path}.value`);
+        return { timestamp: value.value };
+    }
+    const interval = value;
+    interval.value.forEach((endpoint, index) => requireCql2IntervalEndpoint(endpoint, `${path}.value[${index}]`));
+    return { interval: [...interval.value] };
+}
+function cql2TextTemporal(value, path) {
+    if (value.valueType === "date") {
+        requireCql2Date(value.value, `${path}.value`);
+        return `DATE(${cql2StringLiteral(value.value, `${path}.value`)})`;
+    }
+    if (value.valueType === "instant") {
+        requireCql2Timestamp(value.value, `${path}.value`);
+        return `TIMESTAMP(${cql2StringLiteral(value.value, `${path}.value`)})`;
+    }
+    const interval = value;
+    interval.value.forEach((endpoint, index) => requireCql2IntervalEndpoint(endpoint, `${path}.value[${index}]`));
+    return `INTERVAL(${cql2StringLiteral(interval.value[0], `${path}.value[0]`)}, ${cql2StringLiteral(interval.value[1], `${path}.value[1]`)})`;
+}
+function rejectCql2During(operator, path) {
+    if (operator === "during") {
+        semanticUnsupported("unsupported-node", `${path}.operator`, "CQL2 T_DURING requires an interval-valued first operand; semantic temporal properties are instant-valued");
+    }
+}
+function requireCql2Date(value, path) {
+    if (!CQL2_DATE.test(value)) {
+        semanticUnsupported("unsupported-field-type", path, "CQL2 temporal dates require a full-date literal");
+    }
+}
+function requireCql2Timestamp(value, path) {
+    if (!CQL2_TIMESTAMP.test(value)) {
+        semanticUnsupported("unsupported-field-type", path, "CQL2 temporal timestamps require a UTC Z instant");
+    }
+}
+function requireCql2IntervalEndpoint(value, path) {
+    if (!CQL2_DATE.test(value) && !CQL2_TIMESTAMP.test(value)) {
+        semanticUnsupported("unsupported-field-type", path, "CQL2 temporal interval endpoints require a full-date or UTC Z timestamp");
+    }
+}
+function cql2TextProperty(schema, name, path) {
+    return cql2Identifier(cql2FieldName(schema, name, path), path);
+}
+function spatialProperty(filter, schema, path) {
+    if (filter.property)
+        return filter.property.name;
+    if (schema.geometry.state === "known" && schema.geometry.primaryField.state === "known") {
+        return schema.geometry.primaryField.field;
+    }
+    semanticUnsupported("unsupported-source", `${path}.property`, "implicit spatial property requires a known primary geometry field");
+}
+function requireCqlSpatialClass(conformance, operator, geometryType, path) {
+    if (operator !== "intersects") {
+        requireCqlConformance(conformance, "cql2/1.0", "spatial-functions", path);
+        return;
+    }
+    requireCqlConformance(conformance, "cql2/1.0", geometryType === "Point" ? "basic-spatial-functions" : "basic-spatial-functions-plus", path);
+}
+function requireCqlConformance(conformance, standard, name, path) {
+    if (!hasConformanceClass(conformance.conformsTo, standard, name)) {
+        semanticUnsupported("unsupported-node", path, `${name} was not present in explicit discovered conformance`);
+    }
+}
+function compiledOgcFilterCrs(binding, conformance, path) {
+    const dimensions = binding.coordinateOrder.axes.length >= 3 ? 3 : 2;
+    const plan = ogcAxisPlan(binding, dimensions, `${path}.crs`);
+    if (isDefaultFilterCrs(plan.srsName, dimensions))
+        return undefined;
+    requireOgcPart2Crs(conformance, `${path}.crs`);
+    if (!conformance.supportedFilterCrs.includes(plan.srsName)) {
+        semanticUnsupported("unsupported-crs", `${path}.crs`, `filter CRS ${plan.srsName} was not present in discovered source metadata`);
+    }
+    return plan.srsName;
+}
+function compiledOgcOutputCrs(definition, conformance, path) {
+    const uri = ogcCrsUri(definition, path);
+    if (isDefaultOutputCrs(uri))
+        return undefined;
+    requireOgcPart2Crs(conformance, path);
+    if (!conformance.supportedOutputCrs.includes(uri)) {
+        semanticUnsupported("unsupported-crs", path, `output CRS ${uri} was not present in discovered source metadata`);
+    }
+    return uri;
+}
+function requireOgcPart2Crs(conformance, path) {
+    if (!hasConformanceClass(conformance.conformsTo, "ogcapi-features-2/1.0", "crs")) {
+        semanticUnsupported("unsupported-crs", path, "OGC API Features CRS parameters require explicitly discovered Part 2 CRS conformance");
+    }
+}
+function validateOgcSemanticProjection(query, schema) {
+    if (query.kind === "aggregate") {
+        semanticUnsupported("unsupported-node", "$.kind", "OGC API Features has no portable remote aggregation");
+    }
+    if (query.geometry === "omit") {
+        semanticUnsupported("unsupported-projection", "$.geometry", "OGC API Features has no portable geometry-suppression request parameter");
+    }
+    if (query.geometry && typeof query.geometry === "object") {
+        const primary = schema.geometry.state === "known" && schema.geometry.primaryField.state === "known"
+            ? schema.geometry.primaryField.field
+            : undefined;
+        if (query.geometry.field !== primary) {
+            semanticUnsupported("unsupported-projection", "$.geometry.field", "OGC API Features can return only the source primary GeoJSON geometry");
+        }
+    }
+    if (query.select && query.select.length > 0) {
+        semanticUnsupported("unsupported-projection", "$.select", "OGC API Features Core does not define a portable properties projection parameter");
+    }
+}
+function rejectOgcSemanticSort(query) {
+    if (query.sort && query.sort.length > 0) {
+        semanticUnsupported("unsupported-sort", "$.sort", "OGC API Features Core does not define a portable sortby parameter");
+    }
+}
+function assertCql2JsonGeometry(value, path) {
+    if (value.type !== "GeometryCollection")
+        return;
+    if (value.geometries.length < 2) {
+        semanticUnsupported("unsupported-geometry", `${path}.geometries`, "CQL2 JSON GeometryCollection requires at least two members");
+    }
+    value.geometries.forEach((entry, index) => {
+        if (entry.type === "GeometryCollection") {
+            semanticUnsupported("unsupported-geometry", `${path}.geometries[${index}]`, "CQL2 JSON 1.0 does not permit nested GeometryCollection members");
+        }
+    });
+}
+function isDefaultFilterCrs(uri, dimensions) {
+    return dimensions === 3
+        ? uri === "http://www.opengis.net/def/crs/OGC/0/CRS84h"
+        : uri === "http://www.opengis.net/def/crs/OGC/1.3/CRS84";
+}
+function isDefaultOutputCrs(uri) {
+    return (uri === "http://www.opengis.net/def/crs/OGC/1.3/CRS84" || uri === "http://www.opengis.net/def/crs/OGC/0/CRS84h");
+}
+function hasControl(value) {
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: source identifiers cannot contain controls
+    return /[\u0000-\u001f\u007f]/.test(value);
+}
+function compileBbox(spatialFilter, sourceId) {
+    if (spatialFilter.geometryType !== "esriGeometryEnvelope") {
+        throw new HonuaQueryPlanningError("unsupported-query", `Source "${sourceId}" cannot compile spatial geometry "${spatialFilter.geometryType}" to OGC bbox`);
+    }
+    if (spatialFilter.spatialRel !== undefined &&
+        spatialFilter.spatialRel !== "esriSpatialRelIntersects" &&
+        spatialFilter.spatialRel !== "esriSpatialRelEnvelopeIntersects") {
+        throw new HonuaQueryPlanningError("unsupported-query", `Source "${sourceId}" cannot weaken spatial relationship "${spatialFilter.spatialRel}" to OGC envelope-intersects`);
+    }
+    const geometry = spatialFilter.geometry;
+    assertDefaultBboxCrs(geometry.spatialReference, sourceId);
+    const coordinates = [geometry.xmin, geometry.ymin, geometry.xmax, geometry.ymax];
+    if (!coordinates.every((value) => typeof value === "number" && Number.isFinite(value))) {
+        throw new HonuaQueryPlanningError("invalid-query", `Source "${sourceId}" requires finite xmin, ymin, xmax, and ymax values for OGC bbox`);
+    }
+    const [xmin, ymin, xmax, ymax] = coordinates;
+    if (xmin > xmax || ymin > ymax) {
+        throw new HonuaQueryPlanningError("invalid-query", `Source "${sourceId}" requires an ordered OGC bbox where xmin <= xmax and ymin <= ymax`);
+    }
+    return `${xmin},${ymin},${xmax},${ymax}`;
+}
+function assertDefaultBboxCrs(spatialReference, sourceId) {
+    if (spatialReference === undefined)
+        return;
+    if (spatialReference === null || Array.isArray(spatialReference) || typeof spatialReference !== "object") {
+        throw unsupportedBboxCrs(sourceId);
+    }
+    const reference = spatialReference;
+    const declaredWkids = [reference.wkid, reference.latestWkid].filter((value) => value !== undefined);
+    if (declaredWkids.length > 0 && declaredWkids.every((value) => value === 4326) && reference.wkt === undefined) {
+        return;
+    }
+    throw unsupportedBboxCrs(sourceId);
+}
+function unsupportedBboxCrs(sourceId) {
+    return new HonuaQueryPlanningError("unsupported-query", `Source "${sourceId}" can only compile an unstamped or EPSG:4326 envelope to the default OGC bbox CRS`);
+}

package/query-planner/planner.d.ts

@@ -0,0 +1,17 @@
+import { type ExplainGeoParquetQueryOptions, type ExplainQueryOptions, type QueryExecutionPlan, type QueryExecutionPlanV1, type QueryExecutionPlanV2 } from "./types.js";
+export declare function explainQuery<T>(options: ExplainGeoParquetQueryOptions<T>): QueryExecutionPlanV2;
+export declare function explainQuery<T>(options: ExplainQueryOptions<T>): QueryExecutionPlanV1;
+export declare function hashQueryPlan(plan: QueryExecutionPlan): `sha256:${string}`;
+/** @internal Lightweight v1 integrity path for stable consumers that cannot execute v2 resources. */
+export declare function hashQueryPlanV1(plan: QueryExecutionPlanV1): `sha256:${string}` | undefined;
+/** Internal executor boundary: validate once and continue with an immutable detached snapshot. */
+export declare function validateQueryPlanSnapshot(plan: QueryExecutionPlan): QueryExecutionPlan;
+/** Canonical persistence boundary; validated legacy protocol artifacts are upgraded before serialization. */
+export declare function serializeQueryPlan(plan: QueryExecutionPlan): string;
+/** Parse a persisted plan, upgrading validated legacy protocol artifacts without retaining unsafe input. */
+export declare function parseQueryPlan(serialized: string): QueryExecutionPlan;
+/** Stable cache identity derived only after the plan passes the persistence guard. */
+export declare function queryPlanCacheKey(plan: QueryExecutionPlan): string;
+/** Explicitly migrate a credential-free v1 GeoParquet plan to opaque v2 identity. */
+export declare function migrateGeoParquetQueryPlanV1(legacyPlan: QueryExecutionPlanV1, resourceValue: unknown): QueryExecutionPlanV2;
+//# sourceMappingURL=planner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"planner.d.ts","sourceRoot":"","sources":["../../../src/query-planner/planner.ts"],"names":[],"mappings":"AAyBA,OAAO,EAIL,KAAK,6BAA6B,EAClC,KAAK,mBAAmB,EASxB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EAO1B,MAAM,YAAY,CAAC;AAGpB,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,6BAA6B,CAAC,CAAC,CAAC,GAAG,oBAAoB,CAAC;AACjG,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,oBAAoB,CAAC;AAwNvF,wBAAgB,aAAa,CAAC,IAAI,EAAE,kBAAkB,GAAG,UAAU,MAAM,EAAE,CAE1E;AAED,qGAAqG;AACrG,wBAAgB,eAAe,CAAC,IAAI,EAAE,oBAAoB,GAAG,UAAU,MAAM,EAAE,GAAG,SAAS,CAkB1F;AAED,kGAAkG;AAClG,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,kBAAkB,GAAG,kBAAkB,CAItF;AAED,6GAA6G;AAC7G,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAInE;AAED,4GAA4G;AAC5G,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB,CAWrE;AAED,sFAAsF;AACtF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAIlE;AAED,qFAAqF;AACrF,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,oBAAoB,EAChC,aAAa,EAAE,OAAO,GACrB,oBAAoB,CAkCtB"}