@abloatai/ablo 0.25.0 → 0.26.0

package/dist/sync/awaitClaimGrant.js

@@ -31,7 +31,7 @@ export function awaitClaimGrant(transport, claimId, options) {
         unsubs.push(transport.subscribe('claim_acquired', (p) => {
             if (p?.claimId === claimId) {
                 getContext().logger.debug(`claim: acquired ${claimId} (target was free)`);
-                settle(() => resolve({ waited: false }));
+                settle(() => { resolve({ waited: false }); });
             }
         }));
         unsubs.push(transport.subscribe('claim_granted', (p) => {
@@ -39,7 +39,7 @@ export function awaitClaimGrant(transport, claimId, options) {
                 // Promoted to the head of the line — the creator's "it's the agent's
                 // turn now" moment after waiting behind a holder.
                 getContext().logger.info(`claim: granted ${claimId} — your turn (waited in queue)`);
-                settle(() => resolve({ waited: true }));
+                settle(() => { resolve({ waited: true }); });
             }
         }));
         if (options?.maxQueueDepth !== undefined) {
@@ -49,7 +49,9 @@ export function awaitClaimGrant(transport, claimId, options) {
                     return;
                 const position = typeof p.position === 'number' ? p.position : 0;
                 if (position >= max) {
-                    settle(() => reject(new AbloClaimedError(`Claim queue for ${claimId} is ${position} deep (max ${max}).`, { code: 'queue_too_deep' })));
+                    settle(() => {
+                        reject(new AbloClaimedError(`Claim queue for ${claimId} is ${position} deep (max ${max}).`, { code: 'queue_too_deep' }));
+                    });
                 }
             }));
         }
@@ -64,29 +66,35 @@ export function awaitClaimGrant(transport, claimId, options) {
                     field: rejection.target.field,
                 })
                 : claimId;
-            settle(() => reject(new AbloClaimedError(formatClaimedErrorMessage({
-                targetLabel: target,
-                heldBy: rejection.heldBy,
-                claim: rejection.heldByClaim,
-                policyReason: rejection.policyReason,
-                fallback: `Claim rejected for ${target}.`,
-            }), {
-                code: rejection.reason === 'conflict'
-                    ? 'claim_conflict'
-                    : 'claim_lease_unavailable',
-                claims: rejection.heldByClaim ? [rejection.heldByClaim] : undefined,
-            })));
+            settle(() => {
+                reject(new AbloClaimedError(formatClaimedErrorMessage({
+                    targetLabel: target,
+                    heldBy: rejection.heldBy,
+                    claim: rejection.heldByClaim,
+                    policyReason: rejection.policyReason,
+                    fallback: `Claim rejected for ${target}.`,
+                }), {
+                    code: rejection.reason === 'conflict'
+                        ? 'claim_conflict'
+                        : 'claim_lease_unavailable',
+                    claims: rejection.heldByClaim ? [rejection.heldByClaim] : undefined,
+                }));
+            });
         }));
         unsubs.push(transport.subscribe('claim_lost', (p) => {
             if (p?.claimId === claimId) {
-                settle(() => reject(new AbloClaimedError(`Claim lost while queued for ${claimId}.`, {
-                    code: 'claim_lost',
-                })));
+                settle(() => {
+                    reject(new AbloClaimedError(`Claim lost while queued for ${claimId}.`, {
+                        code: 'claim_lost',
+                    }));
+                });
             }
         }));
         if (options?.timeoutMs && options.timeoutMs > 0) {
             timer = setTimeout(() => {
-                settle(() => reject(new AbloClaimedError(`Timed out waiting for the queue grant on claim ${claimId}.`, { code: 'grant_timeout' })));
+                settle(() => {
+                    reject(new AbloClaimedError(`Timed out waiting for the queue grant on claim ${claimId}.`, { code: 'grant_timeout' }));
+                });
             }, options.timeoutMs);
         }
     });

package/dist/sync/bootstrapApply.d.ts

