@abloatai/humans 0.37.0

package/src/local/sync/bootstrapApply.ts

@@ -0,0 +1,130 @@
+/**
+ * Applies a bootstrap result to the in-memory object pool. When a client
+ * connects, the server sends either a full snapshot of the models it can see or
+ * a partial catch-up of the deltas it missed. These functions route that result
+ * into the pool, protect entities that arrived mid-bootstrap from being swept
+ * away as stale, and replay any deltas that queued while the bootstrap was in
+ * flight.
+ *
+ * The functions here reach their host store only through the small
+ * {@link PoolContext} interface, not the store's concrete class, so the two can
+ * reference each other without forming an import cycle. The pool writes
+ * themselves — creating models, healing partial rows, upserting, and removing
+ * stale local copies the server no longer reports — are performed by the sync
+ * client behind that interface.
+ */
+
+import { globalRuntime } from '../context.js';
+import type { RuntimeContext } from '../RuntimeContext.js';
+import type { BootstrapResult } from '../Database.js';
+import type { SyncDelta } from './SyncWebSocket.js';
+
+/** Counts describing what applying a bootstrap changed in the pool: entities
+ *  added, updated, removed, skipped, and healed, plus the elapsed time. */
+export interface RehydrationStats {
+  added: number;
+  updated: number;
+  removed: number;
+  skipped: number;
+  healed: number;
+  elapsedMs: number;
+}
+
+/**
+ * The methods the bootstrap-apply functions call back into on the host store.
+ * The two data-application methods arrive with relation enrichment already
+ * bound by the host, so a subclass override of how relations are enriched still
+ * takes effect through this interface.
+ */
+export interface PoolContext {
+  /** The owning client's runtime. Defaults to the module-global bridge. */
+  readonly runtime?: RuntimeContext;
+  /** Applies persisted delta results to the in-memory pool, with the host's relation enrichment bound. */
+  applyDeltaBatchToPool(results: NonNullable<BootstrapResult['deltaResults']>): void;
+  /** Writes bootstrap data into the pool: creates models, heals partial rows, upserts, and removes stale local copies the server no longer reports. */
+  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, used to work out which entities must survive the stale-sweep (see {@link collectDeltaProtectedIds}). */
+  getAllPoolIds(): string[];
+  /** Deltas that queued while a bootstrap was in flight; null when no bootstrap
+   *  is running. The host backs this with a field exposed through accessors. */
+  bootstrapDeltaQueue: SyncDelta[] | null;
+  /** Applies a complete set of deltas to the pool atomically — one write, one
+   *  re-render. This entry point lives on the host, not in this module. */
+  applyDeltaFrame(deltas: SyncDelta[]): void;
+}
+
+/**
+ * Applies a bootstrap result to the in-memory pool and returns what changed.
+ * A full bootstrap creates, heals, and upserts models and removes stale local
+ * copies the server no longer reports; a partial bootstrap routes the missed
+ * deltas through the delta-apply path so deletions evict their entities. See
+ * {@link RehydrationStats} for the returned counts.
+ */
+export function applyBootstrapToPool(
+  ctx: PoolContext,
+  bootstrapResult: BootstrapResult,
+  protectedIds?: ReadonlySet<string>,
+): RehydrationStats {
+  const { bootstrapData } = bootstrapResult;
+
+  // Partial bootstrap: the missed deltas are already written to the local
+  // store. Route the same results through the delta-apply path so the
+  // in-memory pool also evicts deleted entities and updates modified ones.
+  // Without this, a reconnect delete persists locally but its stale copy
+  // lingers in the pool 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();
+
+  // Creates models, heals partial rows, upserts, and removes stale local copies.
+  const stats = ctx.applyBootstrapDataToPool(bootstrapData, protectedIds);
+
+  const elapsedMs = Math.round((typeof performance !== 'undefined' ? performance.now() : Date.now()) - start);
+
+  (ctx.runtime ?? globalRuntime).logger.info('[BaseSyncedStore] Bootstrap applied', {
+    ...stats, elapsedMs, poolSize: ctx.getPoolSize(),
+  });
+
+  return { ...stats, elapsedMs };
+}
+
+/** Collects the ids that must survive the post-bootstrap stale-sweep: entities added by deltas that arrived while the bootstrap was in flight. */
+export function collectDeltaProtectedIds(
+  ctx: PoolContext,
+  preBootstrapIds: ReadonlySet<string>,
+): Set<string> {
+  const protectedIds = new Set<string>();
+  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;
+}
+
+/** Replays the deltas that queued while a bootstrap was in flight, applying them as one atomic frame. */
+export function replayQueuedDeltas(ctx: PoolContext): void {
+  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/src/local/sync/commitFrames.ts

@@ -0,0 +1,16 @@
+/**
+ * Moved to the settlement core with the duplex transport (ADR 0016): the
+ * commit-path frame builders are stateless wire helpers. This path re-exports
+ * them so existing importers stay unchanged. The core's `buildCommitFrame`
+ * takes the structural `CommitFrameOperation` slice, which this package's
+ * `MutationOperation` satisfies.
+ */
+
+export {
+  buildCommitFrame,
+  parseNotifications,
+  recordClaim,
+  type CommitAck,
+  type CommitFrameOperation,
+  type ClaimTracePorts,
+} from '@abloatai/transaction/transport/commitFrames';

package/src/local/sync/connectionManagerLifecycle.ts

@@ -0,0 +1,158 @@
+import { AbloSessionError } from '@abloatai/transaction/errors';
+import type { ParticipantKind } from '@abloatai/transaction/types/participant';
+import { ConnectionManager } from './ConnectionManager.js';
+import type { DefaultCollaborationEvents, EventMap, SyncWebSocket } from './SyncWebSocket.js';
+import type { SyncStatus } from '../storeContract.js';
+import type { AuthCredentialSource } from '@abloatai/transaction/auth/credentialSource';
+import type { RuntimeContext } from '../RuntimeContext.js';
+import { contextLogger, contextSocketObservability } from './contextPorts.js';
+
+export interface ConnectionManagerHost<
+  TCollaboration extends EventMap<TCollaboration> = DefaultCollaborationEvents,
+> {
+  connectionManager: ConnectionManager | null;
+  onConnectionEvent?: (event: string) => void;
+  syncWebSocket: SyncWebSocket<TCollaboration>;
+  syncStatus: SyncStatus;
+  createConnectionManager(kind?: ParticipantKind): ConnectionManager | null;
+  performReconnect(): Promise<'success' | 'session_error' | 'network_error'>;
+  performCredentialRefresh(): Promise<'refreshed' | 'session_error' | 'network_error'>;
+  handleTerminalSessionError(error: Error): void;
+  updateSyncStatus(updates: Partial<SyncStatus>): void;
+  syncServerUrl?: string;
+  auth?: AuthCredentialSource;
+  runtime: RuntimeContext;
+}
+
+export function createConnectionManager<TCollaboration extends EventMap<TCollaboration>>(
+  host: Pick<ConnectionManagerHost<TCollaboration>, 'syncServerUrl' | 'auth' | 'syncWebSocket'>,
+  kind?: ParticipantKind,
+): ConnectionManager | null {
+  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<TCollaboration extends EventMap<TCollaboration>>(
+  host: Pick<ConnectionManagerHost<TCollaboration>, 'syncWebSocket' | 'runtime'>,
+  timeoutMs: number,
+): Promise<boolean> {
+  const ws = host.syncWebSocket;
+  if (ws.isConnected()) return true;
+  return new Promise<boolean>((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<TCollaboration extends EventMap<TCollaboration>>(
+  host: ConnectionManagerHost<TCollaboration>,
+  kind?: ParticipantKind,
+): void {
+    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: string) => {
+        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/src/local/sync/contextPorts.ts

@@ -0,0 +1,37 @@
+/**
+ * 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';
+import type { Logger } from '@abloatai/transaction/logger';
+import type { SocketObservability } from '@abloatai/transaction/observability';
+
+/** The context's logger, resolved at call time. */
+export const contextLogger: Logger = {
+  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: SocketObservability = {
+  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: (): boolean => getContext().onlineStatus.isOnline(),
+};