@abloatai/ablo 0.35.0 → 0.37.0

package/dist/transaction/transport/commitFrames.js

@@ -1,134 +0,0 @@
-/**
- * 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

@@ -1,215 +0,0 @@
-/**
- * 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 {};