@honua/react 0.0.20-alpha.0

package/core/odata.js

@@ -0,0 +1,913 @@
+/**
+ * OData v4 entity-set adapter. Wraps an OData entity set behind the shared
+ * `Source<T>` contract surface in `src/contract/source.ts`.
+ *
+ * Library posture is recorded in
+ * `docs/decisions/odata-library-selection.md`: the canonical surface is a
+ * thin URL/JSON serializer over `HonuaClient.pipelineFetch` /
+ * `pipelineRequestJson` (rather than the GeoServices-shaped
+ * `request()` helper, which would inject `f=json` and trip Honua
+ * Server's OData validators) so that the auth / retry / telemetry
+ * pipeline stays centralized. The dialect-specific `$batch` / `$apply`
+ * / `$search` / `$deltatoken` operations live behind the typed escape
+ * hatch returned by `Source.protocol("odata")`.
+ *
+ * @module
+ */
+import { createHonuaCacheState, honuaCacheValidatorFromHeaders, honuaMetadataRequestHeaders, isHonuaCacheEntryFresh, normalizeHonuaMetadataRequestOptions, withHonuaCacheState, withoutHonuaCacheState, } from "./cache-state.js";
+import { trimTrailingSlashes } from "./path-utils.js";
+// ── Runtime class ─────────────────────────────────────────────
+/**
+ * Runtime handle for one OData entity set. Returned by
+ * `Source.protocol("odata")` so callers can reach the dialect-specific
+ * surface (`$batch`, `$apply`, `$search`, `$deltatoken`) without leaking
+ * OData-shaped types into the canonical `Source` API.
+ */
+export class HonuaOdataEntitySet {
+    client;
+    entitySet;
+    /**
+     * Unqualified entity-set name used as the CSDL metadata-lookup key.
+     * Equals `entitySet` for direct paths like `"Parcels"`. For
+     * layer-scoped navigation paths like `"Layers(1)/Features"` it is the
+     * navigation suffix `"Features"` so capability and schema lookups
+     * still find the entry the server emits in `<EntitySet Name="…">`.
+     */
+    entitySetName;
+    basePath;
+    cachedMetadata;
+    inflightMetadata;
+    constructor(options) {
+        this.client = options.client;
+        this.entitySet = options.entitySet;
+        this.entitySetName = extractEntitySetName(options.entitySet);
+        this.basePath = normalizeBasePath(options.basePath);
+    }
+    /**
+     * Fetch (and cache) the `$metadata` document. The cache is per
+     * `HonuaOdataEntitySet` instance so callers can pin a metadata snapshot
+     * to a long-lived `Source` without re-parsing on every request.
+     */
+    async metadata(options = {}) {
+        const metadataOptions = normalizeHonuaMetadataRequestOptions(options);
+        const bypass = metadataOptions.cache === "bypass";
+        const now = Date.now();
+        const freshCachedMetadata = this.cachedMetadata
+            ? isHonuaCacheEntryFresh(this.cachedMetadata.cachedAtMs, now, metadataOptions.ttlMs)
+            : false;
+        if (!bypass && !metadataOptions.refresh && this.cachedMetadata && freshCachedMetadata) {
+            return withOdataMetadataCacheState(this.cachedMetadata, "hit", {
+                now,
+                ttlMs: metadataOptions.ttlMs,
+                staleIfErrorMs: metadataOptions.staleIfErrorMs,
+            });
+        }
+        if (!bypass && !metadataOptions.refresh && this.inflightMetadata)
+            return this.inflightMetadata;
+        const previous = this.cachedMetadata;
+        const promise = this.fetchMetadata(metadataOptions, previous).then((entry) => {
+            if (!bypass) {
+                this.cachedMetadata = entry;
+            }
+            const status = bypass ? "bypass" : entry.status;
+            return withOdataMetadataCacheState(entry, status, {
+                now: Date.now(),
+                ttlMs: metadataOptions.ttlMs,
+                staleIfErrorMs: metadataOptions.staleIfErrorMs,
+                ...(status === "refreshed" ? { revalidatedAt: new Date().toISOString() } : {}),
+            });
+        });
+        const staleFallback = (error) => {
+            if (!bypass && metadataOptions.staleIfError && previous) {
+                return withOdataMetadataCacheState(previous, "stale", {
+                    now: Date.now(),
+                    ttlMs: metadataOptions.ttlMs,
+                    staleIfErrorMs: metadataOptions.staleIfErrorMs,
+                    refreshErrorId: odataMetadataRefreshErrorId(error),
+                });
+            }
+            throw error;
+        };
+        if (!bypass && !metadataOptions.refresh) {
+            const trackedPromise = promise.catch(staleFallback).finally(() => {
+                if (this.inflightMetadata === trackedPromise)
+                    this.inflightMetadata = undefined;
+            });
+            this.inflightMetadata = trackedPromise;
+            return trackedPromise;
+        }
+        try {
+            return await promise;
+        }
+        catch (error) {
+            return staleFallback(error);
+        }
+    }
+    /** Fetch one page of the entity set. */
+    async query(params = {}) {
+        const path = this.entitySetPath();
+        const query = serializeQueryParams(params);
+        const body = await this.requestJson("GET", path, query, params.signal);
+        return {
+            rows: body.value ?? [],
+            ...(typeof body["@odata.count"] === "number" ? { totalCount: body["@odata.count"] } : {}),
+            ...(typeof body["@odata.nextLink"] === "string" ? { nextLink: body["@odata.nextLink"] } : {}),
+            ...(typeof body["@odata.deltaLink"] === "string" ? { deltaLink: body["@odata.deltaLink"] } : {}),
+        };
+    }
+    /**
+     * Drain server-driven `@odata.nextLink` pages. When `params.top` is
+     * supplied it is treated as a hard cap on collected rows. Callers that
+     * want a lookahead row to detect truncation must add it themselves; the
+     * canonical `Source.queryAll` path does this with `top = limit + 1`,
+     * while ids-only projections enforce their own result cap.
+     * Returning `top + 1` here would double-count for callers that already
+     * added the lookahead, so this helper respects `top` exactly.
+     */
+    async queryAll(params = {}) {
+        const cap = typeof params.top === "number" && params.top >= 0 ? params.top : undefined;
+        const collected = [];
+        let totalCount;
+        let next;
+        let firstPageParams = params;
+        while (true) {
+            const page = next
+                ? await this.followNextLink(next, params.signal)
+                : await this.query(firstPageParams ?? {});
+            firstPageParams = undefined;
+            if (totalCount === undefined && typeof page.totalCount === "number") {
+                totalCount = page.totalCount;
+            }
+            for (const row of page.rows) {
+                if (cap !== undefined && collected.length >= cap)
+                    break;
+                collected.push(row);
+                if (cap !== undefined && collected.length >= cap)
+                    break;
+            }
+            if (cap !== undefined && collected.length >= cap)
+                break;
+            if (!page.nextLink)
+                break;
+            next = page.nextLink;
+        }
+        return totalCount === undefined ? { rows: collected } : { rows: collected, totalCount };
+    }
+    /** Yield one page per server response. Used by `Source.stream()`. */
+    async *queryStream(params = {}) {
+        let page = await this.query(params);
+        yield page;
+        while (page.nextLink) {
+            page = await this.followNextLink(page.nextLink, params.signal);
+            yield page;
+        }
+    }
+    /** Insert a row via `POST /<entitySet>`. */
+    async add(body, options = {}) {
+        const path = this.entitySetPath();
+        return this.requestJson("POST", path, undefined, options.signal, JSON.stringify(body), {
+            "Content-Type": "application/json",
+        });
+    }
+    /**
+     * Update a row via `PATCH /<entitySet>(<key>)`. The OData server in
+     * Honua Server intentionally does not implement `PUT`; the SDK issues
+     * `PATCH` with the full canonical body to match a `PUT` replacement on
+     * the canonical surface (documented in
+     * `docs/protocol-capability-matrix.md` under the OData section).
+     */
+    async update(key, body, options = {}) {
+        const path = `${this.entitySetPath()}(${encodeOdataKey(key)})`;
+        return this.requestJson("PATCH", path, undefined, options.signal, JSON.stringify(body), {
+            "Content-Type": "application/json",
+        });
+    }
+    /** Delete a row via `DELETE /<entitySet>(<key>)`. */
+    async delete(key, options = {}) {
+        const path = `${this.entitySetPath()}(${encodeOdataKey(key)})`;
+        await this.requestJson("DELETE", path, undefined, options.signal);
+    }
+    /**
+     * Submit a `$batch` request using the OData JSON batch format.
+     * Multipart/mixed fallback is intentionally not implemented; Honua
+     * Server emits both formats but the JSON envelope is sufficient for
+     * the canonical surface and avoids the multipart parser.
+     *
+     * `atomicity: "all"` stamps the same `atomicityGroup` token on every
+     * request so the server runs them in one change-set with rollback on
+     * any failure (per OData v4 §11.7.7.3 and Honua Server's
+     * `ODataBatchHandler`, which groups by `request.AtomicityGroup`).
+     * `atomicity: "none"` (default) leaves the field unset so each request
+     * runs independently.
+     */
+    async batch(operations, options = {}) {
+        if (operations.length === 0)
+            return { responses: [] };
+        const groupId = options.atomicity === "all" ? "g1" : undefined;
+        const requests = operations.map((op, index) => ({
+            id: op.id ?? String(index + 1),
+            method: op.method,
+            url: stripLeadingSlash(op.url),
+            ...(op.headers
+                ? { headers: { "Content-Type": "application/json", ...op.headers } }
+                : {
+                    headers: { "Content-Type": "application/json" },
+                }),
+            ...(op.body !== undefined ? { body: op.body } : {}),
+            ...(groupId !== undefined ? { atomicityGroup: groupId } : {}),
+        }));
+        const response = await this.requestJson("POST", `${this.basePath}/$batch`, undefined, options.signal, JSON.stringify({ requests }), { "Content-Type": "application/json" });
+        return { responses: response.responses ?? [] };
+    }
+    /**
+     * Run an `$apply` aggregation. The OData server applies the
+     * transformation pipeline (`aggregate`, `groupby`, `filter`,
+     * `compute`); the SDK returns the rows unchanged so callers can shape
+     * them onto the canonical `Result.aggregateRows`.
+     */
+    async apply(transformations, params = {}) {
+        const path = this.entitySetPath();
+        const query = serializeQueryParams({ apply: transformations, filter: params.filter });
+        const body = await this.requestJson("GET", path, query, params.signal);
+        return {
+            rows: body.value ?? [],
+            ...(typeof body["@odata.count"] === "number" ? { totalCount: body["@odata.count"] } : {}),
+        };
+    }
+    /**
+     * Run a `$search` full-text query. Returns an `HonuaOdataPage` so the
+     * canonical `Result<T>` projection is symmetric with `query()`.
+     */
+    async search(text, params = {}) {
+        return this.query({ ...params, search: text });
+    }
+    /**
+     * `$deltatoken`-driven change feed. Yields `HonuaOdataDeltaPage` per
+     * server response. The final page carries `deltaLink`; callers persist
+     * the encoded token for the next call to `delta({ since })`.
+     */
+    async *delta(options = {}) {
+        const params = options.since ? { deltatoken: options.since } : {};
+        if (options.signal)
+            params.signal = options.signal;
+        let page = await this.query(params);
+        yield {
+            rows: page.rows,
+            ...(page.nextLink ? { nextLink: page.nextLink } : {}),
+            ...(page.deltaLink ? { deltaLink: page.deltaLink } : {}),
+        };
+        while (page.nextLink) {
+            page = await this.followNextLink(page.nextLink, options.signal);
+            yield {
+                rows: page.rows,
+                ...(page.nextLink ? { nextLink: page.nextLink } : {}),
+                ...(page.deltaLink ? { deltaLink: page.deltaLink } : {}),
+            };
+        }
+    }
+    /**
+     * Last-resort raw passthrough — flows through `HonuaClient.pipelineFetch`
+     * so auth headers, retry, timeout, interceptors, telemetry, and
+     * normalized error mapping all apply. The returned `Response` is
+     * unconsumed; callers pick `.json()`, `.text()`, or `.arrayBuffer()`.
+     */
+    async raw(method, path, init = {}) {
+        const normalized = method.toUpperCase();
+        return this.client.pipelineFetch(normalized, ensureLeadingSlash(path), init);
+    }
+    // ── Internal ────────────────────────────────────────────────
+    entitySetPath() {
+        return `${this.basePath}/${this.entitySet}`;
+    }
+    async fetchMetadata(options, cached) {
+        // Route through pipelineFetch so auth headers, interceptors, retry,
+        // timeout, and normalized error handling all apply. The default
+        // pipeline does not impose an `Accept` header — we ask for XML
+        // explicitly because the OData `$metadata` route emits CSDL.
+        const response = await this.client.pipelineFetch("GET", `${this.basePath}/$metadata`, {
+            headers: honuaMetadataRequestHeaders({
+                accept: "application/xml",
+                refresh: options.refresh || Boolean(cached),
+                bypass: options.cache === "bypass",
+                validator: cached?.validator,
+            }),
+        }, options.signal, { okStatuses: [304] });
+        if (response.status === 304 && cached) {
+            const validator = honuaCacheValidatorFromHeaders(response.headers) ?? cached.validator;
+            return {
+                ...cached,
+                cachedAtMs: Date.now(),
+                ...(validator ? { validator } : {}),
+                status: "refreshed",
+            };
+        }
+        const xml = await response.text();
+        const validator = honuaCacheValidatorFromHeaders(response.headers);
+        const sourceUpdatedAt = response.headers.get("last-modified") ?? undefined;
+        return {
+            metadata: withoutHonuaCacheState(parseOdataMetadata(xml)),
+            cachedAtMs: Date.now(),
+            keyFingerprint: `metadata:odata:${this.basePath}:$metadata`,
+            status: options.cache === "bypass" ? "bypass" : cached ? "refreshed" : "miss",
+            ...(validator ? { validator } : {}),
+            ...(sourceUpdatedAt ? { sourceUpdatedAt } : {}),
+        };
+    }
+    async followNextLink(nextLink, signal) {
+        // OData servers may emit either an absolute URL or a relative one.
+        // Normalize through the same fetch path used by `query()` so retry,
+        // auth interceptors, and telemetry still apply.
+        const { path, query } = parseNextLink(nextLink, this.client.serverBaseUrl, this.basePath);
+        const body = await this.requestJson("GET", path, query, signal);
+        return {
+            rows: body.value ?? [],
+            ...(typeof body["@odata.count"] === "number" ? { totalCount: body["@odata.count"] } : {}),
+            ...(typeof body["@odata.nextLink"] === "string" ? { nextLink: body["@odata.nextLink"] } : {}),
+            ...(typeof body["@odata.deltaLink"] === "string" ? { deltaLink: body["@odata.deltaLink"] } : {}),
+        };
+    }
+    /**
+     * Wrap `HonuaClient.pipelineRequestJson` with OData-shaped query
+     * serialization so callers can pass parsed query bags. Critically this
+     * does **not** go through `HonuaClient.request` — that helper injects
+     * `f=json`, which Honua Server's OData validators reject as
+     * `InvalidQueryOption`. The OData server defaults to JSON when the
+     * request advertises `Accept: application/json` (the pipeline default).
+     */
+    async requestJson(method, path, query, signal, body, headers) {
+        const params = new URLSearchParams();
+        if (query) {
+            for (const [key, value] of Object.entries(query)) {
+                params.set(key, String(value));
+            }
+        }
+        const pathWithQuery = params.size > 0 ? `${path}?${params.toString()}` : path;
+        return this.client.pipelineRequestJson(method, pathWithQuery, {
+            ...(headers ? { headers } : {}),
+            ...(body !== undefined ? { body } : {}),
+        }, signal);
+    }
+}
+// ── Helpers ───────────────────────────────────────────────────
+function withOdataMetadataCacheState(entry, status, options) {
+    return withHonuaCacheState(entry.metadata, createHonuaCacheState({
+        scope: "metadata",
+        status,
+        keyFingerprint: entry.keyFingerprint,
+        ageMs: Math.max(0, options.now - entry.cachedAtMs),
+        ...(options.ttlMs !== undefined ? { ttlMs: options.ttlMs } : {}),
+        ...(options.staleIfErrorMs !== undefined ? { staleIfErrorMs: options.staleIfErrorMs } : {}),
+        ...(options.revalidatedAt ? { revalidatedAt: options.revalidatedAt } : {}),
+        ...(entry.sourceUpdatedAt ? { sourceUpdatedAt: entry.sourceUpdatedAt } : {}),
+        ...(entry.validator ? { validator: entry.validator } : {}),
+        ...(options.refreshErrorId ? { refreshErrorId: options.refreshErrorId } : {}),
+    }));
+}
+function odataMetadataRefreshErrorId(error) {
+    if (error instanceof Error && error.name) {
+        return error.name;
+    }
+    return "unknown";
+}
+function normalizeBasePath(path) {
+    if (path === undefined || path === "")
+        return "/odata";
+    return path.startsWith("/") ? trimTrailingSlashes(path) || "/" : `/${trimTrailingSlashes(path)}`;
+}
+/**
+ * Extract the unqualified entity-set name from a path-shaped token.
+ * Direct identifiers (`"Parcels"`) round-trip unchanged; navigation paths
+ * (`"Layers(1)/Features"`) collapse to the trailing segment so CSDL
+ * metadata lookups (which key by `<EntitySet Name="…">`) still hit.
+ */
+function extractEntitySetName(path) {
+    const slash = path.lastIndexOf("/");
+    return slash === -1 ? path : path.slice(slash + 1);
+}
+function ensureLeadingSlash(path) {
+    return path.startsWith("/") ? path : `/${path}`;
+}
+function stripLeadingSlash(path) {
+    return path.startsWith("/") ? path.slice(1) : path;
+}
+/**
+ * Make an OData entity key safe to interpolate into the URL path segment
+ * `<entitySet>(<key>)`. A raw key containing characters such as `&`, `?`,
+ * `#`, `/`, space, or `'` would otherwise split or mis-target the path
+ * (e.g. `Customers(A&B)`).
+ *
+ * The key is treated as an OData literal: single-quoted spans are kept as
+ * quoted string literals (with embedded `'` doubled per OData v4 §5.1.1.6.1),
+ * and structural characters that delimit composite keys (`,`, `=`) and
+ * literal quotes are preserved. Everything else is percent-encoded so the
+ * resulting segment is a single, correctly-targeted URL path component.
+ */
+function encodeOdataKey(key) {
+    const raw = String(key);
+    let out = "";
+    let inQuote = false;
+    for (let i = 0; i < raw.length; i += 1) {
+        const ch = raw[i];
+        if (ch === "'") {
+            // Toggle quoted-literal state and keep the (URL-safe) quote verbatim.
+            inQuote = !inQuote;
+            out += "'";
+            continue;
+        }
+        if (!inQuote && (ch === "," || ch === "=")) {
+            // Composite-key delimiters stay structural outside quoted spans.
+            out += ch;
+            continue;
+        }
+        // Percent-encode anything that is unsafe in a path segment. Unreserved
+        // characters (RFC 3986) pass through untouched.
+        if (/[A-Za-z0-9\-._~]/.test(ch)) {
+            out += ch;
+        }
+        else {
+            out += encodeURIComponent(ch);
+        }
+    }
+    return out;
+}
+/**
+ * Translate canonical query params onto the OData `$`-prefixed query
+ * string. Empty strings, undefined values, and zero-length lists are
+ * dropped so the URL stays minimal.
+ */
+function serializeQueryParams(params) {
+    const out = {};
+    if (params.filter !== undefined && params.filter !== "")
+        out.$filter = params.filter;
+    if (params.select && params.select.length > 0)
+        out.$select = params.select.join(",");
+    if (params.orderBy && params.orderBy.length > 0)
+        out.$orderby = params.orderBy.join(",");
+    if (typeof params.top === "number" && Number.isFinite(params.top))
+        out.$top = params.top;
+    if (typeof params.skip === "number" && Number.isFinite(params.skip) && params.skip > 0)
+        out.$skip = params.skip;
+    if (params.expand && params.expand.length > 0)
+        out.$expand = params.expand.join(",");
+    if (params.count)
+        out.$count = "true";
+    if (params.skiptoken !== undefined && params.skiptoken !== "")
+        out.$skiptoken = params.skiptoken;
+    if (params.search !== undefined && params.search !== "")
+        out.$search = params.search;
+    if (params.apply !== undefined && params.apply !== "")
+        out.$apply = params.apply;
+    if (params.deltatoken !== undefined && params.deltatoken !== "")
+        out.$deltatoken = params.deltatoken;
+    if (params.extra)
+        Object.assign(out, params.extra);
+    return out;
+}
+/**
+ * `@odata.nextLink` is either an absolute URL (preferred by spec) or a
+ * service-relative URL. Reduce it to the path + query bag the same fetch
+ * pipeline expects.
+ */
+function parseNextLink(link, serverBaseUrl, basePath) {
+    const absolute = link.startsWith("http://") || link.startsWith("https://")
+        ? new URL(link)
+        : new URL(link, `${ensureTrailingSlash(serverBaseUrl)}${stripLeadingSlash(basePath)}/`);
+    const path = absolute.pathname;
+    const query = {};
+    for (const [key, value] of absolute.searchParams)
+        query[key] = value;
+    return { path, query };
+}
+function ensureTrailingSlash(url) {
+    return url.endsWith("/") ? url : `${url}/`;
+}
+// ── EDMX (CSDL) parsing ───────────────────────────────────────
+/**
+ * Parse the subset of CSDL we need to power capability negotiation and
+ * key resolution: entity sets, entity-type keys, property names + types,
+ * `Edm.Geography` / `Edm.Geometry` typing, and `Capabilities.*`
+ * annotations. The XML is read via small regular expressions because we
+ * intentionally do not pull a DOM dep — the surface we read is
+ * well-defined by OData CSDL §6 and the Honua Server spec page.
+ */
+export function parseOdataMetadata(xml) {
+    const entitySets = {};
+    const keys = {};
+    const fields = {};
+    const capabilities = {};
+    // Sibling annotations: <Annotations Target="<schema>.<container>/<entitySet>">
+    // …</Annotations>. Honua Server emits Capabilities.* this way (next to
+    // the EntityContainer) rather than nesting them inside <EntitySet>, so
+    // capability negotiation must merge both shapes.
+    const siblingByEntitySet = new Map();
+    const siblingAnnotationsRe = /<Annotations\s+([^>]*?)>([\s\S]*?)<\/Annotations>/g;
+    for (const match of xml.matchAll(siblingAnnotationsRe)) {
+        const attrs = match[1] ?? "";
+        const target = readAttr(attrs, "Target");
+        if (!target)
+            continue;
+        const slash = target.lastIndexOf("/");
+        if (slash === -1)
+            continue;
+        const setName = target.slice(slash + 1);
+        if (!setName)
+            continue;
+        const body = match[2] ?? "";
+        const existing = siblingByEntitySet.get(setName);
+        siblingByEntitySet.set(setName, existing === undefined ? body : `${existing}\n${body}`);
+    }
+    // Entity sets: <EntitySet Name="Foo" EntityType="ns.FooEntity"/>
+    const entitySetRe = /<EntitySet\s+([^>]*?)\/>|<EntitySet\s+([^>]*?)>([\s\S]*?)<\/EntitySet>/g;
+    for (const match of xml.matchAll(entitySetRe)) {
+        const attrs = match[1] ?? match[2] ?? "";
+        const name = readAttr(attrs, "Name");
+        const type = readAttr(attrs, "EntityType");
+        if (!name || !type)
+            continue;
+        entitySets[name] = stripNamespace(type);
+        const inlineBody = match[3] ?? "";
+        const siblingBody = siblingByEntitySet.get(name) ?? "";
+        capabilities[name] = parseEntitySetAnnotations(`${inlineBody}\n${siblingBody}`);
+        siblingByEntitySet.delete(name);
+    }
+    // Capture annotations for entity sets that were not declared inline (e.g.
+    // when a server emits only the sibling block). The simple-name suffix
+    // from the Target still keys a capability entry so callers can find it.
+    for (const [setName, body] of siblingByEntitySet) {
+        capabilities[setName] = parseEntitySetAnnotations(body);
+    }
+    // Entity types: <EntityType Name="FooEntity">…<Key><PropertyRef Name="Id"/></Key><Property…/>…</EntityType>
+    const entityTypeRe = /<EntityType\s+([^>]*?)>([\s\S]*?)<\/EntityType>/g;
+    for (const match of xml.matchAll(entityTypeRe)) {
+        const attrs = match[1] ?? "";
+        const body = match[2] ?? "";
+        const name = readAttr(attrs, "Name");
+        if (!name)
+            continue;
+        const keyNames = [];
+        const keyBlock = /<Key>([\s\S]*?)<\/Key>/.exec(body);
+        if (keyBlock) {
+            for (const ref of keyBlock[1].matchAll(/<PropertyRef\s+([^>]*?)\/>/g)) {
+                const refName = readAttr(ref[1], "Name");
+                if (refName)
+                    keyNames.push(refName);
+            }
+        }
+        keys[name] = keyNames;
+        const props = [];
+        for (const propMatch of body.matchAll(/<Property\s+([^>]*?)\/>|<Property\s+([^>]*?)>/g)) {
+            const propAttrs = propMatch[1] ?? propMatch[2] ?? "";
+            const propName = readAttr(propAttrs, "Name");
+            const propType = readAttr(propAttrs, "Type");
+            if (!propName || !propType)
+                continue;
+            const nullable = readAttr(propAttrs, "Nullable");
+            const sridAttr = readAttr(propAttrs, "SRID");
+            const isSpatial = propType.startsWith("Edm.Geography") || propType.startsWith("Edm.Geometry");
+            const info = { name: propName, type: propType };
+            if (nullable !== undefined)
+                info.nullable = nullable !== "false";
+            if (isSpatial)
+                info.isSpatial = true;
+            if (sridAttr !== undefined) {
+                const srid = Number(sridAttr);
+                if (Number.isFinite(srid))
+                    info.srid = srid;
+            }
+            props.push(info);
+        }
+        fields[name] = props;
+    }
+    return { entitySets, keys, fields, capabilities };
+}
+/**
+ * Convenience: project the field schema for one entity set into the
+ * canonical `HonuaFieldInfo[]` shape reused by `Result.fields`.
+ */
+export function odataFieldSchema(metadata, entitySet) {
+    const typeName = metadata.entitySets[entitySet];
+    if (!typeName)
+        return [];
+    const props = metadata.fields[typeName];
+    if (!props)
+        return [];
+    return props.map((p) => ({ name: p.name, type: edmToHonuaFieldType(p.type) }));
+}
+function edmToHonuaFieldType(edm) {
+    if (edm.startsWith("Edm.Geography") || edm.startsWith("Edm.Geometry"))
+        return "esriFieldTypeGeometry";
+    if (edm === "Edm.String")
+        return "esriFieldTypeString";
+    if (edm === "Edm.Int32")
+        return "esriFieldTypeInteger";
+    if (edm === "Edm.Int64")
+        return "esriFieldTypeOID";
+    if (edm === "Edm.Double")
+        return "esriFieldTypeDouble";
+    if (edm === "Edm.Single")
+        return "esriFieldTypeSingle";
+    if (edm === "Edm.Boolean")
+        return "esriFieldTypeSmallInteger";
+    if (edm === "Edm.DateTimeOffset" || edm === "Edm.Date")
+        return "esriFieldTypeDate";
+    return "esriFieldTypeString";
+}
+function parseEntitySetAnnotations(body) {
+    const out = {};
+    for (const match of body.matchAll(/<Annotation\s+([^>]*?)(?:\/>|>([\s\S]*?)<\/Annotation>)/g)) {
+        const attrs = match[1] ?? "";
+        const term = readAttr(attrs, "Term");
+        if (!term || !term.includes("Capabilities."))
+            continue;
+        const inner = (match[2] ?? "").trim();
+        const boolValue = readAttr(attrs, "Bool") ??
+            matchBool(inner) ??
+            matchPropertyValueBool(inner, "Insertable") ??
+            matchPropertyValueBool(inner, "Updatable") ??
+            matchPropertyValueBool(inner, "Deletable") ??
+            matchPropertyValueBool(inner, "Searchable") ??
+            matchPropertyValueBool(inner, "Filterable") ??
+            matchPropertyValueBool(inner, "Expandable") ??
+            matchPropertyValueBool(inner, "Selectable") ??
+            matchPropertyValueBool(inner, "Countable") ??
+            // Honua Server uses `Supported` for ChangeTracking and other
+            // capability records; without this fallback, `<PropertyValue
+            // Property="Supported" Bool="false"/>` would be silently treated
+            // as supported.
+            matchPropertyValueBool(inner, "Supported");
+        if (term.endsWith("InsertRestrictions")) {
+            out.insert = matchPropertyValueBool(inner, "Insertable") !== "false";
+        }
+        else if (term.endsWith("UpdateRestrictions")) {
+            out.update = matchPropertyValueBool(inner, "Updatable") !== "false";
+        }
+        else if (term.endsWith("DeleteRestrictions")) {
+            out.delete = matchPropertyValueBool(inner, "Deletable") !== "false";
+        }
+        else if (term.endsWith("BatchSupported") || term.endsWith("BatchSupport")) {
+            out.batch = boolValue !== "false";
+        }
+        else if (term.endsWith("FilterRestrictions") || term.endsWith("FilterFunctions")) {
+            out.filter = boolValue !== "false";
+        }
+        else if (term.endsWith("ExpandRestrictions")) {
+            out.expand = boolValue !== "false";
+        }
+        else if (term.endsWith("SelectSupport")) {
+            out.select = boolValue !== "false";
+        }
+        else if (term.endsWith("SearchRestrictions")) {
+            out.search = boolValue !== "false";
+        }
+        else if (term.endsWith("CountRestrictions")) {
+            out.count = boolValue !== "false";
+        }
+        else if (term.endsWith("ChangeTracking")) {
+            out.delta = boolValue !== "false";
+        }
+        else if (term.endsWith("ApplySupported") || term.endsWith("ApplyRestrictions")) {
+            out.apply = boolValue !== "false";
+        }
+    }
+    return out;
+}
+function readAttr(attrs, name) {
+    const re = new RegExp(`${name}\\s*=\\s*"([^"]*)"`);
+    const match = re.exec(attrs);
+    return match ? match[1] : undefined;
+}
+function stripNamespace(name) {
+    const idx = name.lastIndexOf(".");
+    return idx === -1 ? name : name.slice(idx + 1);
+}
+function matchBool(inner) {
+    const m = /<Bool>(true|false)<\/Bool>/.exec(inner);
+    return m ? m[1] : undefined;
+}
+function matchPropertyValueBool(inner, property) {
+    const re = new RegExp(`<PropertyValue\\s+Property="${property}"\\s+Bool="(true|false)"`);
+    const match = re.exec(inner);
+    return match ? match[1] : undefined;
+}
+const UNSUPPORTED_OPERATOR_RES = [
+    { token: "has", re: /\bhas\b/i },
+    { token: "in", re: /\bin\s*\(/i },
+    { token: "any", re: /\bany\s*\(/i },
+    { token: "all", re: /\ball\s*\(/i },
+    { token: "cast", re: /\bcast\s*\(/i },
+    { token: "isof", re: /\bisof\s*\(/i },
+];
+// ── SQL → OData filter rewrite ────────────────────────────────
+/**
+ * `Query.where` is documented as SQL-92 / CQL2 on the canonical surface.
+ * The OData `$filter` grammar is close to but not identical to SQL-92;
+ * this minimal rewriter handles the cases that would otherwise produce a
+ * server-side parse error rather than a translated query. Full SQL→OData
+ * translation is tracked as follow-up work in
+ * `docs/decisions/odata-library-selection.md`.
+ *
+ * Rewrites applied:
+ *  - `IS NULL` / `IS NOT NULL` → `eq null` / `ne null`
+ *  - `<col> = '...'`, `<col> = N` → `<col> eq '...'` / `<col> eq N`
+ *  - SQL-style `<>` → `ne`
+ *  - SQL comparison operators `>=` / `<=` / `>` / `<` → `ge` / `le` /
+ *    `gt` / `lt` (Honua Server's OData lexer rejects bare punctuation
+ *    comparisons as `InvalidQueryOption`).
+ *
+ * Predicates whose syntax already matches OData (e.g. `STATE eq 'CA'`)
+ * pass through unchanged. Unsupported operators (`HAS`, `IN`, `ANY`,
+ * `ALL`, `CAST`, `ISOF` from the parity matrix) are detected and
+ * rejected with a typed error rather than left to the server.
+ */
+export function rewriteWhereToOdataFilter(where) {
+    if (where === "" || where === "1=1")
+        return "";
+    // Tokenize into alternating non-literal / literal spans so the rewriter
+    // and unsupported-operator detector skip the contents of quoted string
+    // literals. Without this split, a value like `NAME = 'A=B'` would have
+    // its embedded `=` rewritten to ` eq `, corrupting the literal before it
+    // reaches `$filter`. OData uses single-quoted strings with `''` for
+    // embedded quotes (per OData v4 §5.1.1.6.1).
+    const spans = splitOdataLiteralSpans(where);
+    for (let idx = 0; idx < spans.length; idx += 2) {
+        const segment = spans[idx];
+        if (segment === "")
+            continue;
+        for (const banned of UNSUPPORTED_OPERATOR_RES) {
+            if (banned.re.test(segment)) {
+                throw new Error(`odata: $filter does not support "${banned.token}"; the parity matrix lists this operator as unsupported on Honua Server.`);
+            }
+        }
+        let out = segment;
+        out = out.replace(/\bIS\s+NOT\s+NULL\b/gi, "ne null");
+        out = out.replace(/\bIS\s+NULL\b/gi, "eq null");
+        // `<>` must be rewritten before bare `<` / `>` so the not-equal
+        // operator does not get split into `lt` / `gt`. Two-char operators
+        // (`>=` / `<=`) likewise come before bare `>` / `<`.
+        out = out.replace(/<>/g, "ne");
+        out = out.replace(/(\b\w+\b)\s*>=\s*/g, (_match, lhs) => `${lhs} ge `);
+        out = out.replace(/(\b\w+\b)\s*<=\s*/g, (_match, lhs) => `${lhs} le `);
+        out = out.replace(/(\b\w+\b)\s*>\s*/g, (_match, lhs) => `${lhs} gt `);
+        out = out.replace(/(\b\w+\b)\s*<\s*/g, (_match, lhs) => `${lhs} lt `);
+        out = out.replace(/(\b\w+\b)\s*=\s*/g, (_match, lhs) => `${lhs} eq `);
+        out = out.replace(/\bAND\b/gi, "and");
+        out = out.replace(/\bOR\b/gi, "or");
+        out = out.replace(/\bNOT\b/gi, "not");
+        spans[idx] = out;
+    }
+    return spans.join("").trim();
+}
+/**
+ * Split an OData `$filter`-style expression into alternating non-literal
+ * and literal spans. Even indices contain code; odd indices contain
+ * single-quoted string literals (with quotes preserved). Embedded `''`
+ * escape sequences inside a literal are kept verbatim. An unterminated
+ * literal is treated as if it ran to the end of the input.
+ */
+function splitOdataLiteralSpans(input) {
+    const spans = [];
+    let buf = "";
+    let i = 0;
+    while (i < input.length) {
+        const ch = input[i];
+        if (ch !== "'") {
+            buf += ch;
+            i += 1;
+            continue;
+        }
+        spans.push(buf);
+        let literal = "'";
+        i += 1;
+        while (i < input.length) {
+            const c = input[i];
+            if (c === "'") {
+                // OData string literals double the quote to embed it.
+                if (input[i + 1] === "'") {
+                    literal += "''";
+                    i += 2;
+                    continue;
+                }
+                literal += "'";
+                i += 1;
+                break;
+            }
+            literal += c;
+            i += 1;
+        }
+        spans.push(literal);
+        buf = "";
+    }
+    spans.push(buf);
+    return spans;
+}
+export function buildOdataSpatialFilter(spatialFilter, context = {}) {
+    const rel = spatialFilter.spatialRel ?? "esriSpatialRelIntersects";
+    if (rel !== "esriSpatialRelIntersects" &&
+        rel !== "esriSpatialRelEnvelopeIntersects" &&
+        rel !== "esriSpatialRelDistance") {
+        throw new Error(`odata: spatialRel "${rel}" is not supported; OData parity matrix only implements geo.intersects (intersects/envelope-intersects) and geo.distance.`);
+    }
+    const column = resolveGeometryColumn(context);
+    const wkt = geometryToWkt(spatialFilter.geometry, spatialFilter.geometryType);
+    const inputSrid = resolveInputSrid(spatialFilter.geometry, context);
+    const literal = wktLiteral(wkt, inputSrid);
+    if (rel === "esriSpatialRelDistance") {
+        if (typeof spatialFilter.distance !== "number" || !Number.isFinite(spatialFilter.distance)) {
+            throw new Error('odata: spatialRel "esriSpatialRelDistance" requires a numeric distance (meters for geography).');
+        }
+        return `geo.distance(${column},${literal}) le ${spatialFilter.distance}`;
+    }
+    return `geo.intersects(${column},${literal})`;
+}
+function resolveGeometryColumn(context) {
+    if (context.geometryColumn)
+        return context.geometryColumn;
+    const spatial = context.geometryFields?.find((f) => f.isSpatial);
+    if (!spatial) {
+        throw new Error("odata: cannot translate spatialFilter — no geometry column was supplied and metadata exposes no Edm.Geography field.");
+    }
+    return spatial.name;
+}
+function resolveInputSrid(geometry, context) {
+    if (context.inputSrid !== undefined && context.inputSrid !== null && context.inputSrid !== "") {
+        return context.inputSrid;
+    }
+    const sr = geometry.spatialReference;
+    if (sr?.wkid !== undefined && Number.isFinite(sr.wkid))
+        return sr.wkid;
+    if (sr?.latestWkid !== undefined && Number.isFinite(sr.latestWkid))
+        return sr.latestWkid;
+    // Prefer the SRID of the *selected* geometry column when a name was
+    // pinned by the caller — entity types with multiple spatial fields
+    // can declare different SRIDs per column, and the WKT must be stamped
+    // with the SRID of the column the predicate is being evaluated
+    // against. Falls back to the first spatial field only when no column
+    // was pinned (or the pinned column is absent from the supplied
+    // metadata fields).
+    const selected = context.geometryColumn !== undefined
+        ? context.geometryFields?.find((f) => f.name === context.geometryColumn)
+        : undefined;
+    if (selected?.srid !== undefined && Number.isFinite(selected.srid))
+        return selected.srid;
+    if (context.geometryColumn !== undefined && selected)
+        return undefined;
+    const spatial = context.geometryFields?.find((f) => f.isSpatial);
+    if (spatial?.srid !== undefined && Number.isFinite(spatial.srid))
+        return spatial.srid;
+    return undefined;
+}
+function wktLiteral(wkt, srid) {
+    if (srid === undefined || srid === null || srid === "") {
+        return `geography'${wkt}'`;
+    }
+    return `geography'SRID=${srid};${wkt}'`;
+}
+// Coordinates are interpolated verbatim into a WKT string that is wrapped in an
+// OData `geography'...'` literal and passed straight into `$filter`. Any value
+// that is not a finite number must be rejected here: a non-numeric string (e.g.
+// one containing a single quote) would otherwise terminate the OData string
+// literal and inject attacker-controlled tokens into the server-side filter, and
+// NaN/Infinity/undefined would produce malformed WKT.
+function wktCoordinate(value, context) {
+    const num = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(num)) {
+        throw new Error(`odata: spatialFilter ${context} must be a finite number.`);
+    }
+    return num;
+}
+function wktPoint(pt, context) {
+    return `${wktCoordinate(pt[0], `${context}[0]`)} ${wktCoordinate(pt[1], `${context}[1]`)}`;
+}
+function geometryToWkt(geometry, geometryType) {
+    if (geometryType === "esriGeometryEnvelope") {
+        const xmin = wktCoordinate(geometry.xmin, "envelope.xmin");
+        const ymin = wktCoordinate(geometry.ymin, "envelope.ymin");
+        const xmax = wktCoordinate(geometry.xmax, "envelope.xmax");
+        const ymax = wktCoordinate(geometry.ymax, "envelope.ymax");
+        return `POLYGON((${xmin} ${ymin}, ${xmax} ${ymin}, ${xmax} ${ymax}, ${xmin} ${ymax}, ${xmin} ${ymin}))`;
+    }
+    if (geometryType === "esriGeometryPoint") {
+        const x = wktCoordinate(geometry.x, "point.x");
+        const y = wktCoordinate(geometry.y, "point.y");
+        return `POINT(${x} ${y})`;
+    }
+    if (geometryType === "esriGeometryPolygon") {
+        const rings = geometry.rings;
+        if (!Array.isArray(rings) || rings.length === 0) {
+            throw new Error("odata: polygon spatialFilter has no rings");
+        }
+        const inner = rings
+            .map((ring) => `(${ring.map((pt) => wktPoint(pt, "polygon.ring")).join(", ")})`)
+            .join(", ");
+        return `POLYGON(${inner})`;
+    }
+    if (geometryType === "esriGeometryPolyline") {
+        const paths = geometry.paths;
+        if (!Array.isArray(paths) || paths.length === 0) {
+            throw new Error("odata: polyline spatialFilter has no paths");
+        }
+        const path = paths[0];
+        return `LINESTRING(${path.map((pt) => wktPoint(pt, "polyline.path")).join(", ")})`;
+    }
+    throw new Error(`odata: spatialFilter.geometryType "${geometryType}" is not supported.`);
+}