@honua/react 0.1.0-beta.0 → 0.1.1-beta.0

package/contract/source.js

@@ -22,10 +22,11 @@ import { HonuaStacStaticCatalog } from "../core/stac-static.js";
 import { HonuaStacSearch } from "../core/stac.js";
 import { HonuaFeatureLayer, HonuaGeometryService, HonuaGeoprocessingService, HonuaImageService, HonuaMapLayer, HonuaMapService, HonuaOgcFeatureCollection, HonuaOgcFeatures, } from "../core/surfaces.js";
 import { UNSUPPORTED_FES, compileSpatialFilter, compileWhere, geoJsonGeometryToGml, serializeFes, } from "../core/wfs-filter.js";
-import { HonuaWfs, HonuaWfsFeatureType } from "../core/wfs.js";
+import { HonuaWfsFeatureType } from "../core/wfs.js";
 import { HonuaWms, HonuaWmsLayer, parseWmsLayerNames } from "../core/wms.js";
 import { HonuaWmts, HonuaWmtsLayer, HonuaWmtsTileset } from "../core/wmts.js";
-import { HonuaPmtilesArchive, stripPmtilesScheme } from "./pmtiles.js";
+import { pmtilesProtocolModule } from "./pmtiles.js";
+import { addCapabilitySupport, normalizeCapabilityDescriptor } from "./source-capability-support.js";
 import { CAPABILITIES, PROTOCOL_DEFAULT_CAPABILITIES, } from "./types.js";
 /**
  * Construct a protocol-neutral `Dataset` over a `HonuaClient`.
@@ -85,7 +86,8 @@ export function createDataset(options) {
     const descriptors = new Map();
     const handles = new Map();
     let compatibilityPromise;
-    for (const descriptor of sources) {
+    for (const input of sources) {
+        const descriptor = normalizeCapabilityDescriptor(input);
         if (descriptors.has(descriptor.id)) {
             throw new Error(`createDataset: duplicate source id "${descriptor.id}"`);
         }
@@ -95,13 +97,14 @@ export function createDataset(options) {
         const cached = handles.get(descriptor.id);
         if (cached)
             return cached;
-        const built = buildBuiltInSource(descriptor, client, policy) ??
-            resolveSource?.(descriptor, { client, capabilityPolicy: policy });
+        const builtIn = buildBuiltInSource(descriptor, client, policy);
+        const built = builtIn ?? resolveSource?.(descriptor, { client, capabilityPolicy: policy });
         if (!built) {
             throw new HonuaCapabilityNotSupportedError("query", descriptor.protocol, descriptor.id);
         }
-        handles.set(descriptor.id, built);
-        return built;
+        const source = builtIn ?? addCapabilitySupport(built, descriptor);
+        handles.set(descriptor.id, source);
+        return source;
     }
     return {
         id,
@@ -135,6 +138,15 @@ export function createDataset(options) {
 // ── Built-in resolver ─────────────────────────────────────────
 function buildBuiltInSource(descriptor, client, policy) {
     switch (descriptor.protocol) {
+        case "grpc":
+            // Honua gRPC is a transport-selectable fast path over the same
+            // canonical FeatureServer semantics, not a distinct adapter: the
+            // returned `HonuaFeatureLayer` transparently routes `queryFeatures`
+            // over gRPC-Web when `client.transport === "grpc-web"` (see
+            // `docs/protocol-capability-matrix.md`, "gRPC FeatureService"). The
+            // discovered descriptor's narrower `capabilities` (verified through a
+            // live gRPC parity probe in `connect-grpc.ts`) still gate execution.
+            return geoServicesFeatureSource(descriptor, client, policy);
         case "geoservices-feature-service":
             return geoServicesFeatureSource(descriptor, client, policy);
         case "geoservices-map-service":
@@ -196,9 +208,16 @@ function buildBuiltInSource(descriptor, client, policy) {
  * ```
  */
 export function geoServicesFeatureSource(descriptor, client, policy) {
+    descriptor = normalizeCapabilityDescriptor(descriptor);
     const { serviceId, layerId } = requireFeatureServiceLocator(descriptor);
     const layer = new HonuaFeatureLayer({ client, serviceId, layerId });
-    const caps = descriptor.capabilities ?? PROTOCOL_DEFAULT_CAPABILITIES["geoservices-feature-service"];
+    // Indexed by the descriptor's own protocol (not hardcoded to
+    // "geoservices-feature-service") so a `protocol: "grpc"` descriptor built
+    // without explicit capabilities falls back to the narrower gRPC default
+    // set rather than silently inheriting REST-only capabilities (`pbf`,
+    // `sql`, `attachments`, `queryRelated`) the gRPC FeatureService RPC
+    // surface does not support.
+    const caps = descriptor.capabilities ?? PROTOCOL_DEFAULT_CAPABILITIES[descriptor.protocol];
     const adapterRegistry = {
         "geoservices-feature-service": layer,
     };
@@ -287,6 +306,7 @@ export function geoServicesFeatureSource(descriptor, client, policy) {
  * ```
  */
 export function geoServicesMapServiceSource(descriptor, client, policy) {
+    descriptor = normalizeCapabilityDescriptor(descriptor);
     const { serviceId, layerId } = requireMapServiceLocator(descriptor);
     const service = new HonuaMapService({ client, serviceId });
     const layer = new HonuaMapLayer({ client, serviceId, layerId });
@@ -381,6 +401,7 @@ export function geoServicesMapServiceSource(descriptor, client, policy) {
  * ```
  */
 export function ogcFeaturesSource(descriptor, client, policy) {
+    descriptor = normalizeCapabilityDescriptor(descriptor);
     const { collectionId } = requireOgcLocator(descriptor);
     const layoutMode = ogcFeaturesLayoutMode(descriptor.locator.layout);
     const collection = new HonuaOgcFeatureCollection({
@@ -600,6 +621,7 @@ export function ogcFeaturesSource(descriptor, client, policy) {
  * ```
  */
 export function geoServicesImageSource(descriptor, client, policy) {
+    descriptor = normalizeCapabilityDescriptor(descriptor);
     const { serviceId } = requireImageServiceLocator(descriptor);
     const service = new HonuaImageService({ client, serviceId });
     const caps = descriptor.capabilities ?? PROTOCOL_DEFAULT_CAPABILITIES["geoservices-image-service"];
@@ -709,6 +731,7 @@ export function geoServicesImageSource(descriptor, client, policy) {
  * ```
  */
 export function geoServicesGeometryServiceSource(descriptor, client, policy) {
+    descriptor = normalizeCapabilityDescriptor(descriptor);
     const service = new HonuaGeometryService({ client });
     const caps = descriptor.capabilities ?? PROTOCOL_DEFAULT_CAPABILITIES["geoservices-geometry-service"];
     const adapterRegistry = {
@@ -731,6 +754,7 @@ export function geoServicesGeometryServiceSource(descriptor, client, policy) {
  * ```
  */
 export function geoServicesGPServiceSource(descriptor, client, policy) {
+    descriptor = normalizeCapabilityDescriptor(descriptor);
     const caps = descriptor.capabilities ?? PROTOCOL_DEFAULT_CAPABILITIES["geoservices-gp-service"];
     const { serviceId, taskName } = requireGPServiceLocator(descriptor, caps);
     const service = new HonuaGeoprocessingService({
@@ -758,15 +782,19 @@ export function geoServicesGPServiceSource(descriptor, client, policy) {
  * ```
  */
 export function ogcTilesSource(descriptor, client, policy) {
+    descriptor = normalizeCapabilityDescriptor(descriptor);
     const { collectionId, tileMatrixSetId } = requireOgcTilesLocator(descriptor);
     const caps = descriptor.capabilities ?? PROTOCOL_DEFAULT_CAPABILITIES["ogc-tiles"];
+    const basePath = descriptor.locator.basePath;
     // Descriptors without a tileMatrixSetId cannot construct a usable
     // HonuaOgcTileset (every tile route requires `tileMatrixSetId`). Expose
     // the root HonuaOgcTiles adapter instead so callers can discover the
     // tilesets the server advertises for the collection before binding one.
+    // A `connect()`-discovered third-party root threads its basePath so tile
+    // routes resolve against the advertised layout, not the `/ogc/tiles` facade.
     const adapter = tileMatrixSetId !== undefined && tileMatrixSetId !== ""
-        ? new HonuaOgcTileset({ client, collectionId, tileMatrixSetId })
-        : new HonuaOgcTiles({ client });
+        ? new HonuaOgcTileset({ client, collectionId, tileMatrixSetId, ...(basePath !== undefined ? { basePath } : {}) })
+        : new HonuaOgcTiles({ client, ...(basePath !== undefined ? { basePath } : {}) });
     const adapterRegistry = {
         "ogc-tiles": adapter,
     };
@@ -787,6 +815,12 @@ export function ogcTilesSource(descriptor, client, policy) {
  * `locator.url` may carry a leading `pmtiles://` scheme (the MapLibre form) or
  * be a bare archive URL; both resolve to the same archive.
  *
+ * This builds the escape-hatch adapter through {@link pmtilesProtocolModule}
+ * (issue #538) rather than constructing `HonuaPmtilesArchive` directly, so
+ * the built-in wiring runs the same public `ProtocolModule` seam a module
+ * registered through `HonuaPluginRegistry` uses
+ * (`pmtilesProtocolPlugin`, `@honua/sdk-js/plugin`).
+ *
  * @example
  * ```ts
  * const archive = dataset.source("basemap")!.protocol("pmtiles");
@@ -795,13 +829,18 @@ export function ogcTilesSource(descriptor, client, policy) {
  * ```
  */
 export function pmtilesSource(descriptor, _client, policy) {
-    const url = stripPmtilesScheme(requirePmtilesLocator(descriptor));
-    const caps = descriptor.capabilities ?? PROTOCOL_DEFAULT_CAPABILITIES.pmtiles;
-    const archive = new HonuaPmtilesArchive(url);
+    descriptor = normalizeCapabilityDescriptor(descriptor);
+    const discovered = pmtilesProtocolModule().discover(descriptor);
+    if (discovered instanceof Promise) {
+        // PMTiles discovery is always synchronous (the reader opens lazily on the
+        // handle's own first `describe()` call); a module that started returning
+        // a promise would be a breaking change to this built-in's own contract.
+        throw new Error("pmtiles: built-in source construction requires synchronous protocol-module discovery");
+    }
     const adapterRegistry = {
-        pmtiles: archive,
+        pmtiles: discovered.adapter,
     };
-    return makeSource(descriptor, caps, policy, adapterRegistry, unsupportedFeatureSurface(descriptor));
+    return makeSource(descriptor, discovered.capabilities, policy, adapterRegistry, unsupportedFeatureSurface(descriptor));
 }
 // ── OGC API Maps ──────────────────────────────────────────────
 /**
@@ -816,13 +855,18 @@ export function pmtilesSource(descriptor, _client, policy) {
  * ```
  */
 export function ogcMapsSource(descriptor, client, policy) {
-    const root = new HonuaOgcMaps({ client });
+    descriptor = normalizeCapabilityDescriptor(descriptor);
+    const basePath = descriptor.locator.basePath;
+    // A `connect()`-discovered third-party root threads its basePath so render
+    // routes resolve against the advertised layout, not the `/ogc/maps` facade.
+    const root = new HonuaOgcMaps({ client, ...(basePath !== undefined ? { basePath } : {}) });
     const adapterRegistry = {};
     if (descriptor.locator.collectionId !== undefined) {
         adapterRegistry["ogc-maps"] = new HonuaOgcCollectionMap({
             client,
             collectionId: descriptor.locator.collectionId,
             styleId: descriptor.locator.styleId,
+            ...(basePath !== undefined ? { basePath } : {}),
         });
     }
     else {
@@ -846,8 +890,14 @@ export function ogcMapsSource(descriptor, client, policy) {
  * ```
  */
 export function ogcRecordsSource(descriptor, client, policy) {
+    descriptor = normalizeCapabilityDescriptor(descriptor);
     const { collectionId } = requireOgcRecordsLocator(descriptor);
-    const collection = new HonuaOgcRecordCollection({ client, collectionId });
+    const basePath = descriptor.locator.basePath;
+    const collection = new HonuaOgcRecordCollection({
+        client,
+        collectionId,
+        ...(basePath !== undefined ? { basePath } : {}),
+    });
     const caps = descriptor.capabilities ?? PROTOCOL_DEFAULT_CAPABILITIES["ogc-records"];
     const adapterRegistry = {
         "ogc-records": collection,
@@ -959,6 +1009,18 @@ export function ogcRecordsSource(descriptor, client, policy) {
  * ```
  */
 export function wmsSource(descriptor, client, policy) {
+    descriptor = normalizeCapabilityDescriptor(descriptor);
+    const advertisedCaps = descriptor.capabilities ?? PROTOCOL_DEFAULT_CAPABILITIES.wms;
+    if (typeof descriptor.locator.serviceId !== "string" || descriptor.locator.serviceId.length === 0) {
+        if (descriptor.locator.raster?.kind !== "wms-kvp")
+            requireWmsLocator(descriptor);
+        // Raw third-party discovery is renderable through the existing descriptor
+        // → MapLibre raster projection. The existing canonical FeatureInfo adapter
+        // is Honua-service-id based, so keep that surface fail-closed here.
+        const caps = new Set([...advertisedCaps].filter((capability) => capability !== "query"));
+        descriptor = { ...descriptor, capabilities: caps };
+        return makeSource(descriptor, caps, policy, {}, unsupportedFeatureSurface(descriptor));
+    }
     const { serviceId } = requireWmsLocator(descriptor);
     const layerName = descriptor.locator.typeName;
     const styleId = descriptor.locator.styleId;
@@ -981,7 +1043,7 @@ export function wmsSource(descriptor, client, policy) {
             layerOpts.defaultStyleId = styleId;
         adapterRegistry["wms-layer"] = new HonuaWmsLayer(layerOpts);
     }
-    const caps = descriptor.capabilities ?? PROTOCOL_DEFAULT_CAPABILITIES.wms;
+    const caps = advertisedCaps;
     return makeSource(descriptor, caps, policy, adapterRegistry, {
         async query(request) {
             ensureCapability(descriptor, caps, "query");
@@ -1059,6 +1121,16 @@ export function wmsSource(descriptor, client, policy) {
  * ```
  */
 export function wmtsSource(descriptor, client, policy) {
+    descriptor = normalizeCapabilityDescriptor(descriptor);
+    const caps = descriptor.capabilities ?? PROTOCOL_DEFAULT_CAPABILITIES.wmts;
+    if (typeof descriptor.locator.serviceId !== "string" || descriptor.locator.serviceId.length === 0) {
+        if (descriptor.locator.raster?.kind !== "wmts-kvp" && descriptor.locator.raster?.kind !== "wmts-template") {
+            requireWmtsLocator(descriptor);
+        }
+        // Raw WMTS sources use the validated descriptor binding in the existing
+        // MapLibre projection; no second protocol wire adapter is introduced.
+        return makeSource(descriptor, caps, policy, {}, unsupportedFeatureSurface(descriptor));
+    }
     const { serviceId } = requireWmtsLocator(descriptor);
     const layerName = descriptor.locator.typeName;
     const tileMatrixSetId = descriptor.locator.tileMatrixSetId ?? "WebMercatorQuad";
@@ -1081,7 +1153,6 @@ export function wmtsSource(descriptor, client, policy) {
             tileMatrixSetId,
         });
     }
-    const caps = descriptor.capabilities ?? PROTOCOL_DEFAULT_CAPABILITIES.wmts;
     return makeSource(descriptor, caps, policy, adapterRegistry, unsupportedFeatureSurface(descriptor));
 }
 // ── STAC API ──────────────────────────────────────────────────
@@ -1114,6 +1185,7 @@ export function wmtsSource(descriptor, client, policy) {
  * ```
  */
 export function stacSearchSource(descriptor, client, policy) {
+    descriptor = normalizeCapabilityDescriptor(descriptor);
     // Endpoint-layout selection. `stac-api` treats `locator.url` as a raw STAC
     // API root (search / collections mounted directly under it) rather than the
     // Honua `/stac` facade. `stac-static` reads a static catalog.json tree with
@@ -1121,7 +1193,9 @@ export function stacSearchSource(descriptor, client, policy) {
     const layout = descriptor.locator.layout;
     const stacBasePath = layout === "stac-api" ? "" : undefined;
     const stac = new HonuaStacSearch({ client, ...(stacBasePath !== undefined ? { basePath: stacBasePath } : {}) });
-    const staticCatalog = layout === "stac-static" ? new HonuaStacStaticCatalog(client, client.serverBaseUrl) : undefined;
+    const staticCatalog = layout === "stac-static"
+        ? new HonuaStacStaticCatalog(client, descriptor.locator.url, descriptor.locator.stacStatic)
+        : undefined;
     const caps = descriptor.capabilities ?? PROTOCOL_DEFAULT_CAPABILITIES.stac;
     const collectionScope = descriptor.locator.collectionId;
     const adapterRegistry = {
@@ -1268,8 +1342,9 @@ const DEFAULT_WFS_GEOMETRY_PROPERTY = "the_geom";
  * ```
  */
 export function wfsSource(descriptor, client, policy) {
+    descriptor = normalizeCapabilityDescriptor(descriptor);
     const { url, typeName, featureNamespace, srsName: wfsSrsName } = requireWfsLocator(descriptor);
-    const root = new HonuaWfs({ client, endpointUrl: url });
+    const root = client.wfs(url);
     const featureType = new HonuaWfsFeatureType({ root, typeName });
     const caps = descriptor.capabilities ?? PROTOCOL_DEFAULT_CAPABILITIES.wfs;
     void policy;
@@ -1502,6 +1577,10 @@ export function wfsSource(descriptor, client, policy) {
                 summary = { totalInserted: 0, totalUpdated: 0, totalDeleted: 0, insertResults: [] };
             }
             else {
+                // Ensure a caller-cache hit still resolves the advertised Transaction
+                // POST URL before sending edits. Fresh connect discovery reuses this
+                // same root, so the capabilities promise is already settled there.
+                await root.capabilities(envelope.signal ? { signal: envelope.signal } : undefined);
                 const filtered = { ...envelope, updates: validUpdates };
                 const body = buildTransactionBody(typeName, filtered, featureNamespace, wfsSrsName);
                 const transactionOptions = { body };
@@ -1958,21 +2037,12 @@ function canonicalEditResultFromTransaction(envelope, summary, malformedUpdateIn
     }));
     return { added, updated, deleted };
 }
-// ── OData entity set ──────────────────────────────────────────
-/**
- * Build a `Source` over an OData v4 entity set. The `Query` translation
- * lowers `where` / `outFields` / `orderBy` / pagination / spatial filter
- * onto OData's `$`-prefixed query options. Dialect-specific operations
- * (`$batch`, `$apply`, `$search`, `$deltatoken`) live behind
- * `Source.protocol("odata")` on the returned `HonuaOdataEntitySet`.
- *
- * `$metadata` is fetched lazily on the first call that needs it and
- * cached on the entity-set instance. The fetched capability annotations
- * are intersected with the descriptor's declared `Capabilities` set the
- * first time a capability-gated method is invoked — this is the
- * precedent for the metadata-driven downgrade pattern referenced in
- * `docs/shared-client-contract.md`.
- */
+let odataWriteCodecPromise;
+/** Load the opt-in codec once; legacy sources never evaluate this import. */
+function loadOdataWriteCodec() {
+    odataWriteCodecPromise ??= import("../core/odata-write-codec.js");
+    return odataWriteCodecPromise;
+}
 /**
  * Adapter factory for an OData v4 entity set.
  *
@@ -2000,11 +2070,16 @@ function canonicalEditResultFromTransaction(envelope, summary, malformedUpdateIn
  * });
  * ```
  */
-export function odataSource(descriptor, client, policy) {
+export function odataSource(descriptor, client, policy, options = {}) {
+    descriptor = normalizeCapabilityDescriptor(descriptor);
     const { entitySet, basePath } = requireOdataLocator(descriptor);
     const entity = new HonuaOdataEntitySet({ client, entitySet, basePath });
     const declaredCaps = descriptor.capabilities ?? PROTOCOL_DEFAULT_CAPABILITIES.odata;
     const negotiation = new OdataCapabilityNegotiator(entity, declaredCaps);
+    const writeEncoding = options.writeEncoding ?? "legacy";
+    if (writeEncoding !== "legacy" && writeEncoding !== "lossless-json") {
+        throw new TypeError('odata: writeEncoding must be "legacy" or "lossless-json"');
+    }
     const adapterRegistry = {
         odata: entity,
     };
@@ -2107,6 +2182,9 @@ export function odataSource(descriptor, client, policy) {
             ensureCapability(descriptor, declaredCaps, "applyEdits");
             await negotiation.ensureAdvertised(descriptor, "applyEdits");
             const keyFields = await negotiation.keyFields(descriptor.id);
+            const prepared = writeEncoding === "lossless-json"
+                ? prepareLosslessOdataEdits(entity, envelope, keyFields, await negotiation.metadata(), await loadOdataWriteCodec())
+                : undefined;
             // Atomic path: when the caller asks for rollback-on-failure AND the
             // service advertises `$batch`, collapse the envelope into a single
             // OData batch with a shared `atomicityGroup` so a later failure
@@ -2117,9 +2195,9 @@ export function odataSource(descriptor, client, policy) {
             if (envelope.rollbackOnFailure === true) {
                 const batchAdvertised = await negotiation.batchAdvertised();
                 if (batchAdvertised) {
-                    return atomicOdataApplyEdits(entity, envelope, keyFields, descriptor);
+                    return atomicOdataApplyEdits(entity, envelope, keyFields, descriptor, prepared);
                 }
-                const result = await perCallOdataApplyEdits(entity, envelope, keyFields);
+                const result = await perCallOdataApplyEdits(entity, envelope, keyFields, prepared);
                 return {
                     ...result,
                     degraded: [
@@ -2133,7 +2211,7 @@ export function odataSource(descriptor, client, policy) {
                     ],
                 };
             }
-            return perCallOdataApplyEdits(entity, envelope, keyFields);
+            return perCallOdataApplyEdits(entity, envelope, keyFields, prepared);
         },
         async queryRelated() {
             // OData has no canonical related-records surface; navigation
@@ -2144,21 +2222,114 @@ export function odataSource(descriptor, client, policy) {
         attachments: unsupportedAttachmentApi(descriptor),
     });
 }
+/**
+ * Preflight the complete opted-in envelope against one cached metadata
+ * snapshot. Both direct and atomic execution consume this projection, so a
+ * local encoding failure cannot leak a partial request or take a different
+ * branch-specific coercion path.
+ */
+function prepareLosslessOdataEdits(entity, envelope, keyFields, metadata, codec) {
+    const urlKeys = urlKeyFields(entity.entitySet, keyFields);
+    const adds = (envelope.adds ?? []).map((add) => preparedOdataBody(metadata, entity.entitySet, add, codec));
+    const updates = (envelope.updates ?? []).map((update) => {
+        const prepared = preparedOdataBody(metadata, entity.entitySet, update, codec);
+        const key = preparedOdataUpdateKey(metadata, entity.entitySet, update.id, prepared.body, urlKeys, codec);
+        return { ...prepared, key };
+    });
+    const deletes = (envelope.deletes ?? []).map((id) => {
+        if (urlKeys.length > 1) {
+            // The generic contract carries only a scalar FeatureId. Lossless
+            // composite addressing requires named components, so do not interpret
+            // an ad-hoc string expression or risk targeting a different entity.
+            throw new codec.HonuaOdataEdmEncodingError("missing-key", "$.key");
+        }
+        return {
+            key: codec.encodeOdataEntityKey(metadata, entity.entitySet, id, {
+                keyFields: urlKeys,
+            }),
+        };
+    });
+    return { adds, updates, deletes };
+}
+function preparedOdataBody(metadata, entitySet, feature, codec) {
+    const attributes = codec.encodeOdataWriteBody(metadata, entitySet, feature.attributes);
+    let encoded = attributes;
+    if (feature.geometry !== undefined &&
+        feature.geometry !== null &&
+        !Object.hasOwn(attributes.body, "Geometry") &&
+        !Object.hasOwn(attributes.body, "geometry")) {
+        const geometry = codec.encodeOdataWriteBody(metadata, entitySet, { Geometry: feature.geometry });
+        encoded = {
+            body: { ...attributes.body, ...geometry.body },
+            requiresIeee754Compatible: attributes.requiresIeee754Compatible || geometry.requiresIeee754Compatible,
+        };
+    }
+    return {
+        body: encoded.body,
+        contentType: encoded.requiresIeee754Compatible ? "application/json;IEEE754Compatible=true" : "application/json",
+    };
+}
+function preparedOdataUpdateKey(metadata, entitySet, id, attributes, keyFields, codec) {
+    if (keyFields.length === 1) {
+        const field = keyFields[0];
+        const attributeValue = ownPreparedValue(attributes, field);
+        const attributeKey = attributeValue === undefined || attributeValue === null
+            ? undefined
+            : codec.encodeOdataEntityKey(metadata, entitySet, attributeValue, { keyFields });
+        const idKey = id === undefined || id === null ? undefined : codec.encodeOdataEntityKey(metadata, entitySet, id, { keyFields });
+        if (attributeKey &&
+            idKey &&
+            (attributeKey.literal !== idKey.literal || attributeKey.pathSegment !== idKey.pathSegment)) {
+            throw new codec.HonuaOdataEdmEncodingError("invalid-value", "$.key");
+        }
+        return attributeKey ?? idKey ?? codec.encodeOdataEntityKey(metadata, entitySet, undefined, { keyFields });
+    }
+    if (keyFields.length === 0) {
+        return codec.encodeOdataEntityKey(metadata, entitySet, id, { keyFields });
+    }
+    if (id !== undefined && id !== null) {
+        // A scalar generic id cannot prove equivalence to a named composite key.
+        // Reject it even when the body carries all components so the adapter never
+        // targets one identity while reporting another.
+        throw new codec.HonuaOdataEdmEncodingError("invalid-value", "$.key");
+    }
+    const key = Object.create(null);
+    for (const field of keyFields) {
+        const value = ownPreparedValue(attributes, field);
+        if (value === undefined || value === null)
+            continue;
+        Object.defineProperty(key, field, {
+            configurable: true,
+            enumerable: true,
+            writable: true,
+            value,
+        });
+    }
+    return codec.encodeOdataEntityKey(metadata, entitySet, key, { keyFields });
+}
+function ownPreparedValue(attributes, field) {
+    const descriptor = Object.getOwnPropertyDescriptor(attributes, field);
+    return descriptor && "value" in descriptor ? descriptor.value : undefined;
+}
 /**
  * Per-call OData edits — issues independent POST/PATCH/DELETE requests
  * and collects per-row outcomes. This is the non-atomic fallback used
  * when `rollbackOnFailure` is unset or the server does not advertise
  * `$batch`.
  */
-async function perCallOdataApplyEdits(entity, envelope, keyFields) {
+async function perCallOdataApplyEdits(entity, envelope, keyFields, prepared) {
     const added = [];
     const updated = [];
     const deleted = [];
     const { signal } = envelope;
-    for (const add of envelope.adds ?? []) {
+    const adds = envelope.adds ?? [];
+    for (let index = 0; index < adds.length; index += 1) {
+        const add = adds[index];
+        const encoded = prepared?.adds[index];
         try {
-            const created = await entity.add(featureToOdataBody(add), {
+            const created = await entity.add(encoded?.body ?? featureToOdataBody(add), {
                 ...(signal ? { signal } : {}),
+                ...(encoded ? { contentType: encoded.contentType } : {}),
             });
             const id = readKey(created, keyFields, add.id);
             added.push(id !== undefined ? { id, success: true } : { success: true });
@@ -2173,22 +2344,30 @@ async function perCallOdataApplyEdits(entity, envelope, keyFields) {
     // using the full `keyFields` because the response body still carries
     // every key.
     const urlKeys = urlKeyFields(entity.entitySet, keyFields);
-    for (const update of envelope.updates ?? []) {
-        const key = canonicalKeyToOdata(update, urlKeys);
+    const updates = envelope.updates ?? [];
+    for (let index = 0; index < updates.length; index += 1) {
+        const update = updates[index];
+        const encoded = prepared?.updates[index];
+        const key = encoded?.key.literal ?? canonicalKeyToOdata(update, urlKeys);
         if (key === undefined) {
             updated.push({ success: false, error: { code: 400, description: "update.id is required" } });
             continue;
         }
         try {
-            await entity.update(key, featureToOdataBody(update), { ...(signal ? { signal } : {}) });
+            await entity.update(key, encoded?.body ?? featureToOdataBody(update), {
+                ...(signal ? { signal } : {}),
+                ...(encoded ? { contentType: encoded.contentType } : {}),
+            });
             updated.push({ id: update.id ?? readKeyFromBody(update.attributes, keyFields), success: true });
         }
         catch (err) {
             updated.push({ id: update.id, success: false, error: editErrorFromCatch(err) });
         }
     }
-    for (const id of envelope.deletes ?? []) {
-        const key = canonicalKeyToOdata({ id, attributes: {} }, urlKeys);
+    const deletes = envelope.deletes ?? [];
+    for (let index = 0; index < deletes.length; index += 1) {
+        const id = deletes[index];
+        const key = prepared?.deletes[index]?.key.literal ?? canonicalKeyToOdata({ id, attributes: {} }, urlKeys);
         if (key === undefined) {
             deleted.push({ success: false, error: { code: 400, description: "delete id is required" } });
             continue;
@@ -2211,7 +2390,7 @@ async function perCallOdataApplyEdits(entity, envelope, keyFields) {
  * threaded back into per-row `EditOutcome` entries in the original
  * order so callers see the same shape regardless of transport.
  */
-async function atomicOdataApplyEdits(entity, envelope, keyFields, descriptor) {
+async function atomicOdataApplyEdits(entity, envelope, keyFields, descriptor, prepared) {
     const operations = [];
     const plan = [];
     const bucketIndices = { add: [], update: [], delete: [] };
@@ -2223,21 +2402,26 @@ async function atomicOdataApplyEdits(entity, envelope, keyFields, descriptor) {
     // and the test surface stays small.
     let seq = 1;
     const adds = envelope.adds ?? [];
-    for (const add of adds) {
+    for (let index = 0; index < adds.length; index += 1) {
+        const add = adds[index];
+        const encoded = prepared?.adds[index];
         const id = String(seq++);
         operations.push({
             id,
             method: "POST",
             url: stripLeadingSlashLocal(entity.entitySet),
-            body: featureToOdataBody(add),
+            body: encoded?.body ?? featureToOdataBody(add),
+            ...(encoded ? { headers: { "Content-Type": encoded.contentType } } : {}),
         });
         bucketIndices.add.push(plan.length);
         plan.push({ kind: "add", id: add.id });
     }
     const updates = envelope.updates ?? [];
-    for (const update of updates) {
+    for (let index = 0; index < updates.length; index += 1) {
+        const update = updates[index];
+        const encoded = prepared?.updates[index];
         const id = String(seq++);
-        const key = canonicalKeyToOdata(update, urlKeys);
+        const key = encoded?.key.literal ?? canonicalKeyToOdata(update, urlKeys);
         if (key === undefined) {
             bucketIndices.update.push(plan.length);
             plan.push({ kind: "update", id: update.id });
@@ -2246,22 +2430,29 @@ async function atomicOdataApplyEdits(entity, envelope, keyFields, descriptor) {
         operations.push({
             id,
             method: "PATCH",
-            url: `${entity.entitySet}(${key})`,
-            body: featureToOdataBody(update),
+            url: `${entity.entitySet}(${encoded?.key.pathSegment ?? key})`,
+            body: encoded?.body ?? featureToOdataBody(update),
+            ...(encoded ? { headers: { "Content-Type": encoded.contentType } } : {}),
         });
         bucketIndices.update.push(plan.length);
         plan.push({ kind: "update", id: update.id, key });
     }
     const deletes = envelope.deletes ?? [];
-    for (const rawId of deletes) {
+    for (let index = 0; index < deletes.length; index += 1) {
+        const rawId = deletes[index];
+        const encoded = prepared?.deletes[index];
         const id = String(seq++);
-        const key = canonicalKeyToOdata({ id: rawId, attributes: {} }, urlKeys);
+        const key = encoded?.key.literal ?? canonicalKeyToOdata({ id: rawId, attributes: {} }, urlKeys);
         if (key === undefined) {
             bucketIndices.delete.push(plan.length);
             plan.push({ kind: "delete", id: rawId });
             continue;
         }
-        operations.push({ id, method: "DELETE", url: `${entity.entitySet}(${key})` });
+        operations.push({
+            id,
+            method: "DELETE",
+            url: `${entity.entitySet}(${encoded?.key.pathSegment ?? key})`,
+        });
         bucketIndices.delete.push(plan.length);
         plan.push({ kind: "delete", id: rawId, key });
     }
@@ -2552,6 +2743,13 @@ async function buildOdataParams(entity, descriptor, request, options) {
         if (request.returnGeometry === false) {
             rootSelect = rootSelect.filter((f) => !isOdataGeometryFieldName(f, options.geomColumn));
         }
+        else if (options.geomColumn && !rootSelect.includes(options.geomColumn)) {
+            // OData `$select` is exclusive: once callers project attributes the
+            // service omits every unlisted property. Preserve canonical
+            // `returnGeometry` (default true) by explicitly retaining the resolved
+            // geometry column.
+            rootSelect = [...rootSelect, options.geomColumn];
+        }
         if (rootSelect.length > 0)
             out.select = rootSelect;
         if (split.expand.length > 0)
@@ -2790,6 +2988,10 @@ class OdataCapabilityNegotiator {
             return [];
         return meta.keys[typeName] ?? [];
     }
+    /** Return the same single-flight snapshot used by every capability probe. */
+    metadata() {
+        return this.materialize();
+    }
     async keyField(sourceId) {
         const keys = await this.keyFields(sourceId);
         if (keys.length === 1)
@@ -2846,7 +3048,7 @@ function makeSource(descriptor, caps, _policy, adapters, impl) {
     function lookupAdapter(kind) {
         return adapters[kind];
     }
-    return {
+    const source = {
         descriptor: { ...descriptor, capabilities: caps },
         capabilities: caps,
         query: impl.query.bind(impl),
@@ -2861,6 +3063,7 @@ function makeSource(descriptor, caps, _policy, adapters, impl) {
         protocol: lookupAdapter,
         adapter: lookupAdapter,
     };
+    return addCapabilitySupport(source, source.descriptor);
 }
 /**
  * Helper: build a no-attachment-support `AttachmentApi` whose every method
@@ -2989,13 +3192,6 @@ function requireOgcRecordsLocator(descriptor) {
     }
     return { collectionId };
 }
-function requirePmtilesLocator(descriptor) {
-    const { url } = descriptor.locator;
-    if (typeof url !== "string" || url === "") {
-        throw new Error(`createDataset: source "${descriptor.id}" (pmtiles) requires locator.url`);
-    }
-    return url;
-}
 function requireImageServiceLocator(descriptor) {
     const { serviceId } = descriptor.locator;
     if (typeof serviceId !== "string") {
@@ -3035,8 +3231,6 @@ function requireGPServiceLocator(descriptor, caps) {
     // /rest/services/<serviceId>/GPServer/<taskName>/..., so descriptors that
     // advertise the `geoprocess` capability must carry a task name. Without
     // one the lifecycle routes resolve to non-existent paths on the server.
-    // Descriptors with only `connect` (service-root metadata probe) may omit
-    // taskName.
     if (caps.has("geoprocess") && (typeof taskName !== "string" || taskName.length === 0)) {
         throw new Error(`createDataset: source "${descriptor.id}" (geoservices-gp-service) advertises "geoprocess" but locator.taskName is missing; GP lifecycle routes require /GPServer/<taskName>/...`);
     }
@@ -3451,8 +3645,10 @@ function toOgcRequest(request) {
     if (!request)
         return {};
     const out = {};
-    if (request.where !== undefined)
+    if (request.where !== undefined) {
         out.filter = request.where;
+        out.filterLang = "cql2-text";
+    }
     if (request.outFields && request.outFields.length > 0)
         out.properties = [...request.outFields];
     if (request.outSr !== undefined)
@@ -3657,10 +3853,10 @@ function readField(attributes, field) {
 function toApplyEditsRequest(envelope) {
     const out = {};
     if (envelope.adds && envelope.adds.length > 0) {
-        out.adds = envelope.adds.map((f) => canonicalToHonuaFeature(f));
+        out.adds = envelope.adds.map(canonicalToHonuaFeature);
     }
     if (envelope.updates && envelope.updates.length > 0) {
-        out.updates = envelope.updates.map((f) => canonicalToHonuaFeature(f));
+        out.updates = envelope.updates.map(canonicalToHonuaFeature);
     }
     if (envelope.deletes && envelope.deletes.length > 0) {
         const numericIds = [];