@honua/sdk-esri-compat 0.1.12 → 0.1.14

package/query-planner/duckdb.js

@@ -0,0 +1,772 @@
+/**
+ * Compile canonical query IR to deterministic DuckDB SQL over
+ * `read_parquet(...)` for the GeoParquet columnar `Source`, without performing
+ * any network, filesystem, or DuckDB metadata I/O.
+ *
+ * The heavy lifting — identifier/literal escaping, spatial predicate pushdown,
+ * GeoJSON projection, and GROUP BY aggregation — is delegated to the
+ * dependency-free {@link module:core/geoparquet-sql} SQL builder that the live
+ * GeoParquet `Source` already uses, so the planner and the adapter emit the
+ * exact same SQL for the same inputs.
+ *
+ * @module
+ */
+import { validateExecutableCrsBinding } from "../contract/schema.js";
+import { GeoParquetWhereClauseError, compileAggregate, compileQuery, geometryExpr, parquetSourceExpr, quoteIdentifier, } from "../core/geoparquet-sql.js";
+import { queryFromCanonical } from "./ir.js";
+import { parseGeoParquetResourceHandle } from "./resource.js";
+import { hashSemanticQuery } from "./semantic-canonical.js";
+import { prepareSemanticCompilerQuery, runSemanticCompiler, sameCrsDefinition, sameExecutableCrs, semanticSchemaField, semanticUnsupported, } from "./semantic-compiler.js";
+import { HonuaQueryPlanningError } from "./types.js";
+const RESOURCE_SQL_PLACEHOLDER = "honua-resource://resolve-at-execution";
+/**
+ * Compile canonical query IR to a deterministic DuckDB `SELECT`. Reuses the
+ * GeoParquet `Source` SQL builder, so the compiled SQL is byte-identical to
+ * what the live adapter runs for the same descriptor + query.
+ */
+export function compileDuckDbQuery(source, query) {
+    if (source.protocol !== "geoparquet") {
+        throw new HonuaQueryPlanningError("unsupported-compiler", `duckdb-sql-v1 does not compile protocol "${source.protocol}"`);
+    }
+    const geoparquet = source.geoparquet;
+    if (!geoparquet || geoparquet.sources.length === 0) {
+        throw new HonuaQueryPlanningError("invalid-query", `Source "${source.id}" requires locator.url (a parquet file or hive glob) for DuckDB planning`);
+    }
+    if (query.outSr !== undefined) {
+        throw new HonuaQueryPlanningError("unsupported-query", "DuckDB/GeoParquet has no portable output-CRS query option; omit outSr and reproject downstream");
+    }
+    if (query.spatialFilter && !geoparquet.geometryColumn) {
+        throw new HonuaQueryPlanningError("unsupported-query", `Source "${source.id}" has a spatialFilter but no geometry column; set locator.geoparquet.geometryColumn or a geometry schema field`);
+    }
+    const geometry = geoparquet.geometryColumn
+        ? {
+            column: geoparquet.geometryColumn,
+            encoding: geoparquet.geometryEncoding ?? "wkb",
+            ...(geoparquet.bboxColumn ? { bboxColumn: geoparquet.bboxColumn } : {}),
+        }
+        : undefined;
+    const options = {
+        sources: geoparquet.sources,
+        geometryAlias: "geometry",
+        ...(geometry ? { geometry } : {}),
+    };
+    const request = queryFromCanonical(query);
+    try {
+        const compiled = query.aggregation
+            ? compileAggregate({ ...request, aggregation: query.aggregation }, options)
+            : compileQuery(request, options);
+        return {
+            compiler: "duckdb-sql-v1",
+            sql: compiled.sql,
+            sources: geoparquet.sources,
+            ...(geometry ? { geometryColumn: geometry.column, geometryEncoding: geometry.encoding } : {}),
+            ...(compiled.bboxApproximated ? { bboxApproximated: true } : {}),
+        };
+    }
+    catch (error) {
+        rethrowRejectedWhere(error);
+        throw new HonuaQueryPlanningError("unsupported-query", `DuckDB query cannot be compiled deterministically: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Surface a contained `Query.where` rejection as an invalid query rather than
+ * an unsupported one: the raw-text lane is supported, this specific expression
+ * is refused. Only the fixed rejection code travels, never the caller's text.
+ */
+function rethrowRejectedWhere(error) {
+    if (error instanceof GeoParquetWhereClauseError) {
+        throw new HonuaQueryPlanningError("invalid-query", `Query.where was rejected before SQL assembly: ${error.code}`, {
+            cause: error,
+        });
+    }
+}
+/** Compile a credential-free template; execution recompiles with ephemeral resolved sources. */
+export function compileDuckDbQueryV2(source, query) {
+    const geoparquet = source.geoparquet;
+    if (query.outSr !== undefined) {
+        throw new HonuaQueryPlanningError("unsupported-query", "DuckDB/GeoParquet has no portable output-CRS query option; omit outSr and reproject downstream");
+    }
+    if (query.spatialFilter && !geoparquet.geometryColumn) {
+        throw new HonuaQueryPlanningError("unsupported-query", `Source "${source.id}" has a spatialFilter but no geometry column; set locator.geoparquet.geometryColumn or a geometry schema field`);
+    }
+    const geometry = geoparquet.geometryColumn
+        ? {
+            column: geoparquet.geometryColumn,
+            encoding: geoparquet.geometryEncoding ?? "wkb",
+            ...(geoparquet.bboxColumn ? { bboxColumn: geoparquet.bboxColumn } : {}),
+        }
+        : undefined;
+    const options = {
+        sources: [RESOURCE_SQL_PLACEHOLDER],
+        geometryAlias: "geometry",
+        ...(geometry ? { geometry } : {}),
+    };
+    const request = queryFromCanonical(query);
+    try {
+        const compiled = query.aggregation
+            ? compileAggregate({ ...request, aggregation: query.aggregation }, options)
+            : compileQuery(request, options);
+        return {
+            compiler: "duckdb-sql-v2",
+            sqlTemplate: compiled.sql,
+            resource: geoparquet.resource,
+            ...(geometry ? { geometryColumn: geometry.column, geometryEncoding: geometry.encoding } : {}),
+            ...(compiled.bboxApproximated ? { bboxApproximated: true } : {}),
+        };
+    }
+    catch (error) {
+        rethrowRejectedWhere(error);
+        throw new HonuaQueryPlanningError("unsupported-query", "DuckDB query cannot be compiled safely for an opaque GeoParquet resource");
+    }
+}
+/**
+ * Compile the schema-validated semantic AST into parameterized DuckDB SQL.
+ * The table address remains the fixed opaque-resource placeholder; only a
+ * trusted execution boundary may resolve the attached handle to raw locators.
+ */
+export function compileSemanticDuckDbQuery(options) {
+    return runSemanticCompiler(() => {
+        const { query, schema } = prepareSemanticCompilerQuery(options.query, options.schema, "geoparquet");
+        verifyDuckDbPhysicalPaths(schema);
+        const resource = verifiedSemanticResource(options.resource);
+        const geometry = options.geometry ? verifyDuckDbGeometrySource(options.geometry, schema) : undefined;
+        const spatialStrategy = verifiedDuckDbSpatialStrategy(options.spatialStrategy);
+        const state = {
+            schema,
+            ...(geometry ? { geometry } : {}),
+            spatialStrategy,
+            parameters: [],
+            spatial: [],
+            losses: [],
+            usesNativeFilter: false,
+        };
+        const projection = duckDbProjection(query, state);
+        const filter = query.filter
+            ? compileDuckDbFilter(query.filter, state, "$.filter")
+            : undefined;
+        const groupBy = query.kind === "aggregate" ? duckDbGroupBy(query, state) : "";
+        const orderBy = duckDbOrderBy(query, state);
+        const page = duckDbPage(query);
+        const sqlTemplate = `SELECT ${projection.sql} FROM ${parquetSourceExpr([RESOURCE_SQL_PLACEHOLDER])}${filter ? ` WHERE ${filter}` : ""}${groupBy}${orderBy}${page}`;
+        const artifact = {
+            compiler: "duckdb-semantic-query-v1",
+            dialect: "duckdb-sql",
+            schemaFingerprint: schema.fingerprint,
+            queryFingerprint: hashSemanticQuery(query, { schema, protocol: "geoparquet" }),
+            resource,
+            sqlTemplate,
+            parameters: state.parameters,
+            ...(projection.outputGeometry ? { outputGeometry: projection.outputGeometry } : {}),
+            spatial: state.spatial,
+            usesNativeFilter: state.usesNativeFilter,
+        };
+        return { artifact, losses: state.losses };
+    });
+}
+function verifiedDuckDbSpatialStrategy(value) {
+    if (value === undefined || value === "exact")
+        return "exact";
+    if (value === "bbox-envelope")
+        return value;
+    throw new HonuaQueryPlanningError("invalid-query", "options.spatialStrategy is invalid");
+}
+function verifiedSemanticResource(value) {
+    try {
+        return parseGeoParquetResourceHandle(value);
+    }
+    catch {
+        throw new HonuaQueryPlanningError("invalid-query", "Semantic DuckDB compilation requires a valid resource handle");
+    }
+}
+function verifyDuckDbGeometrySource(value, schema) {
+    if (!value || typeof value !== "object") {
+        throw new HonuaQueryPlanningError("invalid-query", "Semantic DuckDB geometry metadata is invalid");
+    }
+    const field = semanticSchemaField(schema, value.field, "options.geometry.field");
+    if (field.type.kind !== "geometry") {
+        throw new HonuaQueryPlanningError("invalid-query", "options.geometry.field must identify a geometry field");
+    }
+    if (field.path.length !== 1) {
+        semanticUnsupported("unsupported-geometry", "options.geometry.field", "DuckDB geometry columns must have one physical path segment");
+    }
+    if (value.encoding !== "wkb" && value.encoding !== "native" && value.encoding !== "geojson") {
+        throw new HonuaQueryPlanningError("invalid-query", "options.geometry.encoding is invalid");
+    }
+    if (value.bboxColumn !== undefined && (typeof value.bboxColumn !== "string" || value.bboxColumn.length === 0)) {
+        throw new HonuaQueryPlanningError("invalid-query", "options.geometry.bboxColumn is invalid");
+    }
+    return {
+        field: field.name,
+        encoding: value.encoding,
+        ...(value.bboxColumn !== undefined ? { bboxColumn: value.bboxColumn } : {}),
+    };
+}
+function duckDbProjection(query, state) {
+    if (query.kind === "aggregate") {
+        if (query.outputCrs) {
+            semanticUnsupported("unsupported-projection", "$.outputCrs", "DuckDB aggregate rows do not carry output geometry");
+        }
+        const parts = query.groupBy.map((name, index) => aliasedDuckDbField(state.schema, name, `$.groupBy[${index}]`));
+        query.metrics.forEach((metric, index) => {
+            const field = metric.field
+                ? semanticSchemaField(state.schema, metric.field, `$.metrics[${index}].field`)
+                : undefined;
+            const operand = field ? duckDbFieldExpression(field, `$.metrics[${index}].field`) : "*";
+            const aggregate = duckDbAggregateFunction(metric.fn, operand);
+            parts.push(`${aggregate} AS ${duckDbIdentifier(metric.as, `$.metrics[${index}].as`)}`);
+        });
+        return { sql: parts.join(", ") };
+    }
+    const geometryField = selectedDuckDbGeometryField(query, state);
+    const names = query.select ?? state.schema.fields.filter((field) => field.type.kind !== "geometry").map((field) => field.name);
+    const parts = [];
+    let geometryAliasCollisionPath;
+    names.forEach((name, index) => {
+        const path = `$.select[${index}]`;
+        const field = semanticSchemaField(state.schema, name, path);
+        if (field.type.kind === "geometry") {
+            if (!geometryField || field.name !== geometryField.name) {
+                semanticUnsupported("unsupported-projection", path, "DuckDB semantic results expose only the selected top-level geometry");
+            }
+            return;
+        }
+        if (duckDbAsciiIdentifierKey(field.name) === "geometry") {
+            geometryAliasCollisionPath = query.select ? path : "$.geometry";
+        }
+        parts.push(aliasedDuckDbField(state.schema, field.name, path));
+    });
+    if (geometryField) {
+        if (geometryAliasCollisionPath) {
+            semanticUnsupported("unsupported-projection", geometryAliasCollisionPath, 'DuckDB cannot project an attribute using the reserved geometry result alias "geometry" while returning geometry');
+        }
+        const geometry = requiredDuckDbGeometry(state, geometryField.name, "$.geometry");
+        const geometrySchema = sourceGeometryField(state.schema, geometryField.name, "$.geometry");
+        const crs = executableDuckDbCrs(geometrySchema.crs, "$.geometry");
+        if (geometrySchema.layout !== "xy" && geometrySchema.layout !== "xyz") {
+            semanticUnsupported("unsupported-geometry", "$.geometry", "DuckDB GeoJSON output requires a known xy or xyz source geometry layout");
+        }
+        assertDuckDbOutputCrs(query, geometryField, state);
+        parts.push(`ST_AsGeoJSON(${duckDbGeometryExpression(geometryField, geometry, "$.geometry")}) AS ${quoteIdentifier("geometry")}`);
+        return {
+            sql: parts.join(", "),
+            outputGeometry: {
+                sourceField: geometryField.name,
+                sourceEncoding: geometry.encoding,
+                resultField: "geometry",
+                resultEncoding: "geojson",
+                crs,
+                layout: geometrySchema.layout,
+            },
+        };
+    }
+    if (query.outputCrs) {
+        semanticUnsupported("unsupported-projection", "$.outputCrs", "DuckDB cannot apply an output CRS when geometry is omitted");
+    }
+    return { sql: parts.length > 0 ? parts.join(", ") : `1 AS ${quoteIdentifier("__honua_row")}` };
+}
+function selectedDuckDbGeometryField(query, state) {
+    if (query.geometry === "omit")
+        return undefined;
+    if (query.geometry && typeof query.geometry === "object") {
+        return semanticSchemaField(state.schema, query.geometry.field, "$.geometry.field");
+    }
+    const geometry = state.schema.geometry;
+    if (geometry.state === "known" && geometry.primaryField.state === "known") {
+        return semanticSchemaField(state.schema, geometry.primaryField.field, "$.geometry");
+    }
+    if (query.geometry === "include") {
+        semanticUnsupported("unsupported-projection", "$.geometry", "DuckDB geometry inclusion requires a known primary geometry field");
+    }
+    return undefined;
+}
+function assertDuckDbOutputCrs(query, field, state) {
+    if (!query.outputCrs)
+        return;
+    const geometry = sourceGeometryField(state.schema, field.name, "$.geometry");
+    const sourceCrs = executableDuckDbCrs(geometry.crs, "$.geometry");
+    if (!sameCrsDefinition(query.outputCrs, sourceCrs.definition)) {
+        semanticUnsupported("crs-transform-required", "$.outputCrs", "DuckDB semantic compilation does not silently insert a CRS transform");
+    }
+}
+function duckDbGroupBy(query, state) {
+    if (query.groupBy.length === 0)
+        return "";
+    return ` GROUP BY ${query.groupBy
+        .map((name, index) => duckDbFieldExpression(semanticSchemaField(state.schema, name, `$.groupBy[${index}]`), `$.groupBy[${index}]`))
+        .join(", ")}`;
+}
+function duckDbAggregateFunction(fn, operand) {
+    switch (fn) {
+        case "count":
+            return `count(${operand})`;
+        case "sum":
+            return `sum(${operand})`;
+        case "avg":
+            return `avg(${operand})`;
+        case "min":
+            return `min(${operand})`;
+        case "max":
+            return `max(${operand})`;
+        case "stddev":
+            return `stddev_samp(${operand})`;
+        case "variance":
+            return `var_samp(${operand})`;
+        default:
+            semanticUnsupported("unsupported-node", "$.metrics", `DuckDB does not support aggregate ${JSON.stringify(fn)}`);
+    }
+}
+function duckDbOrderBy(query, state) {
+    if (!query.sort || query.sort.length === 0)
+        return "";
+    if (query.kind === "aggregate") {
+        const groupFields = new Set(query.groupBy);
+        const unsupportedIndex = query.sort.findIndex((sort) => !groupFields.has(sort.field));
+        if (unsupportedIndex >= 0) {
+            semanticUnsupported("unsupported-sort", `$.sort[${unsupportedIndex}].field`, "Aggregate DuckDB queries may sort only by a grouped source field");
+        }
+    }
+    const parts = query.sort.map((sort, index) => {
+        const field = semanticSchemaField(state.schema, sort.field, `$.sort[${index}].field`);
+        const nulls = sort.nulls === "first" ? " NULLS FIRST" : sort.nulls === "last" ? " NULLS LAST" : "";
+        return `${duckDbFieldExpression(field, `$.sort[${index}].field`)} ${sort.direction.toUpperCase()}${nulls}`;
+    });
+    return ` ORDER BY ${parts.join(", ")}`;
+}
+function duckDbPage(query) {
+    if (!query.page)
+        return "";
+    const limit = query.page.limit === undefined ? "" : ` LIMIT ${query.page.limit}`;
+    const offset = query.page.kind === "offset" && query.page.offset > 0 ? ` OFFSET ${query.page.offset}` : "";
+    return `${limit}${offset}`;
+}
+function compileDuckDbFilter(filter, state, path) {
+    switch (filter.kind) {
+        case "comparison": {
+            const field = semanticSchemaField(state.schema, filter.left.name, `${path}.left.name`);
+            const operator = { eq: "=", ne: "<>", lt: "<", lte: "<=", gt: ">", gte: ">=" }[filter.operator];
+            return `${duckDbFieldExpression(field, `${path}.left.name`)} ${operator} ${duckDbLiteralParameter(filter.right.value, field, state, `${path}.right.value`)}`;
+        }
+        case "list": {
+            const field = semanticSchemaField(state.schema, filter.operand.name, `${path}.operand.name`);
+            const values = filter.values.map((literal, index) => duckDbLiteralParameter(literal.value, field, state, `${path}.values[${index}].value`));
+            return `${duckDbFieldExpression(field, `${path}.operand.name`)} IN (${values.join(", ")})`;
+        }
+        case "range": {
+            const field = semanticSchemaField(state.schema, filter.operand.name, `${path}.operand.name`);
+            return `${duckDbFieldExpression(field, `${path}.operand.name`)} BETWEEN ${duckDbLiteralParameter(filter.lower.value, field, state, `${path}.lower.value`)} AND ${duckDbLiteralParameter(filter.upper.value, field, state, `${path}.upper.value`)}`;
+        }
+        case "null": {
+            const field = semanticSchemaField(state.schema, filter.operand.name, `${path}.operand.name`);
+            return `${duckDbFieldExpression(field, `${path}.operand.name`)} IS ${filter.operator === "is-not-null" ? "NOT " : ""}NULL`;
+        }
+        case "pattern": {
+            const field = semanticSchemaField(state.schema, filter.operand.name, `${path}.operand.name`);
+            const parameter = duckDbParameter(state, filter.pattern, "literal", field);
+            return `${duckDbFieldExpression(field, `${path}.operand.name`)} ${filter.caseSensitive === false ? "ILIKE" : "LIKE"} ${parameter}`;
+        }
+        case "boolean":
+            return `(${filter.args
+                .map((entry, index) => compileDuckDbFilter(entry, state, `${path}.args[${index}]`))
+                .join(` ${filter.operator.toUpperCase()} `)})`;
+        case "not":
+            return `NOT (${compileDuckDbFilter(filter.arg, state, `${path}.arg`)})`;
+        case "temporal": {
+            const field = semanticSchemaField(state.schema, filter.operand.name, `${path}.operand.name`);
+            if (filter.operator === "before" || filter.operator === "after") {
+                const value = filter.value.value;
+                return `${duckDbFieldExpression(field, `${path}.operand.name`)} ${filter.operator === "before" ? "<" : ">"} ${duckDbLiteralParameter(value, field, state, `${path}.value.value`)}`;
+            }
+            const interval = filter.value.value;
+            return `${duckDbFieldExpression(field, `${path}.operand.name`)} BETWEEN ${duckDbLiteralParameter(interval[0], field, state, `${path}.value.value[0]`)} AND ${duckDbLiteralParameter(interval[1], field, state, `${path}.value.value[1]`)}`;
+        }
+        case "spatial":
+            return compileDuckDbSpatial(filter, state, path);
+        case "native": {
+            if (filter.dialect !== "duckdb-sql" || filter.payload.format !== "text") {
+                semanticUnsupported("unsupported-native-filter", path, "DuckDB native filters require a duckdb-sql text payload");
+            }
+            if (hasDuckDbParameterMarker(filter.payload.text)) {
+                semanticUnsupported("unsupported-native-filter", `${path}.payload.text`, "DuckDB native filters cannot contain parameter markers because the native payload carries no bind values");
+            }
+            state.usesNativeFilter = true;
+            return `(${filter.payload.text})`;
+        }
+    }
+}
+function hasDuckDbParameterMarker(text) {
+    let index = 0;
+    while (index < text.length) {
+        const character = text[index];
+        if (character === "'" || character === '"') {
+            index = skipDuckDbQuotedToken(text, index, character);
+            continue;
+        }
+        if (character === "-" && text[index + 1] === "-") {
+            index += 2;
+            while (index < text.length && text[index] !== "\n" && text[index] !== "\r")
+                index += 1;
+            continue;
+        }
+        if (character === "/" && text[index + 1] === "*") {
+            index = skipDuckDbBlockComment(text, index + 2);
+            continue;
+        }
+        if (character === "$") {
+            const delimiter = duckDbDollarQuoteDelimiter(text, index);
+            if (delimiter) {
+                const end = text.indexOf(delimiter, index + delimiter.length);
+                index = end === -1 ? text.length : end + delimiter.length;
+                continue;
+            }
+            if (/[0-9A-Za-z_]/.test(text[index + 1] ?? ""))
+                return true;
+        }
+        if (character === "?")
+            return true;
+        index += 1;
+    }
+    return false;
+}
+function skipDuckDbQuotedToken(text, start, quote) {
+    let index = start + 1;
+    while (index < text.length) {
+        if (text[index] !== quote) {
+            index += 1;
+            continue;
+        }
+        if (text[index + 1] === quote) {
+            index += 2;
+            continue;
+        }
+        return index + 1;
+    }
+    return index;
+}
+function skipDuckDbBlockComment(text, start) {
+    let depth = 1;
+    let index = start;
+    while (index < text.length && depth > 0) {
+        if (text[index] === "/" && text[index + 1] === "*") {
+            depth += 1;
+            index += 2;
+            continue;
+        }
+        if (text[index] === "*" && text[index + 1] === "/") {
+            depth -= 1;
+            index += 2;
+            continue;
+        }
+        index += 1;
+    }
+    return index;
+}
+function duckDbDollarQuoteDelimiter(text, start) {
+    const match = /^\$(?:[A-Za-z_][A-Za-z0-9_]*)?\$/.exec(text.slice(start));
+    return match?.[0];
+}
+function verifyDuckDbPhysicalPaths(schema) {
+    const paths = new Map();
+    schema.fields.forEach((field, index) => {
+        const key = JSON.stringify(field.path.map(duckDbAsciiIdentifierKey));
+        const previous = paths.get(key);
+        if (previous && !sameDuckDbPhysicalPath(previous, field.path)) {
+            semanticUnsupported("unsupported-source", `options.schema.fields[${index}].path`, "DuckDB cannot resolve physical field paths that differ only by ASCII case");
+        }
+        paths.set(key, field.path);
+    });
+}
+function sameDuckDbPhysicalPath(left, right) {
+    return left.length === right.length && left.every((segment, index) => segment === right[index]);
+}
+function duckDbAsciiIdentifierKey(value) {
+    let key = "";
+    for (const character of value) {
+        const code = character.charCodeAt(0);
+        key += code >= 0x41 && code <= 0x5a ? String.fromCharCode(code + 0x20) : character;
+    }
+    return key;
+}
+function compileDuckDbSpatial(filter, state, path) {
+    const fieldName = semanticSpatialField(filter, state.schema, path);
+    const field = semanticSchemaField(state.schema, fieldName, `${path}.property.name`);
+    const geometry = requiredDuckDbGeometry(state, field.name, path);
+    const fieldSchema = sourceGeometryField(state.schema, field.name, path);
+    const sourceCrs = executableDuckDbCrs(fieldSchema.crs, `${path}.property`);
+    if (fieldSchema.layout !== "xy") {
+        semanticUnsupported("unsupported-geometry", path, "DuckDB semantic spatial predicates currently require an xy geometry field");
+    }
+    const sourceExpression = duckDbGeometryExpression(field, geometry, `${path}.property`);
+    if (filter.operator === "bbox-intersects") {
+        if (!sameExecutableCrs(filter.bbox.crs, sourceCrs)) {
+            semanticUnsupported("crs-transform-required", `${path}.bbox.crs`, "Spatial bbox CRS differs from the source field");
+        }
+        if (filter.bbox.box.layout !== "xy") {
+            semanticUnsupported("unsupported-geometry", `${path}.bbox`, "DuckDB bbox predicates currently require xy bounds");
+        }
+        const [xmin, ymin, xmax, ymax] = filter.bbox.box.bounds;
+        const predicate = duckDbExactEnvelopePredicate(sourceExpression, geometry.bboxColumn, [xmin, ymin, xmax, ymax], state);
+        state.spatial.push({ path, field: field.name, encoding: geometry.encoding, strategy: "exact", crs: sourceCrs });
+        return predicate;
+    }
+    if (!sameExecutableCrs(filter.geometry.crs, sourceCrs)) {
+        semanticUnsupported("crs-transform-required", `${path}.geometry.crs`, "Spatial geometry CRS differs from the source field");
+    }
+    if (filter.geometry.layout !== "xy") {
+        semanticUnsupported("unsupported-geometry", `${path}.geometry.layout`, "DuckDB semantic spatial predicates currently require xy literal geometry");
+    }
+    if (state.spatialStrategy === "bbox-envelope" && filter.operator === "intersects") {
+        const bounds = executableGeometryBounds(filter.geometry, `${path}.geometry`);
+        const predicate = duckDbEnvelopePredicate(sourceExpression, geometry.bboxColumn, bounds, state);
+        state.spatial.push({
+            path,
+            field: field.name,
+            encoding: geometry.encoding,
+            strategy: "bbox-envelope",
+            crs: sourceCrs,
+        });
+        state.losses.push({
+            code: "spatial-envelope-reduction",
+            path,
+            message: "The intersects operand was explicitly reduced to its bounding envelope",
+        });
+        return predicate;
+    }
+    const geometryParameter = duckDbParameter(state, JSON.stringify(filter.geometry.geometry), "geometry", field, "geometry-json");
+    const literalExpression = `ST_GeomFromGeoJSON(${geometryParameter})`;
+    state.spatial.push({ path, field: field.name, encoding: geometry.encoding, strategy: "exact", crs: sourceCrs });
+    if (filter.operator === "within-distance" || filter.operator === "beyond-distance") {
+        if (filter.distance.mode !== "planar") {
+            semanticUnsupported("unsupported-distance", `${path}.distance.mode`, "DuckDB geometry distance does not preserve geodesic mode");
+        }
+        assertDuckDbDistanceUnit(filter.distance.unit, sourceCrs, `${path}.distance.unit`);
+        const distance = duckDbParameter(state, filter.distance.value, "distance", field, "distance");
+        const dWithin = `ST_DWithin(${sourceExpression}, ${literalExpression}, ${distance})`;
+        return filter.operator === "within-distance" ? dWithin : `NOT (${dWithin})`;
+    }
+    const fn = {
+        equals: "ST_Equals",
+        intersects: "ST_Intersects",
+        within: "ST_Within",
+        contains: "ST_Contains",
+        disjoint: "ST_Disjoint",
+        touches: "ST_Touches",
+        overlaps: "ST_Overlaps",
+        crosses: "ST_Crosses",
+    }[filter.operator];
+    return `${fn}(${sourceExpression}, ${literalExpression})`;
+}
+function semanticSpatialField(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-geometry", `${path}.property`, "A spatial predicate requires a geometry field");
+}
+function requiredDuckDbGeometry(state, fieldName, path) {
+    if (!state.geometry || state.geometry.field !== fieldName) {
+        semanticUnsupported("unsupported-source", path, "DuckDB physical geometry metadata is unavailable for the requested geometry field");
+    }
+    return state.geometry;
+}
+function sourceGeometryField(schema, fieldName, path) {
+    if (schema.geometry.state !== "known") {
+        semanticUnsupported("unsupported-source", path, "Source geometry metadata is unavailable");
+    }
+    const field = schema.geometry.fields.find((candidate) => candidate.field === fieldName);
+    if (!field)
+        semanticUnsupported("unsupported-source", path, "Source geometry field metadata is unavailable");
+    return field;
+}
+function duckDbGeometryExpression(field, geometry, path) {
+    try {
+        return geometryExpr({ column: field.path[0], encoding: geometry.encoding });
+    }
+    catch {
+        semanticUnsupported("unsupported-source", path, "DuckDB cannot represent the physical geometry field path");
+    }
+}
+function duckDbEnvelopePredicate(sourceExpression, bboxColumn, bounds, state) {
+    const [xmin, ymin, xmax, ymax] = bounds.map((value) => duckDbParameter(state, value, "bbox", undefined, "number"));
+    if (bboxColumn) {
+        const bbox = duckDbIdentifier(bboxColumn, "options.geometry.bboxColumn");
+        // Keep placeholder appearance in the same xmin/ymin/xmax/ymax order as
+        // the parameter array; anonymous DuckDB placeholders cannot be reused.
+        return `(${bbox}.xmax >= ${xmin} AND ${bbox}.ymax >= ${ymin} AND ${bbox}.xmin <= ${xmax} AND ${bbox}.ymin <= ${ymax})`;
+    }
+    return `ST_Intersects(${sourceExpression}, ST_MakeEnvelope(${xmin}, ${ymin}, ${xmax}, ${ymax}))`;
+}
+function duckDbExactEnvelopePredicate(sourceExpression, bboxColumn, bounds, state) {
+    if (!bboxColumn)
+        return duckDbEnvelopePredicate(sourceExpression, undefined, bounds, state);
+    const prefilter = duckDbEnvelopePredicate(sourceExpression, bboxColumn, bounds, state);
+    const exact = duckDbEnvelopePredicate(sourceExpression, undefined, bounds, state);
+    return `(${prefilter} AND ${exact})`;
+}
+function executableGeometryBounds(value, path) {
+    const bounds = {
+        xmin: Number.POSITIVE_INFINITY,
+        ymin: Number.POSITIVE_INFINITY,
+        xmax: Number.NEGATIVE_INFINITY,
+        ymax: Number.NEGATIVE_INFINITY,
+        seen: false,
+    };
+    collectGeometryCoordinates(value.geometry, bounds);
+    if (!bounds.seen)
+        semanticUnsupported("unsupported-geometry", path, "Geometry has no xy coordinates");
+    return [bounds.xmin, bounds.ymin, bounds.xmax, bounds.ymax];
+}
+function executableDuckDbCrs(value, path) {
+    try {
+        return validateExecutableCrsBinding(value, path);
+    }
+    catch {
+        semanticUnsupported("unsupported-crs", path, "DuckDB requires a resolved source CRS and payload order");
+    }
+}
+function collectGeometryCoordinates(value, bounds) {
+    if (Array.isArray(value)) {
+        if (typeof value[0] === "number" && typeof value[1] === "number") {
+            bounds.seen = true;
+            bounds.xmin = Math.min(bounds.xmin, value[0]);
+            bounds.ymin = Math.min(bounds.ymin, value[1]);
+            bounds.xmax = Math.max(bounds.xmax, value[0]);
+            bounds.ymax = Math.max(bounds.ymax, value[1]);
+            return;
+        }
+        value.forEach((entry) => collectGeometryCoordinates(entry, bounds));
+        return;
+    }
+    if (!value || typeof value !== "object")
+        return;
+    const record = value;
+    if (record.coordinates !== undefined)
+        collectGeometryCoordinates(record.coordinates, bounds);
+    if (record.geometries !== undefined)
+        collectGeometryCoordinates(record.geometries, bounds);
+}
+function assertDuckDbDistanceUnit(unit, crs, path) {
+    const axisUnits = crs.coordinateOrder.axes.slice(0, 2).map((axis) => normalizeDistanceUnit(axis.unit));
+    const requested = normalizeDistanceUnit(unit);
+    if (axisUnits.length < 2 || axisUnits.some((axisUnit) => axisUnit !== requested)) {
+        semanticUnsupported("unsupported-distance", path, "DuckDB planar distance unit must match both source coordinate axes");
+    }
+}
+function normalizeDistanceUnit(unit) {
+    const normalized = unit
+        .trim()
+        .toLowerCase()
+        .replace(/[ _-]+/g, "-");
+    if (normalized === "meter" || normalized === "meters")
+        return "metre";
+    if (normalized === "kilometer" || normalized === "kilometers" || normalized === "kilometres")
+        return "kilometre";
+    if (normalized === "feet" || normalized === "ft")
+        return "foot";
+    if (normalized === "us-survey-feet" || normalized === "us-ft")
+        return "us-survey-foot";
+    if (normalized === "miles" || normalized === "mi")
+        return "mile";
+    if (normalized === "nautical-miles")
+        return "nautical-mile";
+    if (normalized === "degrees")
+        return "degree";
+    if (normalized === "radians")
+        return "radian";
+    return normalized;
+}
+function duckDbLiteralParameter(value, field, state, path) {
+    if (value === null || Array.isArray(value) || typeof value === "object") {
+        semanticUnsupported("unsupported-field-type", path, `DuckDB does not bind ${field.type.kind} filter values as scalar parameters`);
+    }
+    const parameter = duckDbParameter(state, value, "literal", field);
+    switch (field.type.kind) {
+        case "integer":
+            if (field.type.jsonEncoding !== "string")
+                return parameter;
+            return `CAST(${parameter} AS ${field.type.signed ? "BIGINT" : "UBIGINT"})`;
+        case "decimal":
+            if (field.type.jsonEncoding !== "string")
+                return parameter;
+            return `CAST(${parameter} AS ${duckDbDecimalType(field, path)})`;
+        case "uuid":
+            return `CAST(${parameter} AS UUID)`;
+        case "date":
+            return `CAST(${parameter} AS DATE)`;
+        case "time":
+            if (field.type.unit === "nanosecond") {
+                semanticUnsupported("unsupported-field-type", path, "DuckDB TIME cannot preserve nanosecond precision");
+            }
+            return `CAST(${parameter} AS TIME)`;
+        case "timestamp":
+            return `CAST(${parameter} AS ${duckDbTimestampType(field, path)})`;
+        case "duration":
+            if (field.type.unit === "nanosecond") {
+                semanticUnsupported("unsupported-field-type", path, "DuckDB INTERVAL cannot preserve nanosecond precision");
+            }
+            return `CAST(${parameter} AS INTERVAL)`;
+        case "binary":
+        case "json":
+        case "geometry":
+        case "list":
+        case "struct":
+        case "union":
+        case "unknown":
+            return semanticUnsupported("unsupported-field-type", path, `DuckDB semantic filtering does not support logical type ${field.type.kind}`);
+        default:
+            return parameter;
+    }
+}
+function duckDbDecimalType(field, path) {
+    if (field.type.kind !== "decimal") {
+        semanticUnsupported("unsupported-field-type", path, "DuckDB decimal compilation requires decimal schema metadata");
+    }
+    if (field.type.precision === undefined || field.type.scale === undefined || field.type.precision > 38) {
+        semanticUnsupported("unsupported-field-type", path, "DuckDB string-encoded decimals require precision and scale with precision at most 38");
+    }
+    return `DECIMAL(${field.type.precision}, ${field.type.scale})`;
+}
+function duckDbTimestampType(field, path) {
+    if (field.type.kind !== "timestamp") {
+        semanticUnsupported("unsupported-field-type", path, "DuckDB timestamp compilation requires timestamp schema metadata");
+    }
+    const zoned = field.type.timezone === "utc" || field.type.timezone === "offset";
+    if (zoned) {
+        if (field.type.unit === "nanosecond") {
+            semanticUnsupported("unsupported-field-type", path, "DuckDB TIMESTAMPTZ cannot preserve nanosecond precision");
+        }
+        return "TIMESTAMPTZ";
+    }
+    return {
+        second: "TIMESTAMP_S",
+        millisecond: "TIMESTAMP_MS",
+        microsecond: "TIMESTAMP",
+        nanosecond: "TIMESTAMP_NS",
+    }[field.type.unit];
+}
+function duckDbParameter(state, value, role, field, logicalType) {
+    state.parameters.push({
+        position: state.parameters.length + 1,
+        role,
+        value,
+        ...(field ? { field: field.name } : {}),
+        ...(logicalType || field ? { logicalType: logicalType ?? field?.type.kind } : {}),
+    });
+    return "?";
+}
+function duckDbFieldExpression(field, path = "$.schema.fields") {
+    return field.path.map((segment) => duckDbIdentifier(segment, path)).join(".");
+}
+function duckDbIdentifier(value, path) {
+    try {
+        return quoteIdentifier(value);
+    }
+    catch {
+        semanticUnsupported("unsupported-source", path, "DuckDB cannot represent the physical identifier");
+    }
+}
+function aliasedDuckDbField(schema, name, path) {
+    const field = semanticSchemaField(schema, name, path);
+    const expression = duckDbFieldExpression(field, path);
+    return `${expression} AS ${duckDbIdentifier(field.name, path)}`;
+}