@abloatai/ablo 0.34.1 → 0.36.0

package/dist/{transactions → transaction/transactions/settlement}/commitEnvelope.js

@@ -7,10 +7,11 @@
  * operations, and the source mutations it supersedes.
  */
 import { z } from 'zod';
-import { readDependencySchema, trackDependencySchema } from '../coordination/schema.js';
-import { commitOperationSchema } from '../wire/frames.js';
-import { correlationIdSchema } from '../wire/commit.js';
+import { readDependencySchema, trackDependencySchema } from '../../coordination/schema.js';
+import { wireCommitOperationSchema } from '../../wire/frames.js';
+import { correlationIdSchema } from '../../wire/commit.js';
 import { idempotencyKeySchema } from './idempotencyKey.js';
+import { snapshotJsonValue } from '../../utils/json.js';
 export const COMMIT_ENVELOPE_VERSION = 1;
 export const COMMIT_ENVELOPE_RECORD_PREFIX = 'commit-envelope:';
 /** One transaction's position in a commit; this is not the envelope itself. */
@@ -24,7 +25,7 @@ export const commitEnvelopeMemberSchema = z
 })
     .refine(({ operationIndex, operationCount }) => operationIndex < operationCount, { message: 'operationIndex must be smaller than operationCount' });
 /** One operation stored exactly as the current commit transport sends it. */
-export const durableCommitOperationSchema = commitOperationSchema
+export const durableCommitOperationSchema = wireCommitOperationSchema
     .pick({
     type: true,
     model: true,
@@ -48,7 +49,6 @@ export const durableCommitOperationSchema = commitOperationSchema
         .optional(),
 });
 const durableCommitOptionsSchema = z.strictObject({
-    causedByTaskId: z.string().min(1).nullable().optional(),
     reads: z.array(readDependencySchema).nullable().optional(),
     track: z.array(trackDependencySchema).nullable().optional(),
 });
@@ -145,9 +145,9 @@ export function createCommitEnvelopeMember(value) {
     return commitEnvelopeMemberSchema.parse(value);
 }
 /**
- * Freezes the exact JSON request that will be persisted and sent. The JSON
- * round-trip deliberately applies the same Date/undefined semantics as the
- * WebSocket transport before the request fingerprint becomes durable.
+ * Freezes the exact JSON request that will be persisted and sent. The shared
+ * snapshot contract makes framework proxies plain and rejects values that
+ * would be lost or corrupted by JSON serialization.
  */
 export function createDurableCommitEnvelope(value) {
     const candidate = {
@@ -157,9 +157,5 @@ export function createDurableCommitEnvelope(value) {
         storageVersion: COMMIT_ENVELOPE_VERSION,
         timestamp: value.sealedAt,
     };
-    const serialized = JSON.stringify(candidate);
-    if (serialized === undefined) {
-        throw new TypeError('Commit envelope is not JSON serializable');
-    }
-    return durableCommitEnvelopeSchema.parse(JSON.parse(serialized));
+    return durableCommitEnvelopeSchema.parse(snapshotJsonValue(candidate, '$.commitEnvelope'));
 }

package/dist/{transactions → transaction/transactions/settlement}/httpCommitEnvelope.d.ts

@@ -4,7 +4,7 @@ export declare const HTTP_COMMIT_ENVELOPE_VERSION: 1;
 export declare const HTTP_COMMIT_ENVELOPE_PREFIX = "http-commit-envelope:";
 /** Stay one hour inside the server's 24-hour idempotency retention window. */
 export declare const HTTP_COMMIT_REPLAY_WINDOW_MS: number;
-/** Apply normal JSON semantics once, then make object-key order canonical. */
+/** Snapshot the JSON contract once, then make object-key order canonical. */
 export declare function canonicalHttpCommitBody(value: unknown): string;
 export declare const durableHttpCommitEnvelopeSchema: z.ZodObject<{
     id: z.ZodString;
@@ -30,11 +30,18 @@ export declare const durableHttpCommitEnvelopeSchema: z.ZodObject<{
     timestamp: z.ZodNumber;
 }, z.core.$strict>;
 export type DurableHttpCommitEnvelope = z.infer<typeof durableHttpCommitEnvelopeSchema>;
+/**
+ * The HTTP verbs a durable commit envelope can carry, projected out of the
+ * persisted schema above. Callers that build, seal, or dispatch an envelope
+ * take this rather than restating the verbs: the envelope is a stored contract,
+ * so a verb the schema does not accept must not be constructible.
+ */
+export type DurableHttpCommitMethod = DurableHttpCommitEnvelope['request']['method'];
 export declare function httpCommitEnvelopeRecordId(idempotencyKey: string, scopeNamespace?: string): string;
 export declare function createDurableHttpCommitEnvelope(input: {
     idempotencyKey: string;
     request: {
-        method: 'POST' | 'PATCH' | 'DELETE';
+        method: DurableHttpCommitMethod;
         path: string;
         body: unknown;
     };

package/dist/{transactions → transaction/transactions/settlement}/httpCommitEnvelope.js

@@ -1,9 +1,9 @@
 /** Crash-durable exact HTTP request used by the stateless agent client. */
 import { z } from 'zod';
 import { v5 as uuidv5 } from 'uuid';
-import { stableStringify } from '../utils/json.js';
-import { correlationIdSchema } from '../wire/commit.js';
-import { PROTOCOL_VERSION } from '../wire/protocolVersion.js';
+import { snapshotJsonValue, stableStringify } from '../../utils/json.js';
+import { correlationIdSchema } from '../../wire/commit.js';
+import { PROTOCOL_VERSION } from '../../wire/protocolVersion.js';
 import { idempotencyKeySchema } from './idempotencyKey.js';
 export const HTTP_COMMIT_ENVELOPE_VERSION = 1;
 export const HTTP_COMMIT_ENVELOPE_PREFIX = 'http-commit-envelope:';
@@ -33,13 +33,9 @@ function hasSafeModelPathSegments(path) {
         return false;
     }
 }
-/** Apply normal JSON semantics once, then make object-key order canonical. */
+/** Snapshot the JSON contract once, then make object-key order canonical. */
 export function canonicalHttpCommitBody(value) {
-    const serialized = JSON.stringify(value);
-    if (serialized === undefined) {
-        throw new TypeError('HTTP commit body is not JSON serializable');
-    }
-    return stableStringify(JSON.parse(serialized));
+    return stableStringify(snapshotJsonValue(value, '$.body'));
 }
 export const durableHttpCommitEnvelopeSchema = z
     .strictObject({

package/dist/{transactions/durableWriteStore.d.ts → transaction/transactions/settlement/pendingWrite.d.ts}

@@ -1,9 +1,14 @@
 /**
- * Product-facing persistence contract for writes that must survive a process
- * restart or an ambiguous network response.
+ * The persisted shape of a write awaiting a definitive outcome.
  *
- * The engine implements this contract with a transactional outbox internally,
- * but callers should only need to think in terms of pending durable writes.
+ * Owns one authoritative union over the two durable commit envelopes — the
+ * WebSocket envelope and its HTTP counterpart — so an injected store and the
+ * engine that reads back from it agree on exactly one set of records. The
+ * envelope schemas in this directory remain authoritative for their own fields;
+ * this module only unions them.
+ *
+ * The port that persists these records is a behavior contract, not a persisted
+ * shape, so it lives outside this directory in `src/durableWrites.ts`.
  */
 import { z } from 'zod';
 /** Every write shape that Ablo may ask an injected store to persist. */
@@ -42,12 +47,11 @@ export declare const pendingWriteSchema: z.ZodUnion<readonly [z.ZodObject<{
     }, z.core.$strip>>;
     sourceMutationIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
     commitOptions: z.ZodDefault<z.ZodObject<{
-        causedByTaskId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         reads: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
             model: z.ZodString;
             id: z.ZodString;
             readAt: z.ZodNumber;
-            fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            fields: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
             onStale: z.ZodOptional<z.ZodEnum<{
                 reject: "reject";
                 overwrite: "overwrite";
@@ -63,8 +67,8 @@ export declare const pendingWriteSchema: z.ZodUnion<readonly [z.ZodObject<{
             }>>;
         }, z.core.$strip>]>>>>;
         track: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
-            model: z.ZodString;
             id: z.ZodString;
+            model: z.ZodString;
             readAt: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>, z.ZodObject<{
             group: z.ZodString;
@@ -106,33 +110,3 @@ export declare const pendingWriteSchema: z.ZodUnion<readonly [z.ZodObject<{
     timestamp: z.ZodNumber;
 }, z.core.$strict>]>;
 export type PendingWrite = z.infer<typeof pendingWriteSchema>;
-/**
- * Persistence port used by `Ablo({ durableWrites })`.
- *
- * `seal` is the durability boundary: it must atomically persist the exact write
- * and consume the staged records that write supersedes. Resolving this promise
- * authorizes Ablo to dispatch the request, so adapters must never report success
- * before the data is durable.
- */
-export interface DurableWriteStore {
-    /**
-     * Atomically reserve a pending write and consume the staged records it owns.
-     * The same id + same request is idempotent; the same id + a different request
-     * must be rejected. For a source-accepted envelope, a re-seal may add the
-     * monotonic `acceptedAt`/`correlationId` evidence and the store must preserve
-     * that upgrade atomically rather than ignoring it.
-     */
-    seal(write: PendingWrite, consumedRecordIds: readonly string[]): Promise<void>;
-    /** Load all unacknowledged writes. Stored data is treated as untrusted. */
-    list(): Promise<readonly unknown[]>;
-    /** Remove one write only after its outcome is definitive. */
-    remove(writeId: string): Promise<void>;
-}
-/** Runtime validation for injected adapters, including JavaScript consumers. */
-export declare const durableWriteStoreSchema: z.ZodCustom<DurableWriteStore, DurableWriteStore>;
-/** Options for crash-durable `create`, `update`, and `delete` calls. */
-export declare const durableWritesConfigSchema: z.ZodObject<{
-    store: z.ZodCustom<DurableWriteStore, DurableWriteStore>;
-    namespace: z.ZodOptional<z.ZodString>;
-}, z.core.$strict>;
-export type DurableWritesConfig = z.infer<typeof durableWritesConfigSchema>;

package/dist/transaction/transactions/settlement/pendingWrite.js

@@ -0,0 +1,20 @@
+/**
+ * The persisted shape of a write awaiting a definitive outcome.
+ *
+ * Owns one authoritative union over the two durable commit envelopes — the
+ * WebSocket envelope and its HTTP counterpart — so an injected store and the
+ * engine that reads back from it agree on exactly one set of records. The
+ * envelope schemas in this directory remain authoritative for their own fields;
+ * this module only unions them.
+ *
+ * The port that persists these records is a behavior contract, not a persisted
+ * shape, so it lives outside this directory in `src/durableWrites.ts`.
+ */
+import { z } from 'zod';
+import { durableCommitEnvelopeSchema } from './commitEnvelope.js';
+import { durableHttpCommitEnvelopeSchema } from './httpCommitEnvelope.js';
+/** Every write shape that Ablo may ask an injected store to persist. */
+export const pendingWriteSchema = z.union([
+    durableCommitEnvelopeSchema,
+    durableHttpCommitEnvelopeSchema,
+]);

package/dist/transaction/transport/commitFrames.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Builds the outgoing frames the sync WebSocket sends on the commit path, and
+ * provides the single place claim events are traced. These are stateless
+ * helpers that hold no socket state, so both the transport and its frame
+ * dispatch can share them.
+ */
+import type { CommitMessage } from '../wire/index.js';
+import type { CommitAck as CanonicalCommitAck } from '../wire/commit.js';
+import type { OnStaleMode, StaleNotification, ReadDependency, TrackDependency } from '../coordination/schema.js';
+import type { ClaimAcquired, ClaimGranted, ClaimQueued, ClaimLost, ClaimRejection, ClaimExpired } from '../coordination/schema.js';
+import type { Logger } from '../logger.js';
+import type { SocketObservability } from '../observability.js';
+/**
+ * The value a commit acknowledgement resolves to. `notifications` is present
+ * only when a guarded write (`onStale: 'notify'`) met a concurrent change; it
+ * carries the advisory signal that lets the writer self-heal, and the same
+ * signal also arrives on the `conflict:notified` event.
+ */
+export type CommitAck = CanonicalCommitAck;
+/**
+ * The slice of a queued client mutation the commit frame reads — a structural
+ * port, so the reactive engine's fatter `MutationOperation` satisfies it
+ * without this module importing the consumer package.
+ */
+export interface CommitFrameOperation {
+    readonly type: string;
+    readonly model: string;
+    readonly id: string;
+    readonly input?: Record<string, unknown>;
+    readonly transactionId?: string;
+    readonly readAt?: number | null;
+    readonly onStale?: OnStaleMode | null;
+    readonly fenceToken?: number | null;
+}
+/**
+ * Converts the client's list of {@link CommitFrameOperation} values into the wire
+ * {@link CommitMessage} the server accepts. This is the one place the loosely
+ * typed operation — its `type` is a string, and it carries client-only
+ * `options` the server never reads — becomes the strict wire contract. Mapping
+ * each field by hand means a change to {@link WireCommitOperation} fails to compile
+ * here; the single `as` cast narrows the validated `type` to the wire union and
+ * is the only place that loosening happens.
+ */
+export declare function buildCommitFrame(operations: readonly CommitFrameOperation[], clientTxId: string, reads?: readonly ReadDependency[] | null, track?: readonly TrackDependency[] | 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;
+/** The reporting ports a claim trace writes through — supplied by the caller
+ *  (the frame dispatch passes its session's own ports). */
+export interface ClaimTracePorts {
+    readonly logger: Logger;
+    readonly observability: SocketObservability;
+}
+/**
+ * Which frame reports each phase of a claim's life.
+ *
+ * The correspondence is real and was previously implicit: six dispatch handlers
+ * each passed their own payload alongside a phase they picked by hand, and
+ * nothing checked that the two matched. Stating it once means a caller cannot
+ * label a rejection as an acquisition.
+ *
+ * Every value is the `z.infer` of the schema the dispatcher parsed with, so no
+ * field is restated here — this maps existing types, it does not describe them.
+ */
+interface ClaimFrameByPhase {
+    acquired: ClaimAcquired;
+    granted: ClaimGranted;
+    queued: ClaimQueued;
+    lost: ClaimLost;
+    rejected: ClaimRejection;
+    expired: ClaimExpired;
+}
+/**
+ * The single place claim events are traced. Every `claim_*` frame passes
+ * through here, so a developer debugging a collision gets one consistent record
+ * — a console line and a structured capture — without each frame case
+ * re-deriving the row and holder shape.
+ *
+ * The payload arrives already validated against its frame's schema, so this
+ * reads it as the shape it is rather than re-narrowing an untyped record. That
+ * distinction is not cosmetic: while this took `Record<string, unknown>` it
+ * read `actor`, `participantKind`, and `description` off frames that carry none
+ * of them, and every one of those reads silently produced `undefined` because a
+ * string key never has to exist.
+ */
+export declare function recordClaim<P extends keyof ClaimFrameByPhase>(ports: ClaimTracePorts, phase: P, payload: ClaimFrameByPhase[P]): void;
+export {};

package/dist/transaction/transport/commitFrames.js

@@ -0,0 +1,134 @@
+/**
+ * Builds the outgoing frames the sync WebSocket sends on the commit path, and
+ * provides the single place claim events are traced. These are stateless
+ * helpers that hold no socket state, so both the transport and its frame
+ * dispatch can share them.
+ */
+import { claimEventReasonSchema, staleNotificationSchema, } from '../coordination/schema.js';
+import { formatClaim } from '../coordination/trace.js';
+import { modelTarget } from '../coordination/locator.js';
+/**
+ * Converts the client's list of {@link CommitFrameOperation} values into the wire
+ * {@link CommitMessage} the server accepts. This is the one place the loosely
+ * typed operation — its `type` is a string, and it carries client-only
+ * `options` the server never reads — becomes the strict wire contract. Mapping
+ * each field by hand means a change to {@link WireCommitOperation} fails to compile
+ * here; the single `as` cast narrows the validated `type` to the wire union and
+ * is the only place that loosening happens.
+ */
+export function buildCommitFrame(operations, clientTxId, reads, track) {
+    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,
+            fenceToken: op.fenceToken,
+        })),
+        clientTxId,
+    };
+    // The batch premise: the rows or groups the writer read before committing.
+    if (reads && reads.length > 0)
+        payload.reads = [...reads];
+    // Durable premises the writer is registering: the rows or groups it
+    // wants to keep hearing about after this commit, delivered on a future receipt.
+    if (track && track.length > 0)
+        payload.track = [...track];
+    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;
+}
+// The phases this map covers and the phases a ClaimEvent can report are the
+// same set. Adding one to either without the other stops compiling here.
+const _phaseCoverage = true;
+void _phaseCoverage;
+/**
+ * The single place claim events are traced. Every `claim_*` frame passes
+ * through here, so a developer debugging a collision gets one consistent record
+ * — a console line and a structured capture — without each frame case
+ * re-deriving the row and holder shape.
+ *
+ * The payload arrives already validated against its frame's schema, so this
+ * reads it as the shape it is rather than re-narrowing an untyped record. That
+ * distinction is not cosmetic: while this took `Record<string, unknown>` it
+ * read `actor`, `participantKind`, and `description` off frames that carry none
+ * of them, and every one of those reads silently produced `undefined` because a
+ * string key never has to exist.
+ */
+export function recordClaim(ports, phase, payload) {
+    // Widened so the members can be told apart with `in`. The parameter above
+    // stays correlated to `phase`, which is what the widening cannot undo.
+    const frame = payload;
+    const target = 'target' in frame ? frame.target : undefined;
+    // The holder rides on the rejection and queued frames, with a summary of
+    // their claim beside it. Collecting it is the whole of "name the
+    // counterparty" — the wire has carried it all along and this projection used
+    // to flatten it into one string alongside the cause.
+    const counterparty = {
+        ...('heldBy' in frame && frame.heldBy !== undefined
+            ? { actor: frame.heldBy }
+            : {}),
+        ...('heldByKind' in frame && frame.heldByKind !== undefined
+            ? { participantKind: frame.heldByKind }
+            : {}),
+        ...('heldByClaimId' in frame && frame.heldByClaimId !== undefined
+            ? { claimId: frame.heldByClaimId }
+            : {}),
+        ...('heldByExpiresAt' in frame && frame.heldByExpiresAt !== undefined
+            ? { expiresAt: frame.heldByExpiresAt }
+            : {}),
+        ...('heldByClaim' in frame && frame.heldByClaim?.description !== undefined
+            ? { description: frame.heldByClaim.description }
+            : {}),
+    };
+    // `reason` is a plain string on the wire, which is frozen, so an older server
+    // may send a word the closed set does not list. One that parses becomes the
+    // typed reason; one that does not is absent rather than passed off as prose.
+    const parsedReason = 'reason' in frame ? claimEventReasonSchema.safeParse(frame.reason) : undefined;
+    const event = {
+        phase,
+        claimId: frame.claimId,
+        ...(target ? modelTarget(target) : {}),
+        ...(target?.field !== undefined ? { field: target.field } : {}),
+        // No claim frame names an actor of its own; the only participant one
+        // carries is the holder that blocked it.
+        ...('heldBy' in frame && frame.heldBy !== undefined
+            ? { actor: frame.heldBy }
+            : {}),
+        ...('position' in frame ? { position: frame.position } : {}),
+        ...(parsedReason?.success ? { reason: parsedReason.data } : {}),
+        ...('policyReason' in frame && frame.policyReason !== undefined
+            ? { policyReason: frame.policyReason }
+            : {}),
+        ...(Object.keys(counterparty).length > 0 ? { heldBy: counterparty } : {}),
+    };
+    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';
+    if (isCollision)
+        ports.logger.warn(message);
+    else
+        ports.logger.debug(message);
+    ports.observability.breadcrumb(message, 'sync.coordination', isCollision ? 'warning' : 'info');
+    ports.observability.captureClaim(event);
+}

package/dist/transaction/transport/connectionManager.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Owns the sync engine's connection lifecycle: the state machine that carries a
+ * client from a healthy connection, through a dropout, and back to live. It
+ * watches the browser's online/offline and visibility events, probes real
+ * connectivity and session validity with {@link probeNetwork}, applies retry
+ * backoff with a ceiling and jitter, and runs a watchdog for the cases where
+ * the browser never fires an event (VPN flips, captive portals). When it
+ * decides to recover, it drives the reconnect sequence — bootstrap, then
+ * WebSocket connect — through the {@link ConnectionCallbacks.onReconnect}
+ * callback and reacts to the outcome.
+ *
+ * It deliberately does not perform the bootstrap, local-storage, or object-pool
+ * work itself; that lives in the embedding store, which the manager reaches
+ * only through its callbacks. One manager is created per store, started on the
+ * first successful connect and disposed on teardown.
+ *
+ * This is a plain state machine, not a reactive object: it lives in the
+ * settlement core, which carries no reactivity runtime (ADR 0016). A consumer
+ * that wants to render recovery progress mirrors the transitions through
+ * {@link ConnectionCallbacks.onStateChange} into its own observable state —
+ * which is what the reactive engine's store does.
+ *
+ *   CONNECTED ──(socket drop)──► PROBING_NETWORK ──► RECONNECTING ──► CONNECTED
+ *        │                              │                  │
+ *   (network lost)                      ▼                  ▼
+ *        ▼                        SESSION_EXPIRED       BACKOFF ──► PROBING_NETWORK
+ *     OFFLINE ──(online)──► PROBING_NETWORK
+ *        │
+ *        ▼
+ *   WAITING_FOR_NETWORK
+ *
+ * Three behaviors are worth calling out. A network return or tab focus during a
+ * backoff delay jumps straight to probing instead of waiting out the full
+ * interval. Reaching the retry ceiling while the browser reports offline parks
+ * in `waiting_for_network` rather than hard-reloading a browser that has no
+ * network. And a socket drop (close code 1006) goes straight to probing rather
+ * than the passive `offline` state — 1006 is generated locally and carries no
+ * connectivity signal, so on a healthy machine no online/offline event ever
+ * fires; only a genuine operating-system network loss parks in `offline` to
+ * wait for the `online` event.
+ */
+import { type ProbeResult } from './networkProbe.js';
+import type { AuthTokenGetter } from '../auth/credentialSource.js';
+import type { CredentialRefreshOutcome } from './credentialLifecycle.js';
+import { type Logger } from '../logger.js';
+import { type TransportObservability } from '../observability.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';
+} | {
+    type: 'NETWORK_ONLINE';
+} | {
+    type: 'TAB_VISIBLE';
+} | {
+    type: 'WS_CONNECTED';
+} | {
+    type: 'WS_DISCONNECTED';
+} | {
+    type: 'WS_SESSION_ERROR';
+} | {
+    type: 'WS_HANDSHAKE_FAILED';
+} | {
+    type: 'PROBE_SUCCESS';
+    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';
+} | {
+    type: 'RECONNECT_FAILED';
+} | {
+    type: 'BACKOFF_ELAPSED';
+} | {
+    type: 'BOOTSTRAP_FAILED_SESSION';
+} | {
+    type: 'MANUAL_RETRY';
+};
+export interface ConnectionCallbacks {
+    /** Run bootstrap + WebSocket reconnect. Returns the outcome. */
+    onReconnect: () => Promise<'success' | 'session_error' | 'network_error'>;
+    /**
+     * Re-mints the short-lived access credential (the `ek_`/`rk_`) and pushes it
+     * into the credential source, then reports the outcome. Invoked in the
+     * `refreshing_credential` state — that is, when a probe found the access key
+     * stale (`PROBE_CREDENTIAL_STALE`). The three outcomes map onto recovery:
+     *   - `'refreshed'`     → a fresh credential is in place; re-probe and reconnect.
+     *   - `'session_error'` → the long-lived login itself is gone (the mint
+     *                          returned null, a 401/403); terminal, so sign out.
+     *   - `'network_error'` → the mint endpoint was unreachable (offline, 5xx, or
+     *                          a throw); transient, so back off and retry rather
+     *                          than sign out.
+     * Optional: a deployment with no re-mint path (for example a static `apiKey`)
+     * omits it, and the state machine falls back to a plain re-probe.
+     */
+    onRefreshCredential?: () => Promise<CredentialRefreshOutcome>;
+    /** Called when the session is confirmed expired — route to signin. */
+    onSessionExpired: () => void;
+    /** Called to tear down the WebSocket when entering a dead state. */
+    onDisconnectWebSocket: () => void;
+    /**
+     * Fires on every state transition. It lets the embedding store mirror
+     * recovery progress into its visible `syncStatus`, so the UI can show
+     * "Reconnecting…" instead of a sticky "offline" while the machine cycles
+     * through `probing_network` → `reconnecting` → `backoff`. Optional; when
+     * omitted, the state machine is simply opaque to the UI.
+     */
+    onStateChange?: (next: ConnectionState, prev: ConnectionState) => void;
+}
+export interface ConnectionManagerOptions {
+    /**
+     * Sync-server base URL used for probes. Falls back to the env-based
+     * 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>;
+    /** Where transitions are logged. Defaults to silent. */
+    logger?: Logger;
+    /** Where dead-end states are reported. Defaults to silent. */
+    observability?: TransportObservability;
+}
+declare const DEFAULT_BACKOFF: {
+    readonly BASE_MS: 2000;
+    readonly MAX_MS: 30000;
+    readonly MAX_ATTEMPTS: 8;
+    readonly JITTER: 0.15;
+};
+export declare class ConnectionManager {
+    state: ConnectionState;
+    offlineSince: Date | null;
+    attempt: number;
+    lastProbeResult: ProbeResult | null;
+    private callbacks;
+    private backoffTimer;
+    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 readonly logger;
+    private readonly observability;
+    private handleBrowserOnline;
+    private handleBrowserOffline;
+    private handleVisibilityChange;
+    constructor(options?: ConnectionManagerOptions);
+    start(callbacks: ConnectionCallbacks): void;
+    dispose(): void;
+    send(event: ConnectionEvent): void;
+    private transition;
+    private onEnterState;
+    /**
+     * FSM effects are fire-and-forget by design (`onEnterState` is sync). Each
+     * effect catches its own operational failures and maps them onto an FSM
+     * event, so a rejection here means the machine wedged mid-transition
+     * (`send()` or a transition listener threw) with no retry timer armed past
+     * it — capture it instead of losing the reconnect loop silently.
+     */
+    private captureEffectFailure;
+    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;
+    private removeBrowserListeners;
+    private startWatchdog;
+    get isConnected(): boolean;
+    get isOffline(): boolean;
+    get isReconnecting(): boolean;
+    get isSessionExpired(): boolean;
+    get offlineDuration(): string | null;
+    private clearBackoffTimer;
+    private clearDebounceTimer;
+}
+export {};