@honua/react 0.0.20-alpha.0 → 0.1.1-beta.0

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

@@ -0,0 +1,158 @@
+/**
+ * Canonical descriptive registry for public Honua SDK error codes.
+ *
+ * The error base consumes a compact classification table so focused SDK
+ * entrypoints do not retain these human-readable summaries. The registry
+ * remains the public documentation source of truth; `check:error-codes`
+ * verifies the compact table against every descriptor.
+ */
+export type HonuaErrorDomain = "core" | "discovery" | "query" | "map" | "runtime" | "realtime" | "offline" | "plugin" | "agent" | "app";
+export type HonuaErrorCategory = "authentication" | "cancellation" | "capability" | "internal" | "network" | "protocol" | "timeout" | "validation";
+export interface HonuaErrorCodeDescriptor {
+    readonly domain: HonuaErrorDomain;
+    readonly category: HonuaErrorCategory;
+    readonly retryable: boolean;
+    readonly summary: string;
+}
+/**
+ * Canonical public code registry. Object keys make duplicate codes a compile
+ * error; the base constructor rejects codes absent from this registry.
+ */
+export declare const HONUA_ERROR_CODE_REGISTRY: Readonly<{
+    readonly "core.http.transient": HonuaErrorCodeDescriptor;
+    readonly "core.http.rejected": HonuaErrorCodeDescriptor;
+    readonly "core.timeout": HonuaErrorCodeDescriptor;
+    readonly "core.network": HonuaErrorCodeDescriptor;
+    readonly "core.cancelled": HonuaErrorCodeDescriptor;
+    readonly "core.grpc.transient": HonuaErrorCodeDescriptor;
+    readonly "core.grpc.rejected": HonuaErrorCodeDescriptor;
+    readonly "core.geometry.unknown-geometry": HonuaErrorCodeDescriptor;
+    readonly "core.geometry.malformed-geometry": HonuaErrorCodeDescriptor;
+    readonly "core.auth.interaction-required": HonuaErrorCodeDescriptor;
+    readonly "core.auth.refresh-failed": HonuaErrorCodeDescriptor;
+    readonly "core.auth.invalid-grant": HonuaErrorCodeDescriptor;
+    readonly "core.capability-not-supported": HonuaErrorCodeDescriptor;
+    readonly "core.exploration-context": HonuaErrorCodeDescriptor;
+    readonly "core.wfs-exception": HonuaErrorCodeDescriptor;
+    readonly "core.job-failed": HonuaErrorCodeDescriptor;
+    readonly "core.wms-capabilities-parse": HonuaErrorCodeDescriptor;
+    readonly "core.wmts-capabilities-parse": HonuaErrorCodeDescriptor;
+    readonly "discovery.ambiguous-protocol": HonuaErrorCodeDescriptor;
+    readonly "discovery.ambiguous-source": HonuaErrorCodeDescriptor;
+    readonly "discovery.invalid-endpoint": HonuaErrorCodeDescriptor;
+    readonly "discovery.invalid-cache-identity": HonuaErrorCodeDescriptor;
+    readonly "discovery.invalid-discovery-cache": HonuaErrorCodeDescriptor;
+    readonly "discovery.invalid-capability": HonuaErrorCodeDescriptor;
+    readonly "discovery.unsupported-protocol": HonuaErrorCodeDescriptor;
+    readonly "discovery.protocol-mismatch": HonuaErrorCodeDescriptor;
+    readonly "query.planning.invalid-query": HonuaErrorCodeDescriptor;
+    readonly "query.planning.unsupported-compiler": HonuaErrorCodeDescriptor;
+    readonly "query.planning.unsupported-query": HonuaErrorCodeDescriptor;
+    readonly "query.planning.capability-not-supported": HonuaErrorCodeDescriptor;
+    readonly "query.planning.fallback-disabled": HonuaErrorCodeDescriptor;
+    readonly "query.planning.unsafe-materialization": HonuaErrorCodeDescriptor;
+    readonly "query.execution.invalid-plan": HonuaErrorCodeDescriptor;
+    readonly "query.execution.plan-context-mismatch": HonuaErrorCodeDescriptor;
+    readonly "query.execution.unsafe-materialization": HonuaErrorCodeDescriptor;
+    readonly "query.execution.invalid-resource-handle": HonuaErrorCodeDescriptor;
+    readonly "query.execution.resource-unavailable": HonuaErrorCodeDescriptor;
+    readonly "query.execution.resource-expired": HonuaErrorCodeDescriptor;
+    readonly "query.execution.resource-resolution-failed": HonuaErrorCodeDescriptor;
+    readonly "query.execution.resource-execution-failed": HonuaErrorCodeDescriptor;
+    readonly "map.source-adapter.disposed": HonuaErrorCodeDescriptor;
+    readonly "map.source-adapter.source-conflict": HonuaErrorCodeDescriptor;
+    readonly "map.source-adapter.layer-conflict": HonuaErrorCodeDescriptor;
+    readonly "map.source-adapter.unsupported-plan": HonuaErrorCodeDescriptor;
+    readonly "map.source-adapter.invalid-option": HonuaErrorCodeDescriptor;
+    readonly "map.source-adapter.map-mutation-failed": HonuaErrorCodeDescriptor;
+    readonly "map.data-bridge.invalid-option": HonuaErrorCodeDescriptor;
+    readonly "map.data-bridge.disposed": HonuaErrorCodeDescriptor;
+    readonly "map.data-bridge.source-conflict": HonuaErrorCodeDescriptor;
+    readonly "map.data-bridge.layer-conflict": HonuaErrorCodeDescriptor;
+    readonly "map.data-bridge.map-mutation-failed": HonuaErrorCodeDescriptor;
+    readonly "map.data-bridge.interaction-unsupported": HonuaErrorCodeDescriptor;
+    readonly "map.data-bridge.filter-unsupported": HonuaErrorCodeDescriptor;
+    readonly "map.automatic-strategy.no-eligible-strategy": HonuaErrorCodeDescriptor;
+    readonly "map.automatic-strategy.stale-plan": HonuaErrorCodeDescriptor;
+    readonly "map.automatic-strategy.source-conflict": HonuaErrorCodeDescriptor;
+    readonly "map.automatic-strategy.layer-conflict": HonuaErrorCodeDescriptor;
+    readonly "map.automatic-strategy.map-mutation-failed": HonuaErrorCodeDescriptor;
+    readonly "map.automatic-strategy.cancelled": HonuaErrorCodeDescriptor;
+    readonly "map.automatic-strategy.disposed": HonuaErrorCodeDescriptor;
+    readonly "map.raster-strategy.unsupported-strategy": HonuaErrorCodeDescriptor;
+    readonly "map.raster-strategy.capability-mismatch": HonuaErrorCodeDescriptor;
+    readonly "map.raster-strategy.missing-metadata": HonuaErrorCodeDescriptor;
+    readonly "map.raster-strategy.invalid-option": HonuaErrorCodeDescriptor;
+    readonly "map.raster-strategy.source-conflict": HonuaErrorCodeDescriptor;
+    readonly "map.raster-strategy.layer-conflict": HonuaErrorCodeDescriptor;
+    readonly "map.raster-strategy.map-mutation-failed": HonuaErrorCodeDescriptor;
+    readonly "map.automatic-integration.disposed": HonuaErrorCodeDescriptor;
+    readonly "map.automatic-integration.invalid-target": HonuaErrorCodeDescriptor;
+    readonly "map.temporal-playback.invalid-option": HonuaErrorCodeDescriptor;
+    readonly "runtime.map-package.fetch": HonuaErrorCodeDescriptor;
+    readonly "runtime.map-package.load": HonuaErrorCodeDescriptor;
+    readonly "runtime.map-package.validate": HonuaErrorCodeDescriptor;
+    readonly "runtime.map-package.update": HonuaErrorCodeDescriptor;
+    readonly "runtime.map-package.style-compose": HonuaErrorCodeDescriptor;
+    readonly "runtime.map-package.source-bind": HonuaErrorCodeDescriptor;
+    readonly "runtime.map-package.view": HonuaErrorCodeDescriptor;
+    readonly "runtime.map-package.popup": HonuaErrorCodeDescriptor;
+    readonly "runtime.map-package.dispose": HonuaErrorCodeDescriptor;
+    readonly "runtime.diagnostic": HonuaErrorCodeDescriptor;
+    readonly "runtime.query-tiles.transient": HonuaErrorCodeDescriptor;
+    readonly "runtime.query-tiles.rejected": HonuaErrorCodeDescriptor;
+    readonly "realtime.cancelled": HonuaErrorCodeDescriptor;
+    readonly "realtime.transport.reconnectable": HonuaErrorCodeDescriptor;
+    readonly "realtime.checkpoint.invalid": HonuaErrorCodeDescriptor;
+    readonly "realtime.sequence.gap": HonuaErrorCodeDescriptor;
+    readonly "realtime.protocol.terminal": HonuaErrorCodeDescriptor;
+    readonly "offline.region.validation": HonuaErrorCodeDescriptor;
+    readonly "offline.region.quota": HonuaErrorCodeDescriptor;
+    readonly "offline.region.integrity": HonuaErrorCodeDescriptor;
+    readonly "offline.cancelled": HonuaErrorCodeDescriptor;
+    readonly "offline.transport.failure": HonuaErrorCodeDescriptor;
+    readonly "offline.transport.transient": HonuaErrorCodeDescriptor;
+    readonly "offline.storage.concurrent": HonuaErrorCodeDescriptor;
+    readonly "offline.storage.failure": HonuaErrorCodeDescriptor;
+    readonly "offline.replica-sync.capability": HonuaErrorCodeDescriptor;
+    readonly "offline.replica-sync.validation": HonuaErrorCodeDescriptor;
+    readonly "offline.replica-sync.permission-denied": HonuaErrorCodeDescriptor;
+    readonly "plugin.registry.validation": HonuaErrorCodeDescriptor;
+    readonly "plugin.compatibility": HonuaErrorCodeDescriptor;
+    readonly "plugin.execution.policy-denied": HonuaErrorCodeDescriptor;
+    readonly "plugin.capability-unavailable": HonuaErrorCodeDescriptor;
+    readonly "plugin.lifecycle.activation": HonuaErrorCodeDescriptor;
+    readonly "plugin.execution.validation": HonuaErrorCodeDescriptor;
+    readonly "plugin.lifecycle.cleanup": HonuaErrorCodeDescriptor;
+    readonly "plugin.cancelled": HonuaErrorCodeDescriptor;
+    readonly "plugin.internal": HonuaErrorCodeDescriptor;
+    readonly "agent.tool.unknown-tool": HonuaErrorCodeDescriptor;
+    readonly "agent.tool.missing-runtime": HonuaErrorCodeDescriptor;
+    readonly "agent.tool.unqualified-selection": HonuaErrorCodeDescriptor;
+    readonly "agent.tool.missing-runtime-method": HonuaErrorCodeDescriptor;
+    readonly "agent.tool.internal": HonuaErrorCodeDescriptor;
+    readonly "agent.safety.aborted": HonuaErrorCodeDescriptor;
+    readonly "agent.safety.invalid-input": HonuaErrorCodeDescriptor;
+    readonly "agent.safety.policy-denied": HonuaErrorCodeDescriptor;
+    readonly "agent.safety.integrity-failed": HonuaErrorCodeDescriptor;
+    readonly "agent.safety.approval-expired": HonuaErrorCodeDescriptor;
+    readonly "agent.safety.context-mismatch": HonuaErrorCodeDescriptor;
+    readonly "agent.safety.signature-invalid": HonuaErrorCodeDescriptor;
+    readonly "agent.safety.execution-failed": HonuaErrorCodeDescriptor;
+    readonly "agent.safety.audit-failed": HonuaErrorCodeDescriptor;
+    readonly "agent.safety.receipt-failed": HonuaErrorCodeDescriptor;
+    readonly "app.unsupported-profile": HonuaErrorCodeDescriptor;
+    readonly "app.unsupported-widget": HonuaErrorCodeDescriptor;
+    readonly "app.missing-manifest": HonuaErrorCodeDescriptor;
+    readonly "app.missing-manifest-artifact": HonuaErrorCodeDescriptor;
+    readonly "app.missing-map-package": HonuaErrorCodeDescriptor;
+    readonly "app.map-package-mismatch": HonuaErrorCodeDescriptor;
+    readonly "app.missing-widget": HonuaErrorCodeDescriptor;
+    readonly "app.missing-binding": HonuaErrorCodeDescriptor;
+    readonly "app.map-load-failed": HonuaErrorCodeDescriptor;
+    readonly "app.data-load-failed": HonuaErrorCodeDescriptor;
+    readonly "app.render-failed": HonuaErrorCodeDescriptor;
+    readonly "app.disposed": 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

@@ -0,0 +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"}

package/core/error-code-registry.js

@@ -0,0 +1,143 @@
+/**
+ * Canonical public code registry. Object keys make duplicate codes a compile
+ * error; the base constructor rejects codes absent from this registry.
+ */
+export const HONUA_ERROR_CODE_REGISTRY = Object.freeze({
+    "core.http.transient": classification("core", "protocol", true, "Retryable HTTP response failure"),
+    "core.http.rejected": classification("core", "protocol", false, "Non-retryable HTTP response failure"),
+    "core.timeout": classification("core", "timeout", true, "Request deadline elapsed"),
+    "core.network": classification("core", "network", true, "Network transport failure"),
+    "core.cancelled": classification("core", "cancellation", false, "Caller cancelled the operation"),
+    "core.grpc.transient": classification("core", "protocol", true, "Retryable gRPC-Web transport failure"),
+    "core.grpc.rejected": classification("core", "protocol", false, "Non-retryable gRPC-Web transport failure"),
+    "core.geometry.unknown-geometry": classification("core", "validation", false, "Geometry shape cannot be classified safely"),
+    "core.geometry.malformed-geometry": classification("core", "validation", false, "Recognized geometry has invalid coordinates or structure"),
+    "core.auth.interaction-required": classification("core", "authentication", false, "Interactive authentication is required"),
+    "core.auth.refresh-failed": classification("core", "authentication", true, "Credential refresh failed transiently"),
+    "core.auth.invalid-grant": classification("core", "authentication", false, "Authorization grant is invalid or expired"),
+    "core.capability-not-supported": classification("core", "capability", false, "Requested source capability is unavailable"),
+    "core.exploration-context": classification("core", "validation", false, "Exploration context operation is invalid"),
+    "core.wfs-exception": classification("core", "protocol", false, "WFS exception report"),
+    "core.job-failed": classification("core", "protocol", false, "Remote job reached a failed terminal state"),
+    "core.wms-capabilities-parse": classification("core", "protocol", false, "WMS capabilities document is invalid"),
+    "core.wmts-capabilities-parse": classification("core", "protocol", false, "WMTS capabilities document is invalid"),
+    "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-endpoint": classification("discovery", "validation", false, "Discovery endpoint is invalid"),
+    "discovery.invalid-cache-identity": classification("discovery", "validation", false, "Discovery cache identity is invalid"),
+    "discovery.invalid-discovery-cache": classification("discovery", "validation", false, "Discovery cache entry is invalid"),
+    "discovery.invalid-capability": classification("discovery", "validation", false, "Discovered capability evidence is invalid"),
+    "discovery.unsupported-protocol": classification("discovery", "capability", false, "Endpoint protocol is unsupported"),
+    "discovery.protocol-mismatch": classification("discovery", "validation", false, "Endpoint protocol conflicts with its hint"),
+    "query.planning.invalid-query": classification("query", "validation", false, "Query is invalid"),
+    "query.planning.unsupported-compiler": classification("query", "capability", false, "No compiler supports the source protocol"),
+    "query.planning.unsupported-query": classification("query", "capability", false, "Query cannot be represented by the compiler"),
+    "query.planning.capability-not-supported": classification("query", "capability", false, "Query requires an unavailable capability"),
+    "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.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"),
+    "query.execution.resource-unavailable": classification("query", "authentication", false, "Query resource is unavailable in the authorization context"),
+    "query.execution.resource-expired": classification("query", "authentication", false, "Query resource authorization has expired"),
+    "query.execution.resource-resolution-failed": classification("query", "internal", false, "Query resource resolution failed"),
+    "query.execution.resource-execution-failed": classification("query", "internal", false, "Resolved query resource execution failed"),
+    "map.source-adapter.disposed": classification("map", "validation", false, "Map source adapter is disposed"),
+    "map.source-adapter.source-conflict": classification("map", "validation", false, "Map source identifier already exists"),
+    "map.source-adapter.layer-conflict": classification("map", "validation", false, "Map layer identifier already exists"),
+    "map.source-adapter.unsupported-plan": classification("map", "capability", false, "Query plan cannot be rendered by the source adapter"),
+    "map.source-adapter.invalid-option": classification("map", "validation", false, "Map source adapter option is invalid"),
+    "map.source-adapter.map-mutation-failed": classification("map", "internal", false, "Renderer mutation failed"),
+    "map.data-bridge.invalid-option": classification("map", "validation", false, "Data-to-map option is invalid"),
+    "map.data-bridge.disposed": classification("map", "validation", false, "Data-to-map bridge is disposed"),
+    "map.data-bridge.source-conflict": classification("map", "validation", false, "Data-to-map source identifier already exists"),
+    "map.data-bridge.layer-conflict": classification("map", "validation", false, "Data-to-map layer identifier already exists"),
+    "map.data-bridge.map-mutation-failed": classification("map", "internal", false, "Data-to-map renderer mutation failed"),
+    "map.data-bridge.interaction-unsupported": classification("map", "capability", false, "Renderer interaction is unsupported"),
+    "map.data-bridge.filter-unsupported": classification("map", "capability", false, "Renderer filter mutation is unsupported"),
+    "map.automatic-strategy.no-eligible-strategy": classification("map", "capability", false, "No exact map source strategy is eligible"),
+    "map.automatic-strategy.stale-plan": classification("map", "validation", false, "Map strategy plan is stale"),
+    "map.automatic-strategy.source-conflict": classification("map", "validation", false, "Automatic strategy source identifier already exists"),
+    "map.automatic-strategy.layer-conflict": classification("map", "validation", false, "Automatic strategy layer identifier already exists"),
+    "map.automatic-strategy.map-mutation-failed": classification("map", "internal", false, "Automatic strategy renderer mutation failed"),
+    "map.automatic-strategy.cancelled": classification("map", "cancellation", false, "Automatic map strategy was cancelled"),
+    "map.automatic-strategy.disposed": classification("map", "validation", false, "Automatic map strategy is disposed"),
+    "map.raster-strategy.unsupported-strategy": classification("map", "capability", false, "Raster strategy is unsupported"),
+    "map.raster-strategy.capability-mismatch": classification("map", "capability", false, "Raster source lacks a required capability"),
+    "map.raster-strategy.missing-metadata": classification("map", "validation", false, "Raster source metadata is incomplete"),
+    "map.raster-strategy.invalid-option": classification("map", "validation", false, "Raster option is invalid"),
+    "map.raster-strategy.source-conflict": classification("map", "validation", false, "Raster source identifier already exists"),
+    "map.raster-strategy.layer-conflict": classification("map", "validation", false, "Raster layer identifier already exists"),
+    "map.raster-strategy.map-mutation-failed": classification("map", "internal", false, "Raster renderer mutation failed"),
+    "map.automatic-integration.disposed": classification("map", "validation", false, "Automatic map integration is disposed"),
+    "map.automatic-integration.invalid-target": classification("map", "validation", false, "Automatic map integration target is invalid"),
+    "map.temporal-playback.invalid-option": classification("map", "validation", false, "Temporal playback option is invalid"),
+    "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.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"),
+    "runtime.map-package.view": classification("runtime", "internal", false, "Renderer view mutation failed"),
+    "runtime.map-package.popup": classification("runtime", "validation", false, "Popup binding failed"),
+    "runtime.map-package.dispose": classification("runtime", "internal", true, "Runtime disposal failed"),
+    "runtime.diagnostic": classification("runtime", "validation", false, "Runtime validation diagnostic"),
+    "runtime.query-tiles.transient": classification("runtime", "protocol", true, "Retryable query-tile response failure"),
+    "runtime.query-tiles.rejected": classification("runtime", "protocol", false, "Non-retryable query-tile response failure"),
+    "realtime.cancelled": classification("realtime", "cancellation", false, "Realtime operation was cancelled"),
+    "realtime.transport.reconnectable": classification("realtime", "network", true, "Realtime transport can reconnect or resnapshot"),
+    "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"),
+    "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.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"),
+    "offline.storage.concurrent": classification("offline", "internal", true, "Offline storage inventory changed before commit"),
+    "offline.storage.failure": classification("offline", "internal", false, "Offline storage operation failed"),
+    "offline.replica-sync.capability": classification("offline", "capability", false, "Replica synchronization capability is unavailable"),
+    "offline.replica-sync.validation": classification("offline", "validation", false, "Replica synchronization request or state is invalid"),
+    "offline.replica-sync.permission-denied": classification("offline", "authentication", false, "Replica synchronization permission was denied"),
+    "plugin.registry.validation": classification("plugin", "validation", false, "Plugin registry input or lifecycle state is invalid"),
+    "plugin.compatibility": classification("plugin", "capability", false, "Plugin declaration is incompatible with the host or its dependencies"),
+    "plugin.execution.policy-denied": classification("plugin", "capability", false, "Plugin execution was denied by host policy"),
+    "plugin.capability-unavailable": classification("plugin", "capability", false, "Plugin execution requires an unavailable capability or dependency"),
+    "plugin.lifecycle.activation": classification("plugin", "internal", false, "Plugin activation or registration failed"),
+    "plugin.execution.validation": classification("plugin", "validation", false, "Plugin execution input is invalid"),
+    "plugin.lifecycle.cleanup": classification("plugin", "internal", false, "Plugin lifecycle cleanup failed"),
+    "plugin.cancelled": classification("plugin", "cancellation", false, "Plugin registration was cancelled"),
+    "plugin.internal": classification("plugin", "internal", false, "Plugin registry internal failure"),
+    "agent.tool.unknown-tool": classification("agent", "validation", false, "Requested agent tool name is not registered"),
+    "agent.tool.missing-runtime": classification("agent", "validation", false, "Agent tool kit requires a runtime, controller, or generated-app runtime"),
+    "agent.tool.unqualified-selection": classification("agent", "validation", false, "Agent tool selection target is not source-qualified"),
+    "agent.tool.missing-runtime-method": classification("agent", "capability", false, "Adapted runtime does not implement the requested agent tool"),
+    "agent.tool.internal": classification("agent", "internal", false, "Agent tool executor internal failure"),
+    "agent.safety.aborted": classification("agent", "cancellation", false, "Agent safety operation was aborted"),
+    "agent.safety.invalid-input": classification("agent", "validation", false, "Agent safety input is invalid"),
+    "agent.safety.policy-denied": classification("agent", "capability", false, "Agent plan step was denied by host policy"),
+    "agent.safety.integrity-failed": classification("agent", "protocol", false, "Agent safety evidence integrity verification failed"),
+    "agent.safety.approval-expired": classification("agent", "authentication", false, "Agent step approval has expired"),
+    "agent.safety.context-mismatch": classification("agent", "validation", false, "Agent execution context does not match the authorized plan"),
+    "agent.safety.signature-invalid": classification("agent", "validation", false, "Agent approval or receipt signature is invalid"),
+    "agent.safety.execution-failed": classification("agent", "internal", false, "Agent plan step execution failed"),
+    "agent.safety.audit-failed": classification("agent", "internal", false, "Agent execution audit record could not be appended"),
+    "agent.safety.receipt-failed": classification("agent", "internal", false, "Agent execution receipt could not be issued or verified"),
+    "app.unsupported-profile": classification("app", "capability", false, "Generated app profile is not supported"),
+    "app.unsupported-widget": classification("app", "capability", false, "Generated app widget kind is not supported"),
+    "app.missing-manifest": classification("app", "validation", false, "Generated app manifest or app package is missing"),
+    "app.missing-manifest-artifact": classification("app", "validation", false, "Generated app manifest artifact is missing"),
+    "app.missing-map-package": classification("app", "validation", false, "Generated app map widget requires a MapPackage"),
+    "app.map-package-mismatch": classification("app", "validation", false, "Generated app MapPackage does not match its manifest"),
+    "app.missing-widget": classification("app", "validation", false, "Generated app manifest is missing a required widget"),
+    "app.missing-binding": classification("app", "validation", false, "Generated app runtime is missing a required binding"),
+    "app.map-load-failed": classification("app", "internal", false, "Generated app map widget failed to load"),
+    "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"),
+});
+function classification(domain, category, retryable, summary) {
+    return Object.freeze({ domain, category, retryable, summary });
+}

package/core/error-envelope.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Shared, serialization-safe error contract for public Honua SDK failures.
+ *
+ * Error instances retain their original `message`, `cause`, and legacy detail
+ * fields for local debugging. Use {@link serializeHonuaError} at telemetry or
+ * process boundaries: it emits only registered classifications and sanitized
+ * context, never messages, stacks, response bodies, or cause payloads.
+ */
+import type { HonuaErrorCategory, HonuaErrorCode, HonuaErrorDomain } from "./error-code-registry.js";
+export type { HonuaErrorCategory, HonuaErrorCode, HonuaErrorCodeDescriptor, HonuaErrorDomain, } from "./error-code-registry.js";
+export declare const HONUA_ERROR_KIND: "honua.sdk.error.v1";
+export type HonuaErrorEnvelopeContextValue = null | boolean | number | string | readonly HonuaErrorEnvelopeContextValue[] | {
+    readonly [key: string]: HonuaErrorEnvelopeContextValue;
+};
+export type HonuaErrorEnvelopeContext = Readonly<Record<string, HonuaErrorEnvelopeContextValue>>;
+export interface HonuaErrorMetadata {
+    readonly operationId?: string;
+    readonly requestId?: string;
+    readonly context?: Readonly<Record<string, unknown>>;
+}
+export interface HonuaErrorOptions extends ErrorOptions, HonuaErrorMetadata {
+}
+export interface SerializedHonuaError {
+    readonly kind: typeof HONUA_ERROR_KIND;
+    readonly name: string;
+    readonly domain: HonuaErrorDomain;
+    readonly code: HonuaErrorCode;
+    readonly category: HonuaErrorCategory;
+    readonly retryable: boolean;
+    readonly operationId?: string;
+    readonly requestId?: string;
+    readonly context: HonuaErrorEnvelopeContext;
+    readonly cause?: SerializedHonuaErrorCause;
+}
+export interface SerializedHonuaErrorCause {
+    readonly name: string;
+    readonly domain?: HonuaErrorDomain;
+    readonly code?: HonuaErrorCode;
+    readonly category?: HonuaErrorCategory;
+    readonly retryable?: boolean;
+}
+/** Base class for every migrated public SDK error. */
+export declare abstract class HonuaSdkError extends Error {
+    readonly kind: "honua.sdk.error.v1";
+    readonly domain: HonuaErrorDomain;
+    /** Globally unique registry code. Legacy subclasses may retain a separate `.code`. */
+    readonly sdkCode: HonuaErrorCode;
+    readonly category: HonuaErrorCategory;
+    readonly retryable: boolean;
+    readonly operationId: string | undefined;
+    readonly requestId: string | 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. */
+    toJSON(): SerializedHonuaError;
+}
+/** Cross-realm type guard backed by the public tag and registered code. */
+export declare function isHonuaSdkError(error: unknown): error is HonuaSdkError;
+/** Serialize a tagged SDK error without crossing its redaction boundary. */
+export declare function serializeHonuaError(error: HonuaSdkError): SerializedHonuaError;
+/** Redact structured context before it is stored on an SDK error. */
+export declare function sanitizeHonuaErrorContext(context?: Readonly<Record<string, unknown>>): HonuaErrorEnvelopeContext;
+/** Merge context inputs without invoking enumerable accessors or honoring prototype-manipulation keys. */
+export declare function mergeHonuaErrorContext(...contexts: readonly (Readonly<Record<string, unknown>> | undefined)[]): Readonly<Record<string, unknown>>;
+export declare function isHonuaErrorCode(code: string): code is HonuaErrorCode;
+/** @internal True only for a valid tagged retryable network or timeout classification. */
+export declare function isRetryableNetworkOrTimeoutHonuaError(error: unknown): boolean;
+//# sourceMappingURL=error-envelope.d.ts.map

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

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