@@ -0,0 +1,60 @@
+/**
+ * bootstrapApply — applying bootstrap results to the in-memory pool.
+ *
+ * Extracted from BaseSyncedStore.ts as a cohesive leaf: routing a
+ * full/partial bootstrap result through the pool-write facade, collecting
+ * the delta-protected ids that must survive ghost removal, and replaying
+ * the deltas queued during an active bootstrap. The store keeps thin
+ * protected delegates with unchanged signatures and talks back through the
+ * minimal {@link PoolContext} — never the store's class type — so no
+ * module cycle forms. The heavy lifting (model creation, healing, upsert,
+ * ghost removal) stays owned by `SyncClient`.
+ */
+import type { BootstrapResult } from '../Database.js';
+import type { SyncDelta } from './SyncWebSocket.js';
+/** Rehydration statistics from bootstrap */
+export interface RehydrationStats {
+    added: number;
+    updated: number;
+    removed: number;
+    skipped: number;
+    healed: number;
+    elapsedMs: number;
+}
+/**
+ * What the bootstrap-apply path needs back from its host store. The two
+ * `SyncClient` facades come with enrichment pre-bound by the host, so the
+ * store's `enrichRelations` override point keeps its dynamic dispatch.
+ */
+export interface PoolContext {
+    /** `SyncClient.applyDeltaBatchToPool` with the host's `enrichRelations` bound. */
+    applyDeltaBatchToPool(results: NonNullable<BootstrapResult['deltaResults']>): void;
+    /** `SyncClient.applyBootstrapDataToPool` — model creation, healing, pool upsert, ghost removal. */
+    applyBootstrapDataToPool(bootstrapData: {
+        models?: Record<string, unknown[]>;
+        failedModels?: string[];
+    }, protectedIds?: ReadonlySet<string>): {
+        added: number;
+        updated: number;
+        removed: number;
+        skipped: number;
+        healed: number;
+    };
+    /** Pool size — for the completion log line. */
+    getPoolSize(): number;
+    /** Every id currently in the pool — for delta-protected-id collection. */
+    getAllPoolIds(): string[];
+    /** Deltas queued during an active bootstrap; null when none is in flight.
+     *  Backed by the host's `bootstrapDeltaQueue` field (get/set accessors). */
+    bootstrapDeltaQueue: SyncDelta[] | null;
+    /** The host's atomic frame apply — `applyDeltaFrame` deliberately stays
+     *  in BaseSyncedStore (the authoritative-apply correctness seam). */
+    applyDeltaFrame(deltas: SyncDelta[]): void;
+}
+/** Apply bootstrap data to the ObjectPool with ghost removal */
+/** Apply bootstrap data to the ObjectPool. Delegates pool writes to SyncClient. */
+export declare function applyBootstrapToPool(ctx: PoolContext, bootstrapResult: BootstrapResult, protectedIds?: ReadonlySet<string>): RehydrationStats;
+/** Collect IDs that must survive ghost removal (added by deltas during bootstrap) */
+export declare function collectDeltaProtectedIds(ctx: PoolContext, preBootstrapIds: ReadonlySet<string>): Set<string>;
+/** Replay deltas queued during bootstrap */
+export declare function replayQueuedDeltas(ctx: PoolContext): void;

package/dist/sync/bootstrapApply.js

