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

package/contract/query-filter.js

@@ -0,0 +1,883 @@
+/**
+ * Canonical typed query filter — the protocol-neutral semantic filter AST that
+ * `Source.query()` accepts on the stable surface, plus the per-protocol
+ * compilers that lower it onto each wire dialect.
+ *
+ * The AST mirrors the experimental `/query-planner` semantic filter (comparison,
+ * list, range, null, pattern, spatial, temporal, boolean composition) with two
+ * deliberate contract-layer differences:
+ *
+ * - Spatial predicates carry the same canonical geometry value the rest of the
+ *   contract uses (`SpatialFilter`-shaped `geometry` + `geometryType`, produced
+ *   by `envelope()` / `point()` / `polygon()`), so a filter composes with
+ *   `Query.spatialFilter` without a second geometry vocabulary.
+ * - Compilation is schema-free. The planner's semantic compilers verify a
+ *   `SourceSchemaV2` before emitting; the canonical surface has no verified
+ *   schema at query time, so literals are typed by the value the caller wrote.
+ *
+ * Every compiler in this module fails closed: a construct the target protocol
+ * cannot express exactly throws `HonuaCapabilityNotSupportedError` naming the
+ * construct and the protocol. Nothing is silently dropped and nothing is
+ * silently widened; a widening that is genuinely safe (the GeoParquet bbox
+ * reduction) is reported through `Result.degraded` by its adapter.
+ *
+ * @module
+ */
+import { HonuaCapabilityNotSupportedError } from "../core/errors.js";
+// ── Builders ──────────────────────────────────────────────────
+function property(name) {
+    return { kind: "property", name };
+}
+function literal(value) {
+    return { kind: "literal", value };
+}
+/**
+ * Ergonomic constructors for {@link QueryFilterExpression}. Every helper returns
+ * plain data, so a filter can equally be written as an object literal, stored as
+ * JSON, or produced by the experimental semantic builder.
+ *
+ * @example
+ * ```ts
+ * import { envelope, queryFilter } from "@honua/sdk-js";
+ *
+ * const filter = queryFilter.and(
+ *   queryFilter.eq("STATUS", "open"),
+ *   queryFilter.gt("SEVERITY", 3),
+ *   queryFilter.spatial("intersects", envelope(-158.5, 21.2, -157.6, 21.7)),
+ * );
+ * ```
+ */
+export const queryFilter = /* @__PURE__ */ Object.freeze({
+    eq: (field, value) => ({
+        kind: "comparison",
+        operator: "eq",
+        left: property(field),
+        right: literal(value),
+    }),
+    ne: (field, value) => ({
+        kind: "comparison",
+        operator: "ne",
+        left: property(field),
+        right: literal(value),
+    }),
+    lt: (field, value) => ({
+        kind: "comparison",
+        operator: "lt",
+        left: property(field),
+        right: literal(value),
+    }),
+    lte: (field, value) => ({
+        kind: "comparison",
+        operator: "lte",
+        left: property(field),
+        right: literal(value),
+    }),
+    gt: (field, value) => ({
+        kind: "comparison",
+        operator: "gt",
+        left: property(field),
+        right: literal(value),
+    }),
+    gte: (field, value) => ({
+        kind: "comparison",
+        operator: "gte",
+        left: property(field),
+        right: literal(value),
+    }),
+    isIn: (field, values) => ({
+        kind: "list",
+        operator: "in",
+        operand: property(field),
+        values: values.map(literal),
+    }),
+    between: (field, lower, upper) => ({
+        kind: "range",
+        operator: "between",
+        operand: property(field),
+        lower: literal(lower),
+        upper: literal(upper),
+    }),
+    isNull: (field) => ({ kind: "null", operator: "is-null", operand: property(field) }),
+    isNotNull: (field) => ({
+        kind: "null",
+        operator: "is-not-null",
+        operand: property(field),
+    }),
+    like: (field, pattern, options = {}) => ({
+        kind: "pattern",
+        operator: "like",
+        operand: property(field),
+        pattern,
+        ...(options.caseSensitive !== undefined ? { caseSensitive: options.caseSensitive } : {}),
+    }),
+    spatial: (operator, geometry, options = {}) => ({
+        kind: "spatial",
+        operator,
+        geometry: { geometry: geometry.geometry, geometryType: geometry.geometryType },
+        ...(options.property !== undefined ? { property: options.property } : {}),
+    }),
+    before: (field, instant) => ({
+        kind: "temporal",
+        operator: "before",
+        operand: property(field),
+        value: { kind: "temporal-literal", valueType: "instant", value: instant },
+    }),
+    after: (field, instant) => ({
+        kind: "temporal",
+        operator: "after",
+        operand: property(field),
+        value: { kind: "temporal-literal", valueType: "instant", value: instant },
+    }),
+    during: (field, start, end) => ({
+        kind: "temporal",
+        operator: "during",
+        operand: property(field),
+        value: { kind: "temporal-literal", valueType: "interval", value: [start, end] },
+    }),
+    timeIntersects: (field, start, end) => ({
+        kind: "temporal",
+        operator: "time-intersects",
+        operand: property(field),
+        value: { kind: "temporal-literal", valueType: "interval", value: [start, end] },
+    }),
+    and: (...args) => ({
+        kind: "boolean",
+        operator: "and",
+        args,
+    }),
+    or: (...args) => ({
+        kind: "boolean",
+        operator: "or",
+        args,
+    }),
+    not: (arg) => ({ kind: "not", arg }),
+});
+// ── Validation ────────────────────────────────────────────────
+/** Structural bounds mirroring the semantic planner's parser limits. */
+export const MAX_QUERY_FILTER_DEPTH = 32;
+export const MAX_QUERY_FILTER_NODES = 512;
+const IDENTIFIER_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const QUALIFIED_IDENTIFIER_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*(?:[.:][A-Za-z_][A-Za-z0-9_]*)*$/;
+const RFC3339_PATTERN = /^\d{4}-\d{2}-\d{2}(?:[Tt ]\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:[Zz]|[+-]\d{2}:\d{2})?)?$/;
+/** Fail closed, naming the construct and the protocol that cannot express it. */
+export function refuseQueryFilterConstruct(construct, ctx) {
+    throw new HonuaCapabilityNotSupportedError(construct, ctx.protocol, ctx.sourceId, {
+        context: { construct, filter: true },
+    });
+}
+/**
+ * Fail closed because this source's evaluated capability evidence excludes the
+ * operator, even though its protocol can express it. The refusal names the same
+ * construct as a protocol refusal so callers branch on one vocabulary, and
+ * stamps `constraint: "capability-profile"` so the two causes stay
+ * distinguishable without parsing messages.
+ */
+function refuseUnsupportedOperator(construct, ctx) {
+    throw new HonuaCapabilityNotSupportedError(construct, ctx.protocol, ctx.sourceId, {
+        context: { construct, filter: true, constraint: ctx.constraintSource ?? "capability-profile" },
+    });
+}
+/** Gate one operator against the source's evaluated allow list. */
+function assertOperatorAllowed(operator, construct, ctx) {
+    if (ctx.supportedFilterOperators && !ctx.supportedFilterOperators.includes(operator)) {
+        refuseUnsupportedOperator(construct, ctx);
+    }
+}
+const QUERY_FILTER_OPERATORS = new Set([
+    "eq",
+    "ne",
+    "lt",
+    "lte",
+    "gt",
+    "gte",
+    "in",
+    "between",
+    "is-null",
+    "is-not-null",
+    "like",
+    "and",
+    "or",
+    "not",
+    "intersects",
+    "contains",
+    "within",
+    "crosses",
+    "touches",
+    "overlaps",
+    "bbox-intersects",
+    "before",
+    "after",
+    "during",
+    "time-intersects",
+]);
+const QUERY_FILTER_SPATIAL_PREDICATES = new Set([
+    "intersects",
+    "contains",
+    "within",
+    "crosses",
+    "touches",
+    "overlaps",
+    "bbox-intersects",
+]);
+const QUERY_FILTER_TEMPORAL_PREDICATES = new Set([
+    "before",
+    "after",
+    "during",
+    "time-intersects",
+]);
+/**
+ * Narrow the evaluated `CapabilityConstraints` of one capability into the
+ * allow lists this compiler understands.
+ *
+ * Vocabularies that the canonical AST cannot name (distance predicates,
+ * extension identifiers) are dropped rather than translated, which fails closed
+ * by construction: a profile that advertises only constructs outside the AST
+ * yields an empty allow list, and every node of that kind is refused. Omitted
+ * constraint arrays stay `undefined` — "the evidence says nothing", not "the
+ * source supports nothing".
+ */
+export function queryFilterConstraints(constraints) {
+    const operators = constraints.filterOperators?.filter((value) => QUERY_FILTER_OPERATORS.has(value));
+    const spatial = constraints.spatialPredicates?.filter((value) => QUERY_FILTER_SPATIAL_PREDICATES.has(value));
+    const temporal = constraints.temporalPredicates?.filter((value) => QUERY_FILTER_TEMPORAL_PREDICATES.has(value));
+    return {
+        ...(operators ? { supportedFilterOperators: operators } : {}),
+        ...(spatial ? { supportedSpatialPredicates: spatial } : {}),
+        ...(temporal ? { supportedTemporalPredicates: temporal } : {}),
+    };
+}
+/**
+ * Validate a caller-supplied filter before any dialect sees it. Rejects
+ * malformed nodes, unbounded nesting, and identifiers that are not plain
+ * source field names (the only identifiers every dialect can quote safely).
+ */
+export function assertQueryFilter(filter, ctx) {
+    let nodes = 0;
+    const visit = (node, depth) => {
+        nodes += 1;
+        if (depth > MAX_QUERY_FILTER_DEPTH)
+            refuseQueryFilterConstruct("filter.depth", ctx);
+        if (nodes > MAX_QUERY_FILTER_NODES)
+            refuseQueryFilterConstruct("filter.size", ctx);
+        if (!node || typeof node !== "object")
+            refuseQueryFilterConstruct("filter.node", ctx);
+        switch (node.kind) {
+            case "comparison":
+                assertFieldName(node.left?.name, ctx);
+                assertScalar(node.right, ctx);
+                assertOperatorAllowed(node.operator, `filter.comparison.${node.operator}`, ctx);
+                return;
+            case "list":
+                assertFieldName(node.operand?.name, ctx);
+                if (!Array.isArray(node.values) || node.values.length === 0)
+                    refuseQueryFilterConstruct("filter.list.values", ctx);
+                for (const value of node.values)
+                    assertScalar(value, ctx);
+                assertOperatorAllowed("in", "filter.list.in", ctx);
+                return;
+            case "range":
+                assertFieldName(node.operand?.name, ctx);
+                assertScalar(node.lower, ctx);
+                assertScalar(node.upper, ctx);
+                assertOperatorAllowed("between", "filter.range.between", ctx);
+                return;
+            case "null":
+                assertFieldName(node.operand?.name, ctx);
+                assertOperatorAllowed(node.operator, `filter.null.${node.operator}`, ctx);
+                return;
+            case "pattern":
+                assertFieldName(node.operand?.name, ctx);
+                if (typeof node.pattern !== "string" || node.pattern.length === 0)
+                    refuseQueryFilterConstruct("filter.pattern.value", ctx);
+                assertPrintable(node.pattern, "filter.pattern.value", ctx);
+                assertOperatorAllowed("like", "filter.pattern.like", ctx);
+                return;
+            case "spatial":
+                if (node.property !== undefined)
+                    assertFieldName(node.property, ctx, true);
+                if (!node.geometry || typeof node.geometry !== "object" || typeof node.geometry.geometry !== "object") {
+                    refuseQueryFilterConstruct("filter.spatial.geometry", ctx);
+                }
+                if (ctx.supportedSpatialPredicates && !ctx.supportedSpatialPredicates.includes(node.operator)) {
+                    refuseUnsupportedOperator(`filter.spatial.${node.operator}`, ctx);
+                }
+                assertOperatorAllowed(node.operator, `filter.spatial.${node.operator}`, ctx);
+                return;
+            case "temporal":
+                assertFieldName(node.operand?.name, ctx, true);
+                assertTemporalLiteral(node.value, ctx);
+                if (ctx.supportedTemporalPredicates && !ctx.supportedTemporalPredicates.includes(node.operator)) {
+                    refuseUnsupportedOperator(`filter.temporal.${node.operator}`, ctx);
+                }
+                assertOperatorAllowed(node.operator, `filter.temporal.${node.operator}`, ctx);
+                return;
+            case "boolean":
+                if (!Array.isArray(node.args) || node.args.length === 0)
+                    refuseQueryFilterConstruct("filter.boolean.args", ctx);
+                assertOperatorAllowed(node.operator, `filter.boolean.${node.operator}`, ctx);
+                for (const arg of node.args)
+                    visit(arg, depth + 1);
+                return;
+            case "not":
+                assertOperatorAllowed("not", "filter.not", ctx);
+                visit(node.arg, depth + 1);
+                return;
+            default:
+                refuseQueryFilterConstruct("filter.node", ctx);
+        }
+    };
+    visit(filter, 1);
+}
+function assertFieldName(name, ctx, qualified = false) {
+    const pattern = qualified ? QUALIFIED_IDENTIFIER_PATTERN : IDENTIFIER_PATTERN;
+    if (typeof name !== "string" || name.length === 0 || name.length > 128 || !pattern.test(name)) {
+        refuseQueryFilterConstruct("filter.property.name", ctx);
+    }
+}
+function assertScalar(node, ctx) {
+    if (!node || typeof node !== "object" || node.kind !== "literal") {
+        refuseQueryFilterConstruct("filter.literal", ctx);
+    }
+    const value = node.value;
+    if (value === null || typeof value === "boolean")
+        return;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            refuseQueryFilterConstruct("filter.literal.number", ctx);
+        return;
+    }
+    if (typeof value === "string") {
+        assertPrintable(value, "filter.literal.text", ctx);
+        return;
+    }
+    refuseQueryFilterConstruct("filter.literal", ctx);
+}
+function assertPrintable(value, construct, ctx) {
+    if (value.length > 4096)
+        refuseQueryFilterConstruct(construct, ctx);
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code <= 0x1f || code === 0x7f)
+            refuseQueryFilterConstruct(construct, ctx);
+    }
+}
+function assertTemporalLiteral(value, ctx) {
+    const node = value;
+    if (!node || node.kind !== "temporal-literal")
+        refuseQueryFilterConstruct("filter.temporal.literal", ctx);
+    if (node.valueType === "instant") {
+        assertInstant(node.value, ctx);
+        return;
+    }
+    if (node.valueType === "interval") {
+        if (!Array.isArray(node.value) || node.value.length !== 2)
+            refuseQueryFilterConstruct("filter.temporal.interval", ctx);
+        assertInstant(node.value[0], ctx);
+        assertInstant(node.value[1], ctx);
+        return;
+    }
+    refuseQueryFilterConstruct("filter.temporal.literal", ctx);
+}
+function assertInstant(value, ctx) {
+    if (typeof value !== "string" || !RFC3339_PATTERN.test(value))
+        refuseQueryFilterConstruct("filter.temporal.instant", ctx);
+}
+/** Validate `Query.temporalFilter` independently of the filter AST. */
+export function assertTemporalFilter(temporal, ctx) {
+    if (!temporal || typeof temporal !== "object")
+        refuseQueryFilterConstruct("temporalFilter", ctx);
+    if (temporal.field !== undefined)
+        assertFieldName(temporal.field, ctx, true);
+    if (temporal.kind === "instant") {
+        assertInstant(temporal.instant, ctx);
+        return;
+    }
+    if (temporal.kind === "interval") {
+        if (temporal.start === null && temporal.end === null)
+            refuseQueryFilterConstruct("temporalFilter.interval", ctx);
+        if (temporal.start !== null)
+            assertInstant(temporal.start, ctx);
+        if (temporal.end !== null)
+            assertInstant(temporal.end, ctx);
+        return;
+    }
+    refuseQueryFilterConstruct("temporalFilter", ctx);
+}
+/**
+ * Lower a field-bound `Query.temporalFilter` into a filter node so every
+ * dialect compiles temporal intent through the same path. Returns `undefined`
+ * when the filter targets the source's own time dimension (no `field`), which
+ * the protocol time parameter carries instead.
+ */
+export function temporalFilterToExpression(temporal, ctx) {
+    assertTemporalFilter(temporal, ctx);
+    if (temporal.field === undefined)
+        return undefined;
+    const field = temporal.field;
+    if (temporal.kind === "instant") {
+        return {
+            kind: "temporal",
+            operator: "time-intersects",
+            operand: { kind: "property", name: field },
+            value: { kind: "temporal-literal", valueType: "instant", value: temporal.instant },
+        };
+    }
+    if (temporal.start !== null && temporal.end !== null) {
+        return {
+            kind: "temporal",
+            operator: "during",
+            operand: { kind: "property", name: field },
+            value: { kind: "temporal-literal", valueType: "interval", value: [temporal.start, temporal.end] },
+        };
+    }
+    // A half-open canonical interval keeps its closed bound INCLUSIVE, so it
+    // lowers to an ordered comparison rather than the strict `after` / `before`
+    // temporal predicates. `[start, ..)` means "at or after start".
+    if (temporal.start !== null) {
+        return {
+            kind: "comparison",
+            operator: "gte",
+            left: { kind: "property", name: field },
+            right: { kind: "literal", value: temporal.start },
+        };
+    }
+    if (temporal.end !== null) {
+        return {
+            kind: "comparison",
+            operator: "lte",
+            left: { kind: "property", name: field },
+            right: { kind: "literal", value: temporal.end },
+        };
+    }
+    return refuseQueryFilterConstruct("temporalFilter.interval", ctx);
+}
+/** Combine a filter and a lowered temporal predicate into one expression. */
+export function andQueryFilters(...parts) {
+    const present = parts.filter((part) => part !== undefined);
+    if (present.length === 0)
+        return undefined;
+    if (present.length === 1)
+        return present[0];
+    return { kind: "boolean", operator: "and", args: present };
+}
+// ── Shared literal helpers ────────────────────────────────────
+function sqlText(value) {
+    return `'${value.replaceAll("'", "''")}'`;
+}
+function sqlTimestamp(instant) {
+    return `TIMESTAMP ${sqlText(instant)}`;
+}
+function isTemporalLike(value) {
+    return typeof value === "string" && RFC3339_PATTERN.test(value) && value.length >= 10 && value.includes("-");
+}
+/** SQL-92 / DuckDB scalar literal. Temporal-shaped strings become timestamps. */
+function sqlLiteral(node, temporal) {
+    const value = node.value;
+    if (value === null)
+        return "NULL";
+    if (typeof value === "boolean")
+        return value ? "1" : "0";
+    if (typeof value === "number")
+        return String(value);
+    return temporal && isTemporalLike(value) ? sqlTimestamp(value) : sqlText(value);
+}
+const SQL_COMPARISON = {
+    eq: "=",
+    ne: "<>",
+    lt: "<",
+    lte: "<=",
+    gt: ">",
+    gte: ">=",
+};
+const ODATA_COMPARISON = {
+    eq: "eq",
+    ne: "ne",
+    lt: "lt",
+    lte: "le",
+    gt: "gt",
+    gte: "ge",
+};
+/**
+ * Resolve a temporal node into bounds plus their strictness.
+ *
+ * `before` and `after` are *strict*: that is what CQL2 `T_BEFORE` / `T_AFTER`,
+ * FES `Before` / `After`, and the schema-verified planner compilers all mean, so
+ * the canonical lowering agrees with them rather than quietly widening the
+ * window by one instant. `during` and `time-intersects` keep both bounds
+ * inclusive, which is the closed-interval reading the reference evaluator and
+ * the conformance corpus use.
+ */
+function temporalBounds(node, ctx) {
+    const value = node.value;
+    if (value.valueType === "instant") {
+        if (node.operator === "before")
+            return { end: { value: value.value, inclusive: false } };
+        if (node.operator === "after")
+            return { start: { value: value.value, inclusive: false } };
+        return { instant: value.value };
+    }
+    if (node.operator === "before")
+        return { end: { value: value.value[0], inclusive: false } };
+    if (node.operator === "after")
+        return { start: { value: value.value[1], inclusive: false } };
+    if (node.operator === "during" || node.operator === "time-intersects") {
+        return {
+            start: { value: value.value[0], inclusive: true },
+            end: { value: value.value[1], inclusive: true },
+        };
+    }
+    return refuseQueryFilterConstruct(`filter.temporal.${node.operator}`, ctx);
+}
+/** Esri spatial relationships the canonical predicates map onto. @internal */
+export const GEOSERVICES_SPATIAL_REL = {
+    intersects: "esriSpatialRelIntersects",
+    contains: "esriSpatialRelContains",
+    within: "esriSpatialRelWithin",
+    crosses: "esriSpatialRelCrosses",
+    touches: "esriSpatialRelTouches",
+    overlaps: "esriSpatialRelOverlaps",
+    // `bbox-intersects` means "the feature intersects this envelope", which is an
+    // ordinary intersects test against an envelope operand — the same lowering the
+    // schema-verified planner compiler uses. `esriSpatialRelEnvelopeIntersects`
+    // would instead compare the *feature's* envelope and return a superset.
+    "bbox-intersects": "esriSpatialRelIntersects",
+};
+/**
+ * Compile to the GeoServices `where` clause plus (at most one) spatial request
+ * parameter set. GeoServices expresses exactly one geometry per `query`
+ * request, and only conjunctively, so a spatial predicate nested inside `OR` /
+ * `NOT` or a second spatial predicate is refused rather than approximated.
+ */
+export function compileQueryFilterToSql92(filter, ctx) {
+    assertQueryFilter(filter, ctx);
+    const spatial = [];
+    const dialect = sql92Dialect(ctx);
+    const where = splitConjunctiveSpatial(filter, ctx, spatial, (node) => emitSql(node, ctx, dialect));
+    if (spatial.length > 1)
+        refuseQueryFilterConstruct("filter.spatial.multiple", ctx);
+    const node = spatial[0];
+    return {
+        ...(where !== undefined ? { where } : {}),
+        ...(node ? { spatialFilter: geoServicesSpatialFilter(node, ctx) } : {}),
+    };
+}
+function geoServicesSpatialFilter(node, ctx) {
+    const spatialRel = GEOSERVICES_SPATIAL_REL[node.operator];
+    if (!spatialRel)
+        refuseQueryFilterConstruct(`filter.spatial.${node.operator}`, ctx);
+    return {
+        geometry: node.geometry.geometry,
+        geometryType: node.geometry.geometryType,
+        spatialRel,
+    };
+}
+/**
+ * Split a top-level conjunction into "spatial predicates carried out of band"
+ * and "everything else, compiled by `emit`". A spatial node under `OR` / `NOT`
+ * cannot be carried out of band without changing the result set, so it throws.
+ */
+function splitConjunctiveSpatial(filter, ctx, spatial, emit) {
+    if (filter.kind === "spatial") {
+        spatial.push(filter);
+        return undefined;
+    }
+    if (filter.kind === "boolean" && filter.operator === "and") {
+        const parts = [];
+        for (const arg of filter.args) {
+            const compiled = splitConjunctiveSpatial(arg, ctx, spatial, emit);
+            if (compiled !== undefined)
+                parts.push(compiled);
+        }
+        if (parts.length === 0)
+            return undefined;
+        return parts.length === 1 ? parts[0] : parts.map((part) => `(${part})`).join(" AND ");
+    }
+    if (containsSpatial(filter))
+        refuseQueryFilterConstruct("filter.spatial.disjunction", ctx);
+    return emit(filter);
+}
+/** True when a filter references geometry anywhere in its tree. */
+export function queryFilterHasSpatial(filter) {
+    return containsSpatial(filter);
+}
+function containsSpatial(filter) {
+    if (filter.kind === "spatial")
+        return true;
+    if (filter.kind === "boolean")
+        return filter.args.some(containsSpatial);
+    if (filter.kind === "not")
+        return containsSpatial(filter.arg);
+    return false;
+}
+function emitSql(filter, ctx, dialect) {
+    const field = (name) => dialect.identifier(name);
+    switch (filter.kind) {
+        case "comparison": {
+            const left = field(filter.left.name);
+            if (filter.right.value === null) {
+                return filter.operator === "eq"
+                    ? `${left} IS NULL`
+                    : filter.operator === "ne"
+                        ? `${left} IS NOT NULL`
+                        : refuseQueryFilterConstruct(`filter.comparison.${filter.operator}.null`, ctx);
+            }
+            return `${left} ${SQL_COMPARISON[filter.operator]} ${sqlLiteral(filter.right, true)}`;
+        }
+        case "list":
+            return `${field(filter.operand.name)} IN (${filter.values.map((value) => sqlLiteral(value, true)).join(", ")})`;
+        case "range":
+            return `${field(filter.operand.name)} BETWEEN ${sqlLiteral(filter.lower, true)} AND ${sqlLiteral(filter.upper, true)}`;
+        case "null":
+            return `${field(filter.operand.name)} IS ${filter.operator === "is-null" ? "NULL" : "NOT NULL"}`;
+        case "pattern": {
+            const pattern = sqlText(filter.pattern);
+            const operand = field(filter.operand.name);
+            return filter.caseSensitive === false
+                ? dialect.caseInsensitiveLike(operand, pattern)
+                : `${operand} LIKE ${pattern}`;
+        }
+        case "temporal": {
+            const bounds = temporalBounds(filter, ctx);
+            const operand = field(filter.operand.name);
+            if (bounds.instant !== undefined)
+                return `${operand} = ${sqlTimestamp(bounds.instant)}`;
+            const parts = [];
+            if (bounds.start !== undefined) {
+                parts.push(`${operand} ${bounds.start.inclusive ? ">=" : ">"} ${sqlTimestamp(bounds.start.value)}`);
+            }
+            if (bounds.end !== undefined) {
+                parts.push(`${operand} ${bounds.end.inclusive ? "<=" : "<"} ${sqlTimestamp(bounds.end.value)}`);
+            }
+            return parts.length === 1 ? parts[0] : `(${parts.join(" AND ")})`;
+        }
+        case "boolean":
+            return filter.args
+                .map((arg) => `(${emitSql(arg, ctx, dialect)})`)
+                .join(filter.operator === "and" ? " AND " : " OR ");
+        case "not":
+            return `NOT (${emitSql(filter.arg, ctx, dialect)})`;
+        case "spatial":
+            return dialect.spatial(filter);
+        default:
+            return refuseQueryFilterConstruct("filter.node", ctx);
+    }
+}
+/** GeoServices carries geometry as request parameters, never inside the SQL. */
+function sql92Dialect(ctx) {
+    return {
+        identifier: (name) => name,
+        caseInsensitiveLike: (operand, pattern) => `UPPER(${operand}) LIKE UPPER(${pattern})`,
+        spatial: () => refuseQueryFilterConstruct("filter.spatial.disjunction", ctx),
+    };
+}
+/**
+ * Compile to a DuckDB `WHERE` fragment. Spatial predicates are emitted through
+ * `emitSpatial`, which the GeoParquet driver supplies (it owns the geometry
+ * column, its encoding, and the bbox reduction that `Result.degraded` reports).
+ */
+export function compileQueryFilterToDuckDbSql(filter, ctx, emitSpatial) {
+    assertQueryFilter(filter, ctx);
+    let bboxApproximated = false;
+    const sql = emitSql(filter, ctx, {
+        identifier: (name) => `"${name}"`,
+        caseInsensitiveLike: (operand, pattern) => `${operand} ILIKE ${pattern}`,
+        spatial: (node) => {
+            const compiled = emitSpatial(node);
+            if (compiled.bboxApproximated)
+                bboxApproximated = true;
+            return compiled.sql;
+        },
+    });
+    return { sql, bboxApproximated };
+}
+// ── CQL2 text (OGC API Features / Records / STAC) ─────────────
+const CQL2_SPATIAL = {
+    intersects: "S_INTERSECTS",
+    contains: "S_CONTAINS",
+    within: "S_WITHIN",
+    crosses: "S_CROSSES",
+    touches: "S_TOUCHES",
+    overlaps: "S_OVERLAPS",
+    "bbox-intersects": "S_INTERSECTS",
+};
+/**
+ * Compile to CQL2 text (OGC API — Features Part 3 / STAC filter extension).
+ * `geometryToWkt` is injected so the WKT writer stays in the OData module that
+ * already owns it instead of being duplicated here.
+ */
+export function compileQueryFilterToCql2Text(filter, ctx, geometryToWkt) {
+    assertQueryFilter(filter, ctx);
+    const emit = (node) => {
+        switch (node.kind) {
+            case "comparison": {
+                if (node.right.value === null) {
+                    return node.operator === "eq"
+                        ? `${node.left.name} IS NULL`
+                        : node.operator === "ne"
+                            ? `${node.left.name} IS NOT NULL`
+                            : refuseQueryFilterConstruct(`filter.comparison.${node.operator}.null`, ctx);
+                }
+                return `${node.left.name} ${SQL_COMPARISON[node.operator]} ${cql2Literal(node.right)}`;
+            }
+            case "list":
+                return `${node.operand.name} IN (${node.values.map(cql2Literal).join(", ")})`;
+            case "range":
+                return `${node.operand.name} BETWEEN ${cql2Literal(node.lower)} AND ${cql2Literal(node.upper)}`;
+            case "null":
+                return `${node.operand.name} IS ${node.operator === "is-null" ? "NULL" : "NOT NULL"}`;
+            case "pattern":
+                return node.caseSensitive === false
+                    ? `CASEI(${node.operand.name}) LIKE CASEI(${sqlText(node.pattern)})`
+                    : `${node.operand.name} LIKE ${sqlText(node.pattern)}`;
+            case "spatial": {
+                const wkt = geometryToWkt(node.geometry.geometry, node.geometry.geometryType);
+                const property = node.property ?? ctx.geometryProperty ?? "geometry";
+                return `${CQL2_SPATIAL[node.operator]}(${property}, ${wkt})`;
+            }
+            case "temporal": {
+                const field = node.operand.name;
+                const value = node.value;
+                if (node.operator === "before") {
+                    return `T_BEFORE(${field}, ${cql2Instant(value.valueType === "instant" ? value.value : value.value[0])})`;
+                }
+                if (node.operator === "after") {
+                    return `T_AFTER(${field}, ${cql2Instant(value.valueType === "instant" ? value.value : value.value[1])})`;
+                }
+                if (value.valueType === "instant") {
+                    return `T_INTERSECTS(${field}, ${cql2Instant(value.value)})`;
+                }
+                const interval = `INTERVAL('${value.value[0]}', '${value.value[1]}')`;
+                return node.operator === "during" ? `T_DURING(${field}, ${interval})` : `T_INTERSECTS(${field}, ${interval})`;
+            }
+            case "boolean":
+                return node.args.map((arg) => `(${emit(arg)})`).join(node.operator === "and" ? " AND " : " OR ");
+            case "not":
+                return `NOT (${emit(node.arg)})`;
+            default:
+                return refuseQueryFilterConstruct("filter.node", ctx);
+        }
+    };
+    return emit(filter);
+}
+function cql2Literal(node) {
+    const value = node.value;
+    if (value === null)
+        return "NULL";
+    if (typeof value === "boolean")
+        return value ? "TRUE" : "FALSE";
+    if (typeof value === "number")
+        return String(value);
+    return isTemporalLike(value) ? cql2Instant(value) : sqlText(value);
+}
+function cql2Instant(instant) {
+    return instant.length === 10 ? `DATE('${instant}')` : `TIMESTAMP('${instant}')`;
+}
+// ── OData v4 ($filter) ────────────────────────────────────────
+/**
+ * Compile to an OData `$filter` expression. Spatial predicates are emitted
+ * through `emitSpatial` so the adapter's `$metadata`-aware geometry column and
+ * SRID resolution stay in one place.
+ */
+export function compileQueryFilterToOData(filter, ctx, emitSpatial) {
+    assertQueryFilter(filter, ctx);
+    const emit = (node) => {
+        switch (node.kind) {
+            case "comparison":
+                return `${node.left.name} ${ODATA_COMPARISON[node.operator]} ${odataLiteral(node.right)}`;
+            case "list":
+                return `${node.operand.name} in (${node.values.map(odataLiteral).join(",")})`;
+            case "range":
+                return `(${node.operand.name} ge ${odataLiteral(node.lower)} and ${node.operand.name} le ${odataLiteral(node.upper)})`;
+            case "null":
+                return `${node.operand.name} ${node.operator === "is-null" ? "eq" : "ne"} null`;
+            case "pattern":
+                return odataPattern(node, ctx);
+            case "spatial":
+                return emitSpatial(node);
+            case "temporal": {
+                const bounds = temporalBounds(node, ctx);
+                const field = node.operand.name;
+                if (bounds.instant !== undefined)
+                    return `${field} eq ${bounds.instant}`;
+                const parts = [];
+                if (bounds.start !== undefined) {
+                    parts.push(`${field} ${bounds.start.inclusive ? "ge" : "gt"} ${bounds.start.value}`);
+                }
+                if (bounds.end !== undefined) {
+                    parts.push(`${field} ${bounds.end.inclusive ? "le" : "lt"} ${bounds.end.value}`);
+                }
+                return parts.length === 1 ? parts[0] : `(${parts.join(" and ")})`;
+            }
+            case "boolean":
+                return node.args.map((arg) => `(${emit(arg)})`).join(node.operator === "and" ? " and " : " or ");
+            case "not":
+                return `not (${emit(node.arg)})`;
+            default:
+                return refuseQueryFilterConstruct("filter.node", ctx);
+        }
+    };
+    return emit(filter);
+}
+function odataLiteral(node) {
+    const value = node.value;
+    if (value === null)
+        return "null";
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "number")
+        return String(value);
+    // Edm.DateTimeOffset literals are unquoted; every other string is quoted.
+    return isTemporalLike(value) && value.length > 10 ? value : sqlText(value);
+}
+/**
+ * OData has no `LIKE`. Only the three anchored shapes map exactly onto
+ * `startswith` / `endswith` / `contains`; anything else (an interior wildcard,
+ * a single-character `_`) is refused instead of being widened.
+ */
+function odataPattern(node, ctx) {
+    if (node.caseSensitive === false)
+        refuseQueryFilterConstruct("filter.pattern.case-insensitive", ctx);
+    const pattern = node.pattern;
+    if (pattern.includes("_"))
+        refuseQueryFilterConstruct("filter.pattern.single-character-wildcard", ctx);
+    const leading = pattern.startsWith("%");
+    const trailing = pattern.endsWith("%");
+    const core = pattern.slice(leading ? 1 : 0, trailing ? pattern.length - 1 : pattern.length);
+    if (core.includes("%"))
+        refuseQueryFilterConstruct("filter.pattern.interior-wildcard", ctx);
+    const literalText = sqlText(core);
+    if (leading && trailing)
+        return `contains(${node.operand.name},${literalText})`;
+    if (trailing)
+        return `startswith(${node.operand.name},${literalText})`;
+    if (leading)
+        return `endswith(${node.operand.name},${literalText})`;
+    return `${node.operand.name} eq ${literalText}`;
+}
+// ── Protocol time parameters ──────────────────────────────────
+/**
+ * GeoServices `time=` value. Instants serialize as epoch milliseconds and
+ * intervals as `start,end`; an open bound serializes as `null`, which the
+ * FeatureServer `time` parameter defines as "unbounded on that side".
+ */
+export function compileTemporalFilterToGeoServicesTime(temporal, ctx) {
+    assertTemporalFilter(temporal, ctx);
+    if (temporal.kind === "instant")
+        return String(epochMillis(temporal.instant, ctx));
+    const start = temporal.start === null ? "null" : String(epochMillis(temporal.start, ctx));
+    const end = temporal.end === null ? "null" : String(epochMillis(temporal.end, ctx));
+    return `${start},${end}`;
+}
+/** OGC / STAC `datetime=` value (RFC 3339 instant or `start/end` interval). */
+export function compileTemporalFilterToOgcDatetime(temporal, ctx) {
+    assertTemporalFilter(temporal, ctx);
+    if (temporal.kind === "instant")
+        return temporal.instant;
+    return `${temporal.start ?? ".."}/${temporal.end ?? ".."}`;
+}
+function epochMillis(instant, ctx) {
+    const millis = Date.parse(instant.length === 10 ? `${instant}T00:00:00Z` : instant);
+    if (!Number.isFinite(millis))
+        refuseQueryFilterConstruct("temporalFilter.instant", ctx);
+    return millis;
+}