@abloatai/humans 0.37.0

package/dist/local/sync/connectionManagerLifecycle.js

@@ -0,0 +1,126 @@
+import { AbloSessionError } from '@abloatai/transaction/errors';
+import { ConnectionManager } from './ConnectionManager.js';
+import { contextLogger, contextSocketObservability } from './contextPorts.js';
+export function createConnectionManager(host, kind) {
+    if (kind === 'agent')
+        return null;
+    return new ConnectionManager({
+        baseUrl: host.syncServerUrl,
+        getAuthToken: () => host.auth?.getAuthToken() ?? host.syncWebSocket.getAuthToken() ?? null,
+        logger: contextLogger,
+        observability: contextSocketObservability,
+    });
+}
+export async function waitForWebSocketConnected(host, timeoutMs) {
+    const ws = host.syncWebSocket;
+    if (ws.isConnected())
+        return true;
+    return new Promise((resolve) => {
+        let resolved = false;
+        const unsubscribe = ws.subscribe('connected', () => {
+            if (resolved)
+                return;
+            resolved = true;
+            unsubscribe();
+            clearTimeout(timer);
+            resolve(true);
+        });
+        const timer = setTimeout(() => {
+            if (resolved)
+                return;
+            resolved = true;
+            unsubscribe();
+            host.runtime.logger.debug(`[BaseSyncedStore] waitForWebSocketConnected timed out after ${timeoutMs}ms — initialize() will return but the next mutation may race the upgrade.`);
+            resolve(false);
+        }, timeoutMs);
+    });
+}
+export function startConnectionManager(host, kind) {
+    host.connectionManager = host.createConnectionManager(kind);
+    if (host.connectionManager) {
+        const manager = host.connectionManager;
+        // Preserve any externally-set onConnectionEvent — chain rather
+        // than overwrite, so subclasses that wire a secondary consumer
+        // still receive events.
+        const priorHook = host.onConnectionEvent;
+        host.onConnectionEvent = (event) => {
+            try {
+                priorHook?.(event);
+            }
+            catch { /* don't let subclass crash the FSM */ }
+            switch (event) {
+                case 'WS_CONNECTED':
+                    manager.send({ type: 'WS_CONNECTED' });
+                    break;
+                case 'WS_DISCONNECTED':
+                    manager.send({ type: 'WS_DISCONNECTED' });
+                    break;
+                case 'WS_SESSION_ERROR':
+                    manager.send({ type: 'WS_SESSION_ERROR' });
+                    break;
+                case 'WS_HANDSHAKE_FAILED':
+                    manager.send({ type: 'WS_HANDSHAKE_FAILED' });
+                    break;
+            }
+        };
+        manager.start({
+            onReconnect: () => host.performReconnect(),
+            onRefreshCredential: () => host.performCredentialRefresh(),
+            onSessionExpired: () => {
+                const err = new AbloSessionError('Session expired');
+                host.handleTerminalSessionError(err);
+            },
+            onDisconnectWebSocket: () => {
+                host.syncWebSocket.disconnect();
+            },
+            // Mirror FSM transitions into the visible `syncStatus.state` so
+            // the UI can show "Reconnecting…" while the FSM cycles through
+            // probing / reconnecting / backoff. Previously these states
+            // were opaque to the UI, leaving the sidebar pinned to
+            // "offline" for the entire recovery window — exactly the
+            // confusing UX the warning log was trying to surface.
+            //
+            // We only override `state` here; `error` / `progress` / etc.
+            // continue to be set by the WebSocket subscription handlers
+            // and bootstrap pipeline, which know more than the FSM does.
+            onStateChange: (next) => {
+                switch (next) {
+                    case 'connected':
+                        // Don't clobber an in-flight 'syncing' / 'idle' update
+                        // that the bootstrap pipeline might be midway through —
+                        // those handlers run their own `updateSyncStatus`. Only
+                        // promote out of an offline / reconnecting / error label.
+                        if (host.syncStatus.state === 'offline' ||
+                            host.syncStatus.state === 'reconnecting' ||
+                            host.syncStatus.state === 'error') {
+                            host.updateSyncStatus({ state: 'idle', offlineSince: undefined });
+                        }
+                        break;
+                    case 'probing_network':
+                    case 'refreshing_credential':
+                    case 'reconnecting':
+                    case 'backoff':
+                        // Active recovery — the UI should reflect that the FSM
+                        // is doing work, not that we've given up. (Re-minting a stale
+                        // access key is just another recovery step, surfaced the same
+                        // way; the user never sees a credential-level distinction.)
+                        if (host.syncStatus.state !== 'reconnecting') {
+                            host.updateSyncStatus({ state: 'reconnecting' });
+                        }
+                        break;
+                    case 'waiting_for_network':
+                    case 'offline':
+                        if (host.syncStatus.state !== 'offline') {
+                            host.updateSyncStatus({
+                                state: 'offline',
+                                offlineSince: host.syncStatus.offlineSince ?? new Date(),
+                            });
+                        }
+                        break;
+                    // 'session_expired' / 'validating_session' are handled by
+                    // the existing session-error / WS subscription paths.
+                }
+            },
+        });
+    }
+}

package/dist/local/sync/contextPorts.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The runtime context, sliced into the ports the settlement core's transport
+ * takes. The core is injected, never service-located (ADR 0016), while this
+ * package resolves its shared dependencies through `getContext()` — so these
+ * adapters bridge the two: each method reads the context at call time, which
+ * preserves the lazy semantics of `getContext()` (a context installed after
+ * construction is still picked up, and the pre-init fallback still applies).
+ */
+import type { Logger } from '@abloatai/transaction/logger';
+import type { SocketObservability } from '@abloatai/transaction/observability';
+/** The context's logger, resolved at call time. */
+export declare const contextLogger: Logger;
+/** The context's observability, resolved at call time, in the transport's shape. */
+export declare const contextSocketObservability: SocketObservability;
+/** The context's online-status provider, resolved at call time. */
+export declare const contextOnlineStatus: {
+    isOnline: () => boolean;
+};

package/dist/local/sync/contextPorts.js

@@ -0,0 +1,31 @@
+/**
+ * The runtime context, sliced into the ports the settlement core's transport
+ * takes. The core is injected, never service-located (ADR 0016), while this
+ * package resolves its shared dependencies through `getContext()` — so these
+ * adapters bridge the two: each method reads the context at call time, which
+ * preserves the lazy semantics of `getContext()` (a context installed after
+ * construction is still picked up, and the pre-init fallback still applies).
+ */
+import { getContext } from '../context.js';
+/** The context's logger, resolved at call time. */
+export const contextLogger = {
+    debug: (message, ...args) => { getContext().logger.debug(message, ...args); },
+    info: (message, ...args) => { getContext().logger.info(message, ...args); },
+    warn: (message, ...args) => { getContext().logger.warn(message, ...args); },
+    error: (message, ...args) => { getContext().logger.error(message, ...args); },
+};
+/** The context's observability, resolved at call time, in the transport's shape. */
+export const contextSocketObservability = {
+    breadcrumb: (message, category, level, data) => {
+        getContext().observability.breadcrumb(message, category, level, data);
+    },
+    captureWebSocketError: (details) => {
+        getContext().observability.captureWebSocketError(details);
+    },
+    captureClaim: (event) => { getContext().observability.captureClaim(event); },
+    captureConflict: (event) => { getContext().observability.captureConflict(event); },
+};
+/** The context's online-status provider, resolved at call time. */
+export const contextOnlineStatus = {
+    isOnline: () => getContext().onlineStatus.isOnline(),
+};

package/dist/local/sync/createClaimStream.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Creates a {@link ClaimStream} over a live sync connection. A claim is a
+ * short-lived, advisory lease a participant takes on an entity (or a field of
+ * one) to signal "I'm working on this"; the stream lets you take claims, see
+ * everyone else's, and watch the wait queue when a claim is contended.
+ *
+ * The stream is built directly on the sync WebSocket and shares that one
+ * connection. It learns about other participants' claims from the same
+ * `presence_update` frames the {@link createPresenceStream} presence stream
+ * consumes — the server piggybacks each participant's `activeClaims` on every
+ * presence frame — and sends its own claims as `claim_begin` and
+ * `claim_abandon` frames.
+ *
+ * Wire frames:
+ *   • Outbound `claim_begin` — announce a claim: `{ claimId, entityType,
+ *       entityId, description, field?, estimatedMs? }`.
+ *   • Outbound `claim_abandon` — release it: `{ claimId, entityType?,
+ *       entityId? }`.
+ *   • Inbound, via presence — `event.activeClaims`, each stamped with
+ *       `declaredAt` and `expiresAt`.
+ *   • Inbound `claim_rejected` — the server refused the claim, with conflict
+ *       metadata.
+ */
+import type { WsTransport } from '@abloatai/transaction/transport/wsTransport';
+import type { ClaimOptions, Claim, ClaimStream, PresenceTarget } from '@abloatai/transaction/types/streams';
+import { type Logger } from '@abloatai/transaction/logger';
+/**
+ * The wire capability the claim stream actually uses: subscribe to typed
+ * inbound frames, check liveness, and send outbound frames. The duplex
+ * `WsTransport` satisfies it, so production wiring is unchanged — but depending on the port
+ * rather than the whole socket class lets a test drive it with a plain object,
+ * no cast. `Pick` carries the exact (generic, typed-payload) `subscribe`
+ * signature, so every handler stays fully typed.
+ */
+export type ClaimTransport = Pick<WsTransport, 'subscribe' | 'isConnected' | 'send'>;
+export interface ClaimStreamConfig {
+    /** Identity used to filter our own active claims out of `others`. */
+    participantId: string;
+    /** Where the coordination trace is logged. Defaults to silent. */
+    logger?: Logger;
+}
+export interface AttachableClaimStream extends ClaimStream {
+    /**
+     * Mints a lease directly: sends the `claim_begin` frame and returns a held
+     * {@link Claim} that carries no row `data` (the resource layer reads the row
+     * and stamps it). This is an internal entry point, not part of the public
+     * {@link ClaimStream}; application code takes a claim through
+     * `ablo.<model>.claim({ id })`, which is built on this.
+     */
+    claim(target: PresenceTarget, opts?: ClaimOptions): Claim;
+    attach(transport: ClaimTransport): void;
+    /**
+     * Seeds the participant identity once the host resolves it. The stream can
+     * be built before identity is known — a hosted client learns who it is
+     * from its credential's scope during connect — and until then the
+     * construction-time id (possibly empty) would let the participant's own
+     * claims into `others`. Idempotent; later frames filter on the new id.
+     */
+    setParticipant(participant: {
+        id: string;
+    }): void;
+    dispose(): void;
+}
+export declare function createClaimStream(config: ClaimStreamConfig, transport?: ClaimTransport | null): AttachableClaimStream;