@abloatai/ablo 0.8.0 → 0.9.1

package/dist/source/migrations.js

@@ -0,0 +1,39 @@
+/**
+ * The table-creation SQL every ORM adapter ships for its OWN infrastructure tables —
+ * `ablo_idempotency` (dedupe by clientTxId) and `ablo_outbox` (transactional
+ * outbox the `events()` feed reads). Defined ONCE here so the Prisma adapter, the
+ * Drizzle adapter, and `ablo migrate` can never disagree on the shape (they used
+ * to inline their own copies, which had already drifted in whitespace).
+ *
+ * These are NOT model tables and are NOT emitted by the hosted provisioner
+ * (`generateProvisionPlan`) — the hosted path uses `sync_deltas` directly. They
+ * exist only on a customer's own database in Data Source mode.
+ */
+/** Canonical adapter-owned table-creation SQL. Idempotent (`IF NOT EXISTS`). */
+export function adapterTableMigrations() {
+    return [
+        {
+            name: 'ablo_idempotency',
+            up: `CREATE TABLE IF NOT EXISTS ablo_idempotency (
+  client_tx_id TEXT PRIMARY KEY,
+  response     JSONB NOT NULL,
+  created_at   TIMESTAMPTZ NOT NULL DEFAULT now()
+);`,
+        },
+        {
+            name: 'ablo_outbox',
+            up: `CREATE TABLE IF NOT EXISTS ablo_outbox (
+  cursor          BIGSERIAL PRIMARY KEY,
+  id              TEXT NOT NULL UNIQUE,
+  model           TEXT NOT NULL,
+  entity_id       TEXT NOT NULL,
+  type            TEXT NOT NULL,
+  data            JSONB,
+  organization_id TEXT,
+  client_tx_id    TEXT,
+  occurred_at     BIGINT,
+  created_at      TIMESTAMPTZ NOT NULL DEFAULT now()
+);`,
+        },
+    ];
+}

package/dist/source/next.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Next.js App Router adapter for Data Source. The core `dataSource()` already
+ * returns a Web-standard `(Request) => Promise<Response>`, which Next App Router
+ * accepts directly — so this is pure ergonomics: wire an ORM `adapter` in via the
+ * bridge and hand back a named `POST` so the customer's route file is the minimum:
+ *
+ *   // app/api/ablo/source/route.ts
+ *   import { dataSourceNext } from '@abloatai/ablo/source/next';
+ *   import { prismaDataSource } from '@abloatai/ablo/source';
+ *   import { schema } from '@/ablo/schema';
+ *   import { prisma } from '@/lib/prisma';
+ *
+ *   export const { POST } = dataSourceNext({
+ *     schema,
+ *     apiKey: process.env.ABLO_API_KEY!,
+ *     adapter: prismaDataSource(prisma, schema),
+ *   });
+ *
+ * Day-one scope: Next + the adapter form only. Hand-written handlers use the core
+ * `dataSource()` directly; Hono/Express are the same one-liner and land on demand
+ * — not pre-built.
+ */
+import type { SchemaRecord } from '../schema/schema.js';
+import { type DataSourceOptions } from './index.js';
+/**
+ * Next options ARE the core options — the `adapter` field lives on the core
+ * handler now, so there is no bridging, no cast, and no per-model-typed boundary
+ * at the call site. Pass `{ schema, apiKey, adapter }`.
+ */
+export type DataSourceNextOptions<S extends SchemaRecord, TAuth = unknown> = DataSourceOptions<S, TAuth>;
+export declare function dataSourceNext<const S extends SchemaRecord, TAuth = unknown>(options: DataSourceNextOptions<S, TAuth>): {
+    readonly POST: (request: Request) => Promise<Response>;
+};

package/dist/source/next.js

