@honua/sdk-esri-compat 0.1.12 → 0.1.14

package/query-planner/cql2-json.js

@@ -0,0 +1,646 @@
+import { parseSourceSchemaV2, validateExecutableCrsBinding, } from "../contract/schema.js";
+import { canonicalStringify, toJsonValue } from "./canonical.js";
+import { MAX_SEMANTIC_QUERY_DEPTH, parseBoundedSemanticJson, parseSemanticQuery } from "./semantic.js";
+import { HonuaQueryPlanningError } from "./types.js";
+const COMPARISON_TO_CQL2 = {
+    eq: "=",
+    ne: "<>",
+    lt: "<",
+    lte: "<=",
+    gt: ">",
+    gte: ">=",
+};
+const CQL2_TO_COMPARISON = {
+    "=": "eq",
+    "<>": "ne",
+    "<": "lt",
+    "<=": "lte",
+    ">": "gt",
+    ">=": "gte",
+};
+const SPATIAL_TO_CQL2 = {
+    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 CQL2_TO_SPATIAL = {
+    s_equals: "equals",
+    s_intersects: "intersects",
+    s_within: "within",
+    s_contains: "contains",
+    s_disjoint: "disjoint",
+    s_touches: "touches",
+    s_overlaps: "overlaps",
+    s_crosses: "crosses",
+};
+const TEMPORAL_TO_CQL2 = {
+    before: "t_before",
+    after: "t_after",
+    during: "t_during",
+    "time-intersects": "t_intersects",
+};
+const CQL2_TO_TEMPORAL = {
+    t_before: "before",
+    t_after: "after",
+    t_during: "during",
+    t_intersects: "time-intersects",
+};
+// Annex C's normative CQL2 JSON schema declares GeometryCollection
+// `geometries` with minItems: 2. Enforce that in both directions even though
+// the broader semantic/GeoJSON model also admits a single member.
+const MIN_CQL2_GEOMETRY_COLLECTION_ITEMS = 2;
+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$/;
+/**
+ * Export the CQL2-representable semantic-filter subset. CQL2 carries spatial
+ * CRS outside the expression, so every spatial export requires `filterCrs`
+ * and verifies that each operand uses that exact executable binding.
+ */
+export function semanticFilterToCql2Json(filter, options = {}) {
+    const context = cql2Context(options);
+    const query = parseSemanticQuery({ kind: "features", filter }, {
+        ...(context.schema ? { schema: context.schema } : {}),
+        ...(context.protocol !== undefined ? { protocol: context.protocol } : {}),
+    });
+    if (!query.filter)
+        throw cql2Invalid("$", "requires a filter");
+    const encoded = exportFilter(query.filter, context, "$", 0);
+    return parseBoundedSemanticJson(encoded);
+}
+/**
+ * Import the strict CQL2 JSON subset into the same runtime-validated semantic
+ * AST used by builders. Unknown functions, property-property comparisons,
+ * distance extensions, and other non-representable constructs fail closed.
+ */
+export function semanticFilterFromCql2Json(value, options = {}) {
+    const json = parseBoundedSemanticJson(value);
+    const context = cql2Context(options);
+    const filter = importFilter(json, context, "$", 0);
+    const query = parseSemanticQuery({ kind: "features", filter }, {
+        ...(context.schema ? { schema: context.schema } : {}),
+        ...(context.protocol !== undefined ? { protocol: context.protocol } : {}),
+    });
+    if (!query.filter)
+        throw cql2Invalid("$", "requires a filter");
+    return query.filter;
+}
+function exportFilter(filter, context, path, depth) {
+    if (depth > MAX_SEMANTIC_QUERY_DEPTH)
+        throw cql2Invalid(path, "exceeds the expression depth bound");
+    switch (filter.kind) {
+        case "comparison": {
+            const field = schemaField(context.schema, filter.left.name);
+            return {
+                op: COMPARISON_TO_CQL2[filter.operator],
+                args: [{ property: filter.left.name }, exportLiteral(filter.right.value, field, `${path}.args[1]`)],
+            };
+        }
+        case "boolean":
+            if (filter.args.length < 2)
+                throw cql2Unsupported(path, "CQL2 and/or requires at least two operands");
+            return {
+                op: filter.operator,
+                args: filter.args.map((entry, index) => exportFilter(entry, context, `${path}.args[${index}]`, depth + 1)),
+            };
+        case "not":
+            return { op: "not", args: [exportFilter(filter.arg, context, `${path}.args[0]`, depth + 1)] };
+        case "null": {
+            const isNull = { op: "isNull", args: [{ property: filter.operand.name }] };
+            return filter.operator === "is-null" ? isNull : { op: "not", args: [isNull] };
+        }
+        case "list": {
+            const field = schemaField(context.schema, filter.operand.name);
+            return {
+                op: "in",
+                args: [
+                    { property: filter.operand.name },
+                    filter.values.map((entry, index) => exportLiteral(entry.value, field, `${path}.args[1][${index}]`)),
+                ],
+            };
+        }
+        case "range": {
+            if (typeof filter.lower.value !== "number" || typeof filter.upper.value !== "number") {
+                throw cql2Unsupported(path, "CQL2 between represents only numeric bounds in the supported subset");
+            }
+            return {
+                op: "between",
+                args: [{ property: filter.operand.name }, filter.lower.value, filter.upper.value],
+            };
+        }
+        case "pattern": {
+            const property = { property: filter.operand.name };
+            if (filter.caseSensitive === false) {
+                return {
+                    op: "like",
+                    args: [
+                        { op: "casei", args: [property] },
+                        { op: "casei", args: [filter.pattern] },
+                    ],
+                };
+            }
+            return { op: "like", args: [property, filter.pattern] };
+        }
+        case "spatial":
+            return exportSpatial(filter, context, path);
+        case "temporal":
+            return {
+                op: TEMPORAL_TO_CQL2[filter.operator],
+                args: [{ property: filter.operand.name }, exportTemporalLiteral(filter.value, `${path}.args[1]`)],
+            };
+        case "native":
+            throw cql2Unsupported(path, "native expressions are dialect escape hatches, not semantic CQL2 nodes");
+    }
+}
+function exportSpatial(filter, context, path) {
+    const property = filter.property?.name ?? primaryGeometryField(context.schema, path);
+    const propertyRef = { property };
+    if (filter.operator === "bbox-intersects") {
+        assertFilterCrs(filter.bbox.crs, context, path);
+        return { op: "s_intersects", args: [propertyRef, { bbox: [...filter.bbox.box.bounds] }] };
+    }
+    if (filter.operator === "within-distance" || filter.operator === "beyond-distance") {
+        throw cql2Unsupported(path, "distance predicates are outside standard CQL2 1.0");
+    }
+    if (filter.geometry.layout !== "xy" && filter.geometry.layout !== "xyz") {
+        throw cql2Unsupported(path, "CQL2 GeoJSON literals cannot preserve measured coordinate layouts");
+    }
+    assertFilterCrs(filter.geometry.crs, context, path);
+    assertCql2GeometryCollectionCardinality(filter.geometry.geometry, `${path}.args[1]`);
+    return {
+        op: SPATIAL_TO_CQL2[filter.operator],
+        args: [propertyRef, toJsonValue(filter.geometry.geometry)],
+    };
+}
+function exportLiteral(value, field, path) {
+    if (field?.type.kind === "date") {
+        if (typeof value !== "string")
+            throw cql2Unsupported(path, "date values require their string encoding");
+        if (!CQL2_DATE.test(value))
+            throw cql2Unsupported(path, "date values require the CQL2 full-date form");
+        return { date: value };
+    }
+    if (field?.type.kind === "timestamp") {
+        if (typeof value !== "string")
+            throw cql2Unsupported(path, "timestamp values require their string encoding");
+        if (!CQL2_TIMESTAMP.test(value)) {
+            throw cql2Unsupported(path, "timestamp values require the CQL2 UTC Z form");
+        }
+        return { timestamp: value };
+    }
+    if ((field?.type.kind === "decimal" && field.type.jsonEncoding === "string") ||
+        (field?.type.kind === "integer" && field.type.jsonEncoding === "string")) {
+        throw cql2Unsupported(path, "CQL2 JSON numbers cannot preserve string-encoded numeric precision");
+    }
+    if (value === null || Array.isArray(value) || typeof value === "object") {
+        throw cql2Unsupported(path, "the supported CQL2 scalar subset accepts only string, number, or boolean literals");
+    }
+    return value;
+}
+function exportTemporalLiteral(value, path) {
+    if (value.valueType === "interval") {
+        return {
+            interval: value.value.map((entry, index) => exportTemporalEndpoint(entry, `${path}.interval[${index}]`)),
+        };
+    }
+    if (value.valueType === "date") {
+        if (!CQL2_DATE.test(value.value))
+            throw cql2Unsupported(path, "date values require the CQL2 full-date form");
+        return { date: value.value };
+    }
+    if (!CQL2_TIMESTAMP.test(value.value)) {
+        throw cql2Unsupported(path, "timestamp values require the CQL2 UTC Z form");
+    }
+    return { timestamp: value.value };
+}
+function exportTemporalEndpoint(value, path) {
+    if (CQL2_DATE.test(value) || CQL2_TIMESTAMP.test(value))
+        return value;
+    throw cql2Unsupported(path, "requires a CQL2 full-date or UTC Z timestamp");
+}
+function importFilter(value, context, path, depth) {
+    if (depth > MAX_SEMANTIC_QUERY_DEPTH)
+        throw cql2Invalid(path, "exceeds the expression depth bound");
+    const object = exactObject(value, path, ["op", "args"]);
+    const op = text(object.op, `${path}.op`);
+    const args = array(object.args, `${path}.args`);
+    if (op === "and" || op === "or") {
+        if (args.length < 2)
+            throw cql2Invalid(`${path}.args`, "must contain at least two expressions");
+        const parsedArgs = [
+            importFilter(args[0], context, `${path}.args[0]`, depth + 1),
+            ...args.slice(1).map((entry, index) => importFilter(entry, context, `${path}.args[${index + 1}]`, depth + 1)),
+        ];
+        return {
+            kind: "boolean",
+            operator: op,
+            args: parsedArgs,
+        };
+    }
+    if (op === "not") {
+        exactLength(args, 1, `${path}.args`);
+        const inner = importFilter(args[0], context, `${path}.args[0]`, depth + 1);
+        if (inner.kind === "null" && inner.operator === "is-null") {
+            return { ...inner, operator: "is-not-null" };
+        }
+        return { kind: "not", arg: inner };
+    }
+    if (hasOwn(CQL2_TO_COMPARISON, op)) {
+        exactLength(args, 2, `${path}.args`);
+        const property = importProperty(args[0], `${path}.args[0]`);
+        const literal = importLiteral(args[1], schemaField(context.schema, property.name), `${path}.args[1]`);
+        return {
+            kind: "comparison",
+            operator: CQL2_TO_COMPARISON[op],
+            left: property,
+            right: literal,
+        };
+    }
+    if (op === "isNull") {
+        exactLength(args, 1, `${path}.args`);
+        return {
+            kind: "null",
+            operator: "is-null",
+            operand: importProperty(args[0], `${path}.args[0]`),
+        };
+    }
+    if (op === "in") {
+        exactLength(args, 2, `${path}.args`);
+        const property = importProperty(args[0], `${path}.args[0]`);
+        const values = array(args[1], `${path}.args[1]`);
+        if (values.length === 0)
+            throw cql2Invalid(`${path}.args[1]`, "must not be empty");
+        const field = schemaField(context.schema, property.name);
+        const parsedValues = [
+            importLiteral(values[0], field, `${path}.args[1][0]`),
+            ...values.slice(1).map((entry, index) => importLiteral(entry, field, `${path}.args[1][${index + 1}]`)),
+        ];
+        return {
+            kind: "list",
+            operator: "in",
+            operand: property,
+            values: parsedValues,
+        };
+    }
+    if (op === "between") {
+        exactLength(args, 3, `${path}.args`);
+        const property = importProperty(args[0], `${path}.args[0]`);
+        if (typeof args[1] !== "number" || typeof args[2] !== "number") {
+            throw cql2Unsupported(path, "the supported between form requires numeric literal bounds");
+        }
+        return {
+            kind: "range",
+            operator: "between",
+            operand: property,
+            lower: { kind: "literal", value: args[1] },
+            upper: { kind: "literal", value: args[2] },
+        };
+    }
+    if (op === "like")
+        return importLike(args, path);
+    if (hasOwn(CQL2_TO_SPATIAL, op))
+        return importSpatial(op, args, context, path);
+    if (hasOwn(CQL2_TO_TEMPORAL, op))
+        return importTemporal(op, args, path);
+    throw cql2Unsupported(`${path}.op`, "uses an unsupported CQL2 function or operator");
+}
+function importLike(args, path) {
+    exactLength(args, 2, `${path}.args`);
+    const leftCaseInsensitive = isOperation(args[0], "casei");
+    const rightCaseInsensitive = isOperation(args[1], "casei");
+    if (leftCaseInsensitive !== rightCaseInsensitive) {
+        throw cql2Invalid(`${path}.args`, "must apply casei to both operands or neither operand");
+    }
+    if (leftCaseInsensitive) {
+        const left = operationArgs(args[0], "casei", `${path}.args[0]`);
+        const right = operationArgs(args[1], "casei", `${path}.args[1]`);
+        exactLength(left, 1, `${path}.args[0].args`);
+        exactLength(right, 1, `${path}.args[1].args`);
+        if (typeof right[0] !== "string")
+            throw cql2Invalid(`${path}.args[1]`, "must wrap a string pattern");
+        return {
+            kind: "pattern",
+            operator: "like",
+            operand: importProperty(left[0], `${path}.args[0].args[0]`),
+            pattern: right[0],
+            caseSensitive: false,
+        };
+    }
+    if (typeof args[1] !== "string")
+        throw cql2Invalid(`${path}.args[1]`, "must be a string pattern");
+    return {
+        kind: "pattern",
+        operator: "like",
+        operand: importProperty(args[0], `${path}.args[0]`),
+        pattern: args[1],
+        caseSensitive: true,
+    };
+}
+function importSpatial(op, args, context, path) {
+    exactLength(args, 2, `${path}.args`);
+    const property = importProperty(args[0], `${path}.args[0]`);
+    const crs = requiredFilterCrs(context, path);
+    const operand = object(args[1], `${path}.args[1]`);
+    if (Object.hasOwn(operand, "bbox") && !Object.hasOwn(operand, "type")) {
+        exactKeys(operand, ["bbox"], `${path}.args[1]`);
+        if (op !== "s_intersects")
+            throw cql2Unsupported(path, "only s_intersects maps a CQL2 BBox literal");
+        const bounds = array(operand.bbox, `${path}.args[1].bbox`);
+        const layout = bounds.length === 4 ? "xy" : bounds.length === 6 ? "xyz" : undefined;
+        if (!layout)
+            throw cql2Invalid(`${path}.args[1].bbox`, "must contain four or six ordinates");
+        return {
+            kind: "spatial",
+            operator: "bbox-intersects",
+            property,
+            bbox: { box: { layout, bounds }, crs },
+        };
+    }
+    const layout = geometryLayout(operand, `${path}.args[1]`);
+    return {
+        kind: "spatial",
+        operator: CQL2_TO_SPATIAL[op],
+        property,
+        // GeoJSON permits an optional bbox on every geometry object. The
+        // protocol-neutral semantic contract intentionally stores canonical
+        // geometry only, so validate those extents above and discard them here.
+        geometry: { state: "present", geometry: geometryWithoutBboxes(operand), crs, layout },
+    };
+}
+function importTemporal(op, args, path) {
+    exactLength(args, 2, `${path}.args`);
+    return {
+        kind: "temporal",
+        operator: CQL2_TO_TEMPORAL[op],
+        operand: importProperty(args[0], `${path}.args[0]`),
+        value: importTemporalLiteral(args[1], `${path}.args[1]`),
+    };
+}
+function importLiteral(value, field, path) {
+    if (value === null || Array.isArray(value)) {
+        throw cql2Unsupported(path, "the supported scalar form accepts string, number, boolean, date, or timestamp");
+    }
+    if (typeof value !== "object") {
+        if (field?.type.kind === "date" || field?.type.kind === "timestamp") {
+            throw cql2Unsupported(path, `schema-typed ${field.type.kind} comparisons require the tagged CQL2 literal form`);
+        }
+        if ((field?.type.kind === "decimal" && field.type.jsonEncoding === "string") ||
+            (field?.type.kind === "integer" && field.type.jsonEncoding === "string")) {
+            throw cql2Unsupported(path, "CQL2 JSON numbers cannot preserve string-encoded numeric precision");
+        }
+        return { kind: "literal", value };
+    }
+    const objectValue = value;
+    if (Object.hasOwn(objectValue, "date")) {
+        exactKeys(objectValue, ["date"], path);
+        if (!field)
+            throw cql2Unsupported(path, "tagged date comparison requires schema context");
+        if (field.type.kind !== "date")
+            throw cql2Invalid(path, "date literal does not match the schema field type");
+        const date = text(objectValue.date, `${path}.date`);
+        if (!CQL2_DATE.test(date))
+            throw cql2Invalid(`${path}.date`, "must use the CQL2 full-date form");
+        return { kind: "literal", value: date };
+    }
+    if (Object.hasOwn(objectValue, "timestamp")) {
+        exactKeys(objectValue, ["timestamp"], path);
+        if (!field)
+            throw cql2Unsupported(path, "tagged timestamp comparison requires schema context");
+        if (field.type.kind !== "timestamp") {
+            throw cql2Invalid(path, "timestamp literal does not match the schema field type");
+        }
+        const timestamp = text(objectValue.timestamp, `${path}.timestamp`);
+        if (!CQL2_TIMESTAMP.test(timestamp)) {
+            throw cql2Invalid(`${path}.timestamp`, "must use the CQL2 UTC Z form");
+        }
+        return { kind: "literal", value: timestamp };
+    }
+    throw cql2Unsupported(path, "uses an unsupported CQL2 scalar expression");
+}
+function importTemporalLiteral(value, path) {
+    const literal = object(value, path);
+    if (Object.hasOwn(literal, "date")) {
+        exactKeys(literal, ["date"], path);
+        const date = text(literal.date, `${path}.date`);
+        if (!CQL2_DATE.test(date))
+            throw cql2Invalid(`${path}.date`, "must use the CQL2 full-date form");
+        return { kind: "temporal-literal", valueType: "date", value: date };
+    }
+    if (Object.hasOwn(literal, "timestamp")) {
+        exactKeys(literal, ["timestamp"], path);
+        const timestamp = text(literal.timestamp, `${path}.timestamp`);
+        if (!CQL2_TIMESTAMP.test(timestamp)) {
+            throw cql2Invalid(`${path}.timestamp`, "must use the CQL2 UTC Z form");
+        }
+        return {
+            kind: "temporal-literal",
+            valueType: "instant",
+            value: timestamp,
+        };
+    }
+    if (Object.hasOwn(literal, "interval")) {
+        exactKeys(literal, ["interval"], path);
+        const interval = array(literal.interval, `${path}.interval`);
+        exactLength(interval, 2, `${path}.interval`);
+        const endpoints = [text(interval[0], `${path}.interval[0]`), text(interval[1], `${path}.interval[1]`)];
+        endpoints.forEach((entry, index) => {
+            if (!CQL2_DATE.test(entry) && !CQL2_TIMESTAMP.test(entry)) {
+                throw cql2Invalid(`${path}.interval[${index}]`, "must use a CQL2 full-date or UTC Z timestamp");
+            }
+        });
+        return {
+            kind: "temporal-literal",
+            valueType: "interval",
+            value: endpoints,
+        };
+    }
+    throw cql2Unsupported(path, "uses an unsupported temporal literal");
+}
+function importProperty(value, path) {
+    const property = exactObject(value, path, ["property"]);
+    const name = text(property.property, `${path}.property`);
+    if (name.length === 0)
+        throw cql2Invalid(`${path}.property`, "must not be empty");
+    return { kind: "property", name };
+}
+function geometryLayout(geometry, path) {
+    const type = text(geometry.type, `${path}.type`);
+    if (type === "GeometryCollection") {
+        exactKeys(geometry, Object.hasOwn(geometry, "bbox") ? ["type", "geometries", "bbox"] : ["type", "geometries"], path);
+        const geometries = array(geometry.geometries, `${path}.geometries`);
+        if (geometries.length < MIN_CQL2_GEOMETRY_COLLECTION_ITEMS) {
+            throw cql2Invalid(`${path}.geometries`, "must contain at least two geometries in CQL2 JSON");
+        }
+        const layouts = geometries.map((entry, index) => {
+            const childPath = `${path}.geometries[${index}]`;
+            const child = object(entry, childPath);
+            if (child.type === "GeometryCollection") {
+                throw cql2Invalid(childPath, "must not be a nested GeometryCollection in CQL2 JSON");
+            }
+            return geometryLayout(child, childPath);
+        });
+        const layout = layouts[0];
+        if (layouts.some((candidate) => candidate !== layout)) {
+            throw cql2Invalid(`${path}.geometries`, "must use one coordinate layout throughout the collection");
+        }
+        validateGeometryBbox(geometry, layout, path);
+        return layout;
+    }
+    if (!["Point", "MultiPoint", "LineString", "MultiLineString", "Polygon", "MultiPolygon"].includes(type)) {
+        throw cql2Unsupported(`${path}.type`, "uses an unsupported GeoJSON geometry type");
+    }
+    exactKeys(geometry, Object.hasOwn(geometry, "bbox") ? ["type", "coordinates", "bbox"] : ["type", "coordinates"], path);
+    let position = geometry.coordinates;
+    while (Array.isArray(position) && position.length > 0 && Array.isArray(position[0])) {
+        position = position[0];
+    }
+    if (!Array.isArray(position))
+        throw cql2Invalid(`${path}.coordinates`, "must contain coordinate positions");
+    if (position.length === 2) {
+        validateGeometryBbox(geometry, "xy", path);
+        return "xy";
+    }
+    if (position.length === 3) {
+        validateGeometryBbox(geometry, "xyz", path);
+        return "xyz";
+    }
+    throw cql2Unsupported(`${path}.coordinates`, "positions must contain two or three ordinates");
+}
+function validateGeometryBbox(geometry, layout, path) {
+    if (!Object.hasOwn(geometry, "bbox"))
+        return;
+    const bbox = array(geometry.bbox, `${path}.bbox`);
+    const expectedLength = layout === "xy" ? 4 : 6;
+    if (bbox.length !== expectedLength) {
+        throw cql2Invalid(`${path}.bbox`, `must contain ${expectedLength} ordinates for ${layout} geometry`);
+    }
+    bbox.forEach((ordinate, index) => {
+        if (typeof ordinate !== "number")
+            throw cql2Invalid(`${path}.bbox[${index}]`, "must be a number");
+    });
+}
+function geometryWithoutBboxes(geometry) {
+    if (geometry.type === "GeometryCollection") {
+        return {
+            type: "GeometryCollection",
+            geometries: geometry.geometries.map((entry) => geometryWithoutBboxes(entry)),
+        };
+    }
+    return { type: geometry.type, coordinates: geometry.coordinates };
+}
+function assertCql2GeometryCollectionCardinality(geometry, path) {
+    if (geometry.type !== "GeometryCollection")
+        return;
+    const geometries = geometry.geometries;
+    if (!Array.isArray(geometries) || geometries.length < MIN_CQL2_GEOMETRY_COLLECTION_ITEMS) {
+        throw cql2Unsupported(`${path}.geometries`, "must contain at least two geometries in CQL2 JSON");
+    }
+    geometries.forEach((entry, index) => {
+        if (entry !== null &&
+            !Array.isArray(entry) &&
+            typeof entry === "object" &&
+            entry.type === "GeometryCollection") {
+            throw cql2Unsupported(`${path}.geometries[${index}]`, "nested GeometryCollection literals are outside CQL2 JSON 1.0");
+        }
+    });
+}
+function assertFilterCrs(value, context, path) {
+    const expected = requiredFilterCrs(context, path);
+    if (canonicalStringify(toJsonValue(value)) !== canonicalStringify(toJsonValue(expected))) {
+        throw cql2Unsupported(path, "spatial operand CRS does not match the external filterCrs context");
+    }
+}
+function requiredFilterCrs(context, path) {
+    if (!context.filterCrs) {
+        throw cql2Unsupported(path, "spatial CQL2 interchange requires an explicit filterCrs binding");
+    }
+    return context.filterCrs;
+}
+function primaryGeometryField(schema, path) {
+    if (schema?.geometry.state === "known" && schema.geometry.primaryField.state === "known") {
+        return schema.geometry.primaryField.field;
+    }
+    throw cql2Unsupported(path, "an implicit semantic geometry property requires schema primary-field context");
+}
+function schemaField(schema, name) {
+    return schema?.fields.find((field) => field.name === name);
+}
+function cql2Context(options) {
+    let schema;
+    let filterCrs;
+    try {
+        schema = options.schema === undefined ? undefined : parseSourceSchemaV2(options.schema);
+    }
+    catch {
+        throw cql2Invalid("$", "requires a valid schema context");
+    }
+    try {
+        filterCrs = options.filterCrs === undefined ? undefined : validateExecutableCrsBinding(options.filterCrs);
+    }
+    catch {
+        throw cql2Invalid("$", "requires a valid executable filterCrs binding");
+    }
+    return {
+        ...(schema ? { schema } : {}),
+        ...(filterCrs ? { filterCrs } : {}),
+        ...(options.protocol !== undefined ? { protocol: options.protocol } : {}),
+    };
+}
+function isOperation(value, op) {
+    return value !== null && !Array.isArray(value) && typeof value === "object" && value.op === op;
+}
+function operationArgs(value, op, path) {
+    const operation = exactObject(value, path, ["op", "args"]);
+    if (operation.op !== op)
+        throw cql2Invalid(`${path}.op`, `must be ${op}`);
+    return array(operation.args, `${path}.args`);
+}
+function exactObject(value, path, keys) {
+    const result = object(value, path);
+    exactKeys(result, keys, path);
+    return result;
+}
+function object(value, path) {
+    if (value === null || Array.isArray(value) || typeof value !== "object") {
+        throw cql2Invalid(path, "must be an object");
+    }
+    return value;
+}
+function array(value, path) {
+    if (!Array.isArray(value))
+        throw cql2Invalid(path, "must be an array");
+    return value;
+}
+function text(value, path) {
+    if (typeof value !== "string")
+        throw cql2Invalid(path, "must be a string");
+    return value;
+}
+function exactLength(value, expected, path) {
+    if (value.length !== expected)
+        throw cql2Invalid(path, `must contain exactly ${expected} entries`);
+}
+function exactKeys(value, expected, path) {
+    const allowed = new Set(expected);
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key))
+            throw cql2Invalid(path, "contains a member outside the supported CQL2 form");
+    }
+    for (const key of expected) {
+        if (!Object.hasOwn(value, key))
+            throw cql2Invalid(`${path}.${key}`, "is required");
+    }
+}
+function hasOwn(value, key) {
+    return Object.prototype.hasOwnProperty.call(value, key);
+}
+function cql2Invalid(path, message) {
+    return new HonuaQueryPlanningError("invalid-query", `CQL2 JSON ${path} ${message}`);
+}
+function cql2Unsupported(path, message) {
+    return new HonuaQueryPlanningError("unsupported-query", `CQL2 JSON ${path} ${message}`);
+}

