@abloatai/humans 0.37.0

package/src/local/adapters/alwaysOnline.ts

@@ -0,0 +1,20 @@
+/**
+ * An {@link OnlineStatusProvider} that always reports the client as online.
+ * Server-side runtimes — Node processes, agents, and sidecars — have no
+ * browser network stack to lose, so there is no offline state to track. A
+ * dropped database connection surfaces as a database error, not a network
+ * transition. This is the server-side counterpart to the browser's
+ * connectivity-aware provider, which watches the real online/offline signal.
+ */
+
+import type { OnlineStatusProvider } from '../interfaces/index.js';
+
+/**
+ * Returns an OnlineStatusProvider that always reports online.
+ * `onStatusChange` never fires — the network never transitions.
+ */
+export function alwaysOnline(): OnlineStatusProvider {
+  return {
+    isOnline: () => true,
+  };
+}

package/src/local/adapters/inMemoryStorage.ts

@@ -0,0 +1,141 @@
+/**
+ * An in-memory {@link ObjectStoreContract} implementation for runtimes
+ * without IndexedDB, such as Node processes, agents, and tests. It keeps
+ * records in a map and maintains simple secondary indexes, satisfying the
+ * same contract the IndexedDB-backed store implements — so if the two ever
+ * diverge, the mismatch becomes a typecheck error here rather than a silent
+ * failure at a call site.
+ *
+ * Nothing is persisted; the data is cleared on process restart. That is
+ * deliberate: server-side runtimes and agent workers rebuild their state from
+ * the server's delta stream rather than from a local cache.
+ */
+
+import type { ObjectStoreContract } from '../stores/ObjectStoreContract.js';
+
+export class InMemoryObjectStore implements ObjectStoreContract {
+  private data = new Map<string, Record<string, unknown>>();
+  private indexes = new Map<string, Map<string, Set<string>>>();
+
+  constructor(
+    public readonly modelName: string,
+    public readonly storeName: string,
+    indexNames: string[] = [],
+  ) {
+    for (const name of indexNames) {
+      this.indexes.set(name, new Map());
+    }
+  }
+
+  add(record: Record<string, unknown>): Promise<void> {
+    const id = record.id as string;
+    if (!id) throw new TypeError('In-memory record must carry an id');
+    if (this.data.has(id)) {
+      const error = new Error(`Record already exists: ${id}`);
+      error.name = 'ConstraintError';
+      throw error;
+    }
+    this.data.set(id, { ...record });
+    this.addToIndexes(id, record);
+    return Promise.resolve();
+  }
+
+  put(record: Record<string, unknown>): Promise<void> {
+    this.putSync(record);
+    return Promise.resolve();
+  }
+
+  /** Synchronous fast path used by Database.processDeltaBatch in memory mode. */
+  putSync(record: Record<string, unknown>): void {
+    const id = record.id as string;
+    if (!id) return;
+
+    // Remove from old index entries if updating
+    const existing = this.data.get(id);
+    if (existing) {
+      this.removeFromIndexes(id, existing);
+    }
+
+    this.data.set(id, { ...record });
+    this.addToIndexes(id, record);
+  }
+
+  get(id: string): Promise<Record<string, unknown> | undefined> {
+    return Promise.resolve(this.getSync(id));
+  }
+
+  /** Synchronous fast path used by Database.processDeltaBatch in memory mode. */
+  getSync(id: string): Record<string, unknown> | undefined {
+    return this.data.get(id);
+  }
+
+  getAll(): Promise<Record<string, unknown>[]> {
+    return Promise.resolve([...this.data.values()]);
+  }
+
+  delete(id: string): Promise<void> {
+    this.deleteSync(id);
+    return Promise.resolve();
+  }
+
+  /** Synchronous fast path used by Database.processDeltaBatch in memory mode. */
+  deleteSync(id: string): void {
+    const existing = this.data.get(id);
+    if (existing) {
+      this.removeFromIndexes(id, existing);
+      this.data.delete(id);
+    }
+  }
+
+  getAllFromIndex(
+    indexName: string,
+    value: IDBValidKey,
+  ): Promise<Record<string, unknown>[]> {
+    const index = this.indexes.get(indexName);
+    if (!index) return Promise.resolve([]);
+    // The in-memory index stores values as strings (it doesn't support
+    // the full IDB key range — Date / BufferSource / arrays). For the
+    // overwhelmingly-common case of string FK ids, coercing through
+    // String() preserves the existing behavior while satisfying the
+    // shared `ObjectStoreContract` signature.
+    const ids = index.get(String(value));
+    if (!ids) return Promise.resolve([]);
+    return Promise.resolve(
+      [...ids]
+        .map((id) => this.data.get(id))
+        .filter((r): r is Record<string, unknown> => r != null),
+    );
+  }
+
+  clear(): Promise<void> {
+    this.data.clear();
+    for (const index of this.indexes.values()) {
+      index.clear();
+    }
+    return Promise.resolve();
+  }
+
+  /** No-op — in-memory stores don't need closing. */
+  markAsClosing(): void {}
+
+  private addToIndexes(id: string, record: Record<string, unknown>): void {
+    for (const [indexName, indexMap] of this.indexes) {
+      const value = record[indexName];
+      if (value != null) {
+        const key = String(value);
+        if (!indexMap.has(key)) indexMap.set(key, new Set());
+        indexMap.get(key)!.add(id);
+      }
+    }
+  }
+
+  private removeFromIndexes(id: string, record: Record<string, unknown>): void {
+    for (const [indexName, indexMap] of this.indexes) {
+      const value = record[indexName];
+      if (value != null) {
+        const key = String(value);
+        indexMap.get(key)?.delete(id);
+      }
+    }
+  }
+}

package/src/local/client/clientPrelude.ts

@@ -0,0 +1,112 @@
+/**
+ * The prelude every interactive client resolves before anything is constructed.
+ *
+ * One pass over the options bag settles the values the composition root then
+ * spends: the credential and its refresh resolver, the base URL, the logger,
+ * and this participant's identity. Nothing here opens a socket, allocates a
+ * store, or touches IndexedDB — so a misconfiguration (a secret key in the
+ * browser, the removed `databaseUrl` option, a CLI key pointing at another
+ * project) fails while the stack still points at the caller's own setup.
+ *
+ * `./Ablo.ts` calls this once and hands the result to whichever client the
+ * plugin list selected.
+ */
+
+import type { ParticipantKind } from '@abloatai/transaction/types/participant';
+import type { Logger } from '@abloatai/transaction/logger';
+import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
+import {
+  createAuthCredentialSource,
+  type AuthCredentialSource,
+} from '@abloatai/transaction/auth/credentialSource';
+import {
+  assertBrowserSafety,
+  readProcessEnv,
+  rejectRemovedDatabaseUrlOption,
+  resolveApiKey,
+  resolveAuthToken,
+  resolveBaseURL,
+  resolveCredentialResolver,
+  warnIfCliKeyMismatch,
+  type CredentialProvider,
+} from '@abloatai/transaction/auth/apiKey';
+import type { AbloOptions, InternalAbloOptions } from './options.js';
+import { createConsoleLogger, resolveLogLevel } from './consoleLogger.js';
+
+/** What one pass over the options bag settles, for the builders downstream. */
+export interface ClientPrelude<S extends SchemaRecord> {
+  /** The same options, widened to the fields only the SDK's own callers set. */
+  readonly internalOptions: InternalAbloOptions<S>;
+  /** The configured key — a literal key string, or a resolver to call. */
+  readonly configuredApiKey: string | CredentialProvider | null;
+  readonly configuredAuthToken: string | null;
+  /**
+   * The credential lifecycle's single resolver, or `null` when auth is static.
+   * It drives both the reactive re-mint (the connection's `credential_stale`
+   * state) and the proactive refresh timer with its wake/online/focus triggers.
+   */
+  readonly credentialResolver: CredentialProvider | null;
+  readonly authCredentials: AuthCredentialSource;
+  readonly logger: Logger;
+  readonly url: string;
+  /**
+   * Identity routing: agents identify by agentId, users by user.id. The server
+   * stamps `isAgent` on outbound presence frames from the connection's
+   * authenticated identity prefix; the local `self` entry uses the kind we know
+   * at construction.
+   */
+  readonly participantId: string;
+  readonly kind: ParticipantKind;
+}
+
+/**
+ * Resolve the prelude, failing fast on a misconfiguration.
+ *
+ * Three checks fire here rather than downstream: a secret key reaching the
+ * browser, the removed `databaseUrl` option, and a CLI key scoped to a
+ * different project than the one being addressed (a warning, not a throw).
+ */
+export function resolveClientPrelude<S extends SchemaRecord>(
+  options: AbloOptions<S>,
+): ClientPrelude<S> {
+  const internalOptions = options as InternalAbloOptions<S>;
+  const env = readProcessEnv();
+  const authInput = { options, env };
+  const configuredApiKey = resolveApiKey(authInput);
+  const configuredAuthToken = resolveAuthToken(authInput);
+  const credentialResolver = resolveCredentialResolver(configuredApiKey);
+  const authCredentials = createAuthCredentialSource(
+    // eslint-disable-next-line @typescript-eslint/no-deprecated -- load-bearing on the self-hosted path; server-internal cap-mint (Phase 3) not shipped
+    internalOptions.capabilityToken ?? configuredAuthToken,
+  );
+  rejectRemovedDatabaseUrlOption(options);
+  assertBrowserSafety({
+    apiKey: configuredApiKey,
+    dangerouslyAllowBrowser: options.dangerouslyAllowBrowser,
+  });
+
+  // Custom logger wins; otherwise build the default `[Ablo]` logger at the level
+  // resolved from `debug`/`logLevel`/`ABLO_LOG_LEVEL` (default `warn`).
+  const logger =
+    internalOptions.logger ??
+    createConsoleLogger(resolveLogLevel({ debug: options.debug, logLevel: options.logLevel }));
+  void warnIfCliKeyMismatch(authInput, (m) => { logger.warn(m); });
+
+  const participantId =
+    // eslint-disable-next-line @typescript-eslint/no-deprecated -- self-hosted identity fallback; hosted path derives identity from the apiKey scope
+    (internalOptions.kind === 'agent' ? internalOptions.agentId : internalOptions.user?.id) ?? '';
+  // eslint-disable-next-line @typescript-eslint/no-deprecated -- self-hosted default; hosted path ignores it (server derives kind from the apiKey scope)
+  const kind = internalOptions.kind ?? 'user';
+
+  return {
+    internalOptions,
+    configuredApiKey,
+    configuredAuthToken,
+    credentialResolver,
+    authCredentials,
+    logger,
+    url: resolveBaseURL(authInput),
+    participantId,
+    kind,
+  };
+}

package/src/local/client/consoleLogger.ts

@@ -0,0 +1,60 @@
+/**
+ * The default `[Ablo]` console logger and its level resolution.
+ *
+ * These helpers are exported so any entry point that needs a default logger can
+ * reuse the same level gating rather than hand-rolling a console wrapper.
+ */
+
+import type { Logger } from '@abloatai/transaction/logger';
+
+// ── Default console logger ────────────────────────────────────────────────
+
+/**
+ * Level threshold for the default console logger.
+ *
+ * The SDK emits a `debug` line per model and per property during schema
+ * registration (see `ModelRegistry`), plus assorted lifecycle chatter. That
+ * is verbose by design but carries no actionable signal for app consumers, so
+ * the default threshold is `warn` — `debug`/`info` are dropped unless a
+ * consumer opts in.
+ *
+ * Opt back in with `ABLO_LOG_LEVEL=debug` (or `info`/`warn`/`error`/`silent`).
+ * Passing a custom `logger` to `Ablo({ logger })` bypasses this entirely.
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+const LOG_LEVEL_RANK: Record<LogLevel, number> = { debug: 10, info: 20, warn: 30, error: 40, silent: 99 };
+
+/**
+ * Resolve the effective level. Precedence: explicit `logLevel` option →
+ * `debug: true` (⇒ debug) → `ABLO_LOG_LEVEL` env → default `warn`. `debug: false`
+ * / omitted just means "don't raise the level" — it falls through to env/default
+ * rather than force-silencing an ops-set env override.
+ */
+export function resolveLogLevel(opts?: { debug?: boolean; logLevel?: LogLevel }): LogLevel {
+  if (opts?.logLevel && opts.logLevel in LOG_LEVEL_RANK) return opts.logLevel;
+  if (opts?.debug === true) return 'debug';
+  // `globalThis.process` guard keeps this safe in browser/edge runtimes that
+  // have no `process` binding — there we fall through to the default.
+  const raw = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env?.ABLO_LOG_LEVEL;
+  const normalized = raw?.toLowerCase();
+  if (normalized && normalized in LOG_LEVEL_RANK) return normalized as LogLevel;
+  return 'warn';
+}
+
+/**
+ * Builds the default logger, gated at `level` and prefixed `[Ablo]` so its lines
+ * stand out in a console full of other tools' output.
+ */
+export function createConsoleLogger(level: LogLevel): Logger {
+  const threshold = LOG_LEVEL_RANK[level];
+  const emit = (lvl: LogLevel, fn: (...args: unknown[]) => void, args: unknown[]) => {
+    if (typeof console === 'undefined' || LOG_LEVEL_RANK[lvl] < threshold) return;
+    fn('[Ablo]', ...args);
+  };
+  return {
+    debug: (...args: unknown[]) => { emit('debug', console.debug, args); },
+    info: (...args: unknown[]) => { emit('info', console.info, args); },
+    warn: (...args: unknown[]) => { emit('warn', console.warn, args); },
+    error: (...args: unknown[]) => { emit('error', console.error, args); },
+  };
+}

package/src/local/client/createInternalComponents.ts

@@ -0,0 +1,163 @@
+/**
+ * Builds the internal component graph the client runs on.
+ *
+ * From the caller's options and schema this wires together the model registry,
+ * object pool, bootstrap helper, database, sync client, and hydration
+ * coordinator. Each component depends on the one before it, so construction
+ * order matters; keeping it here means the client constructor does not have to
+ * know that order.
+ */
+
+import { Database } from '../Database.js';
+import { ModelRegistry, setActiveRegistry } from '../ModelRegistry.js';
+import { InstanceCache } from '../InstanceCache.js';
+import { SyncClient } from '../SyncClient.js';
+import { OnDemandLoader } from '../sync/OnDemandLoader.js';
+import { BootstrapFetcher } from '../sync/BootstrapFetcher.js';
+import type { AuthCredentialSource } from '@abloatai/transaction/auth/credentialSource';
+import type { Schema, SchemaRecord } from '@abloatai/transaction/schema/schema';
+import { loadsAtBootstrap, type LoadStrategy } from '@abloatai/transaction/schema/loadStrategy';
+import { resolveBootstrapBaseUrl } from '@abloatai/transaction/auth/apiKey';
+import {
+  shouldUseInMemoryPersistence,
+  type AbloPersistence,
+} from '../persistence.js';
+import type {
+  DurableWriteStore,
+  DurableWritesConfig,
+} from '@abloatai/transaction/durableWrites';
+import type { RuntimeContext } from '../RuntimeContext.js';
+import { globalRuntime } from '../context.js';
+import { resolveDurableWrites } from '@abloatai/transaction/durableWrites';
+
+export interface InternalComponentsInput<S extends SchemaRecord> {
+  readonly schema: Schema<S>;
+  /** The WebSocket URL. Used to derive the bootstrap HTTP base URL when the
+   * caller has not overridden `bootstrapBaseUrl`. */
+  readonly url: string;
+  readonly options: {
+    readonly maxPoolSize?: number;
+    readonly bootstrapBaseUrl?: string;
+    readonly syncGroups?: string[];
+    readonly persistence?: AbloPersistence;
+    readonly offline?: boolean;
+    readonly inMemory?: boolean;
+    readonly durableWrites?: DurableWritesConfig;
+    /** @deprecated Use `durableWrites`. */
+    readonly commitOutbox?: DurableWriteStore;
+  };
+  readonly auth?: AuthCredentialSource;
+  /** The owning client's runtime, threaded into every component built here.
+   *  Defaults to the module-global bridge for direct construction. */
+  readonly runtime?: RuntimeContext;
+}
+
+export interface InternalComponents {
+  readonly modelRegistry: ModelRegistry;
+  readonly objectPool: InstanceCache;
+  readonly bootstrapHelper: BootstrapFetcher;
+  readonly database: Database;
+  readonly syncClient: SyncClient;
+  readonly hydration: OnDemandLoader;
+}
+
+export function createInternalComponents<S extends SchemaRecord>(
+  input: InternalComponentsInput<S>,
+): InternalComponents {
+  const { schema, url, options, auth } = input;
+  const runtime = input.runtime ?? globalRuntime;
+
+  // The registry is created here, but model registration happens in the caller,
+  // which owns the schema-to-class translation.
+  const modelRegistry = new ModelRegistry({
+    validateOnRegister: false,
+    allowLateReferences: true,
+    runtime,
+  });
+  setActiveRegistry(modelRegistry);
+
+  const objectPool = new InstanceCache(
+    { maxSize: options.maxPoolSize ?? 10000, runtime },
+    modelRegistry,
+  );
+
+  const bootstrapBaseUrl = resolveBootstrapBaseUrl({
+    url,
+    bootstrapBaseUrl: options.bootstrapBaseUrl,
+  });
+  const bootstrapHelper = new BootstrapFetcher({
+    baseUrl: bootstrapBaseUrl,
+    syncGroups: options.syncGroups,
+    instantModels: deriveInstantModels(schema),
+    getAuthToken: auth?.getAuthToken,
+    runtime,
+  });
+
+  const database = new Database(modelRegistry, bootstrapHelper, {
+    // By default there is no browser-local durable store unless the caller asks
+    // for one. Node and edge runtimes always use the in-memory store because
+    // IndexedDB is unavailable there.
+    inMemory: shouldUseInMemoryPersistence(options),
+    runtime,
+  });
+  const durableWrites = resolveDurableWrites(options);
+  const syncClient = new SyncClient(
+    objectPool,
+    database,
+    durableWrites.store,
+    durableWrites.namespace ?? url,
+    runtime,
+  );
+
+  // Lazy-load lane: hydrates the object pool and IndexedDB on demand for
+  // entities not in scope at bootstrap (`load: 'lazy'` models, or an entity
+  // reached by deep link before the pool warmed up). Single-flight, with
+  // write-through to IndexedDB.
+  const hydration = new OnDemandLoader({
+    objectPool,
+    database,
+    registry: modelRegistry,
+    schema,
+    baseUrl: bootstrapBaseUrl,
+    getAuthToken: auth?.getAuthToken,
+    runtime,
+  });
+
+  // Drop the lazy-lane hydration ledger on reconnect. While connected, the
+  // WebSocket delta stream keeps hydrated rows fresh so repeat reads serve
+  // pure-local with no network; after a drop, deltas may have been missed, so
+  // the next read of each query must re-confirm with the server once.
+  syncClient.on('sync:reconnecting', () => { hydration.invalidate(); });
+
+  return {
+    modelRegistry,
+    objectPool,
+    bootstrapHelper,
+    database,
+    syncClient,
+    hydration,
+  };
+}
+
+/**
+ * Derives the set of models to fetch in the initial bootstrap request from each
+ * model's load strategy. Models declared `load: 'lazy'` are left out of the
+ * bootstrap and fetched on demand instead. The default strategy is
+ * `'instant'`, which includes the model.
+ */
+function deriveInstantModels<S extends SchemaRecord>(
+  schema: Schema<S>,
+): string[] {
+  const schemaModels =
+    (schema as { models?: Record<string, unknown> }).models ?? schema;
+  return Object.entries(schemaModels).flatMap(([key, def]) => {
+    if (!def || typeof def !== 'object' || !('load' in def)) {
+      return [key]; // no load → the default strategy
+    }
+    const load = (def as { load?: LoadStrategy }).load;
+    if (loadsAtBootstrap(load)) {
+      return [(def as { typename?: string }).typename ?? key];
+    }
+    return [];
+  });
+}