@@ -0,0 +1,26 @@
+/**
+ * Next.js App Router adapter for Data Source. The core `dataSource()` already
+ * returns a Web-standard `(Request) => Promise<Response>`, which Next App Router
+ * accepts directly — so this is pure ergonomics: wire an ORM `adapter` in via the
+ * bridge and hand back a named `POST` so the customer's route file is the minimum:
+ *
+ *   // app/api/ablo/source/route.ts
+ *   import { dataSourceNext } from '@abloatai/ablo/source/next';
+ *   import { prismaDataSource } from '@abloatai/ablo/source';
+ *   import { schema } from '@/ablo/schema';
+ *   import { prisma } from '@/lib/prisma';
+ *
+ *   export const { POST } = dataSourceNext({
+ *     schema,
+ *     apiKey: process.env.ABLO_API_KEY!,
+ *     adapter: prismaDataSource(prisma, schema),
+ *   });
+ *
+ * Day-one scope: Next + the adapter form only. Hand-written handlers use the core
+ * `dataSource()` directly; Hono/Express are the same one-liner and land on demand
+ * — not pre-built.
+ */
+import { dataSource } from './index.js';
+export function dataSourceNext(options) {
+    return { POST: dataSource(options) };
+}

package/dist/sync/BootstrapHelper.d.ts

@@ -61,7 +61,13 @@ export interface BootstrapOptions {
      * old clients that don't send a models param).
      */
     instantModels?: string[];
+    /**
+     * Shared SDK credential getter. Preferred over `setAuthToken`; read at
+     * request time so token refreshes apply without recreating BootstrapHelper.
+     */
+    getAuthToken?: AuthTokenGetter;
 }