package/query-planner/diagnostics.d.ts

@@ -0,0 +1,35 @@
+import type { CapabilityPolicy, SourceDescriptor } from "../contract/types.js";
+import type { CanonicalQuery, ExplainQueryOptions, QueryFallbackPolicy, QueryIrSourceIdentity, QueryIrSourceIdentityV2, QueryIrV1, QueryIrV2, QueryPlanBoundsV1, QueryPlanCacheDecisionV1, QueryPlanCacheOptions, QueryPlanFidelity, QueryPlanFidelityLoss, QueryPlanProvenanceV1, QueryPlanRepresentation, QueryPlanRepresentationDecisionV1, QueryPlanStepProvenanceV1, QueryPlanValidityV1, QueryPlanWarning, QueryPlanningEstimates } from "./types.js";
+type SourceIdentity = QueryIrSourceIdentity | QueryIrSourceIdentityV2;
+interface DiagnosticStep {
+    readonly engine: "remote" | "client";
+    readonly operation: string;
+    readonly requests?: number;
+    readonly query?: CanonicalQuery;
+    readonly compiled?: object;
+    readonly maxRows?: number;
+    readonly maxBytes?: number;
+}
+export declare function createQueryPlanProvenance(descriptor: SourceDescriptor, source: SourceIdentity, options: Pick<ExplainQueryOptions, "discovery" | "schemaVersion">): QueryPlanProvenanceV1;
+export declare function createStepProvenance(provenance: QueryPlanProvenanceV1): QueryPlanStepProvenanceV1;
+export declare function createCacheDecision(options?: QueryPlanCacheOptions): QueryPlanCacheDecisionV1;
+export declare function createStepDiagnostics(step: DiagnosticStep, estimates: QueryPlanningEstimates, provenance: QueryPlanProvenanceV1): {
+    readonly fidelity: QueryPlanFidelity;
+    readonly losses: readonly QueryPlanFidelityLoss[];
+    readonly bounds: QueryPlanBoundsV1;
+    readonly provenance: QueryPlanStepProvenanceV1;
+};
+export declare function summarizePlanBounds(steps: readonly {
+    readonly bounds: QueryPlanBoundsV1;
+}[]): QueryPlanBoundsV1;
+export declare function summarizeFidelity(steps: readonly {
+    readonly fidelity: QueryPlanFidelity;
+    readonly losses: readonly QueryPlanFidelityLoss[];
+}[]): {
+    readonly fidelity: QueryPlanFidelity;
+    readonly losses: readonly QueryPlanFidelityLoss[];
+};
+export declare function createPlanWarnings(steps: readonly DiagnosticStep[], source: SourceIdentity, representation: QueryPlanRepresentationDecisionV1): readonly QueryPlanWarning[];
+export declare function createPlanValidity(ir: QueryIrV1 | QueryIrV2, provenance: QueryPlanProvenanceV1, capabilityPolicy: CapabilityPolicy, fallback: QueryFallbackPolicy, executionMode: "snapshot" | "delta", representation: QueryPlanRepresentation): QueryPlanValidityV1;
+export {};
+//# sourceMappingURL=diagnostics.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../../src/query-planner/diagnostics.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE/E,OAAO,KAAK,EACV,cAAc,EACd,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,uBAAuB,EACvB,SAAS,EACT,SAAS,EACT,iBAAiB,EACjB,wBAAwB,EACxB,qBAAqB,EAErB,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EAErB,uBAAuB,EACvB,iCAAiC,EACjC,yBAAyB,EAEzB,mBAAmB,EACnB,gBAAgB,EAChB,sBAAsB,EACvB,MAAM,YAAY,CAAC;AAGpB,KAAK,cAAc,GAAG,qBAAqB,GAAG,uBAAuB,CAAC;AAGtE,UAAU,cAAc;IACtB,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,gBAAgB,EAC5B,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,IAAI,CAAC,mBAAmB,EAAE,WAAW,GAAG,eAAe,CAAC,GAChE,qBAAqB,CA6BvB;AAED,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,qBAAqB,GAAG,yBAAyB,CAQjG;AAED,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,wBAAwB,CA0C7F;AAED,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,cAAc,EACpB,SAAS,EAAE,sBAAsB,EACjC,UAAU,EAAE,qBAAqB,GAChC;IACD,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAClD,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,yBAAyB,CAAC;CAChD,CAUA;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS;IAAE,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;CAAE,EAAE,GAAG,iBAAiB,CAU/G;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS;IAAE,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,qBAAqB,EAAE,CAAA;CAAE,EAAE,GAC5G;IAAE,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,qBAAqB,EAAE,CAAA;CAAE,CAO7F;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,SAAS,cAAc,EAAE,EAChC,MAAM,EAAE,cAAc,EACtB,cAAc,EAAE,iCAAiC,GAChD,SAAS,gBAAgB,EAAE,CA2C7B;AAMD,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,SAAS,GAAG,SAAS,EACzB,UAAU,EAAE,qBAAqB,EACjC,gBAAgB,EAAE,gBAAgB,EAClC,QAAQ,EAAE,mBAAmB,EAC7B,aAAa,EAAE,UAAU,GAAG,OAAO,EACnC,cAAc,EAAE,uBAAuB,GACtC,mBAAmB,CAgBrB"}