@honua/app-platform 0.0.20-alpha.0 → 0.1.1-beta.0

package/query-planner/ogc-compiler.d.ts

@@ -0,0 +1,55 @@
+import type { CanonicalGeometry, CrsDefinition, ExecutableBoundingBox, ExecutableCrsBinding, ExecutableGeometryValue, JsonValue, LogicalField, SourceProtocol, SourceSchemaV2 } from "../contract/schema.js";
+export interface OgcAxisPlan {
+    readonly srsName: string;
+    /** Target/definition-axis index to source/payload-axis index. */
+    readonly permutation: readonly number[];
+}
+export interface NormalizedNamespaceBindings {
+    readonly bindings: Readonly<Record<string, string>>;
+    readonly ordered: readonly (readonly [string, string])[];
+}
+/** @internal Normalize an explicit conformance declaration without inferring support. */
+export declare function normalizeConformanceUris(value: readonly string[], path: string): readonly string[];
+/** @internal Normalize explicit CRS/namespace-style URI evidence. */
+export declare function normalizeIdentifierUris(value: readonly string[] | undefined, path: string): readonly string[];
+/** @internal Stable identity for normalized source capability evidence. */
+export declare function compilerEvidenceFingerprint(domain: string, evidence: JsonValue): `sha256:${string}`;
+/** @internal Stable identity for an immutable compiled request pre-image. */
+export declare function compiledRequestFingerprint(domain: string, artifact: JsonValue): `sha256:${string}`;
+/** @internal Match only the OGC conformance identifier itself, not a substring. */
+export declare function hasConformanceClass(conformsTo: readonly string[], standard: string, name: string): boolean;
+/** @internal Select the physical source property represented by one logical field. */
+export declare function ogcFieldPath(schema: SourceSchemaV2, name: string, protocol: Extract<SourceProtocol, "ogc-features" | "wfs">, path: string): readonly string[];
+/** @internal Require a single CQL2 queryable name. */
+export declare function cql2FieldName(schema: SourceSchemaV2, name: string, path: string): string;
+/** @internal Require a namespace-safe FES ValueReference. */
+export declare function fesValueReference(schema: SourceSchemaV2, name: string, namespaces: NormalizedNamespaceBindings, path: string): string;
+/** @internal Validate and deterministically order namespace bindings. */
+export declare function normalizeNamespaceBindings(value: Readonly<Record<string, string>> | undefined, path: string): NormalizedNamespaceBindings;
+/** @internal Verify a QName used for a WFS feature type. */
+export declare function validateFesTypeName(typeName: string, namespaces: NormalizedNamespaceBindings, path: string): string;
+/** @internal Produce a URI usable as CQL2 filter-crs, WFS srsName, or output CRS. */
+export declare function ogcCrsUri(definition: CrsDefinition, path: string): string;
+/** @internal Build an executable axis reordering plan; this never transforms values or units. */
+export declare function ogcAxisPlan(binding: ExecutableCrsBinding, dimensions: 2 | 3, path: string): OgcAxisPlan;
+/** @internal Reorder a validated semantic geometry into CRS-definition axis order. */
+export declare function geometryInDefinitionOrder(value: ExecutableGeometryValue, path: string): CanonicalGeometry;
+/** @internal Reorder a validated semantic bounding box into CRS-definition axis order. */
+export declare function bboxInDefinitionOrder(value: ExecutableBoundingBox, path: string): readonly number[];
+/** @internal Return the executable filter CRS after verifying every spatial leaf agrees. */
+export declare function sharedFilterCrs(current: ExecutableCrsBinding | undefined, next: ExecutableCrsBinding, path: string): ExecutableCrsBinding;
+/** @internal Resolve the field metadata used to encode typed literals. */
+export declare function compilerField(schema: SourceSchemaV2, name: string, path: string): LogicalField;
+/** @internal CQL2 identifiers follow the XML-Name-derived grammar in CQL2 1.0. */
+export declare function cql2Identifier(value: string, path: string): string;
+/** @internal Encode a CQL2 character literal with all standardized control escapes. */
+export declare function cql2StringLiteral(value: string, path: string): string;
+/** @internal Escape XML 1.0 character data after rejecting unrepresentable code points. */
+export declare function xmlText(value: string, path: string): string;
+/** @internal Escape XML 1.0 attribute data after rejecting unrepresentable code points. */
+export declare function xmlAttribute(value: string, path: string): string;
+/** @internal Canonical finite-number rendering shared by CQL2, WKT, and GML. */
+export declare function ogcNumber(value: number, path: string): string;
+/** @internal Convert canonical geometry to deterministic WKT after axis reordering. */
+export declare function geometryToWkt(value: CanonicalGeometry, layout: "xy" | "xyz", path: string): string;
+//# sourceMappingURL=ogc-compiler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ogc-compiler.d.ts","sourceRoot":"","sources":["../../../src/query-planner/ogc-compiler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,aAAa,EACb,qBAAqB,EACrB,oBAAoB,EACpB,uBAAuB,EACvB,SAAS,EACT,YAAY,EAEZ,cAAc,EACd,cAAc,EACf,MAAM,uBAAuB,CAAC;AAW/B,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC;CAC1D;AAED,yFAAyF;AACzF,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAgBlG;AAED,qEAAqE;AACrE,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAuB7G;AAED,2EAA2E;AAC3E,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,GAAG,UAAU,MAAM,EAAE,CAEnG;AAED,6EAA6E;AAC7E,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,GAAG,UAAU,MAAM,EAAE,CAElG;AAED,mFAAmF;AACnF,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAQ1G;AAED,sFAAsF;AACtF,wBAAgB,YAAY,CAC1B,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,OAAO,CAAC,cAAc,EAAE,cAAc,GAAG,KAAK,CAAC,EACzD,IAAI,EAAE,MAAM,GACX,SAAS,MAAM,EAAE,CAgBnB;AAED,sDAAsD;AACtD,wBAAgB,aAAa,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAUxF;AAED,6DAA6D;AAC7D,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,2BAA2B,EACvC,IAAI,EAAE,MAAM,GACX,MAAM,CAMR;AAED,yEAAyE;AACzE,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,EACnD,IAAI,EAAE,MAAM,GACX,2BAA2B,CAqC7B;AAED,4DAA4D;AAC5D,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,2BAA2B,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAMnH;AAED,qFAAqF;AACrF,wBAAgB,SAAS,CAAC,UAAU,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAoBzE;AAED,iGAAiG;AACjG,wBAAgB,WAAW,CAAC,OAAO,EAAE,oBAAoB,EAAE,UAAU,EAAE,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAmCvG;AAED,sFAAsF;AACtF,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,uBAAuB,EAAE,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAazG;AAED,0FAA0F;AAC1F,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,qBAAqB,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAiBnG;AAED,4FAA4F;AAC5F,wBAAgB,eAAe,CAC7B,OAAO,EAAE,oBAAoB,GAAG,SAAS,EACzC,IAAI,EAAE,oBAAoB,EAC1B,IAAI,EAAE,MAAM,GACX,oBAAoB,CAwBtB;AAED,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAE9F;AAED,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CASlE;AAED,uFAAuF;AACvF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAarE;AAYD,2FAA2F;AAC3F,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAG3D;AAED,2FAA2F;AAC3F,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,gFAAgF;AAChF,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAG7D;AAED,uFAAuF;AACvF,wBAAgB,aAAa,CAAC,KAAK,EAAE,iBAAiB,EAAE,MAAM,EAAE,IAAI,GAAG,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAgClG"}

package/query-planner/ogc-compiler.js

@@ -0,0 +1,480 @@
+import { canonicalStringify, sha256, toJsonValue } from "./canonical.js";
+import { semanticSchemaField, semanticUnsupported } from "./semantic-compiler.js";
+import { HonuaQueryPlanningError } from "./types.js";
+const MAX_EVIDENCE_ENTRIES = 256;
+const MAX_EVIDENCE_TEXT_BYTES = 8_192;
+const MAX_NAMESPACE_BINDINGS = 64;
+const MAX_NAMESPACE_TEXT_BYTES = 2_048;
+const TEXT_ENCODER = new TextEncoder();
+/** @internal Normalize an explicit conformance declaration without inferring support. */
+export function normalizeConformanceUris(value, path) {
+    if (!Array.isArray(value))
+        throw new HonuaQueryPlanningError("invalid-query", `${path} must be an array`);
+    if (value.length > MAX_EVIDENCE_ENTRIES) {
+        throw new HonuaQueryPlanningError("invalid-query", `${path} exceeds the ${MAX_EVIDENCE_ENTRIES}-entry evidence bound`);
+    }
+    const normalized = value.map((entry, index) => normalizeEvidenceUri(entry, `${path}[${index}]`));
+    normalized.sort(compareUtf8);
+    for (let index = 1; index < normalized.length; index += 1) {
+        if (normalized[index] === normalized[index - 1]) {
+            throw new HonuaQueryPlanningError("invalid-query", `${path} contains duplicate conformance URI`);
+        }
+    }
+    return Object.freeze(normalized);
+}
+/** @internal Normalize explicit CRS/namespace-style URI evidence. */
+export function normalizeIdentifierUris(value, path) {
+    if (value === undefined)
+        return Object.freeze([]);
+    if (!Array.isArray(value))
+        throw new HonuaQueryPlanningError("invalid-query", `${path} must be an array`);
+    if (value.length > MAX_EVIDENCE_ENTRIES) {
+        throw new HonuaQueryPlanningError("invalid-query", `${path} exceeds the ${MAX_EVIDENCE_ENTRIES}-entry evidence bound`);
+    }
+    const normalized = value.map((entry, index) => {
+        if (typeof entry !== "string" || entry.length === 0 || byteLength(entry) > MAX_EVIDENCE_TEXT_BYTES) {
+            throw new HonuaQueryPlanningError("invalid-query", `${path}[${index}] must be a bounded non-empty URI`);
+        }
+        assertAbsolutePublicIdentifier(entry, `${path}[${index}]`);
+        return entry;
+    });
+    normalized.sort(compareUtf8);
+    for (let index = 1; index < normalized.length; index += 1) {
+        if (normalized[index] === normalized[index - 1]) {
+            throw new HonuaQueryPlanningError("invalid-query", `${path} contains duplicate URI evidence`);
+        }
+    }
+    return Object.freeze(normalized);
+}
+/** @internal Stable identity for normalized source capability evidence. */
+export function compilerEvidenceFingerprint(domain, evidence) {
+    return sha256(`${domain}\n${canonicalStringify(evidence)}`);
+}
+/** @internal Stable identity for an immutable compiled request pre-image. */
+export function compiledRequestFingerprint(domain, artifact) {
+    return sha256(`${domain}\n${canonicalStringify(artifact)}`);
+}
+/** @internal Match only the OGC conformance identifier itself, not a substring. */
+export function hasConformanceClass(conformsTo, standard, name) {
+    const expected = `/spec/${standard.toLowerCase()}/conf/${name.toLowerCase()}`;
+    return conformsTo.some((entry) => {
+        const url = new URL(entry);
+        return (url.hostname.toLowerCase() === "www.opengis.net" && trimTrailingSlash(url.pathname).toLowerCase() === expected);
+    });
+}
+/** @internal Select the physical source property represented by one logical field. */
+export function ogcFieldPath(schema, name, protocol, path) {
+    const field = semanticSchemaField(schema, name, path);
+    const nativePaths = field.native
+        .filter((entry) => entry.protocol === protocol && entry.path !== undefined)
+        .map((entry) => entry.path);
+    if (nativePaths.length > 1) {
+        const identities = new Set(nativePaths.map((entry) => canonicalStringify(toJsonValue(entry))));
+        if (identities.size > 1) {
+            semanticUnsupported("unsupported-source", path, `${protocol} field ${JSON.stringify(name)} has conflicting native property paths`);
+        }
+    }
+    return nativePaths[0] ?? field.path;
+}
+/** @internal Require a single CQL2 queryable name. */
+export function cql2FieldName(schema, name, path) {
+    const fieldPath = ogcFieldPath(schema, name, "ogc-features", path);
+    if (fieldPath.length !== 1) {
+        semanticUnsupported("unsupported-source", path, `CQL2 property ${JSON.stringify(name)} must resolve to exactly one native path segment`);
+    }
+    return fieldPath[0];
+}
+/** @internal Require a namespace-safe FES ValueReference. */
+export function fesValueReference(schema, name, namespaces, path) {
+    const segments = ogcFieldPath(schema, name, "wfs", path);
+    for (const [index, segment] of segments.entries()) {
+        assertFesPathSegment(segment, namespaces, `${path}.nativePath[${index}]`);
+    }
+    return segments.join("/");
+}
+/** @internal Validate and deterministically order namespace bindings. */
+export function normalizeNamespaceBindings(value, path) {
+    if (value === undefined)
+        return { bindings: Object.freeze({}), ordered: Object.freeze([]) };
+    if (value === null || Array.isArray(value) || typeof value !== "object") {
+        throw new HonuaQueryPlanningError("invalid-query", `${path} must be a plain object`);
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new HonuaQueryPlanningError("invalid-query", `${path} must be a plain object`);
+    }
+    const entries = Object.entries(value);
+    if (entries.length > MAX_NAMESPACE_BINDINGS) {
+        throw new HonuaQueryPlanningError("invalid-query", `${path} exceeds the ${MAX_NAMESPACE_BINDINGS}-binding namespace bound`);
+    }
+    const bindings = {};
+    for (const [prefix, uri] of entries) {
+        if (!XML_PREFIX.test(prefix) ||
+            prefix.toLowerCase().startsWith("xml") ||
+            RESERVED_FES_PREFIXES.has(prefix.toLowerCase())) {
+            throw new HonuaQueryPlanningError("invalid-query", `${path}.${prefix} is not a safe XML namespace prefix`);
+        }
+        if (typeof uri !== "string" || uri.length === 0 || byteLength(uri) > MAX_NAMESPACE_TEXT_BYTES) {
+            throw new HonuaQueryPlanningError("invalid-query", `${path}.${prefix} must be a bounded non-empty URI`);
+        }
+        assertAbsolutePublicIdentifier(uri, `${path}.${prefix}`);
+        bindings[prefix] = uri;
+    }
+    const ordered = Object.entries(bindings).sort(([left], [right]) => compareUtf8(left, right));
+    const normalizedBindings = Object.fromEntries(ordered);
+    return {
+        bindings: Object.freeze(normalizedBindings),
+        ordered: Object.freeze(ordered.map((entry) => Object.freeze(entry))),
+    };
+}
+/** @internal Verify a QName used for a WFS feature type. */
+export function validateFesTypeName(typeName, namespaces, path) {
+    if (typeof typeName !== "string" || typeName.length === 0 || typeName.length > 512) {
+        throw new HonuaQueryPlanningError("invalid-query", `${path} must be a bounded non-empty QName`);
+    }
+    assertFesPathSegment(typeName, namespaces, path);
+    return typeName;
+}
+/** @internal Produce a URI usable as CQL2 filter-crs, WFS srsName, or output CRS. */
+export function ogcCrsUri(definition, path) {
+    if (definition.kind === "authority") {
+        if (definition.uri !== undefined) {
+            assertAbsolutePublicIdentifier(definition.uri, path);
+            return definition.uri;
+        }
+        const authority = encodeURIComponent(definition.authority);
+        const version = encodeURIComponent(definition.version ?? "0");
+        const code = encodeURIComponent(definition.code);
+        return `http://www.opengis.net/def/crs/${authority}/${version}/${code}`;
+    }
+    if (definition.kind === "uri") {
+        assertAbsolutePublicIdentifier(definition.uri, path);
+        return definition.uri;
+    }
+    semanticUnsupported("unsupported-crs", path, `OGC request parameters require an authority or URI CRS, not ${definition.kind}`);
+}
+/** @internal Build an executable axis reordering plan; this never transforms values or units. */
+export function ogcAxisPlan(binding, dimensions, path) {
+    if (binding.coordinateEpoch !== undefined) {
+        semanticUnsupported("crs-transform-required", path, "OGC filter encodings cannot preserve a coordinate epoch");
+    }
+    const targetOrder = binding.definition.definitionAxisOrder;
+    if (targetOrder.state !== "known") {
+        semanticUnsupported("unsupported-crs", path, "OGC filter execution requires known CRS-definition axis order");
+    }
+    const sourceAxes = binding.coordinateOrder.axes;
+    const targetAxes = targetOrder.axes;
+    if (sourceAxes.length !== dimensions || targetAxes.length !== dimensions) {
+        semanticUnsupported("crs-transform-required", path, `OGC filter execution requires exactly ${dimensions} source and CRS-definition axes for the coordinate layout`);
+    }
+    const unused = new Set(sourceAxes.map((_, index) => index));
+    const permutation = targetAxes.map((target) => {
+        const matches = [...unused].filter((index) => {
+            const source = sourceAxes[index];
+            return source?.direction === target.direction && normalizeUnit(source.unit) === normalizeUnit(target.unit);
+        });
+        if (matches.length !== 1) {
+            semanticUnsupported("crs-transform-required", path, "payload axes cannot be reordered losslessly into CRS-definition order");
+        }
+        const index = matches[0];
+        unused.delete(index);
+        return index;
+    });
+    return { srsName: ogcCrsUri(binding.definition, path), permutation };
+}
+/** @internal Reorder a validated semantic geometry into CRS-definition axis order. */
+export function geometryInDefinitionOrder(value, path) {
+    if (value.layout !== "xy" && value.layout !== "xyz") {
+        semanticUnsupported("unsupported-geometry", `${path}.layout`, "OGC CQL2/FES geometry literals cannot preserve measured coordinate layouts");
+    }
+    const dimensions = value.layout === "xy" ? 2 : 3;
+    const plan = ogcAxisPlan(value.crs, dimensions, `${path}.crs`);
+    return mapGeometryPositions(value.geometry, (position) => reorderPosition(position, plan.permutation));
+}
+/** @internal Reorder a validated semantic bounding box into CRS-definition axis order. */
+export function bboxInDefinitionOrder(value, path) {
+    const layout = value.box.layout;
+    if (layout !== "xy" && layout !== "xyz") {
+        semanticUnsupported("unsupported-geometry", `${path}.box.layout`, "OGC CQL2/FES bounding boxes cannot preserve measured coordinate layouts");
+    }
+    const dimensions = layout === "xy" ? 2 : 3;
+    const plan = ogcAxisPlan(value.crs, dimensions, `${path}.crs`);
+    const lower = value.box.bounds.slice(0, dimensions);
+    const upper = value.box.bounds.slice(dimensions);
+    return [
+        ...plan.permutation.map((index) => lower[index]),
+        ...plan.permutation.map((index) => upper[index]),
+    ];
+}
+/** @internal Return the executable filter CRS after verifying every spatial leaf agrees. */
+export function sharedFilterCrs(current, next, path) {
+    if (current === undefined)
+        return next;
+    const left = canonicalStringify(toJsonValue({
+        definition: current.definition,
+        coordinateOrder: current.coordinateOrder,
+        coordinateEpoch: current.coordinateEpoch ?? null,
+    }));
+    const right = canonicalStringify(toJsonValue({
+        definition: next.definition,
+        coordinateOrder: next.coordinateOrder,
+        coordinateEpoch: next.coordinateEpoch ?? null,
+    }));
+    if (left !== right) {
+        semanticUnsupported("crs-transform-required", path, "one compiled filter cannot mix spatial operands with different executable CRS bindings");
+    }
+    return current;
+}
+/** @internal Resolve the field metadata used to encode typed literals. */
+export function compilerField(schema, name, path) {
+    return semanticSchemaField(schema, name, path);
+}
+/** @internal CQL2 identifiers follow the XML-Name-derived grammar in CQL2 1.0. */
+export function cql2Identifier(value, path) {
+    if (!CQL_IDENTIFIER.test(value)) {
+        semanticUnsupported("unsupported-source", path, `CQL2 text cannot represent queryable identifier ${JSON.stringify(value)}`);
+    }
+    return CQL_KEYWORDS.has(value.toUpperCase()) ? `"${value}"` : value;
+}
+/** @internal Encode a CQL2 character literal with all standardized control escapes. */
+export function cql2StringLiteral(value, path) {
+    let output = "";
+    for (const character of value) {
+        const code = character.codePointAt(0);
+        const controlEscape = CQL2_CONTROL_ESCAPES[code];
+        if (character === "\\")
+            output += "\\\\";
+        else if (character === "'")
+            output += "''";
+        else if (controlEscape !== undefined)
+            output += controlEscape;
+        else if (code < 0x20 || code === 0x7f) {
+            semanticUnsupported("unsupported-node", path, `CQL2 text cannot preserve control character U+${hex(code)}`);
+        }
+        else
+            output += character;
+    }
+    return `'${output}'`;
+}
+const CQL2_CONTROL_ESCAPES = Object.freeze({
+    7: "\\a",
+    8: "\\b",
+    9: "\\t",
+    10: "\\n",
+    11: "\\v",
+    12: "\\f",
+    13: "\\r",
+});
+/** @internal Escape XML 1.0 character data after rejecting unrepresentable code points. */
+export function xmlText(value, path) {
+    assertXmlCharacters(value, path);
+    return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+/** @internal Escape XML 1.0 attribute data after rejecting unrepresentable code points. */
+export function xmlAttribute(value, path) {
+    return xmlText(value, path).replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+}
+/** @internal Canonical finite-number rendering shared by CQL2, WKT, and GML. */
+export function ogcNumber(value, path) {
+    if (!Number.isFinite(value))
+        throw new HonuaQueryPlanningError("invalid-query", `${path} must be finite`);
+    return Object.is(value, -0) ? "0" : String(value);
+}
+/** @internal Convert canonical geometry to deterministic WKT after axis reordering. */
+export function geometryToWkt(value, layout, path) {
+    const suffix = layout === "xyz" ? " Z" : "";
+    const position = (entry, entryPath) => entry.map((ordinate, index) => ogcNumber(ordinate, `${entryPath}[${index}]`)).join(" ");
+    const sequence = (entries, entryPath) => entries.map((entry, index) => position(entry, `${entryPath}[${index}]`)).join(", ");
+    const polygon = (rings, entryPath) => rings.map((ring, index) => `(${sequence(ring, `${entryPath}[${index}]`)})`).join(", ");
+    switch (value.type) {
+        case "Point":
+            return `POINT${suffix} (${position(value.coordinates, `${path}.coordinates`)})`;
+        case "MultiPoint":
+            return `MULTIPOINT${suffix} (${value.coordinates
+                .map((entry, index) => `(${position(entry, `${path}.coordinates[${index}]`)})`)
+                .join(", ")})`;
+        case "LineString":
+            return `LINESTRING${suffix} (${sequence(value.coordinates, `${path}.coordinates`)})`;
+        case "MultiLineString":
+            return `MULTILINESTRING${suffix} (${value.coordinates
+                .map((entry, index) => `(${sequence(entry, `${path}.coordinates[${index}]`)})`)
+                .join(", ")})`;
+        case "Polygon":
+            return `POLYGON${suffix} (${polygon(value.coordinates, `${path}.coordinates`)})`;
+        case "MultiPolygon":
+            return `MULTIPOLYGON${suffix} (${value.coordinates
+                .map((entry, index) => `(${polygon(entry, `${path}.coordinates[${index}]`)})`)
+                .join(", ")})`;
+        case "GeometryCollection":
+            return `GEOMETRYCOLLECTION${suffix} (${value.geometries
+                .map((entry, index) => geometryToWkt(entry, layout, `${path}.geometries[${index}]`))
+                .join(", ")})`;
+    }
+}
+/** @internal JSON-safe deep coordinate reorder. */
+function mapGeometryPositions(value, transform) {
+    const mapPositions = (input) => {
+        if (!Array.isArray(input))
+            return input;
+        if (input.length >= 2 && input.every((entry) => typeof entry === "number")) {
+            return transform(input);
+        }
+        return input.map(mapPositions);
+    };
+    if (value.type === "GeometryCollection") {
+        return {
+            type: value.type,
+            geometries: value.geometries.map((entry) => mapGeometryPositions(entry, transform)),
+        };
+    }
+    return { type: value.type, coordinates: mapPositions(value.coordinates) };
+}
+function reorderPosition(value, permutation) {
+    return permutation.map((index) => value[index]);
+}
+function normalizeEvidenceUri(value, path) {
+    if (typeof value !== "string" || value.length === 0 || byteLength(value) > MAX_EVIDENCE_TEXT_BYTES) {
+        throw new HonuaQueryPlanningError("invalid-query", `${path} must be a bounded non-empty URI`);
+    }
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new HonuaQueryPlanningError("invalid-query", `${path} must be an absolute URI`);
+    }
+    if ((url.protocol !== "http:" && url.protocol !== "https:") ||
+        url.username ||
+        url.password ||
+        url.search ||
+        url.hash) {
+        throw new HonuaQueryPlanningError("invalid-query", `${path} must be a credential-free HTTP(S) conformance URI`);
+    }
+    url.protocol = "https:";
+    url.hostname = url.hostname.toLowerCase();
+    url.pathname = trimTrailingSlash(url.pathname);
+    return url.toString();
+}
+function assertAbsolutePublicIdentifier(value, path) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new HonuaQueryPlanningError("invalid-query", `${path} must be an absolute URI`);
+    }
+    if (!new Set(["http:", "https:", "urn:"]).has(url.protocol) ||
+        url.username ||
+        url.password ||
+        url.search ||
+        url.hash) {
+        throw new HonuaQueryPlanningError("invalid-query", `${path} must be a credential-free HTTP(S) URI or URN`);
+    }
+}
+function assertFesPathSegment(value, namespaces, path) {
+    if (!FES_PATH_SEGMENT.test(value)) {
+        semanticUnsupported("unsupported-source", path, `FES ValueReference segment ${JSON.stringify(value)} is outside the safe QName subset`);
+    }
+    const colon = value.indexOf(":");
+    if (colon >= 0) {
+        const prefix = value.slice(0, colon);
+        if (!Object.hasOwn(namespaces.bindings, prefix)) {
+            semanticUnsupported("unsupported-source", path, `FES QName prefix ${JSON.stringify(prefix)} has no namespace binding`);
+        }
+    }
+}
+function assertXmlCharacters(value, path) {
+    for (const character of value) {
+        const code = character.codePointAt(0);
+        const valid = code === 0x09 ||
+            code === 0x0a ||
+            code === 0x0d ||
+            (code >= 0x20 && code <= 0xd7ff) ||
+            (code >= 0xe000 && code <= 0xfffd) ||
+            (code >= 0x10000 && code <= 0x10ffff);
+        if (!valid)
+            semanticUnsupported("unsupported-node", path, `XML 1.0 cannot preserve character U+${hex(code)}`);
+    }
+}
+function byteLength(value) {
+    return TEXT_ENCODER.encode(value).byteLength;
+}
+function trimTrailingSlash(value) {
+    return value.length > 1 ? value.replace(/\/+$/, "") : value;
+}
+function compareUtf8(left, right) {
+    const leftBytes = TEXT_ENCODER.encode(left);
+    const rightBytes = TEXT_ENCODER.encode(right);
+    const length = Math.min(leftBytes.length, rightBytes.length);
+    for (let index = 0; index < length; index += 1) {
+        const difference = leftBytes[index] - rightBytes[index];
+        if (difference !== 0)
+            return difference;
+    }
+    return leftBytes.length - rightBytes.length;
+}
+function normalizeUnit(value) {
+    return value.trim().toLowerCase().replaceAll(" ", "-");
+}
+function hex(value) {
+    return value.toString(16).toUpperCase().padStart(4, "0");
+}
+const XML_NAME_START = "(?:[_\\p{L}]|[\\p{Nl}])";
+const XML_NAME_PART = "(?:[-._\\p{L}\\p{Nl}\\p{N}\\p{M}\\u00B7\\u203F\\u2040])";
+const XML_PREFIX = new RegExp(`^${XML_NAME_START}${XML_NAME_PART}*$`, "u");
+const RESERVED_FES_PREFIXES = new Set(["fes", "gml", "wfs", "xs", "xsi"]);
+const FES_QNAME = `(?:${XML_NAME_START}${XML_NAME_PART}*:)?${XML_NAME_START}${XML_NAME_PART}*`;
+const FES_PATH_SEGMENT = new RegExp(`^${FES_QNAME}$`, "u");
+const CQL_IDENTIFIER = new RegExp(`^(?::|${XML_NAME_START})(?::|${XML_NAME_PART})*$`, "u");
+const CQL_KEYWORDS = new Set([
+    "A_EQUALS",
+    "A_CONTAINS",
+    "A_CONTAINEDBY",
+    "A_OVERLAPS",
+    "ACCENTI",
+    "AND",
+    "BBOX",
+    "BETWEEN",
+    "CASEI",
+    "DATE",
+    "DIV",
+    "FALSE",
+    "GEOMETRYCOLLECTION",
+    "IN",
+    "IS",
+    "LIKE",
+    "LINESTRING",
+    "MULTILINESTRING",
+    "MULTIPOINT",
+    "MULTIPOLYGON",
+    "NOT",
+    "NULL",
+    "OR",
+    "POINT",
+    "POLYGON",
+    "S_INTERSECTS",
+    "S_EQUALS",
+    "S_DISJOINT",
+    "S_TOUCHES",
+    "S_WITHIN",
+    "S_OVERLAPS",
+    "S_CROSSES",
+    "S_CONTAINS",
+    "T_AFTER",
+    "T_BEFORE",
+    "T_CONTAINS",
+    "T_DISJOINT",
+    "T_DURING",
+    "T_EQUALS",
+    "T_FINISHEDBY",
+    "T_FINISHES",
+    "T_INTERSECTS",
+    "T_MEETS",
+    "T_METBY",
+    "T_OVERLAPPEDBY",
+    "T_OVERLAPS",
+    "T_STARTEDBY",
+    "T_STARTS",
+    "TIMESTAMP",
+    "TRUE",
+]);

package/query-planner/ogc-features.d.ts

@@ -0,0 +1,53 @@
+import type { ExecutableCrsBinding, SourceSchemaV2 } from "../contract/schema.js";
+import { type SemanticCompilationResult } from "./semantic-compiler.js";
+import type { SemanticQuery, SourceSpatiality } from "./semantic-types.js";
+import type { CanonicalQuery, OgcApiFeaturesCompiledQueryV1, QueryIrSourceIdentity } from "./types.js";
+export type Cql2FilterLanguage = "cql2-json" | "cql2-text";
+/** Explicit metadata discovered for the concrete OGC API Features source. */
+export interface OgcApiFeaturesFilterConformanceEvidence {
+    /** Exact `/conformance` response values. No protocol defaults are inferred. */
+    readonly conformsTo: readonly string[];
+    /** Collection/filter CRS identifiers discovered from Part 2/OpenAPI metadata. */
+    readonly supportedFilterCrs?: readonly string[];
+    /** Collection response CRS identifiers discovered from Part 2 metadata. */
+    readonly supportedOutputCrs?: readonly string[];
+}
+export interface SemanticOgcApiFeaturesSourceIdentity {
+    readonly collectionId: string | number;
+}
+export interface SemanticOgcApiFeaturesCompileOptions<TRecord = Record<string, unknown>, TSpatiality extends SourceSpatiality = SourceSpatiality> {
+    readonly query: SemanticQuery<TRecord, "ogc-features", TSpatiality>;
+    readonly schema: SourceSchemaV2;
+    readonly source: SemanticOgcApiFeaturesSourceIdentity;
+    readonly conformance: OgcApiFeaturesFilterConformanceEvidence;
+    /** Deterministic preference used only when both encodings were explicitly discovered. */
+    readonly preferredFilterLanguage?: Cql2FilterLanguage;
+    /** External CRS context for a native CQL2 escape hatch. Semantic spatial nodes carry their own binding. */
+    readonly nativeFilterCrs?: ExecutableCrsBinding;
+}
+/** Canonical, wire-ready OGC API Features `/items` request semantics. */
+export interface SemanticOgcApiFeaturesCompiledQueryV1 {
+    readonly compiler: "ogc-api-features-semantic-query-v1";
+    readonly dialect?: Cql2FilterLanguage;
+    readonly schemaFingerprint: SourceSchemaV2["fingerprint"];
+    readonly queryFingerprint: `sha256:${string}`;
+    readonly capabilityFingerprint: `sha256:${string}`;
+    readonly requestFingerprint: `sha256:${string}`;
+    readonly collectionId: string | number;
+    /** Text value for the `filter` query parameter; JSON is canonical JSON text. */
+    readonly filter?: string;
+    readonly filterLang?: Cql2FilterLanguage;
+    readonly filterCrs?: string;
+    readonly crs?: string;
+    readonly limit?: number;
+    readonly usesNativeFilter: boolean;
+}
+/**
+ * Compile canonical query IR to an OGC API Features `/items` request. The
+ * compiler is side-effect free and deliberately supports only semantics the
+ * first-party OGC adapter can preserve exactly.
+ */
+export declare function compileOgcApiFeaturesQuery(source: QueryIrSourceIdentity, query: CanonicalQuery): OgcApiFeaturesCompiledQueryV1;
+/** Compile a typed semantic query using only explicitly discovered OGC/CQL2 support. */
+export declare function compileSemanticOgcApiFeaturesQuery<TRecord, TSpatiality extends SourceSpatiality>(options: SemanticOgcApiFeaturesCompileOptions<TRecord, TSpatiality>): SemanticCompilationResult<SemanticOgcApiFeaturesCompiledQueryV1>;
+//# sourceMappingURL=ogc-features.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ogc-features.d.ts","sourceRoot":"","sources":["../../../src/query-planner/ogc-features.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAA2B,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAqB3G,OAAO,EAEL,KAAK,yBAAyB,EAI/B,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAGV,aAAa,EACb,gBAAgB,EAEjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,cAAc,EAAE,6BAA6B,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAGvG,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,WAAW,CAAC;AAE3D,6EAA6E;AAC7E,MAAM,WAAW,uCAAuC;IACtD,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,iFAAiF;IACjF,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChD,2EAA2E;IAC3E,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACjD;AAED,MAAM,WAAW,oCAAoC;IACnD,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;CACxC;AAED,MAAM,WAAW,oCAAoC,CACnD,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,WAAW,SAAS,gBAAgB,GAAG,gBAAgB;IAEvD,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,OAAO,EAAE,cAAc,EAAE,WAAW,CAAC,CAAC;IACpE,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,oCAAoC,CAAC;IACtD,QAAQ,CAAC,WAAW,EAAE,uCAAuC,CAAC;IAC9D,yFAAyF;IACzF,QAAQ,CAAC,uBAAuB,CAAC,EAAE,kBAAkB,CAAC;IACtD,2GAA2G;IAC3G,QAAQ,CAAC,eAAe,CAAC,EAAE,oBAAoB,CAAC;CACjD;AAED,yEAAyE;AACzE,MAAM,WAAW,qCAAqC;IACpD,QAAQ,CAAC,QAAQ,EAAE,oCAAoC,CAAC;IACxD,QAAQ,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,iBAAiB,EAAE,cAAc,CAAC,aAAa,CAAC,CAAC;IAC1D,QAAQ,CAAC,gBAAgB,EAAE,UAAU,MAAM,EAAE,CAAC;IAC9C,QAAQ,CAAC,qBAAqB,EAAE,UAAU,MAAM,EAAE,CAAC;IACnD,QAAQ,CAAC,kBAAkB,EAAE,UAAU,MAAM,EAAE,CAAC;IAChD,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;IACvC,gFAAgF;IAChF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,kBAAkB,CAAC;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;CACpC;AAuED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,qBAAqB,EAC7B,KAAK,EAAE,cAAc,GACpB,6BAA6B,CAuC/B;AAED,wFAAwF;AACxF,wBAAgB,kCAAkC,CAAC,OAAO,EAAE,WAAW,SAAS,gBAAgB,EAC9F,OAAO,EAAE,oCAAoC,CAAC,OAAO,EAAE,WAAW,CAAC,GAClE,yBAAyB,CAAC,qCAAqC,CAAC,CAiDlE"}