@@ -0,0 +1,65 @@
+/**
+ * bootstrapApply — applying bootstrap results to the in-memory pool.
+ *
+ * Extracted from BaseSyncedStore.ts as a cohesive leaf: routing a
+ * full/partial bootstrap result through the pool-write facade, collecting
+ * the delta-protected ids that must survive ghost removal, and replaying
+ * the deltas queued during an active bootstrap. The store keeps thin
+ * protected delegates with unchanged signatures and talks back through the
+ * minimal {@link PoolContext} — never the store's class type — so no
+ * module cycle forms. The heavy lifting (model creation, healing, upsert,
+ * ghost removal) stays owned by `SyncClient`.
+ */
+import { getContext } from '../context.js';
+/** Apply bootstrap data to the ObjectPool with ghost removal */
+/** Apply bootstrap data to the ObjectPool. Delegates pool writes to SyncClient. */
+export function applyBootstrapToPool(ctx, bootstrapResult, protectedIds) {
+    const { bootstrapData } = bootstrapResult;
+    // Partial bootstrap: Database.processDeltaBatch already wrote the deltas
+    // to IDB. Route the same results through the delta-apply path so the
+    // in-memory pool evicts deleted entities (and updates modified ones).
+    // Without this, reconnect DELETEs persist to IDB but the canvas keeps
+    // showing ghost layers until a full reload.
+    if (bootstrapData.type === 'partial') {
+        const deltaResults = bootstrapResult.deltaResults;
+        if (deltaResults && deltaResults.length > 0) {
+            ctx.applyDeltaBatchToPool(deltaResults);
+        }
+        return { added: 0, updated: 0, removed: 0, skipped: 0, healed: 0, elapsedMs: 0 };
+    }
+    if (!bootstrapData.models) {
+        return { added: 0, updated: 0, removed: 0, skipped: 0, healed: 0, elapsedMs: 0 };
+    }
+    const start = typeof performance !== 'undefined' ? performance.now() : Date.now();
+    // SyncClient owns: model creation, healing, pool upsert, ghost removal
+    const stats = ctx.applyBootstrapDataToPool(bootstrapData, protectedIds);
+    const elapsedMs = Math.round((typeof performance !== 'undefined' ? performance.now() : Date.now()) - start);
+    getContext().logger.info('[BaseSyncedStore] Bootstrap applied', {
+        ...stats, elapsedMs, poolSize: ctx.getPoolSize(),
+    });
+    return { ...stats, elapsedMs };
+}
+/** Collect IDs that must survive ghost removal (added by deltas during bootstrap) */
+export function collectDeltaProtectedIds(ctx, preBootstrapIds) {
+    const protectedIds = new Set();
+    for (const id of ctx.getAllPoolIds()) {
+        if (!preBootstrapIds.has(id))
+            protectedIds.add(id);
+    }
+    for (const delta of ctx.bootstrapDeltaQueue ?? []) {
+        if (delta.actionType !== 'D' && delta.modelId)
+            protectedIds.add(delta.modelId);
+    }
+    return protectedIds;
+}
+/** Replay deltas queued during bootstrap */
+export function replayQueuedDeltas(ctx) {
+    const queue = ctx.bootstrapDeltaQueue;
+    ctx.bootstrapDeltaQueue = null;
+    if (!queue || queue.length === 0)
+        return;
+    // Deltas that landed during bootstrap are a complete frame — apply
+    // them atomically (one flush, one re-render) rather than dribbling
+    // each back through the live debounce path.
+    ctx.applyDeltaFrame(queue);
+}

package/dist/sync/commitFrames.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Commit-path frame builders and claim instrumentation for the sync
+ * WebSocket — pure functions with no socket state, extracted from
+ * SyncWebSocket so the wire codec is a leaf the transport (and the frame
+ * dispatch table) can share.
+ */
+import type { CommitMessage } from '../wire/index.js';
+import type { MutationOperation, ClaimEvent } from '../interfaces/index.js';
+import type { StaleNotification, ReadDependency } from '../coordination/schema.js';
+/**
+ * Resolution value of a commit ack. `notifications` is present only when a
+ * guarded write (`onStale: 'notify') hit a concurrent change — the
+ * advisory self-heal signal, surfaced both here and via `conflict:notified`.
+ */
+export interface CommitAck {
+    lastSyncId: number;
+    notifications?: StaleNotification[];
+}
+/**
+ * Project the SDK's `MutationOperation[]` onto the canonical wire
+ * `CommitMessage`. This is the single serialize boundary between the SDK op
+ * type (loose `type: string`, plus an SDK-internal `options` the server never
+ * reads) and the strict wire contract. The per-field map gives compile-time
+ * drift detection (a `CommitOperation` shape change breaks here) and the lone
+ * `as` narrows the validated op `type` to the wire union — the only
+ * loosening, localized to this boundary.
+ */
+export declare function buildCommitFrame(operations: readonly MutationOperation[], clientTxId: string, causedByTaskId?: string | null, reads?: readonly ReadDependency[] | null): CommitMessage;
+/**
+ * Defensively validate the optional `notifications` array off a commit ack.
+ * Untrusted wire data — a malformed entry is dropped rather than throwing,
+ * so a bad notification never sinks an otherwise-successful commit.
+ */
+export declare function parseNotifications(raw: unknown): StaleNotification[] | undefined;
+/**
+ * Single instrumentation point for claim events. Every `claim_*` frame routes
+ * through here so a developer debugging a collision gets one consistent trace
+ * — a console line AND a structured capture — without each dispatch case
+ * re-deriving the row/holder shape. The wire payload is loosely typed
+ * (`Record<string, unknown>`), so this is the one place that narrows it into
+ * a {@link ClaimEvent}.
+ */
+export declare function recordClaim(phase: ClaimEvent['phase'], payload: Record<string, unknown>): void;

package/dist/sync/commitFrames.js

@@ -0,0 +1,94 @@
+/**
+ * Commit-path frame builders and claim instrumentation for the sync
+ * WebSocket — pure functions with no socket state, extracted from
+ * SyncWebSocket so the wire codec is a leaf the transport (and the frame
+ * dispatch table) can share.
+ */
+import { getContext } from '../context.js';
+import { staleNotificationSchema, wireParticipantKindSchema, } from '../coordination/schema.js';
+import { formatClaim } from '../coordination/trace.js';
+/**
+ * Project the SDK's `MutationOperation[]` onto the canonical wire
+ * `CommitMessage`. This is the single serialize boundary between the SDK op
+ * type (loose `type: string`, plus an SDK-internal `options` the server never
+ * reads) and the strict wire contract. The per-field map gives compile-time
+ * drift detection (a `CommitOperation` shape change breaks here) and the lone
+ * `as` narrows the validated op `type` to the wire union — the only
+ * loosening, localized to this boundary.
+ */
+export function buildCommitFrame(operations, clientTxId, causedByTaskId, reads) {
+    const payload = {
+        operations: operations.map((op) => ({
+            type: op.type,
+            model: op.model,
+            id: op.id,
+            input: op.input,
+            transactionId: op.transactionId,
+            readAt: op.readAt,
+            onStale: op.onStale,
+        })),
+        clientTxId,
+    };
+    if (causedByTaskId)
+        payload.causedByTaskId = causedByTaskId;
+    // Batch-level read-set (STORM layer): rows/groups the batch was premised on.
+    if (reads && reads.length > 0)
+        payload.reads = [...reads];
+    return { type: 'commit', payload };
+}
+/**
+ * Defensively validate the optional `notifications` array off a commit ack.
+ * Untrusted wire data — a malformed entry is dropped rather than throwing,
+ * so a bad notification never sinks an otherwise-successful commit.
+ */
+export function parseNotifications(raw) {
+    if (!Array.isArray(raw) || raw.length === 0)
+        return undefined;
+    const out = [];
+    for (const entry of raw) {
+        const parsed = staleNotificationSchema.safeParse(entry);
+        if (parsed.success)
+            out.push(parsed.data);
+    }
+    return out.length > 0 ? out : undefined;
+}
+/**
+ * Single instrumentation point for claim events. Every `claim_*` frame routes
+ * through here so a developer debugging a collision gets one consistent trace
+ * — a console line AND a structured capture — without each dispatch case
+ * re-deriving the row/holder shape. The wire payload is loosely typed
+ * (`Record<string, unknown>`), so this is the one place that narrows it into
+ * a {@link ClaimEvent}.
+ */
+export function recordClaim(phase, payload) {
+    const str = (v) => typeof v === 'string' ? v : undefined;
+    // Targets arrive flat ({ entityType, entityId }) or nested under `target`.
+    const target = payload.target && typeof payload.target === 'object'
+        ? payload.target
+        : payload;
+    const kind = wireParticipantKindSchema.safeParse(payload.participantKind);
+    const event = {
+        phase,
+        claimId: str(payload.claimId),
+        model: str(target.entityType) ?? str(target.model),
+        id: str(target.entityId) ?? str(target.id),
+        field: str(target.field),
+        actor: str(payload.actor) ?? str(payload.heldBy),
+        participantKind: kind.success ? kind.data : undefined,
+        position: typeof payload.position === 'number' ? payload.position : undefined,
+        reason: str(payload.policyReason) ?? str(payload.reason),
+    };
+    const message = formatClaim(event);
+    // A rejection or lost lease is the collision a developer is actively
+    // debugging → warn (shows at the default log level). The routine events
+    // (acquired/queued/granted/expired) are debug-only so they never drown the
+    // console until you opt in with `new Ablo({ debug: true })`.
+    const isCollision = phase === 'rejected' || phase === 'lost';
+    const ctx = getContext();
+    if (isCollision)
+        ctx.logger.warn(message);
+    else
+        ctx.logger.debug(message);
+    ctx.observability.breadcrumb(message, 'sync.coordination', isCollision ? 'warning' : 'info');
+    ctx.observability.captureClaim(event);
+}

package/dist/sync/createClaimStream.js

@@ -189,8 +189,9 @@ export function createClaimStream(config, transport = null) {
             // If WE are in this line, trace our position (the "agent queued behind a
             // claim" moment) — once per position change, so advancing is visible.
             const ourIndex = line.findIndex((c) => ownClaims.has(c.id));
-            if (ourIndex >= 0) {
-                const ourId = line[ourIndex].id;
+            const ourClaim = ourIndex >= 0 ? line[ourIndex] : undefined;
+            if (ourClaim) {
+                const ourId = ourClaim.id;
                 if (lastLoggedQueuePos.get(ourId) !== ourIndex) {
                     lastLoggedQueuePos.set(ourId, ourIndex);
                     getContext().logger.info(`claim: queued for ${claimLabel(p.target.type, p.target.id)} — position ${ourIndex + 1} of ${line.length}, waiting`, { claimId: ourId });

package/dist/sync/createSnapshot.d.ts

@@ -26,8 +26,6 @@ export interface CreateSnapshotArgs<TSchema extends Schema = Schema, K extends k
     /** Returns the engine's current `lastSyncId`. Read at snapshot time
      *  to stamp the watermark; not re-read after. */
     getLastSyncId: () => number;
-    entities: {
-        readonly [M in K]: string | readonly string[];
-    };
+    entities: Readonly<Record<K, string | readonly string[]>>;
 }
 export declare function createSnapshot<TSchema extends Schema, K extends keyof TSchema['models'] & string>(args: CreateSnapshotArgs<TSchema, K>): Snapshot<TSchema, K>;

package/dist/sync/credentialLifecycle.d.ts

@@ -0,0 +1,175 @@
+/**
+ * credentialLifecycle — reconnect-credential re-mint + proactive pre-roll.
+ *
+ * Extracted from BaseSyncedStore.ts as a cohesive leaf: owns the re-mint
+ * hook, the single-flight guard, and the browser-only proactive refresh
+ * (timer + OS-wake listener). The store keeps thin public delegates
+ * (`setCredentialRefresher` / `performCredentialRefresh` /
+ * `startCredentialLifecycle`) so its published surface is unchanged, and
+ * talks back through the minimal {@link CredentialLifecycleContext} —
+ * never the store's class type — so no module cycle forms.
+ */
+import type { RecoveryClass } from '../errorCodes.js';
+/**
+ * Tri-state outcome of a credential re-mint, mirroring the `getToken`
+ * contract (see {@link CredentialLifecycle.refresh}).
+ */
+export type CredentialRefreshOutcome = 'refreshed' | 'session_error' | 'network_error';
+/**
+ * What an auth-rejected transport should do after the backbone has run:
+ * `'retry'` = a fresh credential is in the credential source, replay the
+ * request ONCE; `'stop'` = don't replay (terminal session loss, a rejection
+ * a re-mint can't cure, or a transient mint failure the caller's own
+ * retry/revalidation path will recover later).
+ */
+export type CredentialRecoveryOutcome = 'retry' | 'stop';
+/**
+ * What a credential refresher may resolve with. The plain-string form is the
+ * classic `getToken` contract; the object form additionally carries the mint
+ * response's `expiresAt` (ISO string / epoch ms / Date) so the proactive
+ * pre-roll can schedule off the credential's ACTUAL lifetime instead of
+ * assuming the server's default TTL.
+ */
+export type CredentialRefreshResult = string | {
+    readonly token: string;
+    readonly expiresAt?: string | number | Date;
+} | null;
+/** A credential re-mint hook. `Promise<string | null>` resolvers remain
+ *  assignable — the widened result type is a superset. */
+export type CredentialRefresher = () => Promise<CredentialRefreshResult>;
+/** Fallback pre-roll cadence AND ceiling — the historical 10-minute value,
+ *  comfortably inside the server's 15m default `ek_` TTL. Used verbatim when
+ *  the refresher reports no expiry. */
+export declare const DEFAULT_PREROLL_INTERVAL_MS: number;
+/** Floor so a very short (or already-elapsed) TTL can't hot-loop the mint. */
+export declare const MIN_PREROLL_DELAY_MS: number;
+/**
+ * When to pre-roll a credential that expires at `expiresAtMs`: after ~2/3 of
+ * the REMAINING lifetime (15m TTL → 10m, exactly the historical cadence),
+ * clamped to [{@link MIN_PREROLL_DELAY_MS}, {@link DEFAULT_PREROLL_INTERVAL_MS}].
+ * Unknown expiry (`null`) → the 10-minute fallback. Exported for unit tests.
+ */
+export declare function computePrerollDelayMs(expiresAtMs: number | null, nowMs: number): number;
+/**
+ * What the lifecycle needs back from its host store. Deliberately minimal —
+ * three callbacks, all resolved lazily at call time (the ConnectionManager
+ * behind two of them doesn't exist until `setupWebSocketSync`).
+ */
+export interface CredentialLifecycleContext {
+    /** Push a freshly-minted access token into the shared credential source
+     *  (no-op when the deployment wired no credential source). */
+    setAuthToken(token: string): void;
+    /** Nudge the connection FSM to re-probe with the current credential —
+     *  the host's `nudgeReconnect()` (`CREDENTIAL_REFRESHED`). */
+    nudgeReconnect(): void;
+    /** Surface a terminal session loss to the connection FSM
+     *  (`BOOTSTRAP_FAILED_SESSION`) — the long-lived login is gone. */
+    reportSessionExpired(): void;
+}
+export declare class CredentialLifecycle {
+    private readonly ctx;
+    /**
+     * Re-mint hook for the short-lived access credential (the Stripe-style
+     * `ek_`/`rk_`). Wired by the React provider from its `getToken`/`authEndpoint`
+     * — the engine owns WHEN to refresh (a stale-credential probe / an external
+     * nudge), the integrator owns HOW to mint. Mirrors the `getToken` contract:
+     * resolves a token string on success, `null` when the long-lived login is
+     * gone (terminal), and THROWS on a transient/offline failure. Used by
+     * {@link refresh}. Absent ⇒ no silent re-mint (e.g. a static
+     * `apiKey` deployment whose credential source refreshes out-of-band).
+     */
+    private credentialRefresher;
+    /** Single-flight guard so a wake nudge + an in-flight request + a probe don't
+     *  all mint at once (the classic "token thrash → random logout" bug). */
+    private inFlightCredentialRefresh;
+    /** Teardown for the proactive credential lifecycle (refresh timer + wake/
+     *  online/focus listeners) installed by {@link start};
+     *  cleared on `BaseSyncedStore.disconnect`. Null when no resolver is wired. */
+    private credentialLifecycleTeardown;
+    /** Epoch ms the CURRENT credential expires, when the refresher reports it
+     *  (object-form {@link CredentialRefreshResult}); `null` for the classic
+     *  string-form resolver → the pre-roll falls back to its fixed cadence. */
+    private credentialExpiresAtMs;
+    /** Re-arm hook for the proactive pre-roll timer (set by {@link start}).
+     *  Invoked after every successful mint so a REACTIVE refresh (probe, wake,
+     *  the initial `ready()` mint) immediately re-anchors the schedule to the
+     *  fresh credential's real expiry instead of a stale fixed delay. */
+    private prerollReschedule;
+    constructor(ctx: CredentialLifecycleContext);
+    /**
+     * Register the access-credential re-mint hook. Called by the React provider
+     * with a thunk that mints a fresh `ek_`/`rk_` (typically its `getToken`).
+     * See {@link credentialRefresher}.
+     */
+    setRefresher(refresher: CredentialRefresher | null): void;
+    /**
+     * Re-mint the short-lived access credential and push it into the credential
+     * source, reporting a tri-state outcome the `ConnectionManager` maps to
+     * its FSM. The contract mirrors `getToken` (and PowerSync's `fetchCredentials`
+     * / Liveblocks' `authEndpoint`, but made explicit instead of overloading
+     * return/throw):
+     *   - token string  → `'refreshed'`     (fresh key in place; re-probe & reconnect)
+     *   - `null`        → `'session_error'` (login itself is gone → terminal, sign out)
+     *   - throw         → `'network_error'` (couldn't reach the mint endpoint → transient)
+     *
+     * SINGLE-FLIGHT: concurrent callers (a wake nudge, an in-flight request, the
+     * probe) share one in-flight promise so we never double-mint — the canonical
+     * fix for the "every 401 mints a token → thrash → spurious logout" anti-pattern.
+     *
+     * No refresher wired ⇒ `'refreshed'` (a no-op re-probe): a static-`apiKey`
+     * deployment has no session to re-mint from; its credential source refreshes
+     * out-of-band, so we just re-probe with whatever it currently holds.
+     */
+    refresh(): Promise<CredentialRefreshOutcome>;
+    /**
+     * Route a refresh outcome into the FSM — the ONE place the tri-state is
+     * interpreted, shared by the proactive pre-roll, the wake nudge, and the
+     * HTTP auth-recovery path so every trigger converges on identical behavior.
+     */
+    private routeRefreshOutcome;
+    /**
+     * THE recovery backbone for auth-rejected requests, whatever the transport.
+     * The WS probe already routes 401s through the FSM; HTTP consumers (the
+     * lazy-query lane, bootstrap helpers) call THIS instead of inventing their
+     * own handling — one single-flight mint, one outcome routing, one taxonomy.
+     *
+     * Mirrors `NetworkProbe`'s classification of the same codes:
+     *   - `access_credential_expiry` — the routine case (an expired `ek_`/`rk_`):
+     *     silently re-mint via the single-flight {@link refresh} and tell the
+     *     caller to replay ONCE on success. Never a sign-out by itself — the
+     *     only terminal path is the mint itself resolving `null`.
+     *   - `session_expiry` — the login is gone. Report to the FSM (sign-out
+     *     path) and stop; replaying is pointless.
+     *   - `auth_blocked` / `permission` / everything else — re-minting produces
+     *     the same rejected credential; stop without touching the FSM.
+     */
+    recoverFromAuthRejection(recovery: RecoveryClass): Promise<CredentialRecoveryOutcome>;
+    /**
+     * Install the access-credential lifecycle the CLIENT owns (this used to live
+     * in the React provider — wrong layer). Two parts:
+     *   1. REACTIVE — register `getToken` as the re-mint hook the FSM calls when a
+     *      probe finds the key stale (`credential_stale`) or on a nudge.
+     *   2. PROACTIVE — keep the short-lived key fresh ahead of trouble: a refresh
+     *      timer inside the TTL, plus re-mint on OS wake. The ENTIRE proactive
+     *      block is browser-gated (`typeof window`): server/SSR has no socket to
+     *      keep warm and the resolver is browser-oriented, so arming it in Node
+     *      would fire a relative-URL fetch and throw. (Agents pass a static
+     *      `apiKey` with no resolver, so this method is never called for them.)
+     *
+     * Config-driven and invisible, like Supabase's `autoRefreshToken` — consumers
+     * never call a refresh method. Idempotent (a second call replaces the first);
+     * torn down on `BaseSyncedStore.disconnect`.
+     *
+     * `opts.proactiveInNode` arms the refresh TIMER on a windowless host too —
+     * set for agent/system participants (long-lived server sockets whose
+     * `rk_`/`ek_` must renew BEFORE the hub's keepalive reaper closes them; the
+     * PowerSync/Ably "SDK renews everywhere" model). Node timers are `unref`ed
+     * so a finishing script is never kept alive by the pre-roll. The OS-wake
+     * listener remains browser-only regardless (no `window` to listen on).
+     */
+    start(getToken: CredentialRefresher, opts?: {
+        proactiveInNode?: boolean;
+    }): void;
+    /** Tear down the proactive credential lifecycle (idempotent). */
+    stop(): void;
+}