+import { type AuthTokenGetter } from '../auth/credentialSource.js';
 import { type ValidatedServerDelta } from './schemas.js';
 export declare class BootstrapHelper {
     private options;
@@ -74,6 +80,10 @@ export declare class BootstrapHelper {
      */
     setCacheScope(cacheScope: string): void;
     setSyncGroups(syncGroups: readonly string[] | undefined): void;
+    /**
+     * Compatibility setter for direct BootstrapHelper users. The SDK-owned
+     * `Ablo()` path passes `getAuthToken` and does not mutate this helper.
+     */
     setAuthToken(authToken: string | undefined): void;
     /**
      * Create a promise that rejects after a timeout

package/dist/sync/BootstrapHelper.js

@@ -4,6 +4,7 @@
  */
 import { getContext } from '../context.js';
 import { SyncSessionError, AbloConnectionError, translateHttpError, toAbloError, isRetryableCode } from '../errors.js';
+import { withAuthHeaders } from '../auth/credentialSource.js';
 // SyncObservability replaced by getContext().observability
 import { parseBootstrapResponse } from './schemas.js';
 export class BootstrapHelper {
@@ -46,6 +47,10 @@ export class BootstrapHelper {
     setSyncGroups(syncGroups) {
         this.options.syncGroups = [...(syncGroups ?? [])];
     }
+    /**
+     * Compatibility setter for direct BootstrapHelper users. The SDK-owned
+     * `Ablo()` path passes `getAuthToken` and does not mutate this helper.
+     */
     setAuthToken(authToken) {
         if (!authToken) {
             delete this.options.authToken;
@@ -197,15 +202,11 @@ export class BootstrapHelper {
         // conditional revalidation (If-None-Match) implement it at their own
         // level where they own the cache-key namespace. The 304 branch below
         // remains defensively in place for when a caller enables revalidation.
-        const headers = { 'Content-Type': 'application/json' };
-        if (this.options.authToken) {
-            headers.Authorization = `Bearer ${this.options.authToken}`;
-        }
+        const headers = withAuthHeaders(this.options.getAuthToken, { 'Content-Type': 'application/json' }, this.options.authToken);
         this.abortController = new AbortController();
         const res = await fetch(url, {
             method: 'GET',
             headers,
-            credentials: 'include',
             signal: this.abortController.signal,
         });
         const etag = res.headers.get('ETag');
@@ -272,15 +273,11 @@ export class BootstrapHelper {
         try {
             response = await fetch(url, {
                 method: 'GET',
-                headers: {
+                headers: withAuthHeaders(this.options.getAuthToken, {
                     'Content-Type': 'application/json',
                     'Cache-Control': 'no-cache, no-store, must-revalidate',
                     Pragma: 'no-cache',
-                    ...(this.options.authToken
-                        ? { Authorization: `Bearer ${this.options.authToken}` }
-                        : {}),
-                },
-                credentials: 'include',
+                }, this.options.authToken),
                 signal: this.abortController.signal,
                 cache: 'no-store', // Force browser to not cache
             });
@@ -337,10 +334,9 @@ export class BootstrapHelper {
         const url = `${this.options.baseUrl}/sync/entity/${modelName}/${id}`;
         const response = await fetch(url, {
             method: 'GET',
-            headers: {
+            headers: withAuthHeaders(this.options.getAuthToken, {
                 'Content-Type': 'application/json',
-            },
-            credentials: 'include',
+            }, this.options.authToken),
         });
         if (response.status === 404) {
             return null;
@@ -436,7 +432,6 @@ export class BootstrapHelper {
         try {
             const response = await fetch(`${this.options.baseUrl}/health`, {
                 method: 'GET',
-                credentials: 'include',
                 signal: AbortSignal.timeout(5000),
                 cache: 'no-store',
             });

package/dist/sync/ConnectionManager.d.ts

@@ -34,7 +34,8 @@
  *      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' | 'auth_blocked' | 'session_expired';
+import type { AuthTokenGetter } from '../auth/credentialSource.js';
+export type ConnectionState = 'connected' | 'offline' | 'probing_network' | 'validating_session' | 'refreshing_credential' | 'reconnecting' | 'backoff' | 'waiting_for_network' | 'auth_blocked' | 'session_expired';
 export type ConnectionEvent = {
     type: 'NETWORK_LOST';
 } | {
@@ -54,8 +55,18 @@ export type ConnectionEvent = {
     sessionValid: boolean;
 } | {
     type: 'PROBE_AUTH_BLOCKED';
+}
+/** The probe saw an expired ephemeral access key (`access_credential_expiry`).
+ *  Recoverable: re-mint a fresh `ek_`/`rk_` and re-probe — never a sign-out. */
+ | {
+    type: 'PROBE_CREDENTIAL_STALE';
 } | {
     type: 'PROBE_FAILED';
+}
+/** A fresh access credential is available (the re-mint succeeded, or one was
+ *  pushed in via `setAuthToken`). Re-probe so a parked connection picks it up. */
+ | {
+    type: 'CREDENTIAL_REFRESHED';
 } | {
     type: 'RECONNECT_SUCCESS';
 } | {
@@ -70,6 +81,20 @@ export type ConnectionEvent = {
 export interface ConnectionCallbacks {
     /** Run bootstrap + WebSocket reconnect. Returns the outcome. */
     onReconnect: () => Promise<'success' | 'session_error' | 'network_error'>;
+    /**
+     * Re-mint the short-lived access credential (the Stripe-style `ek_`/`rk_`)
+     * and push it into the credential source, then report the outcome. Invoked
+     * on `refreshing_credential` — i.e. when a probe found the access key stale
+     * (`PROBE_CREDENTIAL_STALE`). Mirrors the `getToken` contract:
+     *   - `'refreshed'`     → a fresh credential is in place; re-probe & reconnect.
+     *   - `'session_error'` → the LONG-LIVED login is gone (mint returned null →
+     *                          401/403); terminal → sign out.
+     *   - `'network_error'` → couldn't reach the mint endpoint (offline/5xx/throw);
+     *                          transient → back off and retry, never sign out.
+     * Optional: a deployment with no re-mint path (e.g. a static `apiKey`) omits
+     * it, and the FSM falls back to a plain re-probe.
+     */
+    onRefreshCredential?: () => Promise<'refreshed' | 'session_error' | 'network_error'>;
     /** Called when the session is confirmed expired — route to signin. */
     onSessionExpired: () => void;
     /** Called to tear down the WebSocket when entering a dead state. */
@@ -90,6 +115,12 @@ export interface ConnectionManagerOptions {
      * default of `probeNetwork`.
      */
     baseUrl?: string;
+    /**
+     * Current bearer credential for authenticated probes. Read lazily so token
+     * refreshes pushed through `Ablo.setAuthToken()` are used by the next probe
+     * without recreating the manager.
+     */
+    getAuthToken?: AuthTokenGetter;
     /** Override retry ceilings / jitter. Production should leave defaults. */
     backoff?: Partial<typeof DEFAULT_BACKOFF>;
 }
@@ -109,8 +140,12 @@ export declare class ConnectionManager {
     private debounceTimer;
     private watchdogTimer;
     private stuckCycles;
+    /** Consecutive access-key re-mints in the current recovery cycle; reset on
+     *  reaching `connected`. See {@link MAX_CREDENTIAL_REFRESH_ATTEMPTS}. */
+    private credentialRefreshAttempts;
     private disposed;
     private readonly baseUrl?;
+    private readonly getAuthToken?;
     private readonly backoff;
     private handleBrowserOnline;
     private handleBrowserOffline;
@@ -122,6 +157,25 @@ export declare class ConnectionManager {
     private transition;
     private onEnterState;
     private runProbe;
+    /**
+     * Re-mint the short-lived access key on `refreshing_credential`. Delegates to
+     * the `onRefreshCredential` callback (which mints a fresh `ek_`/`rk_` from the
+     * still-valid login and pushes it into the credential source) and maps its
+     * tri-state outcome onto the FSM:
+     *   - `refreshed`     → `CREDENTIAL_REFRESHED` → re-probe & reconnect.
+     *   - `session_error` → `BOOTSTRAP_FAILED_SESSION` → sign out (login is gone).
+     *   - `network_error` → `RECONNECT_FAILED` → back off & retry (never sign out).
+     *
+     * A bounded attempt counter guards against a hot loop where the server keeps
+     * reporting the key stale even after a "successful" re-mint (e.g. a clock skew
+     * or a mint that returns an already-rejected key): after
+     * `MAX_CREDENTIAL_REFRESH_ATTEMPTS` we fall through to `auth_blocked` (stop,
+     * no sign-out) rather than spin. The counter resets once we reach `connected`.
+     *
+     * When no refresher is wired (e.g. a static `apiKey` deployment), we re-probe
+     * directly — the credential source's own scheduler owns refresh there.
+     */
+    private runRefreshCredential;
     private runReconnect;
     private scheduleBackoff;
     private setupBrowserListeners;

package/dist/sync/ConnectionManager.js

@@ -46,6 +46,10 @@ const DEFAULT_BACKOFF = {
 const ONLINE_DEBOUNCE_MS = 500;
 const WATCHDOG_INTERVAL_MS = 30_000;
 const MAX_STUCK_CYCLES_BEFORE_RELOAD = 6;
+/** Cap on consecutive access-key re-mints before giving up to `auth_blocked`.
+ *  Stops a hot loop if the server keeps reporting the key stale even after a
+ *  "successful" re-mint (clock skew, a mint returning an already-rejected key). */
+const MAX_CREDENTIAL_REFRESH_ATTEMPTS = 3;
 // ─── ConnectionManager ────────────────────────────────────────────────────
 export class ConnectionManager {
     // Observable state
@@ -59,14 +63,19 @@ export class ConnectionManager {
     debounceTimer = null;
     watchdogTimer = null;
     stuckCycles = 0;
+    /** Consecutive access-key re-mints in the current recovery cycle; reset on
+     *  reaching `connected`. See {@link MAX_CREDENTIAL_REFRESH_ATTEMPTS}. */
+    credentialRefreshAttempts = 0;
     disposed = false;
     baseUrl;
+    getAuthToken;
     backoff;
     handleBrowserOnline = null;
     handleBrowserOffline = null;
     handleVisibilityChange = null;
     constructor(options = {}) {
         this.baseUrl = options.baseUrl;
+        this.getAuthToken = options.getAuthToken;
         this.backoff = { ...DEFAULT_BACKOFF, ...(options.backoff ?? {}) };
         makeAutoObservable(this, {}, { autoBind: true });
     }
@@ -151,6 +160,7 @@ export class ConnectionManager {
                     case 'MANUAL_RETRY':
                     case 'TAB_VISIBLE':
                     case 'WS_HANDSHAKE_FAILED':
+                    case 'CREDENTIAL_REFRESHED':
                         return 'probing_network';
                     case 'WS_SESSION_ERROR':
                     case 'BOOTSTRAP_FAILED_SESSION':
@@ -162,6 +172,9 @@ export class ConnectionManager {
                 switch (event.type) {
                     case 'PROBE_SUCCESS':
                         return event.sessionValid ? 'reconnecting' : 'session_expired';
+                    case 'PROBE_CREDENTIAL_STALE':
+                        // Access key expired but the login is fine — re-mint, don't sign out.
+                        return 'refreshing_credential';
                     case 'PROBE_AUTH_BLOCKED':
                         return 'auth_blocked';
                     case 'PROBE_FAILED':
@@ -177,6 +190,7 @@ export class ConnectionManager {
                     case 'TAB_VISIBLE':
                     case 'MANUAL_RETRY':
                     case 'BACKOFF_ELAPSED':
+                    case 'CREDENTIAL_REFRESHED':
                         return 'probing_network';
                     case 'NETWORK_LOST':
                         return 'offline';
@@ -187,6 +201,8 @@ export class ConnectionManager {
                 switch (event.type) {
                     case 'PROBE_SUCCESS':
                         return event.sessionValid ? 'reconnecting' : 'session_expired';
+                    case 'PROBE_CREDENTIAL_STALE':
+                        return 'refreshing_credential';
                     case 'PROBE_AUTH_BLOCKED':
                         return 'auth_blocked';
                     case 'NETWORK_LOST':
@@ -194,6 +210,31 @@ export class ConnectionManager {
                     default:
                         return null;
                 }
+            case 'refreshing_credential':
+                // Re-minting the short-lived access key (the Stripe-style `ek_`/`rk_`).
+                // The login is presumed valid; this is NOT a sign-out state.
+                switch (event.type) {
+                    case 'CREDENTIAL_REFRESHED':
+                        // Fresh key in hand — re-probe so we reconnect with it.
+                        return 'probing_network';
+                    case 'BOOTSTRAP_FAILED_SESSION':
+                        // The re-mint hit a genuine 401/403: the long-lived login itself is
+                        // gone. THIS is the only path from here to sign-out.
+                        return 'session_expired';
+                    case 'RECONNECT_FAILED':
+                        // Couldn't reach the mint endpoint (offline/5xx/throw) — transient.
+                        // Back off and retry; never sign out for a network failure.
+                        return 'backoff';
+                    case 'PROBE_AUTH_BLOCKED':
+                        // Bounded-attempt fallback: the key keeps coming back stale even
+                        // after re-mint (see runRefreshCredential's attempt guard). Stop
+                        // looping without signing out.
+                        return 'auth_blocked';
+                    case 'NETWORK_LOST':
+                        return 'offline';
+                    default:
+                        return null;
+                }
             case 'reconnecting':
                 switch (event.type) {
                     case 'RECONNECT_SUCCESS':
@@ -218,10 +259,11 @@ export class ConnectionManager {
                         return 'probing_network';
                     case 'NETWORK_ONLINE':
                     case 'TAB_VISIBLE':
-                        // Network came back while we were waiting out a backoff
-                        // delay — jump straight to probing instead of waiting the
-                        // full exponential interval. Fixes the "doesn't retrigger
-                        // when internet comes back" bug.
+                    case 'CREDENTIAL_REFRESHED':
+                        // Network came back (or a fresh credential arrived) while we were
+                        // waiting out a backoff delay — jump straight to probing instead of
+                        // waiting the full exponential interval. Fixes the "doesn't
+                        // retrigger when internet comes back" bug.
                         return 'probing_network';
                     case 'NETWORK_LOST':
                         return 'offline';
@@ -235,12 +277,14 @@ export class ConnectionManager {
                 // 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.
+                // tab-focus / network-return / fresh-credential re-probe (e.g. after a
+                // server deploy or an out-of-band re-mint); a network drop parks
+                // offline; a genuine session error still expires.
                 switch (event.type) {
                     case 'MANUAL_RETRY':
                     case 'TAB_VISIBLE':
                     case 'NETWORK_ONLINE':
+                    case 'CREDENTIAL_REFRESHED':
                         return 'probing_network';
                     case 'NETWORK_LOST':
                         return 'offline';
@@ -261,6 +305,9 @@ export class ConnectionManager {
         switch (state) {
             case 'connected':
                 this.clearBackoffTimer();
+                runInAction(() => {
+                    this.credentialRefreshAttempts = 0;
+                });
                 break;
             case 'offline':
                 this.clearBackoffTimer();
@@ -275,6 +322,9 @@ export class ConnectionManager {
             case 'reconnecting':
                 this.runReconnect();
                 break;
+            case 'refreshing_credential':
+                this.runRefreshCredential();
+                break;
             case 'backoff':
                 this.scheduleBackoff();
                 break;
@@ -299,24 +349,108 @@ export class ConnectionManager {
     // ── Async operations ─────────────────────────────────────────────────
     async runProbe() {
         try {
-            const result = await probeNetwork(this.baseUrl);
+            const result = await probeNetwork({
+                baseUrl: this.baseUrl,
+                getAuthToken: this.getAuthToken,
+            });
             runInAction(() => {
                 this.lastProbeResult = result;
             });
-            if (result.authBlocked) {
-                this.send({ type: 'PROBE_AUTH_BLOCKED' });
-            }
-            else if (result.reachable) {
-                this.send({ type: 'PROBE_SUCCESS', sessionValid: result.sessionValid ?? true });
-            }
-            else {
-                this.send({ type: 'PROBE_FAILED' });
+            // One probe outcome → one event. Exhaustive over ProbeOutcome so a new
+            // outcome can't be silently dropped.
+            switch (result.outcome) {
+                case 'reachable':
+                    this.send({ type: 'PROBE_SUCCESS', sessionValid: true });
+                    break;
+                case 'session_expired':
+                    // Genuine login expiry — terminal. (PROBE_SUCCESS with
+                    // sessionValid:false routes to session_expired in the FSM.)
+                    this.send({ type: 'PROBE_SUCCESS', sessionValid: false });
+                    break;
+                case 'credential_stale':
+                    // Access key expired but the login is fine — re-mint, don't sign out.
+                    this.send({ type: 'PROBE_CREDENTIAL_STALE' });
+                    break;
+                case 'auth_blocked':
+                    this.send({ type: 'PROBE_AUTH_BLOCKED' });
+                    break;
+                case 'unreachable':
+                    this.send({ type: 'PROBE_FAILED' });
+                    break;
+                default: {
+                    const _exhaustive = result.outcome;
+                    void _exhaustive;
+                    this.send({ type: 'PROBE_FAILED' });
+                }
             }
         }
         catch {
             this.send({ type: 'PROBE_FAILED' });
         }
     }
+    /**
+     * Re-mint the short-lived access key on `refreshing_credential`. Delegates to
+     * the `onRefreshCredential` callback (which mints a fresh `ek_`/`rk_` from the
+     * still-valid login and pushes it into the credential source) and maps its
+     * tri-state outcome onto the FSM:
+     *   - `refreshed`     → `CREDENTIAL_REFRESHED` → re-probe & reconnect.
+     *   - `session_error` → `BOOTSTRAP_FAILED_SESSION` → sign out (login is gone).
+     *   - `network_error` → `RECONNECT_FAILED` → back off & retry (never sign out).
+     *
+     * A bounded attempt counter guards against a hot loop where the server keeps
+     * reporting the key stale even after a "successful" re-mint (e.g. a clock skew
+     * or a mint that returns an already-rejected key): after
+     * `MAX_CREDENTIAL_REFRESH_ATTEMPTS` we fall through to `auth_blocked` (stop,
+     * no sign-out) rather than spin. The counter resets once we reach `connected`.
+     *
+     * When no refresher is wired (e.g. a static `apiKey` deployment), we re-probe
+     * directly — the credential source's own scheduler owns refresh there.
+     */
+    async runRefreshCredential() {
+        if (this.credentialRefreshAttempts >= MAX_CREDENTIAL_REFRESH_ATTEMPTS) {
+            getContext().logger.warn('[ConnectionManager] Access key still stale after repeated re-mints — stopping', { attempts: this.credentialRefreshAttempts });
+            runInAction(() => {
+                this.credentialRefreshAttempts = 0;
+            });
+            this.send({ type: 'PROBE_AUTH_BLOCKED' });
+            return;
+        }
+        runInAction(() => {
+            this.credentialRefreshAttempts += 1;
+        });
+        const refresher = this.callbacks?.onRefreshCredential;
+        if (!refresher) {
+            // No re-mint path wired — re-probe with whatever the credential source
+            // holds (a static-key deployment refreshes out-of-band, if at all).
+            this.send({ type: 'CREDENTIAL_REFRESHED' });
+            return;
+        }
+        try {
+            const result = await refresher();
+            switch (result) {
+                case 'refreshed':
+                    this.send({ type: 'CREDENTIAL_REFRESHED' });
+                    break;
+                case 'session_error':
+                    this.send({ type: 'BOOTSTRAP_FAILED_SESSION' });
+                    break;
+                case 'network_error':
+                    this.send({ type: 'RECONNECT_FAILED' });
+                    break;
+                default: {
+                    const _exhaustive = result;
+                    void _exhaustive;
+                    this.send({ type: 'RECONNECT_FAILED' });
+                }
+            }
+        }
+        catch (error) {
+            // A thrown refresher is transient by contract (offline / mint endpoint
+            // unreachable) — back off and retry, never sign out.
+            getContext().logger.warn('[ConnectionManager] Credential re-mint threw (transient)', { error });
+            this.send({ type: 'RECONNECT_FAILED' });
+        }
+    }
     async runReconnect() {
         if (!this.callbacks)
             return;
@@ -431,6 +565,7 @@ export class ConnectionManager {
             const isStuck = this.state !== 'connected' &&
                 this.state !== 'session_expired' &&
                 this.state !== 'probing_network' &&
+                this.state !== 'refreshing_credential' &&
                 this.state !== 'reconnecting';
             if (isStuck) {
                 this.stuckCycles++;
@@ -467,7 +602,11 @@ export class ConnectionManager {
     get isConnected() { return this.state === 'connected'; }
     get isOffline() { return this.state === 'offline' || this.state === 'waiting_for_network'; }
     get isReconnecting() {
-        return this.state === 'probing_network' || this.state === 'reconnecting' || this.state === 'backoff';
+        return (this.state === 'probing_network' ||
+            this.state === 'validating_session' ||
+            this.state === 'refreshing_credential' ||
+            this.state === 'reconnecting' ||
+            this.state === 'backoff');
     }
     get isSessionExpired() { return this.state === 'session_expired'; }
     get offlineDuration() {