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

package/core/client.js

@@ -1,6 +1,6 @@
 import { HONUA_DEFAULT_METADATA_STALE_IF_ERROR_MS, createHonuaCacheState, honuaCacheValidatorFromHeaders, honuaMetadataRequestHeaders, isHonuaCacheEntryFresh, normalizeHonuaMetadataRequestOptions, withHonuaCacheState, withoutHonuaCacheState, } from "./cache-state.js";
 import { HONUA_MINIMUM_SUPPORTED_SERVER_VERSION, MINIMUM_SUPPORTED_SERVER_RELEASE_CHANNEL, describeCompatibilityError, evaluateCompatibility, parseCompatibilityEnvelope, } from "./compatibility.js";
-import { HonuaHttpError, HonuaNetworkError, HonuaTimeoutError } from "./errors.js";
+import { HonuaAbortError, HonuaHttpError, HonuaNetworkError, HonuaTimeoutError } from "./errors.js";
 import { applyEdits, exportMap, findMap, getFeatureServiceMetadata, getLayerMetadata, getMapLayerMetadata, getMapLegend, getMapServiceMetadata, identifyMap, listServices, queryFeaturesRest, queryMapLayer, queryMapRelatedRecords, queryRelatedRecords, } from "./geoservices.js";
 import { HonuaOdataEntitySet } from "./odata.js";
 import { honuaFacadeFeaturesLayout, resolveOgcEndpointLayout } from "./ogc-endpoint-layout.js";
@@ -557,8 +557,18 @@ export class HonuaClient {
     wmts(serviceId) {
         return new HonuaWmts({ client: this, serviceId });
     }
-    ogcProcesses() {
-        return new HonuaOgcProcesses({ client: this });
+    /**
+     * Construct the OGC API Processes client wrapper.
+     *
+     * `basePath` pins every describe / execute / job route to a raw third-party
+     * service root (as discovered by `discoverOgcProcesses()`); omitting it uses
+     * the Honua facade prefix `/ogc/processes`. Pass the discovery result (or a
+     * `/conformance` response) as `conformance` — and optionally
+     * `capabilityPolicy: "strict"` — to gate execution and dismissal against what
+     * the server actually declares.
+     */
+    ogcProcesses(options = {}) {
+        return new HonuaOgcProcesses({ ...options, client: this });
     }
     stac() {
         return new HonuaStacSearch({ client: this });
@@ -575,8 +585,8 @@ export class HonuaClient {
     processRunner(adapter) {
         return createHonuaProcessRunner(adapter);
     }
-    ogcProcessRunner() {
-        return createHonuaProcessRunner(createOgcProcessesAdapter(this.ogcProcesses()));
+    ogcProcessRunner(options = {}) {
+        return createHonuaProcessRunner(createOgcProcessesAdapter(this.ogcProcesses(options)));
     }
     geoprocessingRunner(serviceId, taskName) {
         return createHonuaProcessRunner(createGeoServicesGpAdapter(this.geoprocessing(serviceId, taskName)));
@@ -801,6 +811,7 @@ export class HonuaClient {
             path,
             method,
             init: {
+                ...init,
                 method,
                 headers: await this.composeHeaders(init?.headers),
                 body: init?.body ?? null,
@@ -811,6 +822,9 @@ export class HonuaClient {
             callerSignal,
             ...(options.okStatuses ? { okStatuses: options.okStatuses } : {}),
             ...(options.redirect ? { redirect: options.redirect } : {}),
+            ...(options.beforeAttempt ? { beforeAttempt: options.beforeAttempt } : {}),
+            ...(options.beforeReplay ? { beforeReplay: options.beforeReplay } : {}),
+            ...(options.prepareResponse ? { deadlineThroughFinalize: true } : {}),
             ...(options.discardErrorBody
                 ? {
                     errorBody: (response) => {
@@ -819,9 +833,11 @@ export class HonuaClient {
                     },
                 }
                 : {}),
-            finalize: async (response, _durationMs, _request, runAfter) => {
-                await runAfter();
-                return response;
+            finalize: async (response, _durationMs, _request, runAfter, deadlineSignal) => {
+                const candidate = options.prepareResponse ? await options.prepareResponse(response, deadlineSignal) : response;
+                const prepared = candidate === response ? response : preserveResponseSemantics(candidate, response);
+                await runAfter(prepared);
+                return prepared;
             },
         });
     }
@@ -1334,6 +1350,10 @@ export class HonuaClient {
      * to reach `fetch` directly.
      */
     async requestText(method, path, options) {
+        if (options?.maxResponseBytes !== undefined &&
+            (!Number.isSafeInteger(options.maxResponseBytes) || options.maxResponseBytes <= 0)) {
+            throw new TypeError("maxResponseBytes must be a positive safe integer.");
+        }
         const acceptHeader = options?.accept ?? "*/*";
         const headers = { Accept: acceptHeader };
         if (options?.contentType)
@@ -1350,14 +1370,26 @@ export class HonuaClient {
         };
         return this.executeRequest(request, {
             callerSignal: options?.signal,
-            errorBody: async (response) => {
-                const text = await response.clone().text();
+            deadlineThroughFinalize: options?.maxResponseBytes !== undefined,
+            errorBody: async (response, deadlineSignal) => {
+                const clone = response.clone();
+                const text = options?.maxResponseBytes === undefined
+                    ? await clone.text()
+                    : new TextDecoder().decode(await readBoundedResponseBytes(clone, options.maxResponseBytes, deadlineSignal));
                 const contentType = response.headers.get("content-type") ?? acceptHeader;
                 return text ? { raw: text, contentType } : {};
             },
-            finalize: async (response, _durationMs, _request, runAfter) => {
-                await runAfter();
-                const text = await response.text();
+            finalize: async (response, _durationMs, _request, runAfter, deadlineSignal) => {
+                if (options?.maxResponseBytes === undefined) {
+                    await runAfter();
+                    const text = await response.text();
+                    const contentType = response.headers.get("content-type") ?? acceptHeader;
+                    return { text, contentType, status: response.status };
+                }
+                const bytes = await readBoundedResponseBytes(response, options.maxResponseBytes, deadlineSignal);
+                const prepared = preserveResponseSemantics(bufferedResponse(response, bytes), response);
+                await runAfter(prepared);
+                const text = new TextDecoder().decode(bytes);
                 const contentType = response.headers.get("content-type") ?? acceptHeader;
                 return { text, contentType, status: response.status };
             },
@@ -1424,14 +1456,17 @@ export class HonuaClient {
         let refreshedAuth = false;
         for (let attempt = 0;; attempt += 1) {
             let response;
+            await options.beforeAttempt?.(cloneRequestContext(request), attempt);
             const timeout = createTimeoutSignal(options.callerSignal ?? request.init.signal, this.timeoutMs);
             const startTime = performance.now();
+            let fetchCompleted = false;
             try {
                 response = await this.fetchWithSafeRedirects(request.url, {
                     ...request.init,
                     method: request.method,
                     signal: timeout.signal,
                 }, options.redirect);
+                fetchCompleted = true;
             }
             catch (error) {
                 const durationMs = performance.now() - startTime;
@@ -1439,6 +1474,7 @@ export class HonuaClient {
                     ? new HonuaTimeoutError(this.timeoutMs ?? 0)
                     : normalizeNetworkError(error);
                 if (shouldRetryRequest(this.retryOptions, request.method, attempt, undefined, normalizedError)) {
+                    await options.beforeReplay?.(cloneRequestContext(request), undefined, "retry");
                     await this.sleepBeforeRetry(attempt, undefined, retrySignal);
                     continue;
                 }
@@ -1453,46 +1489,98 @@ export class HonuaClient {
                 throw normalizedError;
             }
             finally {
-                timeout.dispose();
+                if (!fetchCompleted || !options.deadlineThroughFinalize)
+                    timeout.dispose();
             }
             const durationMs = performance.now() - startTime;
             const currentRequest = request;
-            const runAfter = async () => {
+            let terminalErrorNotification;
+            const beginTerminalErrorNotification = (error, errorDurationMs) => {
+                if (terminalErrorNotification) {
+                    return { claimed: false, completion: terminalErrorNotification.completion };
+                }
+                const completion = this.applyErrorInterceptorsConcurrently({
+                    request: cloneRequestContext(currentRequest),
+                    error,
+                    durationMs: errorDurationMs,
+                });
+                terminalErrorNotification = { completion };
+                return { claimed: true, completion };
+            };
+            const awaitDeadlineOwned = async (operation) => {
+                const owned = operation.catch(async (error) => {
+                    const notification = beginTerminalErrorNotification(error, performance.now() - startTime);
+                    if (notification.claimed) {
+                        await notification.completion;
+                    }
+                    throw error;
+                });
+                return await awaitAbortable(owned, timeout.signal);
+            };
+            const runAfter = async (preparedResponse = response) => {
                 try {
-                    await this.applyAfterInterceptors(cloneRequestContext(currentRequest), response, durationMs);
+                    await this.applyAfterInterceptors(cloneRequestContext(currentRequest), preparedResponse, durationMs, options.deadlineThroughFinalize ? timeout.signal : undefined);
                 }
                 catch (error) {
+                    if (options.deadlineThroughFinalize)
+                        throw error;
                     await this.applyErrorInterceptors({ request: cloneRequestContext(currentRequest), error, durationMs });
                     throw error;
                 }
             };
-            if (options.shortCircuit) {
-                const shorted = await options.shortCircuit(response, durationMs, currentRequest, runAfter);
-                if (shorted)
-                    return shorted.value;
-            }
-            if (!response.ok && !options.okStatuses?.includes(response.status)) {
-                const body = options.errorBody ? await options.errorBody(response) : await parseResponseBody(response.clone());
-                const httpError = toHttpError(response.status, body);
-                const authRefreshedRequest = refreshedAuth
-                    ? undefined
-                    : await this.refreshReplaySafeRequestAuth(request, response.status);
-                if (authRefreshedRequest) {
-                    request = authRefreshedRequest;
-                    refreshedAuth = true;
-                    continue;
+            try {
+                if (options.shortCircuit) {
+                    const shorted = await options.shortCircuit(response, durationMs, currentRequest, runAfter);
+                    if (shorted)
+                        return shorted.value;
                 }
-                if (shouldRetryRequest(this.retryOptions, request.method, attempt, response.status, httpError)) {
-                    await this.sleepBeforeRetry(attempt, response, retrySignal);
-                    continue;
+                if (!response.ok && !options.okStatuses?.includes(response.status)) {
+                    const body = options.errorBody
+                        ? await options.errorBody(response, options.deadlineThroughFinalize ? timeout.signal : undefined)
+                        : await parseResponseBody(response.clone());
+                    const httpError = toHttpError(response.status, body);
+                    if (!refreshedAuth &&
+                        (response.status === 401 || response.status === 403) &&
+                        this.authProvider &&
+                        DEFAULT_RETRY_METHODS.has(request.method)) {
+                        await options.beforeReplay?.(cloneRequestContext(request), response.status, "authentication");
+                    }
+                    const authRefreshedRequest = refreshedAuth
+                        ? undefined
+                        : await this.refreshReplaySafeRequestAuth(request, response.status);
+                    if (authRefreshedRequest) {
+                        request = authRefreshedRequest;
+                        refreshedAuth = true;
+                        continue;
+                    }
+                    if (shouldRetryRequest(this.retryOptions, request.method, attempt, response.status, httpError)) {
+                        await options.beforeReplay?.(cloneRequestContext(request), response.status, "retry");
+                        await this.sleepBeforeRetry(attempt, response, retrySignal);
+                        continue;
+                    }
+                    const fallback = options.onTerminalError?.(httpError);
+                    if (fallback !== undefined)
+                        return fallback;
+                    if (options.deadlineThroughFinalize) {
+                        return await awaitDeadlineOwned(Promise.reject(httpError));
+                    }
+                    await this.applyErrorInterceptors({ request: cloneRequestContext(request), error: httpError, durationMs });
+                    throw httpError;
                 }
-                const fallback = options.onTerminalError?.(httpError);
-                if (fallback !== undefined)
-                    return fallback;
-                await this.applyErrorInterceptors({ request: cloneRequestContext(request), error: httpError, durationMs });
-                throw httpError;
+                const finalized = options.finalize(response, durationMs, currentRequest, runAfter, timeout.signal);
+                return await (options.deadlineThroughFinalize ? awaitDeadlineOwned(finalized) : finalized);
+            }
+            catch (error) {
+                if (!options.deadlineThroughFinalize || !timeout.signal?.aborted)
+                    throw error;
+                const terminalError = timeout.didTimeout ? new HonuaTimeoutError(this.timeoutMs ?? 0) : new HonuaAbortError();
+                beginTerminalErrorNotification(terminalError, performance.now() - startTime);
+                throw terminalError;
+            }
+            finally {
+                if (options.deadlineThroughFinalize)
+                    timeout.dispose();
             }
-            return options.finalize(response, durationMs, currentRequest, runAfter);
         }
     }
     async applyBeforeInterceptors(request) {
@@ -1514,7 +1602,7 @@ export class HonuaClient {
         }
         return next;
     }
-    async applyAfterInterceptors(request, response, durationMs) {
+    async applyAfterInterceptors(request, response, durationMs, deadlineSignal) {
         for (const interceptor of this.interceptors) {
             // Only clone the response for interceptors that actually inspect it. This
             // keeps the no-after-interceptor hot path free of `Response.clone()` (so
@@ -1523,12 +1611,16 @@ export class HonuaClient {
             if (!interceptor.after) {
                 continue;
             }
+            if (deadlineSignal?.aborted)
+                throw new HonuaAbortError();
             const context = {
                 request: cloneRequestContext(request),
                 response: response.clone(),
                 durationMs,
             };
             await interceptor.after(context);
+            if (deadlineSignal?.aborted)
+                throw new HonuaAbortError();
         }
     }
     /** Whether any registered interceptor inspects responses (`after` hook). */
@@ -1545,6 +1637,21 @@ export class HonuaClient {
             }
         }
     }
+    /**
+     * Start every terminal error hook independently so one nonsettling hook
+     * cannot prevent later hooks from observing the same failure. Each hook is
+     * contained so a detached deadline notification can never reject unhandled.
+     */
+    async applyErrorInterceptorsConcurrently(context) {
+        await Promise.all(this.interceptors.map(async (interceptor) => {
+            try {
+                await interceptor.error?.(context);
+            }
+            catch {
+                // Preserve the terminal request failure; interceptor failures should not mask it.
+            }
+        }));
+    }
     async refreshReplaySafeRequestAuth(request, statusCode) {
         if ((statusCode !== 401 && statusCode !== 403) ||
             !this.authProvider ||
@@ -1604,13 +1711,17 @@ async function parseResponseBody(response, maxResponseBytes) {
         return { raw: text };
     }
 }
-async function readBoundedResponseBytes(response, maximum) {
+async function readBoundedResponseBytes(response, maximum, signal) {
+    if (signal?.aborted) {
+        void response.body?.cancel().catch(() => undefined);
+        throw new HonuaAbortError();
+    }
     const advertised = response.headers.get("content-length");
     if (advertised !== null) {
         const length = Number(advertised);
         if (Number.isFinite(length) && length > maximum) {
-            await response.body?.cancel().catch(() => undefined);
-            throw new HonuaNetworkError(`Metadata response exceeds the configured ${maximum}-byte limit.`, undefined);
+            void response.body?.cancel().catch(() => undefined);
+            throw new HonuaNetworkError(`Response body exceeds the configured ${maximum}-byte limit.`, undefined);
         }
     }
     if (!response.body)
@@ -1618,20 +1729,32 @@ async function readBoundedResponseBytes(response, maximum) {
     const reader = response.body.getReader();
     const chunks = [];
     let total = 0;
+    const abort = () => void reader.cancel().catch(() => undefined);
+    signal?.addEventListener("abort", abort, { once: true });
     try {
         for (;;) {
+            if (signal?.aborted)
+                throw new HonuaAbortError();
             const { done, value } = await reader.read();
+            if (signal?.aborted)
+                throw new HonuaAbortError();
             if (done)
                 break;
             total += value.byteLength;
             if (total > maximum) {
-                await reader.cancel().catch(() => undefined);
-                throw new HonuaNetworkError(`Metadata response exceeds the configured ${maximum}-byte limit.`, undefined);
+                void reader.cancel().catch(() => undefined);
+                throw new HonuaNetworkError(`Response body exceeds the configured ${maximum}-byte limit.`, undefined);
             }
             chunks.push(value);
         }
     }
+    catch (error) {
+        if (signal?.aborted)
+            throw new HonuaAbortError();
+        throw error;
+    }
     finally {
+        signal?.removeEventListener("abort", abort);
         reader.releaseLock();
     }
     const bytes = new Uint8Array(total);
@@ -1642,6 +1765,14 @@ async function readBoundedResponseBytes(response, maximum) {
     }
     return bytes;
 }
+function bufferedResponse(source, bytes) {
+    const body = source.status === 204 || source.status === 205 || source.status === 304 ? null : bytes.slice();
+    return new Response(body, {
+        status: source.status,
+        statusText: source.statusText,
+        headers: source.headers,
+    });
+}
 function isObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -1672,6 +1803,53 @@ function cloneRequestContext(request) {
         },
     };
 }
+function awaitAbortable(value, signal) {
+    const pending = Promise.resolve(value);
+    if (!signal)
+        return pending;
+    if (signal.aborted) {
+        void pending.catch(() => undefined);
+        return Promise.reject(new HonuaAbortError());
+    }
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (callback) => {
+            if (settled)
+                return;
+            settled = true;
+            signal.removeEventListener("abort", abort);
+            callback();
+        };
+        const abort = () => finish(() => reject(new HonuaAbortError()));
+        signal.addEventListener("abort", abort, { once: true });
+        pending.then((result) => finish(() => resolve(result)), (error) => finish(() => reject(error)));
+    });
+}
+/**
+ * A response prepared under a tighter body boundary still represents the same
+ * physical fetch. Preserve the fetch-owned semantic properties for public
+ * interceptors and for every defensive clone they receive.
+ */
+function preserveResponseSemantics(response, source) {
+    return decorateResponseSemantics(response, Object.freeze({
+        url: source.url,
+        type: source.type,
+        redirected: source.redirected,
+    }));
+}
+function decorateResponseSemantics(response, semantics) {
+    const nativeClone = response.clone.bind(response);
+    Object.defineProperties(response, {
+        url: { configurable: true, value: semantics.url },
+        type: { configurable: true, value: semantics.type },
+        redirected: { configurable: true, value: semantics.redirected },
+        clone: {
+            configurable: true,
+            value: () => decorateResponseSemantics(nativeClone(), semantics),
+        },
+    });
+    return response;
+}
 function cloneHeadersInit(headers) {
     return mergeHeaders(headers);
 }

package/core/error-classifications.d.ts

@@ -48,6 +48,7 @@ export declare const HONUA_ERROR_RUNTIME_CLASSIFICATIONS: Readonly<{
     readonly "query.planning.fallback-disabled": HonuaErrorRuntimeClassification;
     readonly "query.planning.unsafe-materialization": HonuaErrorRuntimeClassification;
     readonly "query.execution.invalid-plan": HonuaErrorRuntimeClassification;
+    readonly "query.execution.wfs-protocol": HonuaErrorRuntimeClassification;
     readonly "query.execution.plan-context-mismatch": HonuaErrorRuntimeClassification;
     readonly "query.execution.unsafe-materialization": HonuaErrorRuntimeClassification;
     readonly "query.execution.invalid-resource-handle": HonuaErrorRuntimeClassification;
@@ -102,9 +103,12 @@ export declare const HONUA_ERROR_RUNTIME_CLASSIFICATIONS: Readonly<{
     readonly "realtime.checkpoint.invalid": HonuaErrorRuntimeClassification;
     readonly "realtime.sequence.gap": HonuaErrorRuntimeClassification;
     readonly "realtime.protocol.terminal": HonuaErrorRuntimeClassification;
+    readonly "realtime.reconciliation.disposed": HonuaErrorRuntimeClassification;
+    readonly "realtime.reconciliation.invalid-option": HonuaErrorRuntimeClassification;
     readonly "offline.region.validation": HonuaErrorRuntimeClassification;
     readonly "offline.region.quota": HonuaErrorRuntimeClassification;
     readonly "offline.region.integrity": HonuaErrorRuntimeClassification;
+    readonly "offline.region.miss": HonuaErrorRuntimeClassification;
     readonly "offline.cancelled": HonuaErrorRuntimeClassification;
     readonly "offline.transport.failure": HonuaErrorRuntimeClassification;
     readonly "offline.transport.transient": HonuaErrorRuntimeClassification;
@@ -149,5 +153,7 @@ export declare const HONUA_ERROR_RUNTIME_CLASSIFICATIONS: Readonly<{
     readonly "app.data-load-failed": HonuaErrorRuntimeClassification;
     readonly "app.render-failed": HonuaErrorRuntimeClassification;
     readonly "app.disposed": HonuaErrorRuntimeClassification;
+    readonly "app.export-unsafe": HonuaErrorRuntimeClassification;
+    readonly "app.export-failed": HonuaErrorRuntimeClassification;
 }>;
 //# sourceMappingURL=error-classifications.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"error-classifications.d.ts","sourceRoot":"","sources":["../../../src/core/error-classifications.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAkB,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAErG;;;;;;;;GAQG;AACH,MAAM,MAAM,+BAA+B,GAAG,SAAS;IACrD,MAAM,EAAE,gBAAgB;IACxB,QAAQ,EAAE,kBAAkB;IAC5B,SAAS,EAAE,OAAO;CACnB,CAAC;AAEF,gBAAgB;AAChB,eAAO,MAAM,mCAAmC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAuI6B,CAAC"}
+{"version":3,"file":"error-classifications.d.ts","sourceRoot":"","sources":["../../../src/core/error-classifications.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAkB,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAErG;;;;;;;;GAQG;AACH,MAAM,MAAM,+BAA+B,GAAG,SAAS;IACrD,MAAM,EAAE,gBAAgB;IACxB,QAAQ,EAAE,kBAAkB;IAC5B,SAAS,EAAE,OAAO;CACnB,CAAC;AAEF,gBAAgB;AAChB,eAAO,MAAM,mCAAmC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6I6B,CAAC"}

package/core/error-classifications.js

@@ -33,6 +33,7 @@ export const HONUA_ERROR_RUNTIME_CLASSIFICATIONS = Object.freeze({
     "query.planning.fallback-disabled": runtimeClassification("query", "capability", false),
     "query.planning.unsafe-materialization": runtimeClassification("query", "validation", false),
     "query.execution.invalid-plan": runtimeClassification("query", "validation", false),
+    "query.execution.wfs-protocol": runtimeClassification("query", "protocol", false),
     "query.execution.plan-context-mismatch": runtimeClassification("query", "validation", false),
     "query.execution.unsafe-materialization": runtimeClassification("query", "validation", false),
     "query.execution.invalid-resource-handle": runtimeClassification("query", "validation", false),
@@ -87,9 +88,12 @@ export const HONUA_ERROR_RUNTIME_CLASSIFICATIONS = Object.freeze({
     "realtime.checkpoint.invalid": runtimeClassification("realtime", "validation", false),
     "realtime.sequence.gap": runtimeClassification("realtime", "protocol", true),
     "realtime.protocol.terminal": runtimeClassification("realtime", "protocol", false),
+    "realtime.reconciliation.disposed": runtimeClassification("realtime", "validation", false),
+    "realtime.reconciliation.invalid-option": runtimeClassification("realtime", "validation", false),
     "offline.region.validation": runtimeClassification("offline", "validation", false),
     "offline.region.quota": runtimeClassification("offline", "validation", false),
     "offline.region.integrity": runtimeClassification("offline", "protocol", false),
+    "offline.region.miss": runtimeClassification("offline", "validation", false),
     "offline.cancelled": runtimeClassification("offline", "cancellation", false),
     "offline.transport.failure": runtimeClassification("offline", "network", false),
     "offline.transport.transient": runtimeClassification("offline", "network", true),
@@ -134,6 +138,8 @@ export const HONUA_ERROR_RUNTIME_CLASSIFICATIONS = Object.freeze({
     "app.data-load-failed": runtimeClassification("app", "internal", false),
     "app.render-failed": runtimeClassification("app", "internal", false),
     "app.disposed": runtimeClassification("app", "validation", false),
+    "app.export-unsafe": runtimeClassification("app", "validation", false),
+    "app.export-failed": runtimeClassification("app", "internal", false),
 });
 function runtimeClassification(domain, category, retryable) {
     return Object.freeze([domain, category, retryable]);

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

@@ -52,6 +52,7 @@ export declare const HONUA_ERROR_CODE_REGISTRY: Readonly<{
     readonly "query.planning.fallback-disabled": HonuaErrorCodeDescriptor;
     readonly "query.planning.unsafe-materialization": HonuaErrorCodeDescriptor;
     readonly "query.execution.invalid-plan": HonuaErrorCodeDescriptor;
+    readonly "query.execution.wfs-protocol": HonuaErrorCodeDescriptor;
     readonly "query.execution.plan-context-mismatch": HonuaErrorCodeDescriptor;
     readonly "query.execution.unsafe-materialization": HonuaErrorCodeDescriptor;
     readonly "query.execution.invalid-resource-handle": HonuaErrorCodeDescriptor;
@@ -106,9 +107,12 @@ export declare const HONUA_ERROR_CODE_REGISTRY: Readonly<{
     readonly "realtime.checkpoint.invalid": HonuaErrorCodeDescriptor;
     readonly "realtime.sequence.gap": HonuaErrorCodeDescriptor;
     readonly "realtime.protocol.terminal": HonuaErrorCodeDescriptor;
+    readonly "realtime.reconciliation.disposed": HonuaErrorCodeDescriptor;
+    readonly "realtime.reconciliation.invalid-option": HonuaErrorCodeDescriptor;
     readonly "offline.region.validation": HonuaErrorCodeDescriptor;
     readonly "offline.region.quota": HonuaErrorCodeDescriptor;
     readonly "offline.region.integrity": HonuaErrorCodeDescriptor;
+    readonly "offline.region.miss": HonuaErrorCodeDescriptor;
     readonly "offline.cancelled": HonuaErrorCodeDescriptor;
     readonly "offline.transport.failure": HonuaErrorCodeDescriptor;
     readonly "offline.transport.transient": HonuaErrorCodeDescriptor;
@@ -153,6 +157,8 @@ export declare const HONUA_ERROR_CODE_REGISTRY: Readonly<{
     readonly "app.data-load-failed": HonuaErrorCodeDescriptor;
     readonly "app.render-failed": HonuaErrorCodeDescriptor;
     readonly "app.disposed": HonuaErrorCodeDescriptor;
+    readonly "app.export-unsafe": HonuaErrorCodeDescriptor;
+    readonly "app.export-failed": HonuaErrorCodeDescriptor;
 }>;
 export type HonuaErrorCode = keyof typeof HONUA_ERROR_CODE_REGISTRY;
 //# sourceMappingURL=error-code-registry.d.ts.map

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,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAsiBwB,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,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0kBwB,CAAC;AAE/D,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,yBAAyB,CAAC"}

package/core/error-code-registry.js

@@ -36,6 +36,7 @@ export const HONUA_ERROR_CODE_REGISTRY = Object.freeze({
     "query.planning.fallback-disabled": classification("query", "capability", false, "Required local fallback is disabled"),
     "query.planning.unsafe-materialization": classification("query", "validation", false, "Planned local materialization exceeds its safety bound"),
     "query.execution.invalid-plan": classification("query", "validation", false, "Query plan is invalid"),
+    "query.execution.wfs-protocol": classification("query", "protocol", false, "WFS protocol evidence or response is invalid"),
     "query.execution.plan-context-mismatch": classification("query", "validation", false, "Execution context does not match the accepted query plan"),
     "query.execution.unsafe-materialization": classification("query", "validation", false, "Query execution exceeded its materialization bound"),
     "query.execution.invalid-resource-handle": classification("query", "validation", false, "Query resource handle is invalid"),
@@ -90,9 +91,12 @@ export const HONUA_ERROR_CODE_REGISTRY = Object.freeze({
     "realtime.checkpoint.invalid": classification("realtime", "validation", false, "Realtime checkpoint or resume context is invalid"),
     "realtime.sequence.gap": classification("realtime", "protocol", true, "Realtime ordering requires a replacement snapshot"),
     "realtime.protocol.terminal": classification("realtime", "protocol", false, "Realtime delivery reached a terminal failure"),
+    "realtime.reconciliation.disposed": classification("realtime", "validation", false, "Realtime reconciliation controller, cache, or adapter is disposed"),
+    "realtime.reconciliation.invalid-option": classification("realtime", "validation", false, "Realtime reconciliation option is invalid"),
     "offline.region.validation": classification("offline", "validation", false, "Offline region input or lifecycle state is invalid"),
     "offline.region.quota": classification("offline", "validation", false, "Offline region exceeds a logical storage quota"),
     "offline.region.integrity": classification("offline", "protocol", false, "Offline resource integrity verification failed"),
+    "offline.region.miss": classification("offline", "validation", false, "Offline region does not cover the requested read"),
     "offline.cancelled": classification("offline", "cancellation", false, "Offline operation was cancelled"),
     "offline.transport.failure": classification("offline", "network", false, "Offline resource or replica transport failed without a transient classification"),
     "offline.transport.transient": classification("offline", "network", true, "Offline resource or replica transport failed transiently"),
@@ -137,6 +141,8 @@ export const HONUA_ERROR_CODE_REGISTRY = Object.freeze({
     "app.data-load-failed": classification("app", "internal", false, "Generated app feature data failed to load"),
     "app.render-failed": classification("app", "internal", false, "Generated app render failed"),
     "app.disposed": classification("app", "validation", false, "Generated app runtime is disposed"),
+    "app.export-unsafe": classification("app", "validation", false, "Component export refused because the artifact could not be proven credential-free"),
+    "app.export-failed": classification("app", "internal", false, "Component export adapter failed to produce an artifact"),
 });
 function classification(domain, category, retryable, summary) {
     return Object.freeze({ domain, category, retryable, summary });

package/core/error-envelope.js

@@ -326,6 +326,7 @@ const SAFE_ERROR_NAMES = new Set([
     "HonuaMapPackageError",
     "HonuaNetworkError",
     "HonuaOfflineRegionError",
+    "HonuaOfflineEditQueueError",
     "HonuaPluginRegistryError",
     "HonuaQueryPlanExecutionError",
     "HonuaQueryPlanningError",
@@ -336,6 +337,7 @@ const SAFE_ERROR_NAMES = new Set([
     "HonuaTemporalPlaybackError",
     "HonuaTimeoutError",
     "HonuaWfsExceptionError",
+    "HonuaWfsProtocolError",
     "HonuaWmsCapabilitiesParseError",
     "HonuaWmtsCapabilitiesParseError",
     "NetworkError",

package/core/errors.d.ts

@@ -15,7 +15,7 @@
  * } from "@honua/sdk-js";
  *
  * try {
- *   await dataset.source("parcels")!.queryAll({ where: "1=1" });
+ *   await dataset.source("parcels")!.queryAll({ pagination: { limit: 100 } });
  * } catch (error) {
  *   if (!isHonuaError(error)) throw error;
  *   if (error instanceof HonuaCapabilityNotSupportedError) return fallback();

package/core/errors.js

@@ -15,7 +15,7 @@
  * } from "@honua/sdk-js";
  *
  * try {
- *   await dataset.source("parcels")!.queryAll({ where: "1=1" });
+ *   await dataset.source("parcels")!.queryAll({ pagination: { limit: 100 } });
  * } catch (error) {
  *   if (!isHonuaError(error)) throw error;
  *   if (error instanceof HonuaCapabilityNotSupportedError) return fallback();