@lunora/client 1.0.0-alpha.15 → 1.0.0-alpha.17

package/dist/auth/index.d.mts

@@ -1,4 +1,4 @@
-import { U as User, L as LunoraClient } from "../packem_shared/lunora-client.d-CtSRWJJ7.mjs";
+import { U as User, L as LunoraClient } from "../packem_shared/lunora-client.d-DPLSlPiP.mjs";
 import '@lunora/runtime';
 interface IdentityStore {
   /** Read the current resolved user, or `null` when signed out / not yet resolved. */

package/dist/auth/index.d.ts

@@ -1,4 +1,4 @@
-import { U as User, L as LunoraClient } from "../packem_shared/lunora-client.d-CtSRWJJ7.js";
+import { U as User, L as LunoraClient } from "../packem_shared/lunora-client.d-DPLSlPiP.js";
 import '@lunora/runtime';
 interface IdentityStore {
   /** Read the current resolved user, or `null` when signed out / not yet resolved. */

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { c as PersistenceAdapter, B as BookmarkStorage, F as FunctionReference, A as ArgsOf, M as MutationCallOptions, R as ReturnOf, O as OfflineQueueOptions, Q as QueryCacheAdapter, d as ReconnectOptions } from "./packem_shared/lunora-client.d-CtSRWJJ7.mjs";
-export { type e as BatchSlot, type C as CachedQuery, type f as ClientMessage, type g as ClientShapeSubscribeMessage, type h as ClientShapeUnsubscribeMessage, type i as ConnectionStatus, D as DEFAULT_MAX_BUFFER, type j as FunctionArgumentDescriptor, type k as FunctionDescriptor, type G as GlobalFacetResult, type l as GlobalFacetValue, type m as GlobalFilterClause, type n as GlobalTableInfo, type o as GlobalTablePage, L as LunoraClient, type p as LunoraClientError, type q as LunoraClientOptions, type r as MutationSettledEvent, type s as OptimisticLocalStore, type t as OptimisticUpdate, type u as OutboxMutation, type v as OutboxSink, type w as PersistedMutation, type P as Preloaded, type x as RowOp, type y as RpcEnvelope, type z as RpcResponseBody, type E as ScheduleRecord, type H as SchedulerPoolStatus, type I as SchedulerStatus, type J as ServerMessage, type K as ServerPokeEndMessage, type N as ServerPokePartMessage, type T as ServerPokeStartMessage, type V as ShardTrafficEntry, type W as ShardTrafficResult, type X as StorageListPage, type Y as StorageObject, type Z as StreamHandle, type _ as StreamIterable, type $ as SubscriptionCallback, type S as SubscriptionError, type b as SubscriptionErrorCallback, a0 as SubscriptionRegistry, type a1 as SubscriptionState, type a2 as SyncWatermark, type a as Unsubscribe, type U as User, type a3 as WorkflowInstanceAction, type a4 as WorkflowInstanceDetail, type a5 as WorkflowInstancePage, type a6 as WorkflowInstanceStatus, type a7 as WorkflowInstanceSummary, type a8 as WorkflowStepDetail, a9 as createLocalStore, aa as createStream } from "./packem_shared/lunora-client.d-CtSRWJJ7.mjs";
-export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-GjXaOwY9.mjs";
+import { c as PersistenceAdapter, B as BookmarkStorage, F as FunctionReference, A as ArgsOf, M as MutationCallOptions, R as ReturnOf, O as OfflineQueueOptions, Q as QueryCacheAdapter, d as ReconnectOptions } from "./packem_shared/lunora-client.d-DPLSlPiP.mjs";
+export { type e as BatchSlot, C as CONFLICT_ERROR_CODE, type f as CachedQuery, type g as ClientMessage, type h as ClientShapeSubscribeMessage, type i as ClientShapeUnsubscribeMessage, type j as ConnectionStatus, D as DEFAULT_MAX_BUFFER, type k as FunctionArgumentDescriptor, type l as FunctionDescriptor, type G as GlobalFacetResult, type m as GlobalFacetValue, type n as GlobalFilterClause, type o as GlobalTableInfo, type p as GlobalTablePage, L as LunoraClient, type q as LunoraClientError, type r as LunoraClientOptions, type s as LunoraErrorCode, type t as MutationSettledEvent, type u as OptimisticLocalStore, type v as OptimisticUpdate, type w as OutboxMutation, type x as OutboxSink, type y as PersistedMutation, type P as Preloaded, type z as RowOp, type E as RpcEnvelope, type H as RpcResponseBody, type I as ScheduleRecord, type J as SchedulerPoolStatus, type K as SchedulerStatus, type N as ServerMessage, type T as ServerPokeEndMessage, type V as ServerPokePartMessage, type W as ServerPokeStartMessage, type X as ShardTrafficEntry, type Y as ShardTrafficResult, type Z as StorageListPage, type _ as StorageObject, type $ as StreamHandle, type a0 as StreamIterable, type a1 as SubscriptionCallback, type S as SubscriptionError, type b as SubscriptionErrorCallback, a2 as SubscriptionRegistry, type a3 as SubscriptionState, type a4 as SyncWatermark, type a as Unsubscribe, type U as User, type a5 as WorkflowInstanceAction, type a6 as WorkflowInstanceDetail, type a7 as WorkflowInstancePage, type a8 as WorkflowInstanceStatus, type a9 as WorkflowInstanceSummary, type aa as WorkflowStepDetail, ab as createLocalStore, ac as createStream, ad as getErrorCode, ae as getRetryAfterMs, af as isConflictError, ag as isForbiddenError, ah as isRateLimitedError, ai as isUnauthorizedError } from "./packem_shared/lunora-client.d-DPLSlPiP.mjs";
+export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-Bpi7xweC.mjs";
 export type { AuthCapabilities, AuthImpersonation, AuthPage, AuthSession, AuthUser, CronJobInfo, KvKeyEntry, KvKeyListResult, KvNamespaceSummary, KvValueResult, VectorIndexSummary, VectorQueryMatch } from '@lunora/runtime';
 /**
 * The slice of React Native's `AsyncStorage` (or any async key/value store —
@@ -95,17 +95,6 @@ declare const isMutationDelta: (value: unknown) => value is MutationDelta;
 * when an `insert`/`update` delta carries no `row` to splice in.
 */
 declare const applyDelta: (current: unknown, delta: MutationDelta) => undefined | unknown[];
-/** Error code the server uses for optimistic-concurrency conflicts (HTTP 409). */
-declare const CONFLICT_ERROR_CODE = "CONFLICT";
-/**
-* Whether an unknown rejection is an optimistic-concurrency conflict — the
-* server lost a write race and the caller should refetch and retry (or surface
-* the conflict). Structural check on the `code` property the client attaches
-* when decoding the worker's `{ error: { code, message } }` envelope.
-*/
-declare const isConflictError: (error: unknown) => error is Error & {
-  code: "CONFLICT";
-};
 /** The single transport method a mutation runner needs — narrowed so adapters can test against a stub. */
 interface MutationCapableClient<F extends FunctionReference> {
   mutation: (function_: F, args: ArgsOf<F>, options?: MutationCallOptions<unknown, unknown, ArgsOf<F>>) => Promise<ReturnOf<F>>;
@@ -409,4 +398,4 @@ interface ReconnectCalculator {
   reset: () => void;
 }
 declare const createReconnect: (options?: ReconnectOptions, random?: () => number) => ReconnectCalculator;
-export { type ArgsOf, type AsyncStorageLike, type AsyncStoragePersistenceOptions, type BookmarkStorage, CONFLICT_ERROR_CODE, type FunctionReference, type IndexedDbPersistenceOptions, type IndexedDbQueryCacheOptions, type MutationCallOptions, type MutationDelta, type MutationRunnerSinks, type MutatorHandle, type MutatorRunnerSinks, type MutatorTransaction, OfflineQueue, type OfflineQueueOptions, type PersistenceAdapter, type QueryCacheAdapter, type QueuedMutation, type ReconnectCalculator, type ReconnectOptions, type ReturnOf, applyDelta, createAsyncStoragePersistence, createInMemoryBookmarkStorage, createInMemoryPersistence, createInMemoryQueryCache, createIndexedDbPersistence, createIndexedDbQueryCache, createMutationRunner, createMutatorRunner, createReconnect, isConflictError, isMutationDelta, queryCacheKey };
+export { type ArgsOf, type AsyncStorageLike, type AsyncStoragePersistenceOptions, type BookmarkStorage, type FunctionReference, type IndexedDbPersistenceOptions, type IndexedDbQueryCacheOptions, type MutationCallOptions, type MutationDelta, type MutationRunnerSinks, type MutatorHandle, type MutatorRunnerSinks, type MutatorTransaction, OfflineQueue, type OfflineQueueOptions, type PersistenceAdapter, type QueryCacheAdapter, type QueuedMutation, type ReconnectCalculator, type ReconnectOptions, type ReturnOf, applyDelta, createAsyncStoragePersistence, createInMemoryBookmarkStorage, createInMemoryPersistence, createInMemoryQueryCache, createIndexedDbPersistence, createIndexedDbQueryCache, createMutationRunner, createMutatorRunner, createReconnect, isMutationDelta, queryCacheKey };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { c as PersistenceAdapter, B as BookmarkStorage, F as FunctionReference, A as ArgsOf, M as MutationCallOptions, R as ReturnOf, O as OfflineQueueOptions, Q as QueryCacheAdapter, d as ReconnectOptions } from "./packem_shared/lunora-client.d-CtSRWJJ7.js";
-export { type e as BatchSlot, type C as CachedQuery, type f as ClientMessage, type g as ClientShapeSubscribeMessage, type h as ClientShapeUnsubscribeMessage, type i as ConnectionStatus, D as DEFAULT_MAX_BUFFER, type j as FunctionArgumentDescriptor, type k as FunctionDescriptor, type G as GlobalFacetResult, type l as GlobalFacetValue, type m as GlobalFilterClause, type n as GlobalTableInfo, type o as GlobalTablePage, L as LunoraClient, type p as LunoraClientError, type q as LunoraClientOptions, type r as MutationSettledEvent, type s as OptimisticLocalStore, type t as OptimisticUpdate, type u as OutboxMutation, type v as OutboxSink, type w as PersistedMutation, type P as Preloaded, type x as RowOp, type y as RpcEnvelope, type z as RpcResponseBody, type E as ScheduleRecord, type H as SchedulerPoolStatus, type I as SchedulerStatus, type J as ServerMessage, type K as ServerPokeEndMessage, type N as ServerPokePartMessage, type T as ServerPokeStartMessage, type V as ShardTrafficEntry, type W as ShardTrafficResult, type X as StorageListPage, type Y as StorageObject, type Z as StreamHandle, type _ as StreamIterable, type $ as SubscriptionCallback, type S as SubscriptionError, type b as SubscriptionErrorCallback, a0 as SubscriptionRegistry, type a1 as SubscriptionState, type a2 as SyncWatermark, type a as Unsubscribe, type U as User, type a3 as WorkflowInstanceAction, type a4 as WorkflowInstanceDetail, type a5 as WorkflowInstancePage, type a6 as WorkflowInstanceStatus, type a7 as WorkflowInstanceSummary, type a8 as WorkflowStepDetail, a9 as createLocalStore, aa as createStream } from "./packem_shared/lunora-client.d-CtSRWJJ7.js";
-export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-NMFbch9j.js";
+import { c as PersistenceAdapter, B as BookmarkStorage, F as FunctionReference, A as ArgsOf, M as MutationCallOptions, R as ReturnOf, O as OfflineQueueOptions, Q as QueryCacheAdapter, d as ReconnectOptions } from "./packem_shared/lunora-client.d-DPLSlPiP.js";
+export { type e as BatchSlot, C as CONFLICT_ERROR_CODE, type f as CachedQuery, type g as ClientMessage, type h as ClientShapeSubscribeMessage, type i as ClientShapeUnsubscribeMessage, type j as ConnectionStatus, D as DEFAULT_MAX_BUFFER, type k as FunctionArgumentDescriptor, type l as FunctionDescriptor, type G as GlobalFacetResult, type m as GlobalFacetValue, type n as GlobalFilterClause, type o as GlobalTableInfo, type p as GlobalTablePage, L as LunoraClient, type q as LunoraClientError, type r as LunoraClientOptions, type s as LunoraErrorCode, type t as MutationSettledEvent, type u as OptimisticLocalStore, type v as OptimisticUpdate, type w as OutboxMutation, type x as OutboxSink, type y as PersistedMutation, type P as Preloaded, type z as RowOp, type E as RpcEnvelope, type H as RpcResponseBody, type I as ScheduleRecord, type J as SchedulerPoolStatus, type K as SchedulerStatus, type N as ServerMessage, type T as ServerPokeEndMessage, type V as ServerPokePartMessage, type W as ServerPokeStartMessage, type X as ShardTrafficEntry, type Y as ShardTrafficResult, type Z as StorageListPage, type _ as StorageObject, type $ as StreamHandle, type a0 as StreamIterable, type a1 as SubscriptionCallback, type S as SubscriptionError, type b as SubscriptionErrorCallback, a2 as SubscriptionRegistry, type a3 as SubscriptionState, type a4 as SyncWatermark, type a as Unsubscribe, type U as User, type a5 as WorkflowInstanceAction, type a6 as WorkflowInstanceDetail, type a7 as WorkflowInstancePage, type a8 as WorkflowInstanceStatus, type a9 as WorkflowInstanceSummary, type aa as WorkflowStepDetail, ab as createLocalStore, ac as createStream, ad as getErrorCode, ae as getRetryAfterMs, af as isConflictError, ag as isForbiddenError, ah as isRateLimitedError, ai as isUnauthorizedError } from "./packem_shared/lunora-client.d-DPLSlPiP.js";
+export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-CmFdZFQi.js";
 export type { AuthCapabilities, AuthImpersonation, AuthPage, AuthSession, AuthUser, CronJobInfo, KvKeyEntry, KvKeyListResult, KvNamespaceSummary, KvValueResult, VectorIndexSummary, VectorQueryMatch } from '@lunora/runtime';
 /**
 * The slice of React Native's `AsyncStorage` (or any async key/value store —
@@ -95,17 +95,6 @@ declare const isMutationDelta: (value: unknown) => value is MutationDelta;
 * when an `insert`/`update` delta carries no `row` to splice in.
 */
 declare const applyDelta: (current: unknown, delta: MutationDelta) => undefined | unknown[];
-/** Error code the server uses for optimistic-concurrency conflicts (HTTP 409). */
-declare const CONFLICT_ERROR_CODE = "CONFLICT";
-/**
-* Whether an unknown rejection is an optimistic-concurrency conflict — the
-* server lost a write race and the caller should refetch and retry (or surface
-* the conflict). Structural check on the `code` property the client attaches
-* when decoding the worker's `{ error: { code, message } }` envelope.
-*/
-declare const isConflictError: (error: unknown) => error is Error & {
-  code: "CONFLICT";
-};
 /** The single transport method a mutation runner needs — narrowed so adapters can test against a stub. */
 interface MutationCapableClient<F extends FunctionReference> {
   mutation: (function_: F, args: ArgsOf<F>, options?: MutationCallOptions<unknown, unknown, ArgsOf<F>>) => Promise<ReturnOf<F>>;
@@ -409,4 +398,4 @@ interface ReconnectCalculator {
   reset: () => void;
 }
 declare const createReconnect: (options?: ReconnectOptions, random?: () => number) => ReconnectCalculator;
-export { type ArgsOf, type AsyncStorageLike, type AsyncStoragePersistenceOptions, type BookmarkStorage, CONFLICT_ERROR_CODE, type FunctionReference, type IndexedDbPersistenceOptions, type IndexedDbQueryCacheOptions, type MutationCallOptions, type MutationDelta, type MutationRunnerSinks, type MutatorHandle, type MutatorRunnerSinks, type MutatorTransaction, OfflineQueue, type OfflineQueueOptions, type PersistenceAdapter, type QueryCacheAdapter, type QueuedMutation, type ReconnectCalculator, type ReconnectOptions, type ReturnOf, applyDelta, createAsyncStoragePersistence, createInMemoryBookmarkStorage, createInMemoryPersistence, createInMemoryQueryCache, createIndexedDbPersistence, createIndexedDbQueryCache, createMutationRunner, createMutatorRunner, createReconnect, isConflictError, isMutationDelta, queryCacheKey };
+export { type ArgsOf, type AsyncStorageLike, type AsyncStoragePersistenceOptions, type BookmarkStorage, type FunctionReference, type IndexedDbPersistenceOptions, type IndexedDbQueryCacheOptions, type MutationCallOptions, type MutationDelta, type MutationRunnerSinks, type MutatorHandle, type MutatorRunnerSinks, type MutatorTransaction, OfflineQueue, type OfflineQueueOptions, type PersistenceAdapter, type QueryCacheAdapter, type QueuedMutation, type ReconnectCalculator, type ReconnectOptions, type ReturnOf, applyDelta, createAsyncStoragePersistence, createInMemoryBookmarkStorage, createInMemoryPersistence, createInMemoryQueryCache, createIndexedDbPersistence, createIndexedDbQueryCache, createMutationRunner, createMutatorRunner, createReconnect, isMutationDelta, queryCacheKey };

package/dist/index.mjs

@@ -1,15 +1,15 @@
 export { createAsyncStoragePersistence } from './packem_shared/createAsyncStoragePersistence-1Z5BZ8RC.mjs';
 export { default as createInMemoryBookmarkStorage } from './packem_shared/createInMemoryBookmarkStorage-BoN7a7TH.mjs';
 export { applyDelta, isMutationDelta } from './packem_shared/applyDelta-4jFGTPA3.mjs';
-export { CONFLICT_ERROR_CODE, isConflictError } from './packem_shared/CONFLICT_ERROR_CODE-aUdVbEDw.mjs';
+export { CONFLICT_ERROR_CODE, getErrorCode, getRetryAfterMs, isConflictError, isForbiddenError, isRateLimitedError, isUnauthorizedError } from './packem_shared/CONFLICT_ERROR_CODE-B8gQ8tyU.mjs';
 export { c as createLocalStore } from './packem_shared/local-store-BNgN3Dw3.mjs';
-export { LunoraClient } from './packem_shared/LunoraClient-ClBd8JUG.mjs';
+export { LunoraClient } from './packem_shared/LunoraClient-jOfAmV8f.mjs';
 export { createMutationRunner } from './packem_shared/createMutationRunner-BqsavzvG.mjs';
 export { createMutatorRunner } from './packem_shared/createMutatorRunner-BETvCd0p.mjs';
 export { O as OfflineQueue } from './packem_shared/offline-queue-B9vfdSqp.mjs';
-export { createInMemoryPersistence, createIndexedDbPersistence } from './packem_shared/createInMemoryPersistence-CY6F0ZvQ.mjs';
+export { createInMemoryPersistence, createIndexedDbPersistence } from './packem_shared/createInMemoryPersistence-Ds7z8n8d.mjs';
 export { preloadQuery, preloadedQueryResult } from './packem_shared/preloadQuery-lobFkD2Z.mjs';
-export { createInMemoryQueryCache, createIndexedDbQueryCache, queryCacheKey } from './packem_shared/createInMemoryQueryCache-Bv4Ruv6n.mjs';
+export { createInMemoryQueryCache, createIndexedDbQueryCache, queryCacheKey } from './packem_shared/createInMemoryQueryCache-iWtKPrid.mjs';
 export { createReconnect } from './packem_shared/createReconnect-Di_-oHH7.mjs';
 export { DEFAULT_MAX_BUFFER, createStream } from './packem_shared/DEFAULT_MAX_BUFFER-BDkqO5PW.mjs';
 export { S as SubscriptionRegistry } from './packem_shared/subscription-DoyO04-2.mjs';

package/dist/packem_shared/CONFLICT_ERROR_CODE-B8gQ8tyU.mjs

@@ -0,0 +1,33 @@
+const LUNORA_ERROR_CODES = [
+  "BAD_REQUEST",
+  "CONFLICT",
+  "COUNT_RLS_UNSUPPORTED",
+  "FORBIDDEN",
+  "INTERNAL_SERVER_ERROR",
+  "MASK_UNSUPPORTED",
+  "NOT_FOUND",
+  "NOT_IMPLEMENTED",
+  "RELATION_PREDICATE_UNSUPPORTED",
+  "TOO_MANY_REQUESTS",
+  "UNAUTHORIZED",
+  "UNPROCESSABLE"
+];
+const KNOWN_ERROR_CODES = new Set(LUNORA_ERROR_CODES);
+const CONFLICT_ERROR_CODE = "CONFLICT";
+const isConflictError = (error) => error instanceof Error && error.code === CONFLICT_ERROR_CODE;
+const isForbiddenError = (error) => error instanceof Error && error.code === "FORBIDDEN";
+const isUnauthorizedError = (error) => error instanceof Error && error.code === "UNAUTHORIZED";
+const isRateLimitedError = (error) => error instanceof Error && error.code === "TOO_MANY_REQUESTS";
+const getErrorCode = (error) => {
+  if (!(error instanceof Error)) {
+    return void 0;
+  }
+  const { code } = error;
+  return typeof code === "string" && KNOWN_ERROR_CODES.has(code) ? code : void 0;
+};
+const getRetryAfterMs = (error) => {
+  const value = error?.data?.retryAfterMs;
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+};
+
+export { CONFLICT_ERROR_CODE, getErrorCode, getRetryAfterMs, isConflictError, isForbiddenError, isRateLimitedError, isUnauthorizedError };

package/dist/packem_shared/{LunoraClient-ClBd8JUG.mjs → LunoraClient-jOfAmV8f.mjs}

@@ -1,10 +1,11 @@
+import { LunoraError } from '@lunora/errors';
 import { S as SubscriptionRegistry, s as stableStringify } from './subscription-DoyO04-2.mjs';
 import createInMemoryBookmarkStorage from './createInMemoryBookmarkStorage-BoN7a7TH.mjs';
 import { isMutationDelta, applyDelta } from './applyDelta-4jFGTPA3.mjs';
 import { a as applyOptimisticLayer, d as dropConfirmedLayers, n as notifySubscription, f as foldOptimistic, c as createLocalStore } from './local-store-BNgN3Dw3.mjs';
 import { O as OfflineQueue, n as nextId, i as isStaleVersion, r as reportPersistenceError } from './offline-queue-B9vfdSqp.mjs';
-import { resolvePersistenceAdapter } from './createInMemoryPersistence-CY6F0ZvQ.mjs';
-import { resolveQueryCacheAdapter, queryCacheKey } from './createInMemoryQueryCache-Bv4Ruv6n.mjs';
+import { resolvePersistenceAdapter } from './createInMemoryPersistence-Ds7z8n8d.mjs';
+import { resolveQueryCacheAdapter, queryCacheKey } from './createInMemoryQueryCache-iWtKPrid.mjs';
 import { createReconnect } from './createReconnect-Di_-oHH7.mjs';
 import { createStream } from './DEFAULT_MAX_BUFFER-BDkqO5PW.mjs';
 
@@ -182,7 +183,14 @@ const decodeWire = (value, depth = 0) => {
           if (error.name !== name) {
             Object.defineProperty(error, "name", { configurable: true, value: name, writable: true });
           }
-          Object.assign(error, decodeWire(value[4], depth + 1));
+          const props = decodeWire(value[4], depth + 1);
+          for (const key of Object.keys(props)) {
+            if (key === UNSAFE_KEY) {
+              Object.defineProperty(error, key, { configurable: true, enumerable: true, value: props[key], writable: true });
+            } else {
+              error[key] = props[key];
+            }
+          }
           if (value.length > 5) {
             Object.defineProperty(error, "cause", { configurable: true, value: decodeWire(value[5], depth + 1), writable: true });
           }
@@ -399,6 +407,12 @@ const reconstructError = (errorBody) => {
   if (errorBody.data !== void 0) {
     error.data = decodeWire(errorBody.data);
   }
+  if (errorBody.hint !== void 0) {
+    error.hint = errorBody.hint;
+  }
+  if (errorBody.docsUrl !== void 0) {
+    error.docsUrl = errorBody.docsUrl;
+  }
   return error;
 };
 const encodeCallArgs = (payload, label) => {
@@ -685,7 +699,7 @@ class LunoraClient {
   async callMutator(functionPath, args, options) {
     const clientSeq = options?.clientSeq;
     if (clientSeq !== void 0 && (!Number.isInteger(clientSeq) || clientSeq <= 0)) {
-      throw new Error(`callMutator: clientSeq must be a positive integer, got ${String(clientSeq)}`);
+      throw new LunoraError("INTERNAL", `callMutator: clientSeq must be a positive integer, got ${String(clientSeq)}`);
     }
     const bucket = options?.shardKey ?? "";
     let ackWatermark;
@@ -969,7 +983,7 @@ class LunoraClient {
   // --- RPC ---------------------------------------------------------------
   async query(function_, args, options = {}) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     return await this.rpc(function_.__lunoraRef, args, options.shardKey, { attachBookmark: true });
   }
@@ -989,10 +1003,10 @@ class LunoraClient {
    */
   async batch(calls) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     if (!this.fetchImpl) {
-      throw new Error("LunoraClient: no `fetch` implementation available");
+      throw new LunoraError("INTERNAL", "LunoraClient: no `fetch` implementation available");
     }
     if (calls.length === 0) {
       return [];
@@ -1019,13 +1033,13 @@ class LunoraClient {
     try {
       body = await response.json();
     } catch {
-      throw new Error(`LunoraClient: batch response was not JSON (status ${response.status.toString()})`);
+      throw new LunoraError("INTERNAL", `LunoraClient: batch response was not JSON (status ${response.status.toString()})`);
     }
     if (!response.ok || body.error && !body.results) {
       if (body.error) {
         throw reconstructError(body.error);
       }
-      throw new Error(`LunoraClient: batch request failed (status ${response.status.toString()})`);
+      throw new LunoraError("INTERNAL", `LunoraClient: batch request failed (status ${response.status.toString()})`);
     }
     return demuxBatchResults(body.results ?? [], calls.length);
   }
@@ -1041,7 +1055,7 @@ class LunoraClient {
    */
   async mutation(function_, args, options = {}) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const argsRecord = args;
     const mutationId = options.mutationId ?? nextId();
@@ -1085,7 +1099,7 @@ class LunoraClient {
   }
   async action(function_, args, options = {}) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     return await this.rpc(function_.__lunoraRef, args, options.shardKey);
   }
@@ -1102,7 +1116,7 @@ class LunoraClient {
    */
   async shardTraffic(table) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(SHARD_TRAFFIC_PATH, "POST", { table });
     return { failed: body.failed ?? 0, ok: body.ok ?? 0, shards: body.shards ?? [] };
@@ -1117,7 +1131,7 @@ class LunoraClient {
    */
   async listScheduledJobs() {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(SCHEDULED_PATH, "GET");
     return body.records ?? [];
@@ -1133,7 +1147,7 @@ class LunoraClient {
    */
   async schedulerStatus() {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(SCHEDULED_STATUS_PATH, "GET");
     return {
@@ -1145,7 +1159,7 @@ class LunoraClient {
   /** Cancel a pending scheduled job by id. Returns whether a job was removed. */
   async cancelScheduledJob(id) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(SCHEDULED_CANCEL_PATH, "POST", { id });
     return { cancelled: body.cancelled === true };
@@ -1160,7 +1174,7 @@ class LunoraClient {
    */
   async listDeadJobs() {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(SCHEDULED_DEAD_PATH, "GET");
     return body.records ?? [];
@@ -1172,7 +1186,7 @@ class LunoraClient {
    */
   async retryDeadJob(id) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(SCHEDULED_DEAD_RETRY_PATH, "POST", { id });
     return { retried: body.retried === true };
@@ -1184,7 +1198,7 @@ class LunoraClient {
    */
   async removeDeadJob(id) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(SCHEDULED_DEAD_CANCEL_PATH, "POST", { id });
     return { removed: body.removed === true };
@@ -1202,7 +1216,7 @@ class LunoraClient {
    */
   async listWorkflowInstances(options) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const query = new URLSearchParams({ name: options.name });
     if (options.status !== void 0) {
@@ -1226,7 +1240,7 @@ class LunoraClient {
   /** Read one workflow instance with its step timeline (`/_lunora/admin/workflows/instance`). */
   async getWorkflowInstance(options) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const query = new URLSearchParams({ id: options.id, name: options.name });
     const body = await this.adminFetch(`${WORKFLOWS_INSTANCE_PATH}?${query.toString()}`, "GET");
@@ -1245,7 +1259,7 @@ class LunoraClient {
   /** Pause / resume / terminate a workflow instance (`/_lunora/admin/workflows/status`). Needs an Edit-scoped Cloudflare token. */
   async setWorkflowInstanceStatus(options) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(WORKFLOWS_STATUS_PATH, "POST", { action: options.action, id: options.id, name: options.name });
     return { status: body.status ?? "unknown" };
@@ -1260,7 +1274,7 @@ class LunoraClient {
    */
   subscribeScheduledJobs(onJobs) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     if (this.WebSocketImpl === void 0) {
       return () => void 0;
@@ -1316,7 +1330,7 @@ class LunoraClient {
    */
   async listFunctions() {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(FUNCTIONS_PATH, "GET");
     return body.functions ?? [];
@@ -1332,7 +1346,7 @@ class LunoraClient {
    */
   async getCronJobs() {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(CRON_JOBS_PATH, "GET");
     return body.jobs ?? [];
@@ -1348,7 +1362,7 @@ class LunoraClient {
    */
   async runCronJob(name) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(CRON_JOBS_RUN_PATH, "POST", { name });
     return { name: body.name ?? name, ran: body.ran === true };
@@ -1363,7 +1377,7 @@ class LunoraClient {
    */
   async fetchOpenApi() {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     return await this.adminFetch(OPENAPI_PATH, "GET");
   }
@@ -1379,7 +1393,7 @@ class LunoraClient {
    */
   async fetchOpenRpc() {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     return await this.adminFetch(OPENRPC_PATH, "GET");
   }
@@ -1393,7 +1407,7 @@ class LunoraClient {
    */
   async listStorageObjects(options = {}) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const params = new URLSearchParams();
     if (options.prefix !== void 0 && options.prefix !== "") {
@@ -1421,7 +1435,7 @@ class LunoraClient {
    */
   async deleteStorageObject(key, options) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const path = `${STORAGE_PATH}?key=${encodeURIComponent(key)}${bucketQuery(options?.bucket)}`;
     const body = await this.adminFetch(path, "DELETE");
@@ -1435,7 +1449,7 @@ class LunoraClient {
    */
   async listStorageBuckets() {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(STORAGE_BUCKETS_PATH, "GET");
     return body.buckets ?? [];
@@ -1449,7 +1463,7 @@ class LunoraClient {
    */
   async uploadStorageObject(options) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const path = `${STORAGE_PATH}?key=${encodeURIComponent(options.key)}${bucketQuery(options.bucket)}`;
     const body = await this.adminFetch(path, "PUT", options.body, options.contentType);
@@ -1468,7 +1482,7 @@ class LunoraClient {
    */
   async signedStorageUrl(key, options) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const expiresInSeconds = options?.expiresInSeconds;
     const expiryQuery = expiresInSeconds === void 0 ? "" : `&expiresIn=${encodeURIComponent(expiresInSeconds.toString())}`;
@@ -1488,7 +1502,7 @@ class LunoraClient {
    */
   async listGlobalTables() {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     return await this.adminFetch(GLOBAL_TABLES_PATH, "GET");
   }
@@ -1500,7 +1514,7 @@ class LunoraClient {
    */
   async readGlobalTablePage(options) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const params = new URLSearchParams({ table: options.table });
     if (options.limit !== void 0) {
@@ -1523,7 +1537,7 @@ class LunoraClient {
    */
   async facetGlobalColumn(options) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const params = new URLSearchParams({ column: options.column, table: options.table });
     if (options.limit !== void 0) {
@@ -1546,7 +1560,7 @@ class LunoraClient {
    */
   async listVectorIndexes() {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(VECTOR_INDEXES_PATH, "GET");
     return body.indexes ?? [];
@@ -1560,7 +1574,7 @@ class LunoraClient {
    */
   async queryVectorIndex(options) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(VECTOR_QUERY_PATH, "POST", options);
     return body.matches ?? [];
@@ -1574,7 +1588,7 @@ class LunoraClient {
    */
   async listKvNamespaces() {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(KV_NAMESPACES_PATH, "GET");
     return body.namespaces ?? [];
@@ -1586,7 +1600,7 @@ class LunoraClient {
    */
   async listKvKeys(options) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const path = withQuery(KV_KEYS_PATH, {
       cursor: options.cursor,
@@ -1603,7 +1617,7 @@ class LunoraClient {
    */
   async getKvValue(options) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const path = withQuery(KV_VALUE_PATH, { key: options.key, namespace: options.namespace });
     return await this.adminFetch(path, "GET");
@@ -1616,7 +1630,7 @@ class LunoraClient {
    */
   async putKvValue(options) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     await this.adminFetch(KV_VALUE_PATH, "PUT", options);
   }
@@ -1626,7 +1640,7 @@ class LunoraClient {
    */
   async deleteKvKey(options) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const path = withQuery(KV_VALUE_PATH, { key: options.key, namespace: options.namespace });
     await this.adminFetch(path, "DELETE");
@@ -1640,7 +1654,7 @@ class LunoraClient {
    */
   async listAuthUsers(options = {}) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const path = withQuery(AUTH_USERS_PATH, {
       filterField: options.filterField,
@@ -1755,7 +1769,7 @@ class LunoraClient {
   /** List auth sessions, paged and optionally filtered to one user. */
   async listAuthSessions(options = {}) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const params = new URLSearchParams();
     if (options.userId !== void 0 && options.userId !== "") {
@@ -1773,7 +1787,7 @@ class LunoraClient {
   // --- Subscriptions ------------------------------------------------------
   subscribe(function_, args, callback, options = {}) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const argsRecord = args ?? {};
     const key = SubscriptionRegistry.key(function_.__lunoraRef, argsRecord, options.shardKey);
@@ -1851,7 +1865,7 @@ class LunoraClient {
    */
   subscribeShape(shape, callback, options = {}) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     this.nextShapeId += 1;
     const id = `shape_${this.nextShapeId.toString()}`;
@@ -1897,10 +1911,10 @@ class LunoraClient {
    */
   stream(function_, args, options = {}) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     if (this.WebSocketImpl === void 0) {
-      throw new Error("LunoraClient: streams require a WebSocket implementation");
+      throw new LunoraError("INTERNAL", "LunoraClient: streams require a WebSocket implementation");
     }
     this.nextStreamId += 1;
     const id = `stream_${this.nextStreamId.toString()}`;
@@ -2350,7 +2364,7 @@ class LunoraClient {
   }
   async rpc(functionPath, args, shardKey, flags = {}) {
     if (!this.fetchImpl) {
-      throw new Error("LunoraClient: no `fetch` implementation available");
+      throw new LunoraError("INTERNAL", "LunoraClient: no `fetch` implementation available");
     }
     const headers = this.rpcRequestHeaders(flags);
     const response = await this.fetchImpl(joinUrl(this.url, RPC_PATH), {
@@ -2372,14 +2386,14 @@ class LunoraClient {
       body = await response.json();
     } catch {
       const statusText = response.statusText ? ` ${response.statusText}` : "";
-      throw new Error(`LunoraClient: response was not JSON (status ${response.status.toString()}${statusText})`);
+      throw new LunoraError("INTERNAL", `LunoraClient: response was not JSON (status ${response.status.toString()}${statusText})`);
     }
     if ("error" in body) {
       throw reconstructError(body.error);
     }
     if (!response.ok) {
       const statusText = response.statusText ? ` ${response.statusText}` : "";
-      throw new Error(`LunoraClient: request failed (status ${response.status.toString()}${statusText})`);
+      throw new LunoraError("INTERNAL", `LunoraClient: request failed (status ${response.status.toString()}${statusText})`);
     }
     flags.onMutationAck?.(body.lastMutationId);
     flags.onCommitCursor?.(body.commitCursor);
@@ -2393,7 +2407,7 @@ class LunoraClient {
    */
   async adminFetch(path, method, payload, contentType) {
     if (!this.fetchImpl) {
-      throw new Error("LunoraClient: no `fetch` implementation available");
+      throw new LunoraError("INTERNAL", "LunoraClient: no `fetch` implementation available");
     }
     const headers = {};
     if (this.authToken) {
@@ -2422,7 +2436,7 @@ class LunoraClient {
       body = await response.json();
     } catch {
       const statusText = response.statusText ? ` ${response.statusText}` : "";
-      throw new Error(`LunoraClient: response was not JSON (status ${response.status.toString()}${statusText})`);
+      throw new LunoraError("INTERNAL", `LunoraClient: response was not JSON (status ${response.status.toString()}${statusText})`);
     }
     if (typeof body === "object" && body !== null && "error" in body) {
       const envelope = body.error;
@@ -2432,7 +2446,7 @@ class LunoraClient {
     }
     if (!response.ok) {
       const statusText = response.statusText ? ` ${response.statusText}` : "";
-      throw new Error(`LunoraClient: admin request failed (status ${response.status.toString()}${statusText})`);
+      throw new LunoraError("INTERNAL", `LunoraClient: admin request failed (status ${response.status.toString()}${statusText})`);
     }
     return body;
   }

package/dist/packem_shared/{createInMemoryPersistence-CY6F0ZvQ.mjs → createInMemoryPersistence-Ds7z8n8d.mjs}

@@ -1,3 +1,5 @@
+import { LunoraError } from '@lunora/errors';
+
 const createInMemoryPersistence = () => {
   const entries = /* @__PURE__ */ new Map();
   const clone = (mutation) => {
@@ -39,7 +41,7 @@ const promisifyRequest = (request) => new Promise((resolve, reject) => {
 const createIndexedDbPersistence = (options = {}) => {
   const factory = options.indexedDB ?? (typeof indexedDB === "undefined" ? void 0 : indexedDB);
   if (!factory) {
-    throw new Error("createIndexedDbPersistence: no IndexedDB available — pass `indexedDB` or use createInMemoryPersistence()");
+    throw new LunoraError("INTERNAL", "createIndexedDbPersistence: no IndexedDB available — pass `indexedDB` or use createInMemoryPersistence()");
   }
   const databaseName = options.databaseName ?? DEFAULT_DATABASE;
   const storeName = options.storeName ?? DEFAULT_STORE;

package/dist/packem_shared/{createInMemoryQueryCache-Bv4Ruv6n.mjs → createInMemoryQueryCache-iWtKPrid.mjs}

@@ -1,3 +1,5 @@
+import { LunoraError } from '@lunora/errors';
+
 const queryCacheKey = (functionPath, argsKey, shardKey) => `${functionPath}::${argsKey}::${shardKey ?? ""}`;
 const DEFAULT_MAX_ENTRIES = 500;
 const createInMemoryQueryCache = (options = {}) => {
@@ -50,7 +52,7 @@ const promisifyRequest = (request) => new Promise((resolve, reject) => {
 const createIndexedDbQueryCache = (options = {}) => {
   const factory = options.indexedDB ?? (typeof indexedDB === "undefined" ? void 0 : indexedDB);
   if (!factory) {
-    throw new Error("createIndexedDbQueryCache: no IndexedDB available — pass `indexedDB` or use createInMemoryQueryCache()");
+    throw new LunoraError("INTERNAL", "createIndexedDbQueryCache: no IndexedDB available — pass `indexedDB` or use createInMemoryQueryCache()");
   }
   const databaseName = options.databaseName ?? DEFAULT_DATABASE;
   const storeName = options.storeName ?? DEFAULT_STORE;

package/dist/packem_shared/{createServerClient-BUEYFHjp.mjs → createServerClient-Blht8tLm.mjs}

@@ -1,4 +1,4 @@
-import { LunoraClient } from './LunoraClient-ClBd8JUG.mjs';
+import { LunoraClient } from './LunoraClient-jOfAmV8f.mjs';
 
 const createServerClient = (options) => {
   const client = new LunoraClient({ fetch: options.fetch, url: options.url });

package/dist/packem_shared/{lunora-client.d-CtSRWJJ7.d.mts → lunora-client.d-DPLSlPiP.d.mts}

@@ -1,4 +1,59 @@
 import { CronJobInfo, VectorIndexSummary, VectorQueryMatch, KvNamespaceSummary, KvKeyListResult, KvValueResult, AuthUser, AuthPage, AuthImpersonation, AuthCapabilities, AuthSession } from '@lunora/runtime';
+/**
+* The machine-readable error codes a client can observe on a failed
+* RPC/batch/subscription. Mirrors the server's `CODE_STATUS` keys
+* (`@lunora/server`'s `error.ts`) by hand — the client is framework-neutral and
+* must never import the server package (wrong dependency direction / would pull
+* the server into the browser bundle). Keep this list in sync when a server code
+* is added or removed (see the drift-guard note in the plan/maintenance docs).
+*/
+declare const LUNORA_ERROR_CODES: readonly ["BAD_REQUEST", "CONFLICT", "COUNT_RLS_UNSUPPORTED", "FORBIDDEN", "INTERNAL_SERVER_ERROR", "MASK_UNSUPPORTED", "NOT_FOUND", "NOT_IMPLEMENTED", "RELATION_PREDICATE_UNSUPPORTED", "TOO_MANY_REQUESTS", "UNAUTHORIZED", "UNPROCESSABLE"];
+/** A machine-readable error `code` the client may observe. Mirror of the server's `LunoraErrorCode`. */
+type LunoraErrorCode = (typeof LUNORA_ERROR_CODES)[number];
+/** Error code the server uses for optimistic-concurrency conflicts (HTTP 409). */
+declare const CONFLICT_ERROR_CODE = "CONFLICT";
+/**
+* Whether an unknown rejection is an optimistic-concurrency conflict — the
+* server lost a write race and the caller should refetch and retry (or surface
+* the conflict). Structural check on the `code` property the client attaches
+* when decoding the worker's `{ error: { code, message } }` envelope.
+*/
+declare const isConflictError: (error: unknown) => error is Error & {
+  code: "CONFLICT";
+};
+/**
+* Whether a rejection is an RLS/policy denial (`FORBIDDEN`, HTTP 403) — the
+* caller is authenticated but not permitted to read/write the row. The most
+* common per-call error a UI must handle in an RLS-first app.
+*/
+declare const isForbiddenError: (error: unknown) => error is Error & {
+  code: "FORBIDDEN";
+};
+/** Whether a rejection is an authentication failure (`UNAUTHORIZED`, HTTP 401) — no/invalid identity. */
+declare const isUnauthorizedError: (error: unknown) => error is Error & {
+  code: "UNAUTHORIZED";
+};
+/**
+* Whether a rejection is a rate-limit denial (`TOO_MANY_REQUESTS`, HTTP 429).
+* The retry hint (if the server sent one) is read with {@link getRetryAfterMs}.
+*/
+declare const isRateLimitedError: (error: unknown) => error is Error & {
+  code: "TOO_MANY_REQUESTS";
+};
+/**
+* Read the server's machine-readable `code` off a rejection, narrowed to the
+* known {@link LunoraErrorCode} union. Returns `undefined` for a non-`Error`, a
+* missing code, or an unrecognized code string (forward-compat server codes read
+* as `undefined` here rather than being falsely narrowed).
+*/
+declare const getErrorCode: (error: unknown) => LunoraErrorCode | undefined;
+/**
+* Read the rate-limit retry hint (`data.retryAfterMs`) off a
+* `TOO_MANY_REQUESTS` rejection without hand-casting the `unknown` `data`
+* payload. Returns the finite millisecond value the server sent, or `undefined`
+* when absent/non-numeric. Pair with {@link isRateLimitedError}.
+*/
+declare const getRetryAfterMs: (error: unknown) => number | undefined;
 /** The registered function kinds a {@link FunctionReference} can describe. `stream` is a query that yields multiple frames over the WS. */
 type FunctionKind = "action" | "mutation" | "query" | "stream";
 /**
@@ -1152,10 +1207,20 @@ interface SyncWatermark {
   checkpoint?: number;
   mutationId?: number;
 }
-/** An `Error` carrying the server's machine-readable `code` and (for a `LunoraError`) structured `data`. The client's public error contract for RPC/batch failures. */
+/**
+* An `Error` carrying the server's machine-readable `code` and (for a
+* `LunoraError`) structured `data`, plus an optional actionable `hint` (Markdown)
+* and `docsUrl` resolved from the central error catalog. The client's public
+* error contract for RPC/batch failures — a UI can render `hint`/`docsUrl` to
+* tell the user how to fix the error. The `(string & {})` arm keeps
+* forward-compat/unknown server codes assignable without losing autocomplete on
+* the known {@link LunoraErrorCode} union.
+*/
 type LunoraClientError = Error & {
-  code?: string;
+  code?: LunoraErrorCode | (string & {});
   data?: unknown;
+  docsUrl?: string;
+  hint?: string | string[];
 };
 /** One demuxed result slot of a {@link LunoraClient.batch} call (plan 088). */
 type BatchSlot = {
@@ -2357,4 +2422,4 @@ declare class LunoraClient {
   */
   private settleReplayBatchSlots;
 }
-export { SubscriptionCallback as $, ArgsOf as A, BookmarkStorage as B, CachedQuery as C, DEFAULT_MAX_BUFFER as D, ScheduleRecord as E, FunctionReference as F, GlobalFacetResult as G, SchedulerPoolStatus as H, SchedulerStatus as I, ServerMessage as J, ServerPokeEndMessage as K, LunoraClient as L, MutationCallOptions as M, ServerPokePartMessage as N, OfflineQueueOptions as O, Preloaded as P, QueryCacheAdapter as Q, ReturnOf as R, SubscriptionError as S, ServerPokeStartMessage as T, User as U, ShardTrafficEntry as V, ShardTrafficResult as W, StorageListPage as X, StorageObject as Y, StreamHandle as Z, StreamIterable as _, Unsubscribe as a, SubscriptionRegistry as a0, SubscriptionState as a1, SyncWatermark as a2, WorkflowInstanceAction as a3, WorkflowInstanceDetail as a4, WorkflowInstancePage as a5, WorkflowInstanceStatus as a6, WorkflowInstanceSummary as a7, WorkflowStepDetail as a8, createLocalStore as a9, createStream as aa, SubscriptionErrorCallback as b, PersistenceAdapter as c, ReconnectOptions as d, BatchSlot as e, ClientMessage as f, ClientShapeSubscribeMessage as g, ClientShapeUnsubscribeMessage as h, ConnectionStatus as i, FunctionArgumentDescriptor as j, FunctionDescriptor as k, GlobalFacetValue as l, GlobalFilterClause as m, GlobalTableInfo as n, GlobalTablePage as o, LunoraClientError as p, LunoraClientOptions as q, MutationSettledEvent as r, OptimisticLocalStore as s, OptimisticUpdate as t, OutboxMutation as u, OutboxSink as v, PersistedMutation as w, RowOp as x, RpcEnvelope as y, RpcResponseBody as z };
+export { StreamHandle as $, ArgsOf as A, BookmarkStorage as B, CONFLICT_ERROR_CODE as C, DEFAULT_MAX_BUFFER as D, RpcEnvelope as E, FunctionReference as F, GlobalFacetResult as G, RpcResponseBody as H, ScheduleRecord as I, SchedulerPoolStatus as J, SchedulerStatus as K, LunoraClient as L, MutationCallOptions as M, ServerMessage as N, OfflineQueueOptions as O, Preloaded as P, QueryCacheAdapter as Q, ReturnOf as R, SubscriptionError as S, ServerPokeEndMessage as T, User as U, ServerPokePartMessage as V, ServerPokeStartMessage as W, ShardTrafficEntry as X, ShardTrafficResult as Y, StorageListPage as Z, StorageObject as _, Unsubscribe as a, StreamIterable as a0, SubscriptionCallback as a1, SubscriptionRegistry as a2, SubscriptionState as a3, SyncWatermark as a4, WorkflowInstanceAction as a5, WorkflowInstanceDetail as a6, WorkflowInstancePage as a7, WorkflowInstanceStatus as a8, WorkflowInstanceSummary as a9, WorkflowStepDetail as aa, createLocalStore as ab, createStream as ac, getErrorCode as ad, getRetryAfterMs as ae, isConflictError as af, isForbiddenError as ag, isRateLimitedError as ah, isUnauthorizedError as ai, SubscriptionErrorCallback as b, PersistenceAdapter as c, ReconnectOptions as d, BatchSlot as e, CachedQuery as f, ClientMessage as g, ClientShapeSubscribeMessage as h, ClientShapeUnsubscribeMessage as i, ConnectionStatus as j, FunctionArgumentDescriptor as k, FunctionDescriptor as l, GlobalFacetValue as m, GlobalFilterClause as n, GlobalTableInfo as o, GlobalTablePage as p, LunoraClientError as q, LunoraClientOptions as r, LunoraErrorCode as s, MutationSettledEvent as t, OptimisticLocalStore as u, OptimisticUpdate as v, OutboxMutation as w, OutboxSink as x, PersistedMutation as y, RowOp as z };

package/dist/packem_shared/{lunora-client.d-CtSRWJJ7.d.ts → lunora-client.d-DPLSlPiP.d.ts}

@@ -1,4 +1,59 @@
 import { CronJobInfo, VectorIndexSummary, VectorQueryMatch, KvNamespaceSummary, KvKeyListResult, KvValueResult, AuthUser, AuthPage, AuthImpersonation, AuthCapabilities, AuthSession } from '@lunora/runtime';
+/**
+* The machine-readable error codes a client can observe on a failed
+* RPC/batch/subscription. Mirrors the server's `CODE_STATUS` keys
+* (`@lunora/server`'s `error.ts`) by hand — the client is framework-neutral and
+* must never import the server package (wrong dependency direction / would pull
+* the server into the browser bundle). Keep this list in sync when a server code
+* is added or removed (see the drift-guard note in the plan/maintenance docs).
+*/
+declare const LUNORA_ERROR_CODES: readonly ["BAD_REQUEST", "CONFLICT", "COUNT_RLS_UNSUPPORTED", "FORBIDDEN", "INTERNAL_SERVER_ERROR", "MASK_UNSUPPORTED", "NOT_FOUND", "NOT_IMPLEMENTED", "RELATION_PREDICATE_UNSUPPORTED", "TOO_MANY_REQUESTS", "UNAUTHORIZED", "UNPROCESSABLE"];
+/** A machine-readable error `code` the client may observe. Mirror of the server's `LunoraErrorCode`. */
+type LunoraErrorCode = (typeof LUNORA_ERROR_CODES)[number];
+/** Error code the server uses for optimistic-concurrency conflicts (HTTP 409). */
+declare const CONFLICT_ERROR_CODE = "CONFLICT";
+/**
+* Whether an unknown rejection is an optimistic-concurrency conflict — the
+* server lost a write race and the caller should refetch and retry (or surface
+* the conflict). Structural check on the `code` property the client attaches
+* when decoding the worker's `{ error: { code, message } }` envelope.
+*/
+declare const isConflictError: (error: unknown) => error is Error & {
+  code: "CONFLICT";
+};
+/**
+* Whether a rejection is an RLS/policy denial (`FORBIDDEN`, HTTP 403) — the
+* caller is authenticated but not permitted to read/write the row. The most
+* common per-call error a UI must handle in an RLS-first app.
+*/
+declare const isForbiddenError: (error: unknown) => error is Error & {
+  code: "FORBIDDEN";
+};
+/** Whether a rejection is an authentication failure (`UNAUTHORIZED`, HTTP 401) — no/invalid identity. */
+declare const isUnauthorizedError: (error: unknown) => error is Error & {
+  code: "UNAUTHORIZED";
+};
+/**
+* Whether a rejection is a rate-limit denial (`TOO_MANY_REQUESTS`, HTTP 429).
+* The retry hint (if the server sent one) is read with {@link getRetryAfterMs}.
+*/
+declare const isRateLimitedError: (error: unknown) => error is Error & {
+  code: "TOO_MANY_REQUESTS";
+};
+/**
+* Read the server's machine-readable `code` off a rejection, narrowed to the
+* known {@link LunoraErrorCode} union. Returns `undefined` for a non-`Error`, a
+* missing code, or an unrecognized code string (forward-compat server codes read
+* as `undefined` here rather than being falsely narrowed).
+*/
+declare const getErrorCode: (error: unknown) => LunoraErrorCode | undefined;
+/**
+* Read the rate-limit retry hint (`data.retryAfterMs`) off a
+* `TOO_MANY_REQUESTS` rejection without hand-casting the `unknown` `data`
+* payload. Returns the finite millisecond value the server sent, or `undefined`
+* when absent/non-numeric. Pair with {@link isRateLimitedError}.
+*/
+declare const getRetryAfterMs: (error: unknown) => number | undefined;
 /** The registered function kinds a {@link FunctionReference} can describe. `stream` is a query that yields multiple frames over the WS. */
 type FunctionKind = "action" | "mutation" | "query" | "stream";
 /**
@@ -1152,10 +1207,20 @@ interface SyncWatermark {
   checkpoint?: number;
   mutationId?: number;
 }
-/** An `Error` carrying the server's machine-readable `code` and (for a `LunoraError`) structured `data`. The client's public error contract for RPC/batch failures. */
+/**
+* An `Error` carrying the server's machine-readable `code` and (for a
+* `LunoraError`) structured `data`, plus an optional actionable `hint` (Markdown)
+* and `docsUrl` resolved from the central error catalog. The client's public
+* error contract for RPC/batch failures — a UI can render `hint`/`docsUrl` to
+* tell the user how to fix the error. The `(string & {})` arm keeps
+* forward-compat/unknown server codes assignable without losing autocomplete on
+* the known {@link LunoraErrorCode} union.
+*/
 type LunoraClientError = Error & {
-  code?: string;
+  code?: LunoraErrorCode | (string & {});
   data?: unknown;
+  docsUrl?: string;
+  hint?: string | string[];
 };
 /** One demuxed result slot of a {@link LunoraClient.batch} call (plan 088). */
 type BatchSlot = {
@@ -2357,4 +2422,4 @@ declare class LunoraClient {
   */
   private settleReplayBatchSlots;
 }
-export { SubscriptionCallback as $, ArgsOf as A, BookmarkStorage as B, CachedQuery as C, DEFAULT_MAX_BUFFER as D, ScheduleRecord as E, FunctionReference as F, GlobalFacetResult as G, SchedulerPoolStatus as H, SchedulerStatus as I, ServerMessage as J, ServerPokeEndMessage as K, LunoraClient as L, MutationCallOptions as M, ServerPokePartMessage as N, OfflineQueueOptions as O, Preloaded as P, QueryCacheAdapter as Q, ReturnOf as R, SubscriptionError as S, ServerPokeStartMessage as T, User as U, ShardTrafficEntry as V, ShardTrafficResult as W, StorageListPage as X, StorageObject as Y, StreamHandle as Z, StreamIterable as _, Unsubscribe as a, SubscriptionRegistry as a0, SubscriptionState as a1, SyncWatermark as a2, WorkflowInstanceAction as a3, WorkflowInstanceDetail as a4, WorkflowInstancePage as a5, WorkflowInstanceStatus as a6, WorkflowInstanceSummary as a7, WorkflowStepDetail as a8, createLocalStore as a9, createStream as aa, SubscriptionErrorCallback as b, PersistenceAdapter as c, ReconnectOptions as d, BatchSlot as e, ClientMessage as f, ClientShapeSubscribeMessage as g, ClientShapeUnsubscribeMessage as h, ConnectionStatus as i, FunctionArgumentDescriptor as j, FunctionDescriptor as k, GlobalFacetValue as l, GlobalFilterClause as m, GlobalTableInfo as n, GlobalTablePage as o, LunoraClientError as p, LunoraClientOptions as q, MutationSettledEvent as r, OptimisticLocalStore as s, OptimisticUpdate as t, OutboxMutation as u, OutboxSink as v, PersistedMutation as w, RowOp as x, RpcEnvelope as y, RpcResponseBody as z };
+export { StreamHandle as $, ArgsOf as A, BookmarkStorage as B, CONFLICT_ERROR_CODE as C, DEFAULT_MAX_BUFFER as D, RpcEnvelope as E, FunctionReference as F, GlobalFacetResult as G, RpcResponseBody as H, ScheduleRecord as I, SchedulerPoolStatus as J, SchedulerStatus as K, LunoraClient as L, MutationCallOptions as M, ServerMessage as N, OfflineQueueOptions as O, Preloaded as P, QueryCacheAdapter as Q, ReturnOf as R, SubscriptionError as S, ServerPokeEndMessage as T, User as U, ServerPokePartMessage as V, ServerPokeStartMessage as W, ShardTrafficEntry as X, ShardTrafficResult as Y, StorageListPage as Z, StorageObject as _, Unsubscribe as a, StreamIterable as a0, SubscriptionCallback as a1, SubscriptionRegistry as a2, SubscriptionState as a3, SyncWatermark as a4, WorkflowInstanceAction as a5, WorkflowInstanceDetail as a6, WorkflowInstancePage as a7, WorkflowInstanceStatus as a8, WorkflowInstanceSummary as a9, WorkflowStepDetail as aa, createLocalStore as ab, createStream as ac, getErrorCode as ad, getRetryAfterMs as ae, isConflictError as af, isForbiddenError as ag, isRateLimitedError as ah, isUnauthorizedError as ai, SubscriptionErrorCallback as b, PersistenceAdapter as c, ReconnectOptions as d, BatchSlot as e, CachedQuery as f, ClientMessage as g, ClientShapeSubscribeMessage as h, ClientShapeUnsubscribeMessage as i, ConnectionStatus as j, FunctionArgumentDescriptor as k, FunctionDescriptor as l, GlobalFacetValue as m, GlobalFilterClause as n, GlobalTableInfo as o, GlobalTablePage as p, LunoraClientError as q, LunoraClientOptions as r, LunoraErrorCode as s, MutationSettledEvent as t, OptimisticLocalStore as u, OptimisticUpdate as v, OutboxMutation as w, OutboxSink as x, PersistedMutation as y, RowOp as z };

package/dist/packem_shared/{preload.d-GjXaOwY9.d.mts → preload.d-Bpi7xweC.d.mts}

@@ -1,4 +1,4 @@
-import { F as FunctionReference, L as LunoraClient, A as ArgsOf, R as ReturnOf, P as Preloaded } from "./lunora-client.d-CtSRWJJ7.mjs";
+import { F as FunctionReference, L as LunoraClient, A as ArgsOf, R as ReturnOf, P as Preloaded } from "./lunora-client.d-DPLSlPiP.mjs";
 /**
 * Run a query once on the server (during SSR) and capture its result in a
 * serializable {@link Preloaded} token. Embed the token in the rendered HTML and

package/dist/packem_shared/{preload.d-NMFbch9j.d.ts → preload.d-CmFdZFQi.d.ts}

@@ -1,4 +1,4 @@
-import { F as FunctionReference, L as LunoraClient, A as ArgsOf, R as ReturnOf, P as Preloaded } from "./lunora-client.d-CtSRWJJ7.js";
+import { F as FunctionReference, L as LunoraClient, A as ArgsOf, R as ReturnOf, P as Preloaded } from "./lunora-client.d-DPLSlPiP.js";
 /**
 * Run a query once on the server (during SSR) and capture its result in a
 * serializable {@link Preloaded} token. Embed the token in the rendered HTML and

package/dist/query/index.d.mts

@@ -1,5 +1,5 @@
-import { S as SubscriptionError, F as FunctionReference, A as ArgsOf, R as ReturnOf, L as LunoraClient, a as Unsubscribe } from "../packem_shared/lunora-client.d-CtSRWJJ7.mjs";
-export type { b as SubscriptionErrorCallback } from "../packem_shared/lunora-client.d-CtSRWJJ7.mjs";
+import { S as SubscriptionError, F as FunctionReference, A as ArgsOf, R as ReturnOf, L as LunoraClient, a as Unsubscribe } from "../packem_shared/lunora-client.d-DPLSlPiP.mjs";
+export type { b as SubscriptionErrorCallback } from "../packem_shared/lunora-client.d-DPLSlPiP.mjs";
 import '@lunora/runtime';
 /**
 * The sentinel a framework adapter resolves its reactive args to when it wants

package/dist/query/index.d.ts

@@ -1,5 +1,5 @@
-import { S as SubscriptionError, F as FunctionReference, A as ArgsOf, R as ReturnOf, L as LunoraClient, a as Unsubscribe } from "../packem_shared/lunora-client.d-CtSRWJJ7.js";
-export type { b as SubscriptionErrorCallback } from "../packem_shared/lunora-client.d-CtSRWJJ7.js";
+import { S as SubscriptionError, F as FunctionReference, A as ArgsOf, R as ReturnOf, L as LunoraClient, a as Unsubscribe } from "../packem_shared/lunora-client.d-DPLSlPiP.js";
+export type { b as SubscriptionErrorCallback } from "../packem_shared/lunora-client.d-DPLSlPiP.js";
 import '@lunora/runtime';
 /**
 * The sentinel a framework adapter resolves its reactive args to when it wants

package/dist/ssr/index.d.mts

@@ -1,6 +1,6 @@
-import { P as Preloaded, L as LunoraClient } from "../packem_shared/lunora-client.d-CtSRWJJ7.mjs";
-export type { A as ArgsOf, F as FunctionReference, R as ReturnOf } from "../packem_shared/lunora-client.d-CtSRWJJ7.mjs";
-export { p as preloadQuery, a as preloadedQueryResult } from "../packem_shared/preload.d-GjXaOwY9.mjs";
+import { P as Preloaded, L as LunoraClient } from "../packem_shared/lunora-client.d-DPLSlPiP.mjs";
+export type { A as ArgsOf, F as FunctionReference, R as ReturnOf } from "../packem_shared/lunora-client.d-DPLSlPiP.mjs";
+export { p as preloadQuery, a as preloadedQueryResult } from "../packem_shared/preload.d-Bpi7xweC.mjs";
 import '@lunora/runtime';
 /**
 * Structural shape of a better-auth `getSession` call's resolved value.

package/dist/ssr/index.d.ts

@@ -1,6 +1,6 @@
-import { P as Preloaded, L as LunoraClient } from "../packem_shared/lunora-client.d-CtSRWJJ7.js";
-export type { A as ArgsOf, F as FunctionReference, R as ReturnOf } from "../packem_shared/lunora-client.d-CtSRWJJ7.js";
-export { p as preloadQuery, a as preloadedQueryResult } from "../packem_shared/preload.d-NMFbch9j.js";
+import { P as Preloaded, L as LunoraClient } from "../packem_shared/lunora-client.d-DPLSlPiP.js";
+export type { A as ArgsOf, F as FunctionReference, R as ReturnOf } from "../packem_shared/lunora-client.d-DPLSlPiP.js";
+export { p as preloadQuery, a as preloadedQueryResult } from "../packem_shared/preload.d-CmFdZFQi.js";
 import '@lunora/runtime';
 /**
 * Structural shape of a better-auth `getSession` call's resolved value.

package/dist/ssr/index.mjs

@@ -1,4 +1,4 @@
 export { getServerSession } from '../packem_shared/getServerSession-8jXewqxd.mjs';
 export { deserializePreloaded, serializePreloaded } from '../packem_shared/deserializePreloaded-C0eJTY_W.mjs';
-export { createServerClient } from '../packem_shared/createServerClient-BUEYFHjp.mjs';
+export { createServerClient } from '../packem_shared/createServerClient-Blht8tLm.mjs';
 export { preloadQuery, preloadedQueryResult } from '../packem_shared/preloadQuery-lobFkD2Z.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/client",
-  "version": "1.0.0-alpha.15",
+  "version": "1.0.0-alpha.17",
   "description": "Lunora browser SDK: WebSocket transport, optimistic updates, and an offline mutation queue",
   "keywords": [
     "cloudflare",
@@ -61,6 +61,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@lunora/errors": "1.0.0-alpha.1"
+  },
   "engines": {
     "node": "^22.15.0 || >=24.11.0"
   }

package/dist/packem_shared/CONFLICT_ERROR_CODE-aUdVbEDw.mjs

@@ -1,4 +0,0 @@
-const CONFLICT_ERROR_CODE = "CONFLICT";
-const isConflictError = (error) => error instanceof Error && error.code === CONFLICT_ERROR_CODE;
-
-export { CONFLICT_ERROR_CODE, isConflictError };