@honua/app-platform 0.1.7-beta.0 → 0.1.10-beta.0

package/core/error-code-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-code-registry.d.ts","sourceRoot":"","sources":["../../../src/core/error-code-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN,WAAW,GACX,OAAO,GACP,KAAK,GACL,SAAS,GACT,UAAU,GACV,SAAS,GACT,QAAQ,GACR,SAAS,GACT,OAAO,GACP,KAAK,CAAC;AAEV,MAAM,MAAM,kBAAkB,GAC1B,gBAAgB,GAChB,cAAc,GACd,YAAY,GACZ,UAAU,GACV,SAAS,GACT,UAAU,GACV,SAAS,GACT,YAAY,CAAC;AAEjB,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkpBwB,CAAC;AAE/D,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,yBAAyB,CAAC"}
+{"version":3,"file":"error-code-registry.d.ts","sourceRoot":"","sources":["../../../src/core/error-code-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN,WAAW,GACX,OAAO,GACP,KAAK,GACL,SAAS,GACT,UAAU,GACV,SAAS,GACT,QAAQ,GACR,SAAS,GACT,OAAO,GACP,KAAK,CAAC;AAEV,MAAM,MAAM,kBAAkB,GAC1B,gBAAgB,GAChB,cAAc,GACd,YAAY,GACZ,UAAU,GACV,SAAS,GACT,UAAU,GACV,SAAS,GACT,YAAY,CAAC;AAEjB,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqrBwB,CAAC;AAE/D,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,yBAAyB,CAAC"}

package/core/error-code-registry.js

@@ -35,6 +35,19 @@ export const HONUA_ERROR_CODE_REGISTRY = Object.freeze({
     "core.coverage.unsupported-format": classification("core", "capability", false, "Coverage format is unsupported"),
     "core.coverage.service-error": classification("core", "protocol", false, "Coverage service rejected the request"),
     "core.coverage.wcs-exception": classification("core", "protocol", false, "WCS exception report"),
+    "core.zarr.invalid-request": classification("core", "validation", false, "Zarr request is invalid"),
+    "core.zarr.invalid-response": classification("core", "protocol", false, "Zarr response is invalid"),
+    "core.zarr.response-too-large": classification("core", "validation", false, "Zarr response exceeds its byte limit"),
+    "core.zarr.metadata-pending": classification("core", "capability", false, "Zarr metadata scan is pending"),
+    "core.zarr.missing-spatial-extent": classification("core", "capability", false, "Zarr storage spatial extent is missing or unusable"),
+    "core.zarr.no-tileable-variable": classification("core", "capability", false, "Zarr metadata contains no tileable variable"),
+    "core.zarr.missing-spatial-reference": classification("core", "capability", false, "Zarr registration is missing a positive storage SRID for tile handoff"),
+    "core.zarr.spatial-reference-mismatch": classification("core", "capability", false, "Zarr storage and tile matrix spatial references do not match"),
+    "core.zarr.unsupported-version": classification("core", "capability", false, "Zarr version is unsupported"),
+    "core.zarr.unsupported-codec": classification("core", "capability", false, "Zarr codec is unsupported"),
+    "core.zarr.unsupported-dtype": classification("core", "capability", false, "Zarr dtype is unsupported"),
+    "core.zarr.ambiguous-dimensions": classification("core", "validation", false, "Zarr dimensions are ambiguous"),
+    "core.zarr.service-error": classification("core", "protocol", false, "Zarr service rejected the request"),
     "discovery.ambiguous-protocol": classification("discovery", "validation", false, "Multiple protocols match the endpoint"),
     "discovery.ambiguous-source": classification("discovery", "validation", false, "Multiple sources match the selection"),
     "discovery.invalid-cloud-native-input": classification("discovery", "validation", false, "Cloud-native discovery input is invalid or ambiguous"),
@@ -94,6 +107,8 @@ export const HONUA_ERROR_CODE_REGISTRY = Object.freeze({
     "runtime.map-package.fetch": classification("runtime", "network", true, "Map package fetch failed"),
     "runtime.map-package.load": classification("runtime", "internal", false, "Map package load failed"),
     "runtime.map-package.validate": classification("runtime", "validation", false, "Map package validation failed"),
+    "runtime.map-package.export": classification("runtime", "validation", false, "Map package export refused"),
+    "runtime.map-package.import": classification("runtime", "validation", false, "Map package import refused"),
     "runtime.map-package.update": classification("runtime", "internal", false, "Map package update failed"),
     "runtime.map-package.style-compose": classification("runtime", "validation", false, "Map package style composition failed"),
     "runtime.map-package.source-bind": classification("runtime", "internal", false, "Map package source binding failed"),

package/core/error-envelope.d.ts

@@ -17,6 +17,7 @@ export interface HonuaErrorMetadata {
     readonly operationId?: string;
     readonly requestId?: string;
     readonly context?: Readonly<Record<string, unknown>>;
+    readonly terminalReceipt?: HonuaTerminalFailureReceipt;
 }
 export interface HonuaErrorOptions extends ErrorOptions, HonuaErrorMetadata {
 }
@@ -29,9 +30,38 @@ export interface SerializedHonuaError {
     readonly retryable: boolean;
     readonly operationId?: string;
     readonly requestId?: string;
+    readonly receipt?: HonuaTerminalFailureReceipt;
     readonly context: HonuaErrorEnvelopeContext;
     readonly cause?: SerializedHonuaErrorCause;
 }
+/** Stable failure classes shared by HTTP, GeoServices, and gRPC terminal receipts. */
+export type HonuaFailureKind = "authentication" | "authorization" | "not-found" | "validation" | "conflict" | "throttled" | "unavailable" | "unknown";
+/** One field- or item-addressable server rejection. */
+export interface HonuaFieldFailure {
+    readonly code?: string;
+    readonly severity?: string;
+    readonly path?: string;
+    readonly fieldId?: string;
+    readonly itemIndex?: number;
+    readonly message?: string;
+}
+/** Protocol-native metadata retained at a terminal transport boundary. */
+export interface HonuaProtocolMetadata {
+    readonly initial: Readonly<Record<string, readonly string[]>>;
+    readonly trailing: Readonly<Record<string, readonly string[]>>;
+}
+/** Machine-actionable receipt exposed by every remote terminal SDK error. */
+export interface HonuaTerminalFailureReceipt {
+    readonly transportStatus?: number;
+    readonly protocolCode?: number | string;
+    readonly kind: HonuaFailureKind;
+    readonly code?: string;
+    readonly retryable: boolean;
+    readonly retryAfterMs?: number;
+    readonly correlationId?: string;
+    readonly fieldErrors: readonly HonuaFieldFailure[];
+    readonly protocolMetadata: HonuaProtocolMetadata;
+}
 export interface SerializedHonuaErrorCause {
     readonly name: string;
     readonly domain?: HonuaErrorDomain;
@@ -49,6 +79,7 @@ export declare abstract class HonuaSdkError extends Error {
     readonly retryable: boolean;
     readonly operationId: string | undefined;
     readonly requestId: string | undefined;
+    readonly terminalReceipt: HonuaTerminalFailureReceipt | undefined;
     readonly context: HonuaErrorEnvelopeContext;
     protected constructor(code: HonuaErrorCode, message: string, options?: HonuaErrorOptions);
     /** Safe JSON projection. Raw messages, stacks, details, bodies, and causes are intentionally omitted. */

package/core/error-envelope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-envelope.d.ts","sourceRoot":"","sources":["../../../src/core/error-envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAErG,YAAY,EACV,kBAAkB,EAClB,cAAc,EACd,wBAAwB,EACxB,gBAAgB,GACjB,MAAM,0BAA0B,CAAC;AAElC,eAAO,MAAM,gBAAgB,EAAG,oBAA6B,CAAC;AAE9D,MAAM,MAAM,8BAA8B,GACtC,IAAI,GACJ,OAAO,GACP,MAAM,GACN,MAAM,GACN,SAAS,8BAA8B,EAAE,GACzC;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,8BAA8B,CAAA;CAAE,CAAC;AAE/D,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,8BAA8B,CAAC,CAAC,CAAC;AAEjG,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACtD;AAED,MAAM,WAAW,iBAAkB,SAAQ,YAAY,EAAE,kBAAkB;CAAG;AAE9E,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,OAAO,gBAAgB,CAAC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,yBAAyB,CAAC;IAC5C,QAAQ,CAAC,KAAK,CAAC,EAAE,yBAAyB,CAAC;CAC5C;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,IAAI,CAAC,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IACvC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,sDAAsD;AACtD,8BAAsB,aAAc,SAAQ,KAAK;IAC/C,SAAgB,IAAI,uBAAoB;IACxC,SAAgB,MAAM,EAAE,gBAAgB,CAAC;IACzC,sFAAsF;IACtF,SAAgB,OAAO,EAAE,cAAc,CAAC;IACxC,SAAgB,QAAQ,EAAE,kBAAkB,CAAC;IAC7C,SAAgB,SAAS,EAAE,OAAO,CAAC;IACnC,SAAgB,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChD,SAAgB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9C,SAAgB,OAAO,EAAE,yBAAyB,CAAC;IAEnD,SAAS,aAAa,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB;IAa5F,yGAAyG;IAClG,MAAM,IAAI,oBAAoB;CAGtC;AAED,2EAA2E;AAC3E,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAoBtE;AAED,4EAA4E;AAC5E,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,GAAG,oBAAoB,CAsB9E;AAED,qEAAqE;AACrE,wBAAgB,yBAAyB,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,yBAAyB,CAShH;AAED,0GAA0G;AAC1G,wBAAgB,sBAAsB,CACpC,GAAG,QAAQ,EAAE,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,EAAE,GACtE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAgBnC;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,cAAc,CAErE;AAED,0FAA0F;AAC1F,wBAAgB,qCAAqC,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAU7E"}
+{"version":3,"file":"error-envelope.d.ts","sourceRoot":"","sources":["../../../src/core/error-envelope.ts"],"names":[],"mappings":"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"}

package/core/error-envelope.js

@@ -18,6 +18,7 @@ export class HonuaSdkError extends Error {
     retryable;
     operationId;
     requestId;
+    terminalReceipt;
     context;
     constructor(code, message, options = {}) {
         const [domain, category, retryable] = errorCodeClassification(code);
@@ -29,6 +30,7 @@ export class HonuaSdkError extends Error {
         this.retryable = retryable;
         this.operationId = sanitizeIdentifier(options.operationId);
         this.requestId = sanitizeIdentifier(options.requestId);
+        this.terminalReceipt = options.terminalReceipt;
         this.context = sanitizeHonuaErrorContext(options.context);
     }
     /** Safe JSON projection. Raw messages, stacks, details, bodies, and causes are intentionally omitted. */
@@ -69,6 +71,7 @@ export function serializeHonuaError(error) {
     const cause = serializeCause(ownDataProperty(error, "cause"));
     const operationId = sanitizeIdentifier(asOptionalString(ownDataProperty(error, "operationId")));
     const requestId = sanitizeIdentifier(asOptionalString(ownDataProperty(error, "requestId")));
+    const receipt = ownDataProperty(error, "terminalReceipt");
     const context = ownDataProperty(error, "context");
     return {
         kind: HONUA_ERROR_KIND,
@@ -79,10 +82,18 @@ export function serializeHonuaError(error) {
         retryable,
         ...(operationId ? { operationId } : {}),
         ...(requestId ? { requestId } : {}),
+        ...(isTerminalFailureReceipt(receipt) ? { receipt } : {}),
         context: isRecord(context) && !Array.isArray(context) ? sanitizeHonuaErrorContext(context) : emptyContext(),
         ...(cause ? { cause } : {}),
     };
 }
+function isTerminalFailureReceipt(value) {
+    return (isRecord(value) &&
+        typeof ownDataProperty(value, "kind") === "string" &&
+        typeof ownDataProperty(value, "retryable") === "boolean" &&
+        Array.isArray(ownDataProperty(value, "fieldErrors")) &&
+        isRecord(ownDataProperty(value, "protocolMetadata")));
+}
 /** Redact structured context before it is stored on an SDK error. */
 export function sanitizeHonuaErrorContext(context) {
     if (!context)

package/core/errors.d.ts

@@ -30,7 +30,17 @@
  *
  * @packageDocumentation
  */
-import { type HonuaErrorMetadata, type HonuaErrorOptions, HonuaSdkError } from "./error-envelope.js";
+import { type HonuaErrorMetadata, type HonuaErrorOptions, type HonuaFailureKind, type HonuaFieldFailure, type HonuaProtocolMetadata, HonuaSdkError, type HonuaTerminalFailureReceipt } from "./error-envelope.js";
+export type { HonuaFailureKind, HonuaFieldFailure, HonuaProtocolMetadata, HonuaTerminalFailureReceipt };
+export interface HonuaHttpErrorOptions extends HonuaErrorOptions {
+    readonly responseHeaders?: Pick<Headers, "entries" | "get"> | Readonly<Record<string, string | readonly string[]>>;
+    readonly protocolCode?: number | string;
+    readonly transportStatus?: number;
+}
+export interface HonuaGrpcErrorOptions extends HonuaErrorOptions {
+    readonly initialMetadata?: unknown;
+    readonly trailingMetadata?: unknown;
+}
 export type HonuaDiscoveryErrorCode = "ambiguous-protocol" | "ambiguous-source" | "invalid-cloud-native-input" | "invalid-cloud-native-manifest" | "invalid-endpoint" | "invalid-cache-identity" | "invalid-discovery-cache" | "invalid-capability" | "cloud-native-operation-unavailable" | "unsupported-protocol" | "protocol-mismatch";
 /** Discovery input, metadata, or cache identity is invalid or inconsistent. */
 export declare class HonuaDiscoveryError extends HonuaSdkError {
@@ -60,7 +70,8 @@ export declare class HonuaGeometryError extends HonuaSdkError {
 export declare class HonuaHttpError extends HonuaSdkError {
     readonly statusCode: number;
     readonly body: unknown;
-    constructor(statusCode: number, message: string, body: unknown, options?: HonuaErrorOptions);
+    readonly receipt: HonuaTerminalFailureReceipt;
+    constructor(statusCode: number, message: string, body: unknown, options?: HonuaHttpErrorOptions);
 }
 /** Thrown when a request exceeds the configured timeout. */
 export declare class HonuaTimeoutError extends HonuaSdkError {
@@ -80,7 +91,8 @@ export declare class HonuaAbortError extends HonuaSdkError {
 export declare class HonuaGrpcError extends HonuaSdkError {
     readonly code: number;
     readonly details: unknown;
-    constructor(code: number, message: string, details?: unknown, options?: HonuaErrorOptions);
+    readonly receipt: HonuaTerminalFailureReceipt;
+    constructor(code: number, message: string, details?: unknown, options?: HonuaGrpcErrorOptions);
 }
 /**
  * Thrown when a `Source` is asked to perform an operation that the underlying

package/core/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,aAAa,EAGd,MAAM,qBAAqB,CAAC;AAE7B,MAAM,MAAM,uBAAuB,GAC/B,oBAAoB,GACpB,kBAAkB,GAClB,4BAA4B,GAC5B,+BAA+B,GAC/B,kBAAkB,GAClB,wBAAwB,GACxB,yBAAyB,GACzB,oBAAoB,GACpB,oCAAoC,GACpC,sBAAsB,GACtB,mBAAmB,CAAC;AAExB,+EAA+E;AAC/E,qBAAa,mBAAoB,SAAQ,aAAa;aAElC,IAAI,EAAE,uBAAuB;aAE7B,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAF1C,IAAI,EAAE,uBAAuB,EAC7C,OAAO,EAAE,MAAM,EACC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,YAAA,EAC1D,OAAO,GAAE,iBAAsB;CAQlC;AAED,gFAAgF;AAChF,MAAM,MAAM,sBAAsB,GAAG,kBAAkB,GAAG,oBAAoB,CAAC;AAE/E;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,aAAa;aAEjC,IAAI,EAAE,sBAAsB;aAE5B,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAF1C,IAAI,EAAE,sBAAsB,EAC5C,OAAO,EAAE,MAAM,EACC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,YAAA,EAC1D,OAAO,GAAE,iBAAsB;CAQlC;AAED;;;;;;GAMG;AACH,qBAAa,cAAe,SAAQ,aAAa;IAC/C,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,IAAI,EAAE,OAAO,CAAC;gBAEX,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,GAAE,iBAAsB;CAavG;AAED,4DAA4D;AAC5D,qBAAa,iBAAkB,SAAQ,aAAa;IAClD,SAAgB,SAAS,EAAE,MAAM,CAAC;gBAEf,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB;CAQtE;AAED,kFAAkF;AAClF,qBAAa,iBAAkB,SAAQ,aAAa;IAClD,SAAyB,KAAK,EAAE,OAAO,CAAC;gBAErB,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,GAAE,kBAAuB;CAKtF;AAED,0EAA0E;AAC1E,qBAAa,eAAgB,SAAQ,aAAa;gBAC7B,OAAO,SAAwB,EAAE,OAAO,GAAE,iBAAsB;CAIpF;AAED,kFAAkF;AAClF,qBAAa,cAAe,SAAQ,aAAa;aAI7B,IAAI,EAAE,MAAM;IAH9B,SAAgB,OAAO,EAAE,OAAO,CAAC;gBAGf,IAAI,EAAE,MAAM,EAC5B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,OAAO,EACjB,OAAO,GAAE,iBAAsB;CASlC;AAED;;;;;;GAMG;AACH,qBAAa,gCAAiC,SAAQ,aAAa;IACjE,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,EAAE,OAAO,GAAE,iBAAsB;CAa5G;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,kBAAkB,GAAG,sBAAsB,GAAG,gBAAgB,GAAG,eAAe,CAAC;AAE7F;;;;;;;;GAQG;AACH,qBAAa,cAAe,SAAQ,aAAa;aAI7B,IAAI,EAAE,kBAAkB;IAH1C,SAAyB,KAAK,EAAE,OAAO,CAAC;gBAGtB,IAAI,EAAE,kBAAkB,EACxC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,iBAAsB;CAMlC;AAED;;;;;GAKG;AACH,qBAAa,4BAA6B,SAAQ,aAAa;aAE3C,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM,EAC5B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,iBAAsB;CAQlC;AAED;;;;;;;GAOG;AACH,qBAAa,sBAAuB,SAAQ,aAAa;IACvD,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,EAAE,OAAO,GAAE,iBAAsB;CAY7G;AAED,iEAAiE;AACjE,MAAM,MAAM,UAAU,GAAG,aAAa,CAAC;AAEvC,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

@@ -73,14 +73,19 @@ export class HonuaGeometryError extends HonuaSdkError {
 export class HonuaHttpError extends HonuaSdkError {
     statusCode;
     body;
+    receipt;
     constructor(statusCode, message, body, options = {}) {
-        super(HTTP_RETRYABLE_STATUSES.has(statusCode) ? "core.http.transient" : "core.http.rejected", `HTTP ${statusCode}: ${message}`, {
+        const receipt = httpFailureReceipt(statusCode, body, options);
+        super(receipt.retryable ? "core.http.transient" : "core.http.rejected", `HTTP ${statusCode}: ${message}`, {
             ...options,
+            requestId: options.requestId ?? receipt.correlationId,
+            terminalReceipt: receipt,
             context: mergeHonuaErrorContext(options.context, { statusCode }),
         });
         this.name = "HonuaHttpError";
         this.statusCode = statusCode;
         this.body = body;
+        this.receipt = receipt;
     }
 }
 /** Thrown when a request exceeds the configured timeout. */
@@ -115,14 +120,19 @@ export class HonuaAbortError extends HonuaSdkError {
 export class HonuaGrpcError extends HonuaSdkError {
     code;
     details;
+    receipt;
     constructor(code, message, details, options = {}) {
-        super(GRPC_RETRYABLE_CODES.has(code) ? "core.grpc.transient" : "core.grpc.rejected", message, {
+        const receipt = grpcFailureReceipt(code, details, options);
+        super(receipt.retryable ? "core.grpc.transient" : "core.grpc.rejected", message, {
             ...options,
+            requestId: options.requestId ?? receipt.correlationId,
+            terminalReceipt: receipt,
             context: mergeHonuaErrorContext(options.context, { grpcCode: code }),
         });
         this.code = code;
         this.name = "HonuaGrpcError";
         this.details = details;
+        this.receipt = receipt;
     }
 }
 /**
@@ -221,3 +231,245 @@ const AUTH_ERROR_CODES = {
     refresh_failed: "core.auth.refresh-failed",
     invalid_grant: "core.auth.invalid-grant",
 };
+function httpFailureReceipt(statusCode, body, options) {
+    const root = isObject(body) ? body : undefined;
+    const protocolError = root && isObject(root.error) ? root.error : undefined;
+    const source = protocolError ?? root;
+    const protocolCode = options.protocolCode ?? scalarCode(protocolError?.code);
+    const classificationCode = typeof protocolCode === "number" ? protocolCode : statusCode;
+    const metadata = metadataRecord(options.responseHeaders);
+    const bodyKind = stringValue(source?.kind);
+    const kind = isFailureKind(bodyKind) ? bodyKind : failureKindForHttp(classificationCode, statusCode);
+    const code = stringValue(source?.machineCode) ?? stringValue(source?.code) ?? stringValue(root?.code) ?? defaultCode(kind);
+    const explicitRetryable = booleanValue(source?.retryable) ?? booleanValue(root?.retryable);
+    const retryAfterSeconds = numberValue(source?.retryAfterSeconds) ?? numberValue(root?.retryAfterSeconds);
+    const headerDelay = parseRetryAfter(metadataGetter(options.responseHeaders));
+    const correlationId = stringValue(source?.correlationId) ??
+        stringValue(root?.correlationId) ??
+        firstMetadata(metadata, "x-correlation-id", "honua-request-id", "x-request-id", "honua-correlation-id");
+    const fieldErrors = parseFieldFailures(source?.errors ?? root?.errors);
+    return freezeReceipt({
+        transportStatus: options.transportStatus ?? statusCode,
+        ...(protocolCode !== undefined ? { protocolCode } : {}),
+        kind,
+        ...(code ? { code } : {}),
+        retryable: explicitRetryable ??
+            (HTTP_RETRYABLE_STATUSES.has(classificationCode) ||
+                HTTP_RETRYABLE_STATUSES.has(options.transportStatus ?? statusCode)),
+        ...(retryAfterSeconds !== undefined
+            ? { retryAfterMs: Math.max(0, retryAfterSeconds * 1_000) }
+            : headerDelay !== undefined
+                ? { retryAfterMs: headerDelay }
+                : {}),
+        ...(correlationId ? { correlationId } : {}),
+        fieldErrors,
+        protocolMetadata: { initial: metadata, trailing: emptyMetadata() },
+    });
+}
+function grpcFailureReceipt(code, details, options) {
+    const initial = metadataRecord(options.initialMetadata);
+    const trailing = metadataRecord(options.trailingMetadata);
+    const declaredMachineCode = firstMetadata(trailing, "honua-error-code") ?? firstMetadata(initial, "honua-error-code");
+    const declaredKind = firstMetadata(trailing, "honua-error-kind") ?? firstMetadata(initial, "honua-error-kind");
+    const kind = isFailureKind(declaredKind) ? declaredKind : failureKindForGrpc(code);
+    const machineCode = declaredMachineCode ?? defaultCode(kind);
+    const declaredRetryable = firstMetadata(trailing, "honua-retryable", "honua-error-retryable") ??
+        firstMetadata(initial, "honua-retryable", "honua-error-retryable");
+    const retryAfterMs = parseRetryAfter(metadataGetterFromRecords(trailing, initial));
+    const correlationId = firstMetadata(trailing, "x-correlation-id", "honua-request-id", "x-request-id", "honua-correlation-id") ??
+        firstMetadata(initial, "x-correlation-id", "honua-request-id", "x-request-id", "honua-correlation-id");
+    const encodedErrors = firstMetadata(trailing, "honua-error-details") ?? firstMetadata(initial, "honua-error-details");
+    return freezeReceipt({
+        protocolCode: code,
+        kind,
+        code: machineCode,
+        retryable: parseBoolean(declaredRetryable) ?? GRPC_RETRYABLE_CODES.has(code),
+        ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+        ...(correlationId ? { correlationId } : {}),
+        fieldErrors: parseEncodedFieldFailures(encodedErrors, details),
+        protocolMetadata: { initial, trailing },
+    });
+}
+function failureKindForHttp(code, transportStatus) {
+    if (code === 401 || code === 498 || code === 499)
+        return "authentication";
+    if (code === 403)
+        return "authorization";
+    if (code === 404)
+        return "not-found";
+    if (code === 400 || code === 422)
+        return "validation";
+    if (code === 409 || code === 412 || code === 428)
+        return "conflict";
+    if (code === 429)
+        return "throttled";
+    if (HTTP_RETRYABLE_STATUSES.has(code) || transportStatus >= 500)
+        return "unavailable";
+    return "unknown";
+}
+function failureKindForGrpc(code) {
+    if (code === 16)
+        return "authentication";
+    if (code === 7)
+        return "authorization";
+    if (code === 5)
+        return "not-found";
+    if (code === 3)
+        return "validation";
+    if (code === 10 || code === 6)
+        return "conflict";
+    if (code === 8)
+        return "throttled";
+    if (GRPC_RETRYABLE_CODES.has(code))
+        return "unavailable";
+    return "unknown";
+}
+function defaultCode(kind) {
+    return {
+        authentication: "authentication_required",
+        authorization: "permission_denied",
+        "not-found": "resource_not_found",
+        validation: "validation_failed",
+        conflict: "resource_conflict",
+        throttled: "rate_limit_exceeded",
+        unavailable: "service_unavailable",
+        unknown: "unknown_failure",
+    }[kind];
+}
+function metadataRecord(value) {
+    const result = Object.create(null);
+    const add = (key, item) => {
+        const normalized = key.toLowerCase();
+        if (SENSITIVE_METADATA_KEYS.has(normalized))
+            return;
+        const values = Array.isArray(item)
+            ? item.filter((entry) => typeof entry === "string")
+            : [String(item)];
+        if (values.length > 0)
+            result[normalized] = Object.freeze(values.slice(0, 20));
+    };
+    if (value && typeof value.entries === "function") {
+        for (const [key, item] of value.entries())
+            add(key, item);
+    }
+    else if (isObject(value)) {
+        for (const [key, item] of Object.entries(value))
+            add(key, item);
+    }
+    return Object.freeze(result);
+}
+function metadataGetter(value) {
+    if (value && typeof value.get === "function")
+        return value;
+    return metadataGetterFromRecords(metadataRecord(value));
+}
+function metadataGetterFromRecords(...records) {
+    return {
+        get(name) {
+            for (const record of records) {
+                const value = firstMetadata(record, name);
+                if (value)
+                    return value;
+            }
+            return null;
+        },
+    };
+}
+function firstMetadata(record, ...keys) {
+    for (const key of keys) {
+        const value = record[key.toLowerCase()]?.[0];
+        if (value)
+            return value;
+    }
+    return undefined;
+}
+function parseRetryAfter(headers) {
+    const value = headers.get("retry-after");
+    if (!value)
+        return undefined;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return seconds * 1_000;
+    const target = Date.parse(value);
+    return Number.isFinite(target) ? Math.max(0, target - Date.now()) : undefined;
+}
+function parseEncodedFieldFailures(encoded, details) {
+    if (encoded) {
+        try {
+            return parseFieldFailures(JSON.parse(encoded));
+        }
+        catch {
+            return [];
+        }
+    }
+    return parseFieldFailures(details);
+}
+function parseFieldFailures(value) {
+    if (!Array.isArray(value))
+        return Object.freeze([]);
+    return Object.freeze(value.filter(isObject).map((item) => {
+        const code = stringValue(item.code);
+        const severity = stringValue(item.severity);
+        const path = stringValue(item.path);
+        const fieldId = stringValue(item.fieldId);
+        const itemIndex = numberValue(item.itemIndex);
+        const message = stringValue(item.message);
+        return Object.freeze({
+            ...(code ? { code } : {}),
+            ...(severity ? { severity } : {}),
+            ...(path ? { path } : {}),
+            ...(fieldId ? { fieldId } : {}),
+            ...(itemIndex !== undefined ? { itemIndex } : {}),
+            ...(message ? { message } : {}),
+        });
+    }));
+}
+function freezeReceipt(receipt) {
+    return Object.freeze({
+        ...receipt,
+        fieldErrors: Object.freeze([...receipt.fieldErrors]),
+        protocolMetadata: Object.freeze({
+            initial: receipt.protocolMetadata.initial,
+            trailing: receipt.protocolMetadata.trailing,
+        }),
+    });
+}
+function emptyMetadata() {
+    return Object.freeze(Object.create(null));
+}
+function scalarCode(value) {
+    return typeof value === "number" || typeof value === "string" ? value : undefined;
+}
+function stringValue(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function booleanValue(value) {
+    return typeof value === "boolean" ? value : undefined;
+}
+function parseBoolean(value) {
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    return undefined;
+}
+function numberValue(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function isFailureKind(value) {
+    return value !== undefined && FAILURE_KINDS.has(value);
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const FAILURE_KINDS = new Set([
+    "authentication",
+    "authorization",
+    "not-found",
+    "validation",
+    "conflict",
+    "throttled",
+    "unavailable",
+    "unknown",
+]);
+const SENSITIVE_METADATA_KEYS = new Set(["authorization", "cookie", "set-cookie", "x-api-key"]);

package/core/geometry-input-sr.d.ts

@@ -0,0 +1,3 @@
+/** GeoServices query geometry defaults to WGS84, never the target layer CRS. */
+export declare function geometryInputSpatialReference(geometry: unknown): string | number;
+//# sourceMappingURL=geometry-input-sr.d.ts.map

package/core/geometry-input-sr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geometry-input-sr.d.ts","sourceRoot":"","sources":["../../../src/core/geometry-input-sr.ts"],"names":[],"mappings":"AAEA,gFAAgF;AAChF,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAqBhF"}

package/core/geometry-input-sr.js

@@ -0,0 +1,28 @@
+import { HonuaGeometryError } from "./errors.js";
+/** GeoServices query geometry defaults to WGS84, never the target layer CRS. */
+export function geometryInputSpatialReference(geometry) {
+    if (typeof geometry === "string") {
+        try {
+            geometry = JSON.parse(geometry);
+        }
+        catch {
+            // GeoServices also accepts comma-separated coordinate strings.
+            return 4326;
+        }
+    }
+    if (typeof geometry !== "object" || geometry === null || !("spatialReference" in geometry))
+        return 4326;
+    const sr = geometry.spatialReference;
+    if (typeof sr === "object" && sr !== null) {
+        if ("wkt" in sr && typeof sr.wkt === "string" && sr.wkt.trim())
+            return JSON.stringify(sr);
+        if ("latestWkid" in sr && typeof sr.latestWkid === "number" && Number.isInteger(sr.latestWkid) && sr.latestWkid > 0)
+            return sr.latestWkid;
+        if ("wkid" in sr && typeof sr.wkid === "number" && Number.isInteger(sr.wkid) && sr.wkid > 0)
+            return sr.wkid;
+    }
+    throw new HonuaGeometryError("malformed-geometry", "Query geometry has an invalid spatialReference", {
+        operation: "query-input-spatial-reference",
+        reason: "invalid-spatial-reference",
+    });
+}

package/core/geoservices.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"geoservices.d.ts","sourceRoot":"","sources":["../../../src/core/geoservices.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AAEpE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAChB,uBAAuB,EACvB,sBAAsB,EACtB,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,2BAA2B,EAC3B,oBAAoB,EACpB,qBAAqB,EACrB,cAAc,EACd,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,EAChB,wBAAwB,EACxB,oBAAoB,EAEpB,0BAA0B,EAC3B,MAAM,YAAY,CAAC;AAIpB,wBAAsB,YAAY,CAChC,SAAS,EAAE,sBAAsB,EACjC,MAAM,EAAE,MAAM,GAAG,OAAO,EACxB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,qBAAqB,CAAC,CAIhC;AAED,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,sBAAsB,EACjC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,kBAAkB,CAAC,CAQ7B;AAED,wBAAsB,yBAAyB,CAC7C,SAAS,EAAE,sBAAsB,EACjC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,oBAAoB,CAAC,CAQ/B;AAED,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,sBAAsB,EACjC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,oBAAoB,CAAC,CAQ/B;AAED,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,sBAAsB,EACjC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,kBAAkB,CAAC,CAQ7B;AAID;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,oBAAoB,EAC7B,YAAY,EAAE,OAAO,GACpB,OAAO,CAAC,kBAAkB,CAAC,CAsC7B;AAED,wBAAsB,aAAa,CACjC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,kBAAkB,CAAC,CA2B7B;AAED,wBAAsB,UAAU,CAC9B,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,uBAAuB,CAAC,CA0BlC;AAED,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,2BAA2B,CAAC,CAyCtC;AAED,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,2BAA2B,CAAC,CAwCtC;AAED,wBAAsB,SAAS,CAC7B,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,sBAAsB,CAAC,CA6CjC;AAED,wBAAsB,YAAY,CAChC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,mBAAmB,CAAC,CAiB9B;AAED,wBAAsB,WAAW,CAC/B,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,qBAAqB,CAAC,CA8ChC;AAED,wBAAsB,OAAO,CAAC,SAAS,EAAE,sBAAsB,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA2DpH"}
+{"version":3,"file":"geoservices.d.ts","sourceRoot":"","sources":["../../../src/core/geoservices.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AAGpE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAChB,uBAAuB,EACvB,sBAAsB,EACtB,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,2BAA2B,EAC3B,oBAAoB,EACpB,qBAAqB,EACrB,cAAc,EACd,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,EAChB,wBAAwB,EACxB,oBAAoB,EAEpB,0BAA0B,EAC3B,MAAM,YAAY,CAAC;AAIpB,wBAAsB,YAAY,CAChC,SAAS,EAAE,sBAAsB,EACjC,MAAM,EAAE,MAAM,GAAG,OAAO,EACxB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,qBAAqB,CAAC,CAIhC;AAED,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,sBAAsB,EACjC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,kBAAkB,CAAC,CAQ7B;AAED,wBAAsB,yBAAyB,CAC7C,SAAS,EAAE,sBAAsB,EACjC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,oBAAoB,CAAC,CAQ/B;AAED,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,sBAAsB,EACjC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,oBAAoB,CAAC,CAQ/B;AAED,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,sBAAsB,EACjC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,kBAAkB,CAAC,CAQ7B;AAoBD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,oBAAoB,EAC7B,YAAY,EAAE,OAAO,GACpB,OAAO,CAAC,kBAAkB,CAAC,CAwC7B;AAED,wBAAsB,aAAa,CACjC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,kBAAkB,CAAC,CA4B7B;AAED,wBAAsB,UAAU,CAC9B,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,uBAAuB,CAAC,CA0BlC;AAED,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,2BAA2B,CAAC,CAyCtC;AAED,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,2BAA2B,CAAC,CAwCtC;AAED,wBAAsB,SAAS,CAC7B,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,sBAAsB,CAAC,CA6CjC;AAED,wBAAsB,YAAY,CAChC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,mBAAmB,CAAC,CAiB9B;AAED,wBAAsB,WAAW,CAC/B,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,qBAAqB,CAAC,CA8ChC;AAED,wBAAsB,OAAO,CAAC,SAAS,EAAE,sBAAsB,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA2DpH"}

package/core/geoservices.js

@@ -8,6 +8,7 @@
  *
  * @module
  */
+import { geometryInputSpatialReference } from "./geometry-input-sr.js";
 import { encodeServiceIdPath } from "./path-utils.js";
 // ── Metadata ────────────────────────────────────────────────────
 export async function listServices(transport, format, options = {}) {
@@ -36,6 +37,17 @@ export async function getMapLayerMetadata(transport, serviceId, layerId, options
     return transport.requestCachedMetadataJson(`geoservices-map:${serviceId}:${layerId}`, path, options);
 }
 // ── FeatureServer / MapServer operations ────────────────────────
+// A conservative request-target budget avoids common browser/proxy URL limits.
+// Measure encoded parameters plus the configured base path: Unicode, polygon
+// coordinates, and a deployment prefix (e.g. `/honua`) can all expand the
+// actual request target that `resolveRequestUrl` sends. Explicit caller
+// choices remain authoritative.
+function queryMethod(method, path, params, baseUrl) {
+    if (method !== undefined)
+        return method;
+    const url = new URL(`${baseUrl}${path}?${params.toString()}`, globalThis.location?.href ?? "https://honua.invalid");
+    return url.pathname.length + url.search.length > 2_000 ? "POST" : "GET";
+}
 /**
  * REST portion of `client.queryFeatures` (the gRPC-web fast path is
  * orchestrated by the client). Maps directly to the FeatureServer `query`
@@ -43,16 +55,18 @@ export async function getMapLayerMetadata(transport, serviceId, layerId, options
  * `preferBinary` is set.
  */
 export async function queryFeaturesRest(transport, request, preferBinary) {
-    const method = request.method ?? "GET";
-    const usePbf = preferBinary && method === "GET";
     const params = new URLSearchParams();
-    params.set("f", usePbf ? "pbf" : "json");
+    params.set("f", preferBinary && (request.method === undefined || request.method === "GET") ? "pbf" : "json");
     params.set("where", request.where ?? "1=1");
     params.set("outFields", normalizeOutFields(request.outFields));
     params.set("returnGeometry", String(request.returnGeometry ?? true));
     serializeQueryParams(params, request);
     appendQueryExtraParams(params, request);
     const path = `/rest/services/${encodeServiceIdPath(request.serviceId)}/FeatureServer/${request.layerId}/query`;
+    const method = queryMethod(request.method, path, params, transport.baseUrl);
+    const usePbf = preferBinary && method === "GET";
+    if (request.method === undefined && method === "POST" && params.get("f") === "pbf")
+        params.set("f", "json");
     if (usePbf) {
         return transport.requestBinaryWithJsonFallback("GET", `${path}?${params.toString()}`, params, request.signal);
     }
@@ -64,10 +78,9 @@ export async function queryFeaturesRest(transport, request, preferBinary) {
             "Content-Type": "application/x-www-form-urlencoded",
         },
         body: params.toString(),
-    }, request.signal);
+    }, request.signal, request.method === undefined ? { readOnlyQuery: true } : undefined);
 }
 export async function queryMapLayer(transport, request) {
-    const method = request.method ?? "GET";
     const params = new URLSearchParams();
     params.set("f", "json");
     params.set("where", request.where ?? "1=1");
@@ -76,6 +89,7 @@ export async function queryMapLayer(transport, request) {
     serializeQueryParams(params, request);
     appendQueryExtraParams(params, request);
     const path = `/rest/services/${encodeServiceIdPath(request.serviceId)}/MapServer/${request.layerId}/query`;
+    const method = queryMethod(request.method, path, params, transport.baseUrl);
     if (method === "GET") {
         return transport.requestJson("GET", `${path}?${params.toString()}`, undefined, request.signal);
     }
@@ -84,7 +98,7 @@ export async function queryMapLayer(transport, request) {
             "Content-Type": "application/x-www-form-urlencoded",
         },
         body: params.toString(),
-    }, request.signal);
+    }, request.signal, request.method === undefined ? { readOnlyQuery: true } : undefined);
 }
 export async function applyEdits(transport, request) {
     const path = `/rest/services/${encodeServiceIdPath(request.serviceId)}/FeatureServer/${request.layerId}/applyEdits`;
@@ -392,6 +406,7 @@ function serializeQueryParams(params, request) {
         params.set("objectIds", Array.isArray(request.objectIds) ? request.objectIds.join(",") : String(request.objectIds));
     }
     if (request.geometry !== undefined) {
+        params.set("inSR", String(request.extraParams?.inSR ?? geometryInputSpatialReference(request.geometry)));
         params.set("geometry", typeof request.geometry === "object" && request.geometry !== null
             ? JSON.stringify(request.geometry)
             : String(request.geometry));
@@ -402,6 +417,18 @@ function serializeQueryParams(params, request) {
     if (request.spatialRel !== undefined) {
         params.set("spatialRel", request.spatialRel);
     }
+    if (request.distance !== undefined) {
+        params.set("distance", String(request.distance));
+    }
+    if (request.units !== undefined) {
+        params.set("units", request.units);
+    }
+    if (request.nearestCount !== undefined) {
+        params.set("nearestCount", String(request.nearestCount));
+    }
+    if (request.returnDistance !== undefined) {
+        params.set("returnDistance", String(request.returnDistance));
+    }
     if (request.returnDistinctValues !== undefined) {
         params.set("returnDistinctValues", String(request.returnDistinctValues));
     }