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

package/core/errors.d.ts

@@ -1,8 +1,9 @@
 /**
- * Honua SDK error hierarchy. Every error thrown by `@honua/sdk-js` is an
- * instance of one of the classes in this file plus the runtime-type guard
- * `isHonuaError(error)`. See [`docs/errors.md`](../../docs/errors.md) for the
- * full reference table including recovery hints and the retry-policy mapping.
+ * Tagged hierarchy for the migrated Honua SDK error domains. The common
+ * `isHonuaError(error)` guard also recognizes migrated query, map, runtime,
+ * realtime, offline, and plugin subclasses. See
+ * [`docs/errors.md`](../../docs/errors.md) for exact coverage, residual domains,
+ * recovery hints, and the retryability classification.
  *
  * @example
  * ```ts
@@ -29,9 +30,26 @@
  *
  * @packageDocumentation
  */
-import { HonuaJobFailedError } from "./ogc-processes.js";
-import { HonuaWmsCapabilitiesParseError } from "./wms-capabilities.js";
-import { HonuaWmtsCapabilitiesParseError } from "./wmts-capabilities.js";
+import { type HonuaErrorMetadata, type HonuaErrorOptions, HonuaSdkError } from "./error-envelope.js";
+export type HonuaDiscoveryErrorCode = "ambiguous-protocol" | "ambiguous-source" | "invalid-endpoint" | "invalid-cache-identity" | "invalid-discovery-cache" | "invalid-capability" | "unsupported-protocol" | "protocol-mismatch";
+/** Discovery input, metadata, or cache identity is invalid or inconsistent. */
+export declare class HonuaDiscoveryError extends HonuaSdkError {
+    readonly code: HonuaDiscoveryErrorCode;
+    readonly detail?: Readonly<Record<string, unknown>> | undefined;
+    constructor(code: HonuaDiscoveryErrorCode, message: string, detail?: Readonly<Record<string, unknown>> | undefined, options?: HonuaErrorOptions);
+}
+/** Stable reason codes for geometry inputs that cannot be classified safely. */
+export type HonuaGeometryErrorCode = "unknown-geometry" | "malformed-geometry";
+/**
+ * Thrown when a geometry cannot be classified without guessing. The structured
+ * `code` and `detail` fields let callers distinguish an unsupported shape from
+ * a recognized-but-malformed Esri geometry without parsing the message.
+ */
+export declare class HonuaGeometryError extends HonuaSdkError {
+    readonly code: HonuaGeometryErrorCode;
+    readonly detail?: Readonly<Record<string, unknown>> | undefined;
+    constructor(code: HonuaGeometryErrorCode, message: string, detail?: Readonly<Record<string, unknown>> | undefined, options?: HonuaErrorOptions);
+}
 /**
  * Thrown when the server returns a non-2xx HTTP status. Branch on
  * `.statusCode` to decide recovery: refresh credentials on 401/403, respect
@@ -39,30 +57,30 @@ import { HonuaWmtsCapabilitiesParseError } from "./wmts-capabilities.js";
  *
  * @see [`docs/errors.md`](../../docs/errors.md)
  */
-export declare class HonuaHttpError extends Error {
+export declare class HonuaHttpError extends HonuaSdkError {
     readonly statusCode: number;
     readonly body: unknown;
-    constructor(statusCode: number, message: string, body: unknown);
+    constructor(statusCode: number, message: string, body: unknown, options?: HonuaErrorOptions);
 }
 /** Thrown when a request exceeds the configured timeout. */
-export declare class HonuaTimeoutError extends Error {
+export declare class HonuaTimeoutError extends HonuaSdkError {
     readonly timeoutMs: number;
-    constructor(timeoutMs: number);
+    constructor(timeoutMs: number, options?: HonuaErrorOptions);
 }
 /** Thrown when a network-level failure occurs (DNS, connection refused, etc.). */
-export declare class HonuaNetworkError extends Error {
+export declare class HonuaNetworkError extends HonuaSdkError {
     readonly cause: unknown;
-    constructor(message: string, cause: unknown);
+    constructor(message: string, cause: unknown, metadata?: HonuaErrorMetadata);
 }
 /** Thrown when a request is aborted via a caller-provided AbortSignal. */
-export declare class HonuaAbortError extends Error {
-    constructor(message?: string);
+export declare class HonuaAbortError extends HonuaSdkError {
+    constructor(message?: string, options?: HonuaErrorOptions);
 }
 /** Thrown when a gRPC-Web request fails, wrapping the underlying ConnectError. */
-export declare class HonuaGrpcError extends Error {
+export declare class HonuaGrpcError extends HonuaSdkError {
     readonly code: number;
     readonly details: unknown;
-    constructor(code: number, message: string, details?: unknown);
+    constructor(code: number, message: string, details?: unknown, options?: HonuaErrorOptions);
 }
 /**
  * Thrown when a `Source` is asked to perform an operation that the underlying
@@ -71,11 +89,11 @@ export declare class HonuaGrpcError extends Error {
  * decide whether to swap protocols, fall back to a degraded strategy, or
  * surface the limitation to the user.
  */
-export declare class HonuaCapabilityNotSupportedError extends Error {
+export declare class HonuaCapabilityNotSupportedError extends HonuaSdkError {
     readonly capability: string;
     readonly protocol: string;
     readonly sourceId: string | undefined;
-    constructor(capability: string, protocol: string, sourceId?: string);
+    constructor(capability: string, protocol: string, sourceId?: string, options?: HonuaErrorOptions);
 }
 /**
  * Cause codes for {@link HonuaAuthError}. They classify *why* an auth flow
@@ -102,12 +120,10 @@ export type HonuaAuthErrorCode = "interaction_required" | "refresh_failed" | "in
  *
  * @see [`docs/errors.md`](../../docs/errors.md)
  */
-export declare class HonuaAuthError extends Error {
+export declare class HonuaAuthError extends HonuaSdkError {
     readonly code: HonuaAuthErrorCode;
     readonly cause: unknown;
-    constructor(code: HonuaAuthErrorCode, message: string, options?: {
-        cause?: unknown;
-    });
+    constructor(code: HonuaAuthErrorCode, message: string, options?: HonuaErrorOptions);
 }
 /**
  * Thrown when an `ExplorationContext` operation is invalid — for example,
@@ -115,9 +131,9 @@ export declare class HonuaAuthError extends Error {
  * an incompatible snapshot, or binding a view that requests a slice that is
  * not exposed by the current dataset.
  */
-export declare class HonuaExplorationContextError extends Error {
+export declare class HonuaExplorationContextError extends HonuaSdkError {
     readonly code: string;
-    constructor(code: string, message: string);
+    constructor(code: string, message: string, options?: HonuaErrorOptions);
 }
 /**
  * Thrown when a WFS server replies with an `ows:ExceptionReport`. Carries the
@@ -127,13 +143,13 @@ export declare class HonuaExplorationContextError extends Error {
  * `src/core/wfs-capabilities.ts`; raw access lives behind the `protocol("wfs")`
  * escape hatch.
  */
-export declare class HonuaWfsExceptionError extends Error {
+export declare class HonuaWfsExceptionError extends HonuaSdkError {
     readonly exceptionCode: string;
     readonly locator: string | undefined;
-    constructor(exceptionCode: string, message: string, locator?: string);
+    constructor(exceptionCode: string, message: string, locator?: string, options?: HonuaErrorOptions);
 }
-/** All Honua SDK error types that can be discriminated with `instanceof`. */
-export type HonuaError = HonuaHttpError | HonuaTimeoutError | HonuaNetworkError | HonuaAbortError | HonuaGrpcError | HonuaAuthError | HonuaCapabilityNotSupportedError | HonuaExplorationContextError | HonuaWfsExceptionError | HonuaJobFailedError | HonuaWmsCapabilitiesParseError | HonuaWmtsCapabilitiesParseError;
+/** Any public SDK error participating in the tagged envelope. */
+export type HonuaError = HonuaSdkError;
 /** Type guard that narrows any value to one of the Honua SDK error types. */
 export declare function isHonuaError(error: unknown): error is HonuaError;
 //# sourceMappingURL=errors.d.ts.map

package/core/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,8BAA8B,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,EAAE,+BAA+B,EAAE,MAAM,wBAAwB,CAAC;AAEzE;;;;;;GAMG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,IAAI,EAAE,OAAO,CAAC;gBAEX,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO;CAMtE;AAED,4DAA4D;AAC5D,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,SAAgB,SAAS,EAAE,MAAM,CAAC;gBAEf,SAAS,EAAE,MAAM;CAKrC;AAED,kFAAkF;AAClF,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,SAAyB,KAAK,EAAE,OAAO,CAAC;gBAErB,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAKnD;AAED,0EAA0E;AAC1E,qBAAa,eAAgB,SAAQ,KAAK;gBACrB,OAAO,SAAwB;CAInD;AAED,kFAAkF;AAClF,qBAAa,cAAe,SAAQ,KAAK;IACvC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,OAAO,EAAE,OAAO,CAAC;gBAEd,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAMpE;AAED;;;;;;GAMG;AACH,qBAAa,gCAAiC,SAAQ,KAAK;IACzD,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;gBAE1B,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM;CAW3E;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,kBAAkB,GAAG,sBAAsB,GAAG,gBAAgB,GAAG,eAAe,CAAC;AAE7F;;;;;;;;GAQG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,SAAgB,IAAI,EAAE,kBAAkB,CAAC;IACzC,SAAyB,KAAK,EAAE,OAAO,CAAC;gBAErB,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAMhG;AAED;;;;;GAKG;AACH,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,SAAgB,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAKjD;AAED;;;;;;;GAOG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,SAAgB,aAAa,EAAE,MAAM,CAAC;IACtC,SAAgB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEzB,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAU5E;AAED,6EAA6E;AAC7E,MAAM,MAAM,UAAU,GAClB,cAAc,GACd,iBAAiB,GACjB,iBAAiB,GACjB,eAAe,GACf,cAAc,GACd,cAAc,GACd,gCAAgC,GAChC,4BAA4B,GAC5B,sBAAsB,GACtB,mBAAmB,GACnB,8BAA8B,GAC9B,+BAA+B,CAAC;AAEpC,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAehE"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/core/errors.ts"],"names":[],"mappings":"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"}

package/core/errors.js

@@ -1,8 +1,9 @@
 /**
- * Honua SDK error hierarchy. Every error thrown by `@honua/sdk-js` is an
- * instance of one of the classes in this file plus the runtime-type guard
- * `isHonuaError(error)`. See [`docs/errors.md`](../../docs/errors.md) for the
- * full reference table including recovery hints and the retry-policy mapping.
+ * Tagged hierarchy for the migrated Honua SDK error domains. The common
+ * `isHonuaError(error)` guard also recognizes migrated query, map, runtime,
+ * realtime, offline, and plugin subclasses. See
+ * [`docs/errors.md`](../../docs/errors.md) for exact coverage, residual domains,
+ * recovery hints, and the retryability classification.
  *
  * @example
  * ```ts
@@ -29,9 +30,39 @@
  *
  * @packageDocumentation
  */
-import { HonuaJobFailedError } from "./ogc-processes.js";
-import { HonuaWmsCapabilitiesParseError } from "./wms-capabilities.js";
-import { HonuaWmtsCapabilitiesParseError } from "./wmts-capabilities.js";
+import { HonuaSdkError, isHonuaSdkError, mergeHonuaErrorContext, } from "./error-envelope.js";
+/** Discovery input, metadata, or cache identity is invalid or inconsistent. */
+export class HonuaDiscoveryError extends HonuaSdkError {
+    code;
+    detail;
+    constructor(code, message, detail, options = {}) {
+        super(`discovery.${code}`, message, {
+            ...options,
+            context: mergeHonuaErrorContext(detail, options.context),
+        });
+        this.code = code;
+        this.detail = detail;
+        this.name = "HonuaDiscoveryError";
+    }
+}
+/**
+ * Thrown when a geometry cannot be classified without guessing. The structured
+ * `code` and `detail` fields let callers distinguish an unsupported shape from
+ * a recognized-but-malformed Esri geometry without parsing the message.
+ */
+export class HonuaGeometryError extends HonuaSdkError {
+    code;
+    detail;
+    constructor(code, message, detail, options = {}) {
+        super(`core.geometry.${code}`, message, {
+            ...options,
+            context: mergeHonuaErrorContext(detail, options.context),
+        });
+        this.code = code;
+        this.detail = detail;
+        this.name = "HonuaGeometryError";
+    }
+}
 /**
  * Thrown when the server returns a non-2xx HTTP status. Branch on
  * `.statusCode` to decide recovery: refresh credentials on 401/403, respect
@@ -39,49 +70,58 @@ import { HonuaWmtsCapabilitiesParseError } from "./wmts-capabilities.js";
  *
  * @see [`docs/errors.md`](../../docs/errors.md)
  */
-export class HonuaHttpError extends Error {
+export class HonuaHttpError extends HonuaSdkError {
     statusCode;
     body;
-    constructor(statusCode, message, body) {
-        super(`HTTP ${statusCode}: ${message}`);
+    constructor(statusCode, message, body, options = {}) {
+        super(HTTP_RETRYABLE_STATUSES.has(statusCode) ? "core.http.transient" : "core.http.rejected", `HTTP ${statusCode}: ${message}`, {
+            ...options,
+            context: mergeHonuaErrorContext(options.context, { statusCode }),
+        });
         this.name = "HonuaHttpError";
         this.statusCode = statusCode;
         this.body = body;
     }
 }
 /** Thrown when a request exceeds the configured timeout. */
-export class HonuaTimeoutError extends Error {
+export class HonuaTimeoutError extends HonuaSdkError {
     timeoutMs;
-    constructor(timeoutMs) {
-        super(`Request timed out after ${timeoutMs}ms`);
+    constructor(timeoutMs, options = {}) {
+        super("core.timeout", `Request timed out after ${timeoutMs}ms`, {
+            ...options,
+            context: mergeHonuaErrorContext(options.context, { timeoutMs }),
+        });
         this.name = "HonuaTimeoutError";
         this.timeoutMs = timeoutMs;
     }
 }
 /** Thrown when a network-level failure occurs (DNS, connection refused, etc.). */
-export class HonuaNetworkError extends Error {
+export class HonuaNetworkError extends HonuaSdkError {
     cause;
-    constructor(message, cause) {
-        super(message);
+    constructor(message, cause, metadata = {}) {
+        super("core.network", message, { ...metadata, cause });
         this.name = "HonuaNetworkError";
         this.cause = cause;
     }
 }
 /** Thrown when a request is aborted via a caller-provided AbortSignal. */
-export class HonuaAbortError extends Error {
-    constructor(message = "Request was aborted") {
-        super(message);
+export class HonuaAbortError extends HonuaSdkError {
+    constructor(message = "Request was aborted", options = {}) {
+        super("core.cancelled", message, options);
         this.name = "HonuaAbortError";
     }
 }
 /** Thrown when a gRPC-Web request fails, wrapping the underlying ConnectError. */
-export class HonuaGrpcError extends Error {
+export class HonuaGrpcError extends HonuaSdkError {
     code;
     details;
-    constructor(code, message, details) {
-        super(message);
-        this.name = "HonuaGrpcError";
+    constructor(code, message, details, options = {}) {
+        super(GRPC_RETRYABLE_CODES.has(code) ? "core.grpc.transient" : "core.grpc.rejected", message, {
+            ...options,
+            context: mergeHonuaErrorContext(options.context, { grpcCode: code }),
+        });
         this.code = code;
+        this.name = "HonuaGrpcError";
         this.details = details;
     }
 }
@@ -92,14 +132,18 @@ export class HonuaGrpcError extends Error {
  * decide whether to swap protocols, fall back to a degraded strategy, or
  * surface the limitation to the user.
  */
-export class HonuaCapabilityNotSupportedError extends Error {
+export class HonuaCapabilityNotSupportedError extends HonuaSdkError {
     capability;
     protocol;
     sourceId;
-    constructor(capability, protocol, sourceId) {
-        super(sourceId
+    constructor(capability, protocol, sourceId, options = {}) {
+        const message = sourceId
             ? `Capability "${capability}" is not supported by protocol "${protocol}" on source "${sourceId}"`
-            : `Capability "${capability}" is not supported by protocol "${protocol}"`);
+            : `Capability "${capability}" is not supported by protocol "${protocol}"`;
+        super("core.capability-not-supported", message, {
+            ...options,
+            context: mergeHonuaErrorContext(options.context, { capability, protocol, sourceId }),
+        });
         this.name = "HonuaCapabilityNotSupportedError";
         this.capability = capability;
         this.protocol = protocol;
@@ -115,13 +159,13 @@ export class HonuaCapabilityNotSupportedError extends Error {
  *
  * @see [`docs/errors.md`](../../docs/errors.md)
  */
-export class HonuaAuthError extends Error {
+export class HonuaAuthError extends HonuaSdkError {
     code;
     cause;
     constructor(code, message, options = {}) {
-        super(message);
-        this.name = "HonuaAuthError";
+        super(AUTH_ERROR_CODES[code], message, options);
         this.code = code;
+        this.name = "HonuaAuthError";
         this.cause = options.cause;
     }
 }
@@ -131,12 +175,15 @@ export class HonuaAuthError extends Error {
  * an incompatible snapshot, or binding a view that requests a slice that is
  * not exposed by the current dataset.
  */
-export class HonuaExplorationContextError extends Error {
+export class HonuaExplorationContextError extends HonuaSdkError {
     code;
-    constructor(code, message) {
-        super(message);
-        this.name = "HonuaExplorationContextError";
+    constructor(code, message, options = {}) {
+        super("core.exploration-context", message, {
+            ...options,
+            context: mergeHonuaErrorContext(options.context, { reason: code }),
+        });
         this.code = code;
+        this.name = "HonuaExplorationContextError";
     }
 }
 /**
@@ -147,13 +194,17 @@ export class HonuaExplorationContextError extends Error {
  * `src/core/wfs-capabilities.ts`; raw access lives behind the `protocol("wfs")`
  * escape hatch.
  */
-export class HonuaWfsExceptionError extends Error {
+export class HonuaWfsExceptionError extends HonuaSdkError {
     exceptionCode;
     locator;
-    constructor(exceptionCode, message, locator) {
-        super(locator
+    constructor(exceptionCode, message, locator, options = {}) {
+        const formattedMessage = locator
             ? `WFS ExceptionReport ${exceptionCode} (${locator}): ${message}`
-            : `WFS ExceptionReport ${exceptionCode}: ${message}`);
+            : `WFS ExceptionReport ${exceptionCode}: ${message}`;
+        super("core.wfs-exception", formattedMessage, {
+            ...options,
+            context: mergeHonuaErrorContext(options.context, { exceptionCode, locator }),
+        });
         this.name = "HonuaWfsExceptionError";
         this.exceptionCode = exceptionCode;
         this.locator = locator;
@@ -161,16 +212,12 @@ export class HonuaWfsExceptionError extends Error {
 }
 /** Type guard that narrows any value to one of the Honua SDK error types. */
 export function isHonuaError(error) {
-    return (error instanceof HonuaHttpError ||
-        error instanceof HonuaTimeoutError ||
-        error instanceof HonuaNetworkError ||
-        error instanceof HonuaAbortError ||
-        error instanceof HonuaGrpcError ||
-        error instanceof HonuaAuthError ||
-        error instanceof HonuaCapabilityNotSupportedError ||
-        error instanceof HonuaExplorationContextError ||
-        error instanceof HonuaWfsExceptionError ||
-        error instanceof HonuaJobFailedError ||
-        error instanceof HonuaWmsCapabilitiesParseError ||
-        error instanceof HonuaWmtsCapabilitiesParseError);
+    return isHonuaSdkError(error);
 }
+const HTTP_RETRYABLE_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
+const GRPC_RETRYABLE_CODES = new Set([4, 8, 10, 14]);
+const AUTH_ERROR_CODES = {
+    interaction_required: "core.auth.interaction-required",
+    refresh_failed: "core.auth.refresh-failed",
+    invalid_grant: "core.auth.invalid-grant",
+};

package/core/geoparquet-sql.d.ts

@@ -66,8 +66,23 @@ export declare function parquetSourceExpr(urls: readonly string[]): string;
  *   2.11, Mar 2025) — DuckDB reads it as a `GEOMETRY`, used directly.
  * - `geojson`: GeoParquet `GeoJSON` encoding (string) — wrap with
  *   `ST_GeomFromGeoJSON(...)`.
- */
-export type GeometryEncoding = "wkb" | "native" | "geojson";
+ * - `geoarrow-point` / `geoarrow-linestring` / `geoarrow-polygon` /
+ *   `geoarrow-multipoint` / `geoarrow-multilinestring` /
+ *   `geoarrow-multipolygon`: GeoParquet **1.1** native single-geometry
+ *   encodings (`geo.columns[].encoding`). DuckDB exposes these as nested
+ *   `STRUCT`/`LIST` columns, not a `GEOMETRY` value — there is no DuckDB
+ *   spatial expression for them. Geometry projection is decoded in JS by
+ *   `@honua/sdk-js/geoparquet`'s native decoder (`native-geometry.ts`, built
+ *   on `src/columnar/geoarrow.ts`); a spatial predicate against one of these
+ *   columns requires a GeoParquet 1.1 bbox-covering column
+ *   ({@link GeometryColumnPlan.bboxColumn}) and otherwise fails closed — see
+ *   {@link geometryExpr}.
+ */
+export type GeometryEncoding = "wkb" | "native" | "geojson" | "geoarrow-point" | "geoarrow-linestring" | "geoarrow-polygon" | "geoarrow-multipoint" | "geoarrow-multilinestring" | "geoarrow-multipolygon";
+/** The `geoarrow-*` subset of {@link GeometryEncoding} (GeoParquet 1.1 native). */
+export type GeoArrowNativeGeometryEncoding = Extract<GeometryEncoding, `geoarrow-${string}`>;
+/** True for a GeoParquet 1.1 native single-geometry encoding (see {@link GeometryEncoding}). */
+export declare function isGeoArrowNativeEncoding(encoding: GeometryEncoding): encoding is GeoArrowNativeGeometryEncoding;
 export interface GeometryColumnPlan {
     /** Geometry column name in the parquet file. */
     readonly column: string;
@@ -79,10 +94,23 @@ export interface GeometryColumnPlan {
      * can prune row groups without decoding any geometry.
      */
     readonly bboxColumn?: string;
+    /**
+     * Coordinate dimensions physically stored by a `geoarrow-*` encoding.
+     * Required (and only meaningful) when {@link encoding} is one of the
+     * `geoarrow-*` values; GeoParquet 1.1 native encodings carry no `M`.
+     */
+    readonly nativeDimensions?: "xy" | "xyz";
 }
 /**
  * SQL expression that yields a DuckDB `GEOMETRY` from the stored geometry
  * column, adapting to the physical encoding.
+ *
+ * @throws for a `geoarrow-*` encoding — GeoParquet 1.1 native columns are
+ *   nested `STRUCT`/`LIST` values with no DuckDB spatial-predicate
+ *   expression. Callers must fail closed before constructing SQL rather than
+ *   let a malformed `ST_Intersects(...)` reach DuckDB; use a bbox-covering
+ *   column for spatial pushdown and the dedicated native decoder for
+ *   geometry projection instead.
  */
 export declare function geometryExpr(plan: GeometryColumnPlan): string;
 export interface BBox {

package/core/geoparquet-sql.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"geoparquet-sql.d.ts","sourceRoot":"","sources":["../../../src/core/geoparquet-sql.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"geoparquet-sql.d.ts","sourceRoot":"","sources":["../../../src/core/geoparquet-sql.ts"],"names":[],"mappings":"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"}

package/core/geoparquet-sql.js

@@ -90,9 +90,28 @@ export function parquetSourceExpr(urls) {
     const arg = list.length === 1 ? list[0] : `[${list.join(", ")}]`;
     return `read_parquet(${arg}, union_by_name = true, hive_partitioning = true)`;
 }
+const GEOARROW_NATIVE_ENCODINGS = new Set([
+    "geoarrow-point",
+    "geoarrow-linestring",
+    "geoarrow-polygon",
+    "geoarrow-multipoint",
+    "geoarrow-multilinestring",
+    "geoarrow-multipolygon",
+]);
+/** True for a GeoParquet 1.1 native single-geometry encoding (see {@link GeometryEncoding}). */
+export function isGeoArrowNativeEncoding(encoding) {
+    return GEOARROW_NATIVE_ENCODINGS.has(encoding);
+}
 /**
  * SQL expression that yields a DuckDB `GEOMETRY` from the stored geometry
  * column, adapting to the physical encoding.
+ *
+ * @throws for a `geoarrow-*` encoding — GeoParquet 1.1 native columns are
+ *   nested `STRUCT`/`LIST` values with no DuckDB spatial-predicate
+ *   expression. Callers must fail closed before constructing SQL rather than
+ *   let a malformed `ST_Intersects(...)` reach DuckDB; use a bbox-covering
+ *   column for spatial pushdown and the dedicated native decoder for
+ *   geometry projection instead.
  */
 export function geometryExpr(plan) {
     const col = quoteIdentifier(plan.column);
@@ -103,6 +122,13 @@ export function geometryExpr(plan) {
             return `ST_GeomFromGeoJSON(${col})`;
         case "native":
             return col;
+        case "geoarrow-point":
+        case "geoarrow-linestring":
+        case "geoarrow-polygon":
+        case "geoarrow-multipoint":
+        case "geoarrow-multilinestring":
+        case "geoarrow-multipolygon":
+            throw new Error(`geoparquet: column ${JSON.stringify(plan.column)} uses the GeoParquet 1.1 native "${plan.encoding.slice("geoarrow-".length)}" encoding, which DuckDB stores as a nested struct/list value with no spatial-predicate expression. Supply a bbox-covering column for spatialFilter pushdown; geometry projection is decoded separately from the raw column.`);
     }
 }
 /**
@@ -209,7 +235,15 @@ function projection(query, options) {
     const geom = options.geometry;
     const geomAlias = quoteIdentifier(options.geometryAlias ?? DEFAULT_GEOMETRY_ALIAS);
     const wantGeometry = query.returnGeometry !== false && geom !== undefined;
-    const geomSelect = wantGeometry ? `ST_AsGeoJSON(${geometryExpr(geom)}) AS ${geomAlias}` : undefined;
+    // `geoarrow-*` columns are raw nested struct/list values, not a DuckDB
+    // `GEOMETRY` — project them as-is and let the caller's native decoder
+    // (built on src/columnar/geoarrow.ts) turn the materialized rows into
+    // GeoJSON. Every other encoding keeps projecting `ST_AsGeoJSON(...)` text.
+    const geomSelect = wantGeometry
+        ? isGeoArrowNativeEncoding(geom.encoding)
+            ? `${quoteIdentifier(geom.column)} AS ${geomAlias}`
+            : `ST_AsGeoJSON(${geometryExpr(geom)}) AS ${geomAlias}`
+        : undefined;
     const outFields = query.outFields;
     if (outFields && outFields.length > 0) {
         const cols = outFields.filter((f) => !geom || f !== geom.column).map((f) => quoteIdentifier(f));
@@ -328,6 +362,7 @@ export function rowEstimateSql(sources) {
  * rows for Parquet-native geometry files, which carry no `geo` metadata.
  */
 export function geoMetadataSql(sources) {
-    const first = stringLiteral(sources[0] ?? "");
-    return `SELECT value FROM parquet_kv_metadata(${first}) WHERE decode(key) = 'geo'`;
+    const list = sources.map(stringLiteral);
+    const arg = list.length === 1 ? list[0] : `[${list.join(", ")}]`;
+    return `SELECT files.file_name, geo.value FROM parquet_file_metadata(${arg}) AS files LEFT JOIN parquet_kv_metadata(${arg}) AS geo ON geo.file_name = files.file_name AND decode(geo.key) = 'geo' ORDER BY files.file_name`;
 }

package/core/odata-key-path.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Encode an OData key predicate without hiding its structural grammar.
+ *
+ * Quotes plus the `,` / `=` delimiters outside quoted literals remain
+ * visible to direct and JSON-batch OData parsers. Unsafe value characters
+ * are percent-encoded by Unicode code point so non-BMP string keys remain
+ * valid path data rather than splitting or truncating the target URL.
+ *
+ * @internal
+ */
+export declare function encodeOdataKeyPredicatePath(key: string | number): string;
+//# sourceMappingURL=odata-key-path.d.ts.map

package/core/odata-key-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"odata-key-path.d.ts","sourceRoot":"","sources":["../../../src/core/odata-key-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAiBxE"}

package/core/odata-key-path.js

@@ -0,0 +1,28 @@
+/**
+ * Encode an OData key predicate without hiding its structural grammar.
+ *
+ * Quotes plus the `,` / `=` delimiters outside quoted literals remain
+ * visible to direct and JSON-batch OData parsers. Unsafe value characters
+ * are percent-encoded by Unicode code point so non-BMP string keys remain
+ * valid path data rather than splitting or truncating the target URL.
+ *
+ * @internal
+ */
+export function encodeOdataKeyPredicatePath(key) {
+    const raw = String(key);
+    let output = "";
+    let inQuote = false;
+    for (const character of raw) {
+        if (character === "'") {
+            inQuote = !inQuote;
+            output += "'";
+            continue;
+        }
+        if (!inQuote && (character === "," || character === "=")) {
+            output += character;
+            continue;
+        }
+        output += /[A-Za-z0-9\-._~]/.test(character) ? character : encodeURIComponent(character);
+    }
+    return output;
+}

package/core/odata-write-codec.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Metadata-driven OData write encoding primitives.
+ *
+ * This module deliberately has no transport dependencies. Callers supply the
+ * already-cached CSDL projection and decide how to attach the encoded body,
+ * content type, and key to an HTTP request.
+ */
+import { type HonuaOdataMetadata } from "./odata.js";
+/** Stable failure categories for local, pre-transport encoding errors. */
+export type HonuaOdataEdmEncodingErrorCode = "cyclic-value" | "invalid-metadata" | "invalid-options" | "invalid-value" | "max-depth-exceeded" | "missing-key" | "resource-limit-exceeded" | "unknown-entity-set" | "unsupported-type";
+/**
+ * A redacted local encoding failure.
+ *
+ * Messages contain a fixed explanation and a bounded, escaped property path.
+ * The rejected value and request body are intentionally never retained.
+ */
+export declare class HonuaOdataEdmEncodingError extends TypeError {
+    readonly code: HonuaOdataEdmEncodingErrorCode;
+    readonly path: string;
+    constructor(code: HonuaOdataEdmEncodingErrorCode, path: string);
+}
+/**
+ * Controls the hard recursion bound for complex, collection, and untyped
+ * values. Fixed breadth and aggregate-node budgets also protect every call.
+ */
+export interface HonuaOdataEdmEncodingOptions {
+    /** Maximum nested container depth. Defaults to and cannot exceed 32. */
+    readonly maxDepth?: number;
+}
+/** Controls metadata-typed entity-key encoding. */
+export interface HonuaOdataEntityKeyEncodingOptions extends HonuaOdataEdmEncodingOptions {
+    /**
+     * Ordered metadata key fields to place in this URL predicate. Omit this for
+     * a direct entity set. Navigation paths may provide the child-key subset
+     * because the parent key is already carried by the path.
+     */
+    readonly keyFields?: readonly string[];
+}
+/** Body projection consumed by a later HTTP/edit integration layer. */
+export interface HonuaOdataEncodedWriteBody {
+    /** JSON-compatible body with metadata-declared values encoded losslessly. */
+    readonly body: Record<string, unknown>;
+    /** Whether the body requires `IEEE754Compatible=true` on its media type. */
+    readonly requiresIeee754Compatible: boolean;
+}
+/** Key projection consumed by direct and batch URL builders. */
+export interface HonuaOdataEncodedEntityKey {
+    /** OData key predicate content, without surrounding parentheses. */
+    readonly literal: string;
+    /** The same predicate encoded as one RFC 3986-safe URL path segment. */
+    readonly pathSegment: string;
+}
+/**
+ * Encode one entity body using the entity and complex property declarations in
+ * an existing OData metadata snapshot.
+ */
+export declare function encodeOdataWriteBody(metadata: HonuaOdataMetadata, entitySet: string, body: Readonly<Record<string, unknown>>, options?: HonuaOdataEdmEncodingOptions): HonuaOdataEncodedWriteBody;
+/**
+ * Encode a single or composite primary key in metadata declaration order.
+ *
+ * A single key accepts either its scalar value or an object carrying the key
+ * property. Composite keys require an object so component names cannot be
+ * confused or reordered by the caller.
+ */
+export declare function encodeOdataEntityKey(metadata: HonuaOdataMetadata, entitySet: string, key: unknown, options?: HonuaOdataEntityKeyEncodingOptions): HonuaOdataEncodedEntityKey;
+//# sourceMappingURL=odata-write-codec.d.ts.map

package/core/odata-write-codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"odata-write-codec.d.ts","sourceRoot":"","sources":["../../../src/core/odata-write-codec.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAGL,KAAK,kBAAkB,EAGxB,MAAM,YAAY,CAAC;AAwCpB,0EAA0E;AAC1E,MAAM,MAAM,8BAA8B,GACtC,cAAc,GACd,kBAAkB,GAClB,iBAAiB,GACjB,eAAe,GACf,oBAAoB,GACpB,aAAa,GACb,yBAAyB,GACzB,oBAAoB,GACpB,kBAAkB,CAAC;AAEvB;;;;;GAKG;AACH,qBAAa,0BAA2B,SAAQ,SAAS;IACvD,SAAgB,IAAI,EAAE,8BAA8B,CAAC;IACrD,SAAgB,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,8BAA8B,EAAE,IAAI,EAAE,MAAM;CAMtE;AAED;;;GAGG;AACH,MAAM,WAAW,4BAA4B;IAC3C,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,mDAAmD;AACnD,MAAM,WAAW,kCAAmC,SAAQ,4BAA4B;IACtF;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED,uEAAuE;AACvE,MAAM,WAAW,0BAA0B;IACzC,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,4EAA4E;IAC5E,QAAQ,CAAC,yBAAyB,EAAE,OAAO,CAAC;CAC7C;AAED,gEAAgE;AAChE,MAAM,WAAW,0BAA0B;IACzC,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,wEAAwE;IACxE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAkBD;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,kBAAkB,EAC5B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACvC,OAAO,GAAE,4BAAiC,GACzC,0BAA0B,CAS5B;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,kBAAkB,EAC5B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE,kCAAuC,GAC/C,0BAA0B,CAyC5B"}