@honua/sdk-esri-compat 0.1.12 → 0.1.13

package/query-planner/resource.js

@@ -0,0 +1,526 @@
+import { HonuaAbortError } from "../core/errors.js";
+import { canonicalStringify, sha256, toJsonValue } from "./canonical.js";
+import { HonuaQueryPlanExecutionError } from "./types.js";
+/** Discriminant for versioned, serializable query resource handles. */
+export const QUERY_RESOURCE_HANDLE_KIND = "honua.query-resource";
+/** First opaque query resource handle format. */
+export const QUERY_RESOURCE_HANDLE_VERSION = "1.0";
+const DEFAULT_MAX_ENTRIES = 256;
+const HARD_MAX_ENTRIES = 4_096;
+const MAX_SOURCE_COUNT = 64;
+const MAX_SOURCE_BYTES = 16_384;
+const MAX_TOTAL_SOURCE_BYTES = 131_072;
+const MAX_RESOLVER_LENGTH = 255;
+const MAX_IDENTITY_LENGTH = 256;
+const EXTENSION_IDENTIFIER_PATTERN = /^[a-z0-9](?:[a-z0-9_-]*\.)+[a-z0-9][a-z0-9_-]*$/;
+const RESOURCE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:~-]*$/;
+const AUTHORIZATION_CONTEXT_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:/~-]*$/;
+const JWT_SHAPE = /^eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}$/;
+const INVALID_HANDLE_MESSAGE = "GeoParquet resource handle is invalid";
+const RESOURCE_UNAVAILABLE_MESSAGE = "GeoParquet resource is unavailable";
+const RESOURCE_EXPIRED_MESSAGE = "GeoParquet resource authorization has expired";
+const RESOLUTION_FAILED_MESSAGE = "GeoParquet resource resolution failed";
+const INVALID_REGISTRY_OPTIONS_MESSAGE = "GeoParquet resource registry options are invalid";
+const INVALID_REGISTRATION_MESSAGE = "GeoParquet resource registration is invalid";
+const EXPIRED_ENTRY = Object.freeze({ state: "expired" });
+/** Create a credential-free handle without registering or resolving a locator. */
+export function createGeoParquetResourceHandle(input) {
+    const parsed = inspectRecord(input, ["resolver", "id", "authorizationContextId"], ["resourceVersion"]);
+    if (!parsed)
+        throw invalidHandle();
+    return parseGeoParquetResourceHandle({
+        kind: QUERY_RESOURCE_HANDLE_KIND,
+        version: QUERY_RESOURCE_HANDLE_VERSION,
+        protocol: "geoparquet",
+        resource: {
+            kind: "resolver",
+            resolver: parsed.get("resolver"),
+            id: parsed.get("id"),
+        },
+        authorizationContextId: parsed.get("authorizationContextId"),
+        ...(parsed.has("resourceVersion") ? { resourceVersion: parsed.get("resourceVersion") } : {}),
+    });
+}
+/** Parse an exact v1 handle without invoking accessors or retaining rejected input. */
+export function parseGeoParquetResourceHandle(value) {
+    const parsed = inspectRecord(value, ["kind", "version", "protocol", "resource", "authorizationContextId"], ["resourceVersion"]);
+    if (!parsed)
+        throw invalidHandle();
+    const resource = inspectRecord(parsed.get("resource"), ["kind", "resolver", "id"]);
+    const resolver = resource?.get("resolver");
+    const id = resource?.get("id");
+    const authorizationContextId = parsed.get("authorizationContextId");
+    const resourceVersion = parsed.get("resourceVersion");
+    const hasResourceVersion = parsed.has("resourceVersion");
+    if (parsed.get("kind") !== QUERY_RESOURCE_HANDLE_KIND ||
+        parsed.get("version") !== QUERY_RESOURCE_HANDLE_VERSION ||
+        parsed.get("protocol") !== "geoparquet" ||
+        resource?.get("kind") !== "resolver" ||
+        !isResolverIdentifier(resolver) ||
+        !isResourceIdentity(id) ||
+        !isAuthorizationContextId(authorizationContextId)) {
+        throw invalidHandle();
+    }
+    let normalizedResourceVersion;
+    if (hasResourceVersion) {
+        if (!isResourceIdentity(resourceVersion))
+            throw invalidHandle();
+        normalizedResourceVersion = resourceVersion;
+    }
+    return freezeHandle({
+        resource: { resolver, id },
+        authorizationContextId,
+        ...(normalizedResourceVersion !== undefined ? { resourceVersion: normalizedResourceVersion } : {}),
+    });
+}
+/** Stable credential-free fingerprint for plan/cache identity. */
+export function hashGeoParquetResourceHandle(value) {
+    const handle = parseGeoParquetResourceHandle(value);
+    return sha256(canonicalStringify(toJsonValue(handle)));
+}
+/**
+ * Resolve a handle through an injected resolver after enforcing scope,
+ * cancellation, output bounds, and fixed-message error redaction.
+ */
+export async function resolveGeoParquetResource(value, resolver, context) {
+    const handle = parseGeoParquetResourceHandle(value);
+    const safeContext = parseResolutionContext(context);
+    if (typeof resolver !== "function")
+        throw resolutionFailed();
+    if (isSignalAborted(safeContext.signal))
+        throw new HonuaAbortError();
+    if (safeContext.authorizationContextId !== handle.authorizationContextId)
+        throw resourceUnavailable();
+    let pending;
+    try {
+        pending = resolver(handle, safeContext);
+    }
+    catch (error) {
+        throw normalizeResolverFailure(error, safeContext.signal);
+    }
+    let resolved;
+    try {
+        resolved = await awaitAbortable(pending, safeContext.signal);
+    }
+    catch (error) {
+        throw normalizeResolverFailure(error, safeContext.signal);
+    }
+    const output = inspectRecord(resolved, ["sources"]);
+    const sources = output ? copyBoundedSources(output.get("sources")) : undefined;
+    if (!sources)
+        throw resolutionFailed();
+    return Object.freeze({ sources });
+}
+/** Create a bounded in-memory registry for private, rotation-friendly locators. */
+export function createGeoParquetResourceRegistry(options) {
+    const parsedOptions = inspectRecord(options, ["resolver"], ["maxEntries", "now"]);
+    const resolverId = parsedOptions?.get("resolver");
+    const configuredMaxEntries = parsedOptions?.get("maxEntries");
+    const configuredNow = parsedOptions?.get("now");
+    if (!parsedOptions ||
+        !isResolverIdentifier(resolverId) ||
+        (configuredMaxEntries !== undefined && !isMaxEntries(configuredMaxEntries)) ||
+        (configuredNow !== undefined && !isClock(configuredNow))) {
+        throw new TypeError(INVALID_REGISTRY_OPTIONS_MESSAGE);
+    }
+    const maxEntries = configuredMaxEntries ?? DEFAULT_MAX_ENTRIES;
+    const now = configuredNow ?? Date.now;
+    const entries = new Map();
+    let disposed = false;
+    let readingClock = false;
+    const readCurrentTime = () => {
+        if (readingClock)
+            throw resolutionFailed();
+        readingClock = true;
+        try {
+            return readClock(now);
+        }
+        finally {
+            readingClock = false;
+        }
+    };
+    const resolver = (handleValue, contextValue) => {
+        const handle = parseGeoParquetResourceHandle(handleValue);
+        const context = parseResolutionContext(contextValue);
+        if (isSignalAborted(context.signal))
+            throw new HonuaAbortError();
+        if (context.authorizationContextId !== handle.authorizationContextId ||
+            handle.resource.resolver !== resolverId ||
+            disposed) {
+            throw resourceUnavailable();
+        }
+        const key = resourceKey(handle);
+        const entry = entries.get(key);
+        if (!entry)
+            throw resourceUnavailable();
+        if (entry.state === "expired")
+            throw resourceExpired();
+        if (entry.expiresAt !== undefined) {
+            const currentTime = readCurrentTime();
+            if (disposed || entries.get(key) !== entry)
+                throw resourceUnavailable();
+            if (currentTime >= entry.expiresAt) {
+                entries.set(key, EXPIRED_ENTRY);
+                throw resourceExpired();
+            }
+        }
+        return Object.freeze({ sources: entry.sources });
+    };
+    const registry = {
+        register(input) {
+            if (disposed)
+                throw resourceUnavailable();
+            const registration = parseRegistration(input);
+            const handle = freezeHandle({
+                resource: { resolver: resolverId, id: registration.id },
+                authorizationContextId: registration.authorizationContextId,
+                ...(registration.resourceVersion !== undefined ? { resourceVersion: registration.resourceVersion } : {}),
+            });
+            const key = resourceKey(handle);
+            if (!entries.has(key) && entries.size >= maxEntries)
+                reclaimExpiredEntries(entries, maxEntries);
+            if (!entries.has(key) && entries.size >= maxEntries && hasExpiringEntries(entries)) {
+                const snapshot = [...entries.entries()];
+                const currentTime = readCurrentTime();
+                if (disposed || !entriesMatchSnapshot(entries, snapshot))
+                    throw resourceUnavailable();
+                reclaimExpiredEntries(entries, maxEntries, currentTime);
+            }
+            if (!entries.has(key) && entries.size >= maxEntries)
+                throw resourceUnavailable();
+            entries.set(key, Object.freeze({
+                state: "active",
+                sources: registration.sources,
+                ...(registration.expiresAt !== undefined ? { expiresAt: registration.expiresAt } : {}),
+            }));
+            return handle;
+        },
+        resolver,
+        revoke(handleValue) {
+            const handle = parseGeoParquetResourceHandle(handleValue);
+            if (handle.resource.resolver === resolverId)
+                entries.delete(resourceKey(handle));
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            entries.clear();
+        },
+    };
+    return Object.freeze(registry);
+}
+function parseRegistration(input) {
+    const parsed = inspectRecord(input, ["id", "authorizationContextId", "sources"], ["resourceVersion", "expiresAt"]);
+    const id = parsed?.get("id");
+    const authorizationContextId = parsed?.get("authorizationContextId");
+    const resourceVersion = parsed?.get("resourceVersion");
+    const expiresAt = parsed?.get("expiresAt");
+    const sources = parsed ? copyBoundedSources(parsed.get("sources")) : undefined;
+    if (!parsed ||
+        !isResourceIdentity(id) ||
+        !isAuthorizationContextId(authorizationContextId) ||
+        (resourceVersion !== undefined && !isResourceIdentity(resourceVersion)) ||
+        (expiresAt !== undefined && !isEpochMilliseconds(expiresAt)) ||
+        !sources) {
+        throw new TypeError(INVALID_REGISTRATION_MESSAGE);
+    }
+    return {
+        id,
+        authorizationContextId,
+        ...(resourceVersion !== undefined ? { resourceVersion } : {}),
+        sources,
+        ...(expiresAt !== undefined ? { expiresAt } : {}),
+    };
+}
+function parseResolutionContext(value) {
+    const parsed = inspectRecord(value, ["authorizationContextId"], ["signal"]);
+    const authorizationContextId = parsed?.get("authorizationContextId");
+    const signal = parsed?.get("signal");
+    if (!parsed ||
+        !isAuthorizationContextId(authorizationContextId) ||
+        (signal !== undefined && !isAbortSignal(signal))) {
+        throw resourceUnavailable();
+    }
+    return Object.freeze({
+        authorizationContextId,
+        ...(signal !== undefined ? { signal } : {}),
+    });
+}
+function freezeHandle(input) {
+    const resource = Object.freeze({
+        kind: "resolver",
+        resolver: input.resource.resolver,
+        id: input.resource.id,
+    });
+    return Object.freeze({
+        kind: QUERY_RESOURCE_HANDLE_KIND,
+        version: QUERY_RESOURCE_HANDLE_VERSION,
+        protocol: "geoparquet",
+        resource,
+        authorizationContextId: input.authorizationContextId,
+        ...(input.resourceVersion !== undefined ? { resourceVersion: input.resourceVersion } : {}),
+    });
+}
+function resourceKey(handle) {
+    return canonicalStringify(toJsonValue([
+        handle.resource.resolver,
+        handle.resource.id,
+        handle.authorizationContextId,
+        handle.resourceVersion ?? null,
+    ]));
+}
+function reclaimExpiredEntries(entries, maxEntries, currentTime) {
+    for (const [key, entry] of entries) {
+        if (entry.state === "expired" ||
+            (currentTime !== undefined && entry.expiresAt !== undefined && currentTime >= entry.expiresAt)) {
+            entries.delete(key);
+        }
+        if (entries.size < maxEntries)
+            return;
+    }
+}
+function hasExpiringEntries(entries) {
+    for (const entry of entries.values()) {
+        if (entry.state === "active" && entry.expiresAt !== undefined)
+            return true;
+    }
+    return false;
+}
+function entriesMatchSnapshot(entries, snapshot) {
+    return entries.size === snapshot.length && snapshot.every(([key, entry]) => entries.get(key) === entry);
+}
+function inspectRecord(value, requiredKeys, optionalKeys = []) {
+    try {
+        if (value === null || typeof value !== "object" || Array.isArray(value))
+            return undefined;
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null)
+            return undefined;
+        const keys = Reflect.ownKeys(value);
+        if (keys.some((key) => typeof key !== "string"))
+            return undefined;
+        const allowed = new Set([...requiredKeys, ...optionalKeys]);
+        if (keys.length < requiredKeys.length || keys.length > allowed.size)
+            return undefined;
+        if (keys.some((key) => typeof key !== "string" || !allowed.has(key)))
+            return undefined;
+        const result = new Map();
+        for (const key of requiredKeys) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor || !descriptor.enumerable || !("value" in descriptor))
+                return undefined;
+            result.set(key, descriptor.value);
+        }
+        for (const key of optionalKeys) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor)
+                continue;
+            if (!descriptor.enumerable || !("value" in descriptor))
+                return undefined;
+            result.set(key, descriptor.value);
+        }
+        return result;
+    }
+    catch {
+        return undefined;
+    }
+}
+function copyBoundedSources(value) {
+    try {
+        if (!Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype)
+            return undefined;
+        const lengthDescriptor = Object.getOwnPropertyDescriptor(value, "length");
+        const length = lengthDescriptor && "value" in lengthDescriptor ? lengthDescriptor.value : undefined;
+        if (typeof length !== "number" || !Number.isInteger(length) || length < 1 || length > MAX_SOURCE_COUNT) {
+            return undefined;
+        }
+        const keys = Reflect.ownKeys(value);
+        if (keys.length !== length + 1 || keys.some((key) => typeof key !== "string"))
+            return undefined;
+        if (keys.some((key) => typeof key === "string" && key !== "length" && !isArrayIndex(key, length))) {
+            return undefined;
+        }
+        let totalBytes = 0;
+        const copy = [];
+        for (let index = 0; index < length; index++) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+            if (!descriptor || !descriptor.enumerable || !("value" in descriptor))
+                return undefined;
+            const source = descriptor.value;
+            if (typeof source !== "string" ||
+                source.length === 0 ||
+                source.length > MAX_SOURCE_BYTES ||
+                containsControlCharacter(source)) {
+                return undefined;
+            }
+            const bytes = new TextEncoder().encode(source).byteLength;
+            if (bytes > MAX_SOURCE_BYTES)
+                return undefined;
+            totalBytes += bytes;
+            if (totalBytes > MAX_TOTAL_SOURCE_BYTES)
+                return undefined;
+            copy.push(source);
+        }
+        return Object.freeze(copy);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isArrayIndex(key, length) {
+    if (!/^(?:0|[1-9][0-9]*)$/.test(key))
+        return false;
+    const index = Number(key);
+    return Number.isSafeInteger(index) && index >= 0 && index < length;
+}
+function containsControlCharacter(value) {
+    for (let index = 0; index < value.length; index++) {
+        const code = value.charCodeAt(index);
+        if (code <= 0x1f || code === 0x7f)
+            return true;
+    }
+    return false;
+}
+function isResolverIdentifier(value) {
+    return typeof value === "string" && value.length <= MAX_RESOLVER_LENGTH && EXTENSION_IDENTIFIER_PATTERN.test(value);
+}
+function isResourceIdentity(value) {
+    return (typeof value === "string" &&
+        value.length <= MAX_IDENTITY_LENGTH &&
+        RESOURCE_ID_PATTERN.test(value) &&
+        !JWT_SHAPE.test(value));
+}
+function isAuthorizationContextId(value) {
+    return (typeof value === "string" &&
+        value.length <= MAX_IDENTITY_LENGTH &&
+        AUTHORIZATION_CONTEXT_PATTERN.test(value) &&
+        !value.endsWith("/") &&
+        !value.includes("//") &&
+        !value.split("/").some((segment) => segment === "." || segment === "..") &&
+        !JWT_SHAPE.test(value));
+}
+function isMaxEntries(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= HARD_MAX_ENTRIES;
+}
+function isClock(value) {
+    return typeof value === "function";
+}
+function isEpochMilliseconds(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function isAbortSignal(value) {
+    try {
+        return (value !== null &&
+            typeof value === "object" &&
+            typeof value.aborted === "boolean" &&
+            typeof value.addEventListener === "function" &&
+            typeof value.removeEventListener === "function");
+    }
+    catch {
+        return false;
+    }
+}
+function isSignalAborted(signal) {
+    try {
+        return signal?.aborted === true;
+    }
+    catch {
+        throw resolutionFailed();
+    }
+}
+function readClock(now) {
+    try {
+        const value = now();
+        if (!isEpochMilliseconds(value))
+            throw resolutionFailed();
+        return value;
+    }
+    catch {
+        throw resolutionFailed();
+    }
+}
+function awaitAbortable(value, signal) {
+    const pending = Promise.resolve(value);
+    if (!signal)
+        return pending;
+    if (isSignalAborted(signal)) {
+        void pending.catch(() => undefined);
+        throw new HonuaAbortError();
+    }
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (callback) => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                signal.removeEventListener("abort", abort);
+            }
+            catch {
+                // The fixed failure below retains no foreign signal data.
+            }
+            callback();
+        };
+        const abort = () => finish(() => reject(new HonuaAbortError()));
+        try {
+            signal.addEventListener("abort", abort, { once: true });
+        }
+        catch {
+            void pending.catch(() => undefined);
+            finish(() => reject(resolutionFailed()));
+            return;
+        }
+        try {
+            if (isSignalAborted(signal)) {
+                abort();
+                void pending.catch(() => undefined);
+                return;
+            }
+        }
+        catch (error) {
+            void pending.catch(() => undefined);
+            finish(() => reject(error));
+            return;
+        }
+        pending.then((result) => finish(() => resolve(result)), (error) => finish(() => reject(error)));
+    });
+}
+function normalizeResolverFailure(error, signal) {
+    if (isSignalAborted(signal))
+        return new HonuaAbortError();
+    try {
+        if (error instanceof HonuaQueryPlanExecutionError) {
+            const code = ownDataProperty(error, "code");
+            if (code === "resource-unavailable")
+                return resourceUnavailable();
+            if (code === "resource-expired")
+                return resourceExpired();
+        }
+    }
+    catch {
+        // Proxy and cross-realm failures are projected to the same fixed error.
+    }
+    return resolutionFailed();
+}
+function ownDataProperty(value, key) {
+    try {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        return descriptor && "value" in descriptor ? descriptor.value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function invalidHandle() {
+    return new HonuaQueryPlanExecutionError("invalid-resource-handle", INVALID_HANDLE_MESSAGE);
+}
+function resourceUnavailable() {
+    return new HonuaQueryPlanExecutionError("resource-unavailable", RESOURCE_UNAVAILABLE_MESSAGE);
+}
+function resourceExpired() {
+    return new HonuaQueryPlanExecutionError("resource-expired", RESOURCE_EXPIRED_MESSAGE);
+}
+function resolutionFailed() {
+    return new HonuaQueryPlanExecutionError("resource-resolution-failed", RESOLUTION_FAILED_MESSAGE);
+}

package/query-planner/semantic-canonical.d.ts

@@ -0,0 +1,15 @@
+import type { CanonicalSemanticQueryOptions } from "./semantic-types.js";
+export declare const SEMANTIC_QUERY_CANONICAL_KIND: "honua.semantic-query-canonical";
+export declare const SEMANTIC_QUERY_CANONICAL_VERSION: 1;
+export declare const SEMANTIC_QUERY_HASH_DOMAIN: "honua.semantic-query.hash.v1";
+/**
+ * Serialize a validated semantic query plus its schema/CRS/policy identity.
+ * Object keys are UTF-8 deterministically ordered; array order stays
+ * significant. Volatile execution state is not accepted by the semantic AST.
+ */
+export declare function serializeCanonicalSemanticQuery(value: unknown, options?: CanonicalSemanticQueryOptions): string;
+/** Return a fresh UTF-8 byte copy of the canonical semantic-query envelope. */
+export declare function canonicalSemanticQueryBytes(value: unknown, options?: CanonicalSemanticQueryOptions): Uint8Array;
+/** Domain-separated SHA-256 identity for a canonical semantic query. */
+export declare function hashSemanticQuery(value: unknown, options?: CanonicalSemanticQueryOptions): `sha256:${string}`;
+//# sourceMappingURL=semantic-canonical.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-canonical.d.ts","sourceRoot":"","sources":["../../../src/query-planner/semantic-canonical.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,qBAAqB,CAAC;AAIzE,eAAO,MAAM,6BAA6B,EAAG,gCAAyC,CAAC;AACvF,eAAO,MAAM,gCAAgC,EAAG,CAAU,CAAC;AAC3D,eAAO,MAAM,0BAA0B,EAAG,8BAAuC,CAAC;AAKlF;;;;GAIG;AACH,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,6BAAkC,GAAG,MAAM,CAoBnH;AAED,+EAA+E;AAC/E,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,6BAAkC,GAAG,UAAU,CAEnH;AAED,wEAAwE;AACxE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,6BAAkC,GAAG,UAAU,MAAM,EAAE,CAEjH"}

package/query-planner/semantic-canonical.js

@@ -0,0 +1,62 @@
+import { parseSourceSchemaV2 } from "../contract/schema.js";
+import { canonicalStringify, sha256, toJsonValue } from "./canonical.js";
+import { parseSemanticQuery } from "./semantic.js";
+import { HonuaQueryPlanningError } from "./types.js";
+export const SEMANTIC_QUERY_CANONICAL_KIND = "honua.semantic-query-canonical";
+export const SEMANTIC_QUERY_CANONICAL_VERSION = 1;
+export const SEMANTIC_QUERY_HASH_DOMAIN = "honua.semantic-query.hash.v1";
+const MAX_IDENTITY_VERSION_BYTES = 4096;
+const TEXT_ENCODER = new TextEncoder();
+/**
+ * Serialize a validated semantic query plus its schema/CRS/policy identity.
+ * Object keys are UTF-8 deterministically ordered; array order stays
+ * significant. Volatile execution state is not accepted by the semantic AST.
+ */
+export function serializeCanonicalSemanticQuery(value, options = {}) {
+    const schema = verifiedSchema(options.schema);
+    const query = parseSemanticQuery(value, {
+        ...(schema ? { schema } : {}),
+        ...(options.protocol !== undefined ? { protocol: options.protocol } : {}),
+    });
+    const identity = {
+        schemaFingerprint: schema?.fingerprint ?? null,
+        crsVersion: identityVersion(options.crsVersion, "crsVersion"),
+        policyVersion: identityVersion(options.policyVersion, "policyVersion"),
+        protocol: options.protocol ?? null,
+    };
+    return canonicalStringify(toJsonValue({
+        kind: SEMANTIC_QUERY_CANONICAL_KIND,
+        version: SEMANTIC_QUERY_CANONICAL_VERSION,
+        identity,
+        query,
+    }));
+}
+/** Return a fresh UTF-8 byte copy of the canonical semantic-query envelope. */
+export function canonicalSemanticQueryBytes(value, options = {}) {
+    return TEXT_ENCODER.encode(serializeCanonicalSemanticQuery(value, options));
+}
+/** Domain-separated SHA-256 identity for a canonical semantic query. */
+export function hashSemanticQuery(value, options = {}) {
+    return sha256(`${SEMANTIC_QUERY_HASH_DOMAIN}\n${serializeCanonicalSemanticQuery(value, options)}`);
+}
+function verifiedSchema(value) {
+    if (value === undefined)
+        return undefined;
+    try {
+        return parseSourceSchemaV2(value);
+    }
+    catch {
+        throw new HonuaQueryPlanningError("invalid-query", "Canonical semantic-query identity requires a valid schema");
+    }
+}
+function identityVersion(value, name) {
+    if (value === undefined)
+        return null;
+    if (typeof value !== "string" || value.length === 0) {
+        throw new HonuaQueryPlanningError("invalid-query", `${name} must be a non-empty string when supplied`);
+    }
+    if (TEXT_ENCODER.encode(value).byteLength > MAX_IDENTITY_VERSION_BYTES) {
+        throw new HonuaQueryPlanningError("invalid-query", `${name} exceeds the ${MAX_IDENTITY_VERSION_BYTES}-byte bound`);
+    }
+    return value;
+}

package/query-planner/semantic-compat.d.ts

@@ -0,0 +1,10 @@
+import type { LegacyWhereDialectFor, LegacyWhereProtocol, NativeFilter } from "./semantic-types.js";
+/**
+ * Convert deprecated v1 `Query.where` text into an explicitly tagged native
+ * filter. This is a migration bridge, not a protocol-neutral parser.
+ *
+ * @deprecated Build a typed semantic filter instead. Keep this only while a
+ * v1 caller still owns protocol-native `where` text.
+ */
+export declare function legacyWhereToNativeFilter<TProtocol extends LegacyWhereProtocol>(protocol: TProtocol, where: string): NativeFilter<LegacyWhereDialectFor<TProtocol>>;
+//# sourceMappingURL=semantic-compat.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-compat.d.ts","sourceRoot":"","sources":["../../../src/query-planner/semantic-compat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAepG;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,SAAS,mBAAmB,EAC7E,QAAQ,EAAE,SAAS,EACnB,KAAK,EAAE,MAAM,GACZ,YAAY,CAAC,qBAAqB,CAAC,SAAS,CAAC,CAAC,CAsBhD"}

package/query-planner/semantic-compat.js

@@ -0,0 +1,35 @@
+import { parseSemanticQuery } from "./semantic.js";
+import { HonuaQueryPlanningError } from "./types.js";
+const LEGACY_WHERE_DIALECT = {
+    "geoservices-feature-service": "geoservices-sql92",
+    "geoservices-map-service": "geoservices-sql92",
+    "geoservices-image-service": "geoservices-sql92",
+    "ogc-features": "cql2-text",
+    "ogc-records": "cql2-text",
+    stac: "cql2-text",
+    odata: "odata-4.0",
+    geoparquet: "duckdb-sql",
+};
+/**
+ * Convert deprecated v1 `Query.where` text into an explicitly tagged native
+ * filter. This is a migration bridge, not a protocol-neutral parser.
+ *
+ * @deprecated Build a typed semantic filter instead. Keep this only while a
+ * v1 caller still owns protocol-native `where` text.
+ */
+export function legacyWhereToNativeFilter(protocol, where) {
+    const dialect = typeof protocol === "string" && Object.prototype.hasOwnProperty.call(LEGACY_WHERE_DIALECT, protocol)
+        ? LEGACY_WHERE_DIALECT[protocol]
+        : undefined;
+    if (!dialect) {
+        throw new HonuaQueryPlanningError("unsupported-query", "The supplied protocol has no lossless raw-where compatibility dialect");
+    }
+    if (typeof where !== "string" || where.trim().length === 0) {
+        throw new HonuaQueryPlanningError("invalid-query", "Legacy raw where must be a non-empty string");
+    }
+    const query = parseSemanticQuery({
+        kind: "features",
+        filter: { kind: "native", dialect, payload: { format: "text", text: where } },
+    }, { protocol });
+    return query.filter;
+}