@abloatai/ablo 0.7.0 → 0.8.0

package/dist/query/client.js

@@ -12,6 +12,7 @@
  * without duplicating the fetch boilerplate.
  */
 import { z } from 'zod';
+import { translateHttpError } from '../errors.js';
 // ── Response validation ─────────────────────────────────────────────────
 //
 // Each result slot is an array of rows (or an object for bundled
@@ -60,14 +61,24 @@ export async function postQuery(options, batch) {
             signal: controller.signal,
         });
         if (!response.ok) {
-            // Direct console.error is INTENTIONAL — operators alert on the
-            // `[postQuery.error]` prefix in browser console. Routing through
-            // an injected logger here would require a coordinated change to
-            // the alerting pipeline. Tracked as future work; the dual-channel
-            // alternative (logger + observability.captureException) is the
-            // production target. Never throw — fire-and-forget callers would
-            // kill Next.js router on unhandled rejection.
-            console.error(`[postQuery.error] ${response.status} ${response.statusText} for ${batch.queries.map((q) => q.model).join(',')}`);
+            // Build the typed AbloError for this HTTP failure (same code→class
+            // map the throwing paths use) so the log is tagged + carries a
+            // registry `code` (e.g. AbloAuthenticationError/session_expired on a
+            // 401) instead of a bare status. We deliberately DON'T throw —
+            // fire-and-forget callers would kill the Next.js router on an
+            // unhandled rejection — and still return empty slots, but the failure
+            // is now legible as an Ablo error. Direct console.error is
+            // INTENTIONAL: operators alert on the `[postQuery.error]` prefix.
+            let body = null;
+            try {
+                body = await response.clone().json();
+            }
+            catch {
+                // non-JSON error page — translateHttpError falls back to status text
+            }
+            const err = translateHttpError(response.status, body);
+            console.error(`[postQuery.error] ${err.type} ${err.code ?? response.status} for ` +
+                `${batch.queries.map((q) => q.model).join(',')}: ${err.message}`);
             return { results: batch.queries.map(() => []) };
         }
         const raw = await response.json();

package/dist/react/AbloProvider.d.ts

@@ -72,6 +72,31 @@ export interface AbloProviderProps<R extends SchemaRecord = SchemaRecord> {
      * same-origin session cookies.
      */
     apiKey?: string;
+    /**
+     * Static bearer auth token, sent as `Authorization: Bearer <token>` on the
+     * WebSocket upgrade + HTTP. For a token that must be refreshed (e.g. a
+     * short-lived JWT), prefer {@link getToken}.
+     */
+    authToken?: string | null;
+    /**
+     * Async resolver for a short-lived bearer token. Called once before the
+     * engine connects (so the first connection carries a fresh token) and then on
+     * a refresh interval ahead of expiry — each result is pushed via
+     * `engine.setAuthToken` without tearing down the connection. Wire this to
+     * a resolver that mints a short-lived session token (`ek_`/`rk_`) — e.g.
+     * `getSyncCapabilityToken` — or your own. Takes precedence over
+     * {@link authEndpoint}.
+     */
+    getToken?: () => Promise<string | null>;
+    /**
+     * Liveblocks/Stripe-style auth endpoint: a URL on YOUR backend that returns
+     * `{ token }` — the `ek_` ephemeral key your server minted for the logged-in
+     * user with `ablo.sessions.create({ user: { id } })`. The provider POSTs to it
+     * (with cookies) to fetch + refresh the bearer, so the browser carries no
+     * secret. Shorthand for a {@link getToken} that does the fetch; ignored when
+     * `getToken` is set.
+     */
+    authEndpoint?: string;
     /** Optional Zero-style custom mutators. */
     mutators?: MutatorDefs<Schema<R>>;
     /** Options forwarded to the internal `useMutators` call (e.g., `undoScope`). */

package/dist/react/AbloProvider.js

@@ -5,7 +5,7 @@ import { Ablo } from '../client/Ablo.js';
 import { createParticipantClaimId, parseParticipantTtlSeconds, resolveParticipantSyncGroups, } from '../sync/participants.js';
 import { SyncContext } from './context.js';
 import { AbloInternalContext } from './internalContext.js';
-import { AbloValidationError } from '../errors.js';
+import { AbloValidationError, AbloAuthenticationError } from '../errors.js';
 import { useSyncStatus } from './useSyncStatus.js';
 import { DefaultFallback } from './DefaultFallback.js';
 // ── Implementation ───────────────────────────────────────────────────
@@ -32,7 +32,7 @@ function createErrorEmitter() {
     };
 }
 export function AbloProvider(props) {
-    const { schema, url = 'wss://mesh.ablo.finance', userId, teamIds, apiKey, preventUnsavedChanges, onSessionExpired, onError, observability, logger, mutationExecutor, mutationDispatcher, sessionErrorDetector, onlineStatus, configOverrides, syncGroups, scope, bootstrapBaseUrl, maxPoolSize, persistence, bootstrapMode, fallback = _jsx(DefaultFallback, {}), children, } = props;
+    const { schema, url = 'wss://mesh.ablo.finance', userId, teamIds, apiKey, authToken, getToken, authEndpoint, preventUnsavedChanges, onSessionExpired, onError, observability, logger, mutationExecutor, mutationDispatcher, sessionErrorDetector, onlineStatus, configOverrides, syncGroups, scope, bootstrapBaseUrl, maxPoolSize, persistence, bootstrapMode, fallback = _jsx(DefaultFallback, {}), children, } = props;
     // Account scope is no longer accepted from props. The engine learns
     // it from auth (capability token) at bootstrap and we read it back
     // out of `_store.orgId` once `engine.ready()` resolves.
@@ -54,6 +54,25 @@ export function AbloProvider(props) {
     useEffect(() => {
         return errorEmitter.subscribe((err) => onErrorRef.current?.(err));
     }, [errorEmitter]);
+    // Stash the token resolver in a ref so a new function identity each render
+    // does not re-key (tear down) the engine. Read at fire time in the connect +
+    // refresh paths below — same `useEventCallback` idiom as `onError`. `getToken`
+    // wins; otherwise `authEndpoint` is fetched for `{ token }`.
+    const tokenFromEndpoint = authEndpoint
+        ? async () => {
+            const res = await fetch(authEndpoint, {
+                method: 'POST',
+                credentials: 'include',
+                headers: { 'Content-Type': 'application/json' },
+            });
+            if (!res.ok)
+                return null;
+            const body = (await res.json());
+            return body.token ?? null;
+        }
+        : undefined;
+    const getTokenRef = useRef(getToken ?? tokenFromEndpoint);
+    getTokenRef.current = getToken ?? tokenFromEndpoint;
     // ── Engine lifecycle keyed on (userId, url) ─────────────────────
     //
     // The engine rotates when either of these change. For everything
@@ -79,6 +98,7 @@ export function AbloProvider(props) {
             schema,
             ...(userId ? { user: { id: userId, teamIds } } : {}),
             apiKey,
+            ...(authToken ? { authToken } : {}),
             logger,
             observability,
             sessionErrorDetector,
@@ -121,6 +141,52 @@ export function AbloProvider(props) {
         // saves once `useAblo` exists.
         (async () => {
             try {
+                // Resolve a fresh bearer token BEFORE `ready()` (which connects —
+                // the engine is built with `autoStart: false`), so the first WS
+                // upgrade + bootstrap carry it. No race: nothing has connected yet.
+                const fetchToken = getTokenRef.current;
+                if (fetchToken) {
+                    const token = await fetchToken();
+                    if (isStale || abort.signal.aborted)
+                        return;
+                    if (token) {
+                        engine.setAuthToken(token);
+                    }
+                    else {
+                        // A configured `getToken` that resolves to falsy means "no active
+                        // session" — the session-token resolver (e.g. `getSyncCapabilityToken`)
+                        // returns null when logged out, the session hasn't hydrated, or the
+                        // mint endpoint rejects. Its contract is "the provider then surfaces
+                        // the usual unauthenticated path rather than connecting with a bad token."
+                        //
+                        // We MUST short-circuit here rather than fall through to
+                        // `engine.ready()`. On apps/web's identity path (org + user.id are
+                        // both supplied) `resolveParticipantIdentity` takes the
+                        // trust-the-caller Branch 3, which does NOT validate the (absent)
+                        // token — so init would proceed into `store.initialize()` and open
+                        // IndexedDB *before* any auth-bearing bootstrap/WS call. If storage
+                        // is at all wedged the no-session condition then surfaces only as an
+                        // opaque `IndexedDB "ablo_databases" open did not resolve within
+                        // 10000ms` stall, never the real auth error. Surface `session_expired`
+                        // explicitly and let the app redirect to sign-in.
+                        //
+                        // Unlike the server-detected `onSessionError` handler above, we do
+                        // NOT purge: nothing connected or wrote this mount, so any cached
+                        // IndexedDB belongs to a prior session and is reconciled by the next
+                        // valid bootstrap — purging here would drop a still-valid offline
+                        // queue on a merely transient null token.
+                        const authErr = new AbloAuthenticationError('No session token available — getToken() resolved to null. The ' +
+                            'session is missing or expired; sign in again.', { code: 'session_expired' });
+                        errorEmitter.emit(authErr);
+                        try {
+                            await onSessionExpired?.();
+                        }
+                        catch (hookErr) {
+                            errorEmitter.emit(hookErr);
+                        }
+                        return;
+                    }
+                }
                 await engine.ready();
                 if (isStale || abort.signal.aborted)
                     return;
@@ -146,6 +212,35 @@ export function AbloProvider(props) {
         // `mutationExecutor` identity change would destroy the WebSocket.
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [engineKey]);
+    // ── Bearer-token refresh ─────────────────────────────────────────
+    //
+    // Short-lived tokens (the sync-server JWT defaults to 15m) must be rolled
+    // before they expire or the next reconnect/HTTP call fails auth. Re-resolve
+    // ahead of expiry and push via `engine.setAuthToken`, which swaps the token
+    // on the live WebSocket + bootstrap header without tearing down the engine.
+    // Only runs when a `getToken` resolver is wired (cookie deployments skip it).
+    useEffect(() => {
+        const engine = engineState.engine;
+        if (!engine || !getTokenRef.current)
+            return;
+        // Comfortably inside the 15m JWT lifetime; a missed tick is recovered by
+        // the next one well before expiry.
+        const REFRESH_INTERVAL_MS = 10 * 60 * 1000;
+        const id = setInterval(() => {
+            void (async () => {
+                try {
+                    const token = await getTokenRef.current?.();
+                    if (token)
+                        engine.setAuthToken(token);
+                }
+                catch {
+                    // Transient (offline / session check). The next tick retries; the
+                    // engine keeps using the still-valid current token until then.
+                }
+            })();
+        }, REFRESH_INTERVAL_MS);
+        return () => clearInterval(id);
+    }, [engineState.engine]);
     // ── beforeunload + preventUnsavedChanges ─────────────────────────
     useEffect(() => {
         if (typeof window === 'undefined')

package/dist/react/ClientSideSuspense.d.ts

@@ -33,4 +33,4 @@ export interface ClientSideSuspenseProps {
     /** What to render once the subtree is cleared to render. */
     children: ReactNode;
 }
-export declare function ClientSideSuspense({ fallback, children }: ClientSideSuspenseProps): import("react/jsx-runtime").JSX.Element;
+export declare function ClientSideSuspense({ fallback, children }: ClientSideSuspenseProps): import("react").JSX.Element;

package/dist/react/DefaultFallback.d.ts

@@ -21,4 +21,4 @@
  * pass `fallback={null}`. Consumers who want to skip the gate entirely
  * pass `fallback="passthrough"`.
  */
-export declare function DefaultFallback(): import("react/jsx-runtime").JSX.Element;
+export declare function DefaultFallback(): import("react").JSX.Element;

package/dist/react/SyncGroupProvider.d.ts

@@ -4,7 +4,7 @@ export interface SyncGroupProviderProps {
     id: string;
     children: ReactNode;
 }
-export declare function SyncGroupProvider({ id, children }: SyncGroupProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function SyncGroupProvider({ id, children }: SyncGroupProviderProps): import("react").JSX.Element;
 /**
  * Returns the ID of the nearest `<SyncGroupProvider>`. Throws if
  * called outside one — sync-group awareness is mandatory by design,

package/dist/react/index.d.ts

@@ -13,9 +13,10 @@
  *     immediately. The provider-level `fallback` is the default path.
  *
  * Data hooks:
- *   useAblo((ablo) => ablo.tasks.retrieve(id)) — primary React read API
+ *   useAblo((ablo) => ablo.tasks.get(id))     — primary React read API (sync local snapshot)
  *   useAblo()                                  — typed client for callbacks/effects
- *                                                (reads: ablo.<model>.retrieve/list;
+ *                                                (sync local reads: ablo.<model>.get/getAll;
+ *                                                 async server reads: ablo.<model>.retrieve/list;
  *                                                 writes: ablo.<model>.create/update/delete)
  *   useMutators(defs, opts?)                   — Zero-style custom mutators
  *   useUndoScope(name)                         — per-surface undo/redo

package/dist/react/index.js

@@ -13,9 +13,10 @@
  *     immediately. The provider-level `fallback` is the default path.
  *
  * Data hooks:
- *   useAblo((ablo) => ablo.tasks.retrieve(id)) — primary React read API
+ *   useAblo((ablo) => ablo.tasks.get(id))     — primary React read API (sync local snapshot)
  *   useAblo()                                  — typed client for callbacks/effects
- *                                                (reads: ablo.<model>.retrieve/list;
+ *                                                (sync local reads: ablo.<model>.get/getAll;
+ *                                                 async server reads: ablo.<model>.retrieve/list;
  *                                                 writes: ablo.<model>.create/update/delete)
  *   useMutators(defs, opts?)                   — Zero-style custom mutators
  *   useUndoScope(name)                         — per-surface undo/redo

package/dist/react/useAblo.d.ts

@@ -45,11 +45,11 @@ export type UseAbloHydratedModelResult<T> = Omit<UseAbloModelResult<T>, 'data'>
  * // With Register augmentation (recommended):
  * const ablo = useAblo();
  * if (!ablo) return <Loading />;
- * const docs = await ablo.documents.load({ where: { id } });
+ * const doc = await ablo.documents.retrieve(id); // async server read
  *
- * // Reactive selector:
- * const doc = useAblo((ablo) => ablo.documents.retrieve(id)) ?? serverDoc;
- * const active = useAblo((ablo) => ablo.documents.claimState(id));
+ * // Reactive selector (sync local-graph snapshot):
+ * const doc = useAblo((ablo) => ablo.documents.get(id)) ?? serverDoc;
+ * const active = useAblo((ablo) => ablo.documents.claim.state(id));
  *
  * // Without augmentation, pass the schema generic:
  * const ablo = useAblo<(typeof schema)['models']>();

package/dist/react/useAblo.js

@@ -9,7 +9,7 @@ function readModelResult(engine, modelClient, id, initial) {
     if (!modelClient || id === undefined) {
         return { data: initial, claims: EMPTY_CLAIMS, claimed: false };
     }
-    const data = snapshotValue(modelClient.retrieve(id) ?? initial);
+    const data = snapshotValue(modelClient.get(id) ?? initial);
     const meta = getModelClientMeta(modelClient);
     const claims = meta && engine
         ? engine.intents.list({ model: meta.key, id })
@@ -29,7 +29,6 @@ export function useAblo(modelOrSelect, id, options) {
     const ctx = useContext(AbloInternalContext);
     const engine = ctx?.engine ?? null;
     const initial = options?.initial;
-    const hasSelection = modelOrSelect !== undefined;
     const isSelectorOnly = typeof modelOrSelect === 'function' && id === undefined;
     const modelClient = typeof modelOrSelect === 'function' && id !== undefined
         ? engine
@@ -38,14 +37,20 @@ export function useAblo(modelOrSelect, id, options) {
         : typeof modelOrSelect === 'function'
             ? undefined
             : modelOrSelect;
+    // Claims live on a non-MobX event emitter (engine.intents), so the useReactive
+    // reactions below cannot track them — we bridge changes through a setState bump.
+    // ONLY the model-row form (`id !== undefined`) actually reads claims, so gate the
+    // subscription on `id`. The selector-only form (`useAblo((a) => a.x.get/getAll)`)
+    // never reads claims; subscribing it to the workspace-global intent stream would
+    // re-render + double-compute it on every intent/presence delta anywhere (a real
+    // storm during AI editing / live collaboration) for a value that can't change.
     const [claimVersion, setClaimVersion] = useState(0);
     useEffect(() => {
-        if (!engine || !hasSelection)
+        if (!engine || id === undefined)
             return;
         return engine.intents.onChange(() => setClaimVersion((version) => version + 1));
-    }, [engine, hasSelection]);
+    }, [engine, id]);
     const selected = useReactive(() => {
-        void claimVersion;
         if (!engine || !isSelectorOnly || typeof modelOrSelect !== 'function') {
             return undefined;
         }

package/dist/react/useReactive.js

@@ -66,16 +66,29 @@ export function useReactive(compute, equals = defaultEquals) {
     const subscribeVersionRef = useRef(0);
     if (snapshotRef.current === null) {
         snapshotRef.current = { value: compute() };
-        computeRef.current = compute;
     }
     else if (computeRef.current !== compute) {
+        // `compute` is a fresh inline arrow at virtually every call site, so this
+        // branch runs on essentially every render. Reconcile the snapshot against
+        // the latest closure, but only force a re-subscription when the value
+        // ACTUALLY changed. For the dominant case (same observable source, new
+        // arrow identity, unchanged value) this avoids tearing down + recreating
+        // the MobX reaction — and its double-compute — on every render. A genuine
+        // source swap (a memoized compute closing over a new observable source)
+        // changes the value, which both updates the snapshot and bumps
+        // `subscribeVersion` so the reaction below re-subscribes and re-tracks the
+        // new source's observables.
         const next = compute();
         if (!equals(snapshotRef.current.value, next)) {
             snapshotRef.current = { value: next };
+            subscribeVersionRef.current++;
         }
-        computeRef.current = compute;
-        subscribeVersionRef.current++;
     }
+    // Point the long-lived reaction at the latest closure every render. The
+    // reaction expression reads `computeRef.current` at fire time, so it always
+    // runs the newest compute (and re-tracks its observables) even when we did
+    // not re-subscribe above.
+    computeRef.current = compute;
     const subscribeVersion = subscribeVersionRef.current;
     const subscribe = useCallback((onChange) => {
         return reaction(() => computeRef.current(), (next) => {

package/dist/schema/serialize.d.ts

@@ -8,7 +8,7 @@
  * This is the GraphQL `printSchema` / `buildSchema` model: one `Schema`
  * type, two representations. A hosted multi-tenant server obtains a tenant's
  * `Schema` by `parseSchema(json)` instead of an in-process import — the JSON
- * is what travels over the control plane (`ablo schema push`) and is stored
+ * is what travels over the control plane (`ablo push`) and is stored
  * per `(tenant, version)`.
  *
  * What round-trips:
@@ -62,7 +62,7 @@ export interface ModelJSON {
     readonly autoFill?: readonly AutoFillRule[];
     readonly requiredFields?: readonly string[];
 }
-/** The JSON form of a {@link Schema}. The `@ablo schema push` payload. */
+/** The JSON form of a {@link Schema}. The `ablo push` payload. */
 export interface SchemaJSON {
     readonly v: typeof SCHEMA_JSON_VERSION;
     readonly models: Record<string, ModelJSON>;
@@ -74,7 +74,7 @@ export interface SchemaJSON {
  * rebuild need. The result is plain data — `JSON.stringify`-safe.
  */
 export declare function toSchemaJSON(schema: Schema<SchemaRecord>): SchemaJSON;
-/** Serialize a `Schema` to a JSON string (the `ablo schema push` payload). */
+/** Serialize a `Schema` to a JSON string (the `ablo push` payload). */
 export declare function serializeSchema(schema: Schema<SchemaRecord>): string;
 /**
  * Reconstruct a working `Schema` from its JSON form. Validators are rebuilt

package/dist/schema/serialize.js

@@ -8,7 +8,7 @@
  * This is the GraphQL `printSchema` / `buildSchema` model: one `Schema`
  * type, two representations. A hosted multi-tenant server obtains a tenant's
  * `Schema` by `parseSchema(json)` instead of an in-process import — the JSON
- * is what travels over the control plane (`ablo schema push`) and is stored
+ * is what travels over the control plane (`ablo push`) and is stored
  * per `(tenant, version)`.
  *
  * What round-trips:
@@ -88,7 +88,7 @@ export function toSchemaJSON(schema) {
     }
     return { v: SCHEMA_JSON_VERSION, models, identityRoles: schema.identityRoles };
 }
-/** Serialize a `Schema` to a JSON string (the `ablo schema push` payload). */
+/** Serialize a `Schema` to a JSON string (the `ablo push` payload). */
 export function serializeSchema(schema) {
     return JSON.stringify(toSchemaJSON(schema));
 }

package/dist/sync/BootstrapHelper.js

@@ -3,7 +3,7 @@
  * Removed problematic caching that was serving stale data
  */
 import { getContext } from '../context.js';
-import { SyncSessionError, AbloConnectionError, translateHttpError } from '../errors.js';
+import { SyncSessionError, AbloConnectionError, translateHttpError, toAbloError, isRetryableCode } from '../errors.js';
 // SyncObservability replaced by getContext().observability
 import { parseBootstrapResponse } from './schemas.js';
 export class BootstrapHelper {
@@ -60,7 +60,9 @@ export class BootstrapHelper {
     createTimeoutPromise(ms, operation) {
         return new Promise((_, reject) => {
             setTimeout(() => {
-                reject(new Error(`Bootstrap ${operation} timed out after ${ms}ms`));
+                reject(new AbloConnectionError(`Bootstrap ${operation} timed out after ${ms}ms`, {
+                    code: 'bootstrap_fetch_timeout',
+                }));
             }, ms);
         });
     }
@@ -138,6 +140,17 @@ export class BootstrapHelper {
                     });
                     throw error;
                 }
+                // Don't retry NON-retryable errors. A 401/403/4xx auth or client error
+                // (api_key_required, jwt_issuer_untrusted, …) will NOT succeed by
+                // repeating the same request with the same credential — retrying just
+                // hammers the server and floods the console with doomed requests. Only
+                // transient failures (5xx, 429, timeouts, network blips, or an
+                // unclassified error with no code) flow through to the retry/backoff.
+                const ablo = toAbloError(error);
+                if (ablo.code && !isRetryableCode(ablo.code)) {
+                    getContext().observability.breadcrumb('Bootstrap non-retryable error — failing fast', 'sync.bootstrap', 'warning', { code: ablo.code, httpStatus: ablo.httpStatus });
+                    throw ablo;
+                }
                 lastError = error;
                 getContext().observability.breadcrumb('Bootstrap fetch failed', 'sync.bootstrap', 'warning', {
                     attempt: attempt + 1,
@@ -157,7 +170,11 @@ export class BootstrapHelper {
             });
             return cached;
         }
-        throw lastError || new Error('Failed to fetch bootstrap data');
+        throw lastError
+            ? toAbloError(lastError)
+            : new AbloConnectionError('Failed to fetch bootstrap data', {
+                code: 'bootstrap_fetch_timeout',
+            });
     }
     /**
      * Fetch bootstrap with ETag, returning 304 hints
@@ -198,17 +215,6 @@ export class BootstrapHelper {
             return { notModified: true, etag };
         }
         if (!res.ok) {
-            // Check for session/auth errors - these should redirect to login
-            if (SyncSessionError.isSessionErrorResponse(res.status)) {
-                let body = '';
-                try {
-                    body = await res.text();
-                }
-                catch {
-                    // Ignore body parsing errors
-                }
-                throw new SyncSessionError(body || `Session expired or invalid: ${res.status}`, res.status);
-            }
             const bodyText = await res.text().catch(() => '');
             let parsed = bodyText;
             if (bodyText) {
@@ -219,7 +225,21 @@ export class BootstrapHelper {
                     // Keep as string.
                 }
             }
-            throw translateHttpError(res.status, parsed || `Bootstrap fetch failed: ${res.status} ${res.statusText}`, res.headers.get('x-request-id') ?? undefined);
+            // Translate the canonical envelope FIRST so the server's specific code +
+            // message survive (e.g. `api_key_required`, `jwt_issuer_untrusted`).
+            const translated = translateHttpError(res.status, parsed || `Bootstrap fetch failed: ${res.status} ${res.statusText}`, res.headers.get('x-request-id') ?? undefined);
+            // Only a genuine session/JWT EXPIRY — or a bare auth failure carrying no
+            // structured code — should drive the sign-in redirect. A specific auth
+            // code like `api_key_required` is NOT an expired session: re-logging-in
+            // mints the same credential and loops. Surface it as its real typed error
+            // instead of a `session_expired` wrapping the stringified body.
+            if (translated.code === 'session_expired' ||
+                translated.code === 'jwt_expired' ||
+                ((res.status === 401 || res.status === 403) &&
+                    translated.code === undefined)) {
+                throw new SyncSessionError(translated.message, res.status);
+            }
+            throw translated;
         }
         const rawJson = await res.json();
         const data = parseBootstrapResponse(rawJson);
@@ -275,17 +295,6 @@ export class BootstrapHelper {
         }
         clearTimeout(timeoutId);
         if (!response.ok) {
-            // Check for session/auth errors - these should redirect to login
-            if (SyncSessionError.isSessionErrorResponse(response.status)) {
-                let body = '';
-                try {
-                    body = await response.text();
-                }
-                catch {
-                    // Ignore body parsing errors
-                }
-                throw new SyncSessionError(body || `Session expired or invalid: ${response.status}`, response.status);
-            }
             const bodyText = await response.text().catch(() => '');
             let parsed = bodyText;
             if (bodyText) {
@@ -296,7 +305,17 @@ export class BootstrapHelper {
                     // Keep as string.
                 }
             }
-            throw translateHttpError(response.status, parsed || `Bootstrap fetch failed: ${response.status} ${response.statusText}`, response.headers.get('x-request-id') ?? undefined);
+            // Same code-aware handling as the primary bootstrap fetch: preserve the
+            // server's specific code/message; only a genuine expiry (or a bare,
+            // code-less auth failure) drives the sign-in redirect.
+            const translated = translateHttpError(response.status, parsed || `Bootstrap fetch failed: ${response.status} ${response.statusText}`, response.headers.get('x-request-id') ?? undefined);
+            if (translated.code === 'session_expired' ||
+                translated.code === 'jwt_expired' ||
+                ((response.status === 401 || response.status === 403) &&
+                    translated.code === undefined)) {
+                throw new SyncSessionError(translated.message, response.status);
+            }
+            throw translated;
         }
         const rawJson = await response.json();
         const data = parseBootstrapResponse(rawJson);

package/dist/sync/ConnectionManager.d.ts

@@ -34,7 +34,7 @@
  *      instead of hard-reloading an already-offline browser.
  */
 import { type ProbeResult } from './NetworkProbe.js';
-export type ConnectionState = 'connected' | 'offline' | 'probing_network' | 'validating_session' | 'reconnecting' | 'backoff' | 'waiting_for_network' | 'session_expired';
+export type ConnectionState = 'connected' | 'offline' | 'probing_network' | 'validating_session' | 'reconnecting' | 'backoff' | 'waiting_for_network' | 'auth_blocked' | 'session_expired';
 export type ConnectionEvent = {
     type: 'NETWORK_LOST';
 } | {
@@ -52,6 +52,8 @@ export type ConnectionEvent = {
 } | {
     type: 'PROBE_SUCCESS';
     sessionValid: boolean;
+} | {
+    type: 'PROBE_AUTH_BLOCKED';
 } | {
     type: 'PROBE_FAILED';
 } | {

package/dist/sync/ConnectionManager.js

@@ -162,6 +162,8 @@ export class ConnectionManager {
                 switch (event.type) {
                     case 'PROBE_SUCCESS':
                         return event.sessionValid ? 'reconnecting' : 'session_expired';
+                    case 'PROBE_AUTH_BLOCKED':
+                        return 'auth_blocked';
                     case 'PROBE_FAILED':
                         return 'waiting_for_network';
                     case 'NETWORK_LOST':
@@ -185,6 +187,8 @@ export class ConnectionManager {
                 switch (event.type) {
                     case 'PROBE_SUCCESS':
                         return event.sessionValid ? 'reconnecting' : 'session_expired';
+                    case 'PROBE_AUTH_BLOCKED':
+                        return 'auth_blocked';
                     case 'NETWORK_LOST':
                         return 'offline';
                     default:
@@ -227,6 +231,25 @@ export class ConnectionManager {
                     default:
                         return null;
                 }
+            case 'auth_blocked':
+                // Reachable, but the data-plane rejected the credential (non-retryable,
+                // non-expiry — e.g. api_key_required, jwt_issuer_untrusted). Don't
+                // auto-reconnect and don't sign out. Allow a manual retry or a
+                // tab-focus / network-return re-probe (e.g. after a server deploy);
+                // a network drop parks offline; a genuine session error still expires.
+                switch (event.type) {
+                    case 'MANUAL_RETRY':
+                    case 'TAB_VISIBLE':
+                    case 'NETWORK_ONLINE':
+                        return 'probing_network';
+                    case 'NETWORK_LOST':
+                        return 'offline';
+                    case 'WS_SESSION_ERROR':
+                    case 'BOOTSTRAP_FAILED_SESSION':
+                        return 'session_expired';
+                    default:
+                        return null;
+                }
             case 'session_expired':
                 return null; // terminal
             default:
@@ -255,6 +278,16 @@ export class ConnectionManager {
             case 'backoff':
                 this.scheduleBackoff();
                 break;
+            case 'auth_blocked':
+                // Stop — reachable but the credential was rejected (e.g.
+                // api_key_required / jwt_issuer_untrusted from the data plane). Neither
+                // reconnecting nor re-auth fixes it. Drop the socket and wait for a
+                // manual retry / re-probe. Crucially NOT onSessionExpired (no sign-out)
+                // and NOT a reconnect — that's the whole point of this state.
+                this.clearBackoffTimer();
+                this.callbacks?.onDisconnectWebSocket();
+                getContext().observability.breadcrumb('Auth blocked — reachable but credential rejected; not reconnecting or signing out', 'sync.offline', 'error');
+                break;
             case 'session_expired':
                 this.clearBackoffTimer();
                 this.callbacks?.onDisconnectWebSocket();
@@ -270,7 +303,10 @@ export class ConnectionManager {
             runInAction(() => {
                 this.lastProbeResult = result;
             });
-            if (result.reachable) {
+            if (result.authBlocked) {
+                this.send({ type: 'PROBE_AUTH_BLOCKED' });
+            }
+            else if (result.reachable) {
                 this.send({ type: 'PROBE_SUCCESS', sessionValid: result.sessionValid ?? true });
             }
             else {

package/dist/sync/HydrationCoordinator.js

@@ -20,6 +20,7 @@
  * models accessed by id/where after the engine is ready.
  */
 import { ModelScope } from '../ObjectPool.js';
+import { AbloValidationError } from '../errors.js';
 import { postQuery } from '../query/client.js';
 export class HydrationCoordinator {
     opts;
@@ -53,8 +54,8 @@ export class HydrationCoordinator {
         const ModelClass = this.opts.registry.getModelByName(typename)
             ?? this.opts.registry.getModelByName(modelName);
         if (!ModelClass) {
-            throw new Error(`HydrationCoordinator.fetch: unknown model "${modelName}" — ` +
-                `not registered in the schema.`);
+            throw new AbloValidationError(`HydrationCoordinator.fetch: unknown model "${modelName}" — ` +
+                `not registered in the schema.`, { code: 'model_not_registered' });
         }
         const clauses = normalizeWhere(options?.where);
         const queryKey = stableKey(modelName, clauses, options?.orderBy, options?.limit);