@abloatai/humans 0.37.0

package/src/local/client/storeLifecycle.ts

@@ -0,0 +1,343 @@
+/**
+ * The materialiser's lifecycle: the first credential mint, identity
+ * resolution, the credential-refresh machinery, and the idempotent `ready()`
+ * that drives the store's initialize generator to completion. Extracted from
+ * the interactive composition root (docs/plans/package-split.md):
+ * the engine wires it with the prelude's credential slice and consumes
+ * `ready`; resolved identity flows back through one callback, so the
+ * engine-side state it seeds (the self locals, the streams) stays with the
+ * engine.
+ */
+
+import type { SchemaRecord, Schema } from '@abloatai/transaction/schema/schema';
+import type { ParticipantKind } from '@abloatai/transaction/types/participant';
+import type { Logger } from '@abloatai/transaction/logger';
+import type { AuthCredentialSource } from '@abloatai/transaction/auth/credentialSource';
+import type { RefreshScheduler } from '@abloatai/transaction/auth';
+import type { CredentialProvider } from '@abloatai/transaction/auth/apiKey';
+import { resolveParticipantIdentity } from '@abloatai/transaction/auth/identity';
+import {
+  AbloAuthenticationError,
+  AbloConnectionError,
+  toAbloError,
+} from '@abloatai/transaction/errors';
+import type { AbloError } from '@abloatai/transaction/errors';
+import type { InternalAbloOptions } from './options.js';
+import type { StoreCluster } from './storeCluster.js';
+
+/** What identity resolution settled, handed back for the engine to seed. */
+export interface IdentitySeed {
+  readonly userId: string;
+  readonly participantKind: ParticipantKind;
+  /** The resolved account scope; null until known. */
+  readonly accountScope: string | null;
+  readonly syncGroups: readonly string[];
+}
+
+export interface StoreLifecycle {
+  /**
+   * Drives initialization to completion: first mint, identity resolution,
+   * seeding, then the store's initialize generator. Idempotent — the first
+   * call starts it, later calls share the promise; a failed attempt clears
+   * the memo so retry triggers can re-bootstrap.
+   */
+  ready: () => Promise<void>;
+  /** Stops the credential refresh scheduler, if identity resolution installed one. */
+  dispose(): void;
+}
+
+export interface StoreLifecycleDeps<S extends SchemaRecord> {
+  readonly cluster: StoreCluster;
+  readonly schema: Schema<S>;
+  readonly internalOptions: InternalAbloOptions<S>;
+  readonly authCredentials: AuthCredentialSource;
+  readonly credentialResolver: CredentialProvider | null;
+  readonly configuredApiKey: string | CredentialProvider | null;
+  readonly configuredAuthToken: string | null;
+  readonly url: string;
+  readonly kind: ParticipantKind;
+  readonly logger: Logger;
+  /** The engine's up-front options validation; a present error makes `ready()` reject with it. */
+  readonly validationError: AbloError | null;
+  /** Seeds resolved identity into the engine's own state: the self locals and the streams. */
+  readonly onIdentityResolved: (seed: IdentitySeed) => void;
+}
+
+/**
+ * Wires the credential machinery onto the cluster and returns the `ready`
+ * the client exposes. Wiring happens now — the refresh lifecycle, the
+ * lazy-query auth recovery, the executor binding, and the opt-in auto-start;
+ * the first mint waits for `ready()` so the first connection carries a
+ * token.
+ */
+export function startStoreLifecycle<S extends SchemaRecord>(
+  deps: StoreLifecycleDeps<S>,
+): StoreLifecycle {
+  const {
+    cluster,
+    schema,
+    internalOptions,
+    authCredentials,
+    credentialResolver,
+    configuredApiKey,
+    configuredAuthToken,
+    url,
+    kind,
+    logger,
+    validationError,
+    onIdentityResolved,
+  } = deps;
+  const { store, components, runtime } = cluster;
+  const { bootstrapHelper, hydration, syncClient } = components;
+
+  // Hand the credential lifecycle to the client (refresher + proactive refresh
+  // timer + wake/online/focus re-mint). Installed once here so refresh works for
+  // any consumer of `Ablo({ auth })`, not only those who render `<AbloProvider>`.
+  // The first mint happens in `ready()` so the first connection carries a token.
+  //
+  // Long-lived server clients also get the pre-roll timer on windowless hosts
+  // (`proactiveInNode`): their socket must renew its `rk_` or `ek_` before the
+  // server's keepalive reaper closes it (4001 `credential_expired`). Two signals
+  // qualify — an agent or system participant, and an absolute endpoint-string
+  // `apiKey` (a relative one can't be fetched in Node, so an absolute URL is
+  // unambiguously a deliberate server client). User-kind clients in Node (an
+  // SSR/RSC module evaluating scaffolded browser code) stay reactive-only.
+  if (credentialResolver) {
+    const rawEndpoint = internalOptions.authEndpoint ?? internalOptions.apiKey;
+    const absoluteEndpoint =
+      typeof rawEndpoint === 'string' && /^https?:\/\//i.test(rawEndpoint);
+    store.startCredentialLifecycle(credentialResolver, {
+      /* eslint-disable @typescript-eslint/no-deprecated -- `kind` gates the self-hosted proactive pre-roll; hosted path derives it from the apiKey scope */
+      proactiveInNode:
+        internalOptions.kind === 'agent' ||
+        internalOptions.kind === 'system' ||
+        absoluteEndpoint,
+      /* eslint-enable @typescript-eslint/no-deprecated */
+    });
+  }
+
+  // Put the lazy-query lane on the same auth-recovery path as the WebSocket probe
+  // and the proactive pre-roll: a 401 on `/sync/query` re-mints via the store's
+  // single-flight lifecycle and replays once, instead of silently returning empty
+  // rows against an expired `ek_` until the next proactive tick. Late-bound
+  // because the coordinator is constructed before the store exists.
+  hydration.setCredentialRecovery((recovery) => store.recoverFromAuthRejection(recovery));
+
+  // Bind this client's executor to its MutationQueue explicitly. The queue
+  // already resolves it through this client's own `runtime`, so this is the
+  // same executor either way; the explicit binding also covers a queue that
+  // was constructed without the instance runtime (subclass and test paths).
+  syncClient.getMutationQueue().setMutationExecutor(runtime.mutationExecutor);
+
+  // Status is tracked in store.syncStatus (MobX observable) — the single
+  // source of truth. No duplicate closure variables.
+  let _readyPromise: Promise<void> | null = null;
+  let _refreshScheduler: RefreshScheduler | null = null;
+
+  async function ready(): Promise<void> {
+    if (_readyPromise) return _readyPromise;
+
+    if (validationError) {
+      _readyPromise = Promise.reject(validationError);
+      return _readyPromise;
+    }
+
+    _readyPromise = (async () => {
+      try {
+        // Mint the first access credential before we connect, so the initial
+        // WebSocket upgrade and bootstrap carry a valid bearer (no tokenless first
+        // connect that has to self-heal). Only when a refreshing resolver is wired
+        // and no static credential is already present. Follows the `apiKey`
+        // resolver contract: `null` means the login is gone (terminal — fail ready
+        // so the app shows sign-in); a throw means transient (rethrown; autoStart
+        // swallows it and the lifecycle's online/wake triggers retry).
+        if (credentialResolver && !authCredentials.getAuthToken()) {
+          const outcome = await store.performCredentialRefresh();
+          if (outcome === 'session_error') {
+            throw new AbloAuthenticationError(
+              'Auth resolver returned null before connect — the user is not signed in.',
+              { code: 'auth_no_credentials' },
+            );
+          }
+          if (outcome === 'network_error') {
+            throw new AbloConnectionError(
+              'The credential endpoint could not mint the initial session credential.',
+              { code: 'exchange_network_error' },
+            );
+          }
+        }
+
+        // Resolve participant identity + scope. Three branches —
+        // hosted-cloud apiKey exchange, self-derived from capability
+        // token, or legacy explicit options. See `./identity.ts`.
+        const resolved = await resolveParticipantIdentity({
+          options: internalOptions,
+          internalOptions,
+          url,
+          kind,
+          configuredApiKey,
+          // Resolve identity against the live token, not the construction-time
+          // `configuredAuthToken`. Consumers using a function `apiKey` never pass
+          // `authToken` at construction — the lifecycle mints the first `ek_` or
+          // `rk_` and calls `setAuthToken()` before `ready()`, which updates the
+          // shared credential source. Reading the frozen `configuredAuthToken`
+          // here made `/auth/identity` fire with no bearer (returning
+          // `no_matching_provider` / `session_expired`) even though the token was
+          // present. This reads the shared credential source, like every other
+          // transport.
+          configuredAuthToken: authCredentials.getAuthToken() ?? configuredAuthToken,
+          bootstrapHelper,
+          auth: authCredentials,
+          logger,
+        });
+        const {
+          userId,
+          accountScope,
+          projectId,
+          environment,
+          sandboxId,
+          teamIds,
+          capabilityToken,
+          syncGroups,
+          participantKind,
+        } = resolved;
+
+        // Fail-loud guard: detect the degenerate "no real sync groups
+        // resolved" state before opening the socket. It is the same class of bug as
+        // a sensible-looking default that's functionally broken: the
+        // SDK ends up subscribing only to the server-side
+        // `['default']` fallback, no
+        // delta has that tag, live fan-out silently never delivers.
+        // For human users (kind:'user') this is almost certainly a
+        // misconfiguration upstream — either the caller didn't pass
+        // `syncGroups`, or auth resolution didn't derive them, or
+        // both. Warn loudly so the next debugging session starts here
+        // instead of with "live updates don't work, hard reload fixes
+        // it."
+        const resolvedSyncGroups = syncGroups ?? [];
+        if (
+          participantKind === 'user' &&
+          (resolvedSyncGroups.length === 0 ||
+            (resolvedSyncGroups.length === 1 && resolvedSyncGroups[0] === 'default'))
+        ) {
+          // Actionable and not self-healing (no live updates until fixed):
+          // kept at warn level for consumers; the low-level diagnostic
+          // fields ride the debug log below.
+          logger.warn(
+            'This client was started without sync groups, so it will not receive ' +
+              'live updates. Pass `syncGroups` (for example ' +
+              '`["org:<id>", "user:<id>"]`) or check that your auth provider supplies them.',
+          );
+          logger.debug('degenerate syncGroups — details', { participantKind, resolvedSyncGroups });
+        }
+
+        // Seed the resolved identity into everything that filters or stamps
+        // by participant — the engine's self locals and its streams, through
+        // the one callback. This runs before the store connects, so no frame
+        // is ever filtered against the construction-time guess.
+        onIdentityResolved({
+          userId,
+          participantKind,
+          accountScope,
+          syncGroups: resolvedSyncGroups,
+        });
+
+        if (resolved.refreshScheduler) {
+          _refreshScheduler = resolved.refreshScheduler;
+        }
+
+        // Drive the generator to completion. Each yielded promise is awaited
+        // then fed back — this is standard generator consumption.
+        //
+        // The store.initialize() generator updates store.syncStatus as it
+        // progresses (syncing → idle on success, error on failure), so the
+        // consumer's `sync.syncStatus` observable reflects real-time state.
+        // Resolve bootstrap mode: explicit option wins; otherwise
+        // agents default to 'none' (transactional participant — see
+        // option doc) and everyone else defaults to 'full'.
+        const resolvedBootstrapMode: 'full' | 'none' =
+          internalOptions.bootstrapMode ?? (participantKind === 'agent' ? 'none' : 'full');
+
+        const gen = store.initialize({
+          userId,
+          organizationId: accountScope,
+          projectId,
+          environment,
+          sandboxId,
+          teamIds,
+          kind: participantKind,
+          capabilityToken,
+          syncGroups,
+          bootstrapMode: resolvedBootstrapMode,
+        });
+        let current = gen.next();
+        while (!current.done) {
+          const yielded = current.value;
+          const settled = yielded instanceof Promise ? await yielded : yielded;
+          current = gen.next(settled);
+        }
+
+        const result = current.value;
+        if (!result.success) {
+          throw result.error
+            ? toAbloError(result.error)
+            : new AbloConnectionError('Sync engine initialization failed', {
+                code: 'bootstrap_fetch_timeout',
+              });
+        }
+
+        logger.info('Sync engine ready', { models: Object.keys(schema.models).length });
+      } catch (err) {
+        // Coerce so the rejection a consumer awaiting `ready()` catches is
+        // always an AbloError — connection setup is held to the same
+        // never-leak-untagged contract as the model operations.
+        const error = toAbloError(err);
+        // Make sure syncStatus reflects the failure for observer() components
+        store.syncStatus.state = 'error';
+        store.syncStatus.error = error;
+        // Log the typed envelope (type + code + status), not just the bare
+        // message — so the console line names it as an Ablo error and carries
+        // the code (e.g. AbloAuthenticationError/identity_resolve_failed on a
+        // 401) instead of reading like an untagged failure.
+        logger.error('Sync engine failed to initialize', {
+          type: error.type,
+          code: error.code,
+          httpStatus: error.httpStatus,
+          error: error.message,
+        });
+        // Clear the memo so a future `ready()` re-attempts bootstrap instead of
+        // replaying this rejection forever. Bootstrap failures here are transient
+        // by nature — offline, an IndexedDB open timeout, a bootstrap fetch
+        // hiccup — and the early `if (_readyPromise) return _readyPromise` guard
+        // would otherwise hand every later caller this same dead promise, bricking
+        // the engine until a full page reload. Nulling it lets the provider's
+        // online/wake/retry triggers drive a clean re-bootstrap. (The terminal
+        // `validationError` branch above intentionally stays cached — config
+        // can't change without recreating the engine.)
+        _readyPromise = null;
+        throw error;
+      }
+    })();
+
+    return _readyPromise;
+  }
+
+  // Optional auto-start for convenience. Opt-in because silent background
+  // init has historically been the #1 source of "why isn't my data loading"
+  // bug reports. Explicit `await sync.ready()` is the default — errors
+  // surface immediately instead of being swallowed.
+  if (!validationError && internalOptions.autoStart) {
+    void ready().catch(() => {
+      // Error is captured in store.syncStatus; consumers should check
+      // `sync.syncStatus.state === 'error'` to detect failures.
+    });
+  }
+
+  return {
+    ready,
+    dispose(): void {
+      _refreshScheduler?.dispose();
+      _refreshScheduler = null;
+    },
+  };
+}

package/src/local/client/validateAbloOptions.ts

@@ -0,0 +1,95 @@
+/**
+ * Validates the options passed when constructing an interactive client, before any
+ * connection is attempted. Returns the first problem it finds as an
+ * {@link AbloError}, or null when every check passes. The caller records that
+ * error on the client's sync status, so a misconfiguration surfaces through the
+ * normal status channel rather than throwing at the call site.
+ *
+ * The order of checks matters: a missing `url` is reported before any identity
+ * problem, because the identity error messages mention the URL and would
+ * mislead if the URL were the thing actually missing.
+ */
+
+import { AbloError, AbloValidationError } from '@abloatai/transaction/errors';
+import type { ParticipantKind } from '@abloatai/transaction/types/participant';
+
+/**
+ * The subset of client options this validator reads. It is declared as its own
+ * interface, structurally compatible with the full options type, so a real
+ * options object satisfies it without the validator having to depend on the
+ * complete type.
+ */
+export interface ValidatableAbloOptions {
+  readonly schema?: { readonly models?: Record<string, unknown> } | null;
+  readonly kind?: ParticipantKind;
+  readonly user?: { readonly id?: string } | undefined;
+  readonly agentId?: string | undefined;
+  readonly capabilityToken?: string | undefined;
+}
+
+export interface ValidateAbloOptionsInput {
+  readonly options: ValidatableAbloOptions;
+  readonly url: string;
+  /**
+   * Truthy when an API key was supplied (string or callable). The
+   * validator only inspects presence, never the value, so the input
+   * shape stays loose to accept whatever the caller resolved.
+   */
+  readonly configuredApiKey: unknown;
+  readonly configuredAuthToken: unknown;
+}
+
+export function validateAbloOptions(input: ValidateAbloOptionsInput): AbloError | null {
+  const { options, url, configuredApiKey, configuredAuthToken } = input;
+  const kind = options.kind ?? 'user';
+
+  if (!url) {
+    return new AbloValidationError(
+      'Ablo: `url` is required. Pass the sync server URL, e.g. ' +
+        `Ablo({ baseURL: 'wss://api.abloatai.com', schema, user })`,
+      { code: 'base_url_missing' },
+    );
+  }
+
+  if (!options.schema?.models) {
+    return new AbloValidationError(
+      'Ablo: `schema` is required. Define it once and access models as `ablo.<model>`.',
+      { code: 'invalid_options', param: 'schema' },
+    );
+  }
+
+  if (
+    !configuredApiKey &&
+    !configuredAuthToken &&
+    !options.capabilityToken &&
+    kind === 'user' &&
+    options.user &&
+    !options.user.id
+  ) {
+    return new AbloValidationError(
+      'Ablo: `user.id` must be a non-empty string when `user` is provided.',
+      { code: 'invalid_options', param: 'user.id' },
+    );
+  }
+
+  if (!configuredApiKey && !configuredAuthToken && kind === 'agent' && !options.agentId) {
+    return new AbloValidationError(
+      'Ablo: provide either `apiKey` or `agentId` for `kind: "agent"`. ' +
+        'Hosted-cloud consumers pass `apiKey` and the server derives the ' +
+        'agent identity from its scope; self-hosted passes `agentId` + ' +
+        '`capabilityToken` directly.',
+      { code: 'invalid_options', param: 'agentId' },
+    );
+  }
+
+  if (!configuredApiKey && !configuredAuthToken && kind === 'agent' && !options.capabilityToken) {
+    return new AbloValidationError(
+      'Ablo: provide either `apiKey` (hosted cloud — SDK exchanges internally) ' +
+        'or `capabilityToken` (self-hosted — your auth layer mints + hands in). ' +
+        'See https://abloatai.com/docs/api-keys for the full pattern.',
+      { code: 'invalid_options', param: 'capabilityToken' },
+    );
+  }
+
+  return null;
+}

package/src/local/client/wsMutationExecutor.ts

@@ -0,0 +1,110 @@
+/**
+ * The default {@link MutationExecutor}. It sends each change as a `commit`
+ * frame over the sync engine's own WebSocket, resolving that socket lazily at
+ * commit time because it does not exist yet when the executor is created. A
+ * client wires this up automatically unless you supply your own executor.
+ */
+
+import type { ReadDependency, TrackDependency } from '@abloatai/transaction/coordination/schema';
+import type {
+  MutationExecutor,
+  MutationOperation,
+  MutationOptions,
+} from '../interfaces/index.js';
+import type { CommitAck } from '../sync/commitFrames.js';
+import { AbloError, AbloConnectionError } from '@abloatai/transaction/errors';
+
+// ── Default mutation executor (wire: `commit` frame over WebSocket) ──────
+
+/**
+ * Creates the default mutation executor, which sends each change as a `commit`
+ * frame over the sync engine's own WebSocket. The engine owns its socket, so
+ * you pass a URL and credentials rather than transport callbacks.
+ *
+ * The factory takes a `getWs` accessor instead of a socket directly because the
+ * socket is created later during client startup and does not exist yet when
+ * this executor is constructed. The accessor is called at commit time to reach
+ * the ready socket.
+ *
+ * When set, `options.idempotencyKey` is sent as the wire-level `clientTxId`, so
+ * retrying a call with the same key is safe. MutationQueue always supplies
+ * this key before its first attempt and owns reuse across retries. The fallback
+ * generation below exists only for direct, one-shot executor consumers.
+ */
+	export function createDefaultMutationExecutor(
+	  getWs: () => {
+	    sendCommit?: (
+	      operations: readonly MutationOperation[],
+	      clientTxId: string,
+	      timeoutMs?: number,
+	      reads?: readonly ReadDependency[] | null,
+	      track?: readonly TrackDependency[] | null,
+	    ) => Promise<CommitAck>;
+	  } | null,
+	): MutationExecutor {
+	  async function commit(
+	    operations: MutationOperation[],
+	    options?: MutationOptions,
+	  ) {
+    const ws = getWs();
+    if (!ws?.sendCommit) {
+      throw new AbloConnectionError(
+        'SyncWebSocket not ready for commit. The engine must finish bootstrap ' +
+          'before mutations can be sent.',
+        { code: 'ws_not_ready' },
+      );
+    }
+	    const clientTxId =
+	      options?.idempotencyKey ??
+	      (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
+	        ? crypto.randomUUID()
+	        : `tx_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`);
+	    try {
+	      return await ws.sendCommit(
+	        operations,
+	        clientTxId,
+	        undefined, // use sendCommit's built-in 15s default; no per-call override
+	        options?.reads,
+	        options?.track,
+	      );
+    } catch (err) {
+      // Wrap transport-level failures as connection errors so the transaction
+      // queue's retry classifier treats them as transient and retries them.
+      if (err instanceof AbloError) throw err;
+      if (err instanceof Error) {
+        if (/not connected|timed out|connection|ECONN/i.test(err.message)) {
+          const wrapped = new AbloConnectionError(err.message, { cause: err });
+          // Preserve any `diagnostics` snapshot the underlying SyncWebSocket
+          // attached to the rejection. Without this, the wrapped error
+          // bottoms out at "AbloConnectionError: not connected" with no
+          // attribution to which close code / heartbeat trip / session
+          // error caused it. See SyncWebSocket.notConnectedError().
+          if (
+            err &&
+            typeof err === 'object' &&
+            'diagnostics' in err &&
+            (err as { diagnostics?: unknown }).diagnostics
+          ) {
+            Reflect.set(wrapped, 'diagnostics', err.diagnostics);
+          }
+          throw wrapped;
+        }
+      }
+      throw err;
+    }
+  }
+
+  return {
+    commit,
+    executeCreate: (model, id, input, _txId, options) =>
+      commit([{ type: 'CREATE', model: model.toLowerCase(), id, input }], options).then(() => {}),
+    executeUpdate: (model, id, data, _txId, options) =>
+      commit([{ type: 'UPDATE', model: model.toLowerCase(), id, input: data }], options),
+    executeDelete: (model, id, _txId, options) =>
+      commit([{ type: 'DELETE', model: model.toLowerCase(), id }], options).then(() => {}),
+    executeArchive: (model, id, _txId, options) =>
+      commit([{ type: 'ARCHIVE', model: model.toLowerCase(), id }], options).then(() => {}),
+    executeUnarchive: (model, id, _txId, options) =>
+      commit([{ type: 'UNARCHIVE', model: model.toLowerCase(), id }], options).then(() => {}),
+  };
+}

package/src/local/context.ts

@@ -0,0 +1,96 @@
+/**
+ * Module-level accessor for the sync engine's runtime context.
+ *
+ * The context is set once, during initialization, by {@link initRuntime}.
+ * Code throughout the package reaches its shared dependencies — logger,
+ * observability, online-status detector, configuration, and the mutation
+ * executor — through {@link getContext} instead of receiving them through every
+ * constructor.
+ */
+
+import type { RuntimeContext } from './RuntimeContext.js';
+import {
+  noopLogger,
+  noopObservability,
+  browserOnlineStatus,
+  defaultSessionErrorDetector,
+  emptyConfig,
+} from './RuntimeContext.js';
+
+let _context: RuntimeContext | null = null;
+
+/**
+ * Install the caller-provided runtime dependencies. Must be called before any
+ * operation that reaches {@link getContext}.
+ */
+export function initRuntime(context: RuntimeContext): void {
+  _context = context;
+}
+
+/**
+ * Get the current sync engine context.
+ * Returns a safe fallback with no-op implementations if not yet initialized,
+ * so SDK files can import at module load time without crashing.
+ */
+export function getContext(): RuntimeContext {
+  if (!_context) {
+    return _fallback;
+  }
+  return _context;
+}
+
+/**
+ * The module-global runtime as an instance-shaped value — the bridge for code
+ * that is not yet constructed with its client's own `RuntimeContext`.
+ *
+ * Every member reads {@link getContext} at call time, so a context installed
+ * after construction is still picked up (tests construct first and
+ * `initRuntime` later). Classes take `runtime` as a constructor option with
+ * this as the default; a client that threads its own instance is isolated
+ * from other clients in the same process, a construction that doesn't is
+ * last-writer-wins exactly as before. Retired reference by reference as
+ * construction moves behind `humans()` (docs/plans/package-split.md).
+ */
+export const globalRuntime: RuntimeContext = {
+  get logger() { return getContext().logger; },
+  get observability() { return getContext().observability; },
+  get analytics() { return getContext().analytics; },
+  get sessionErrorDetector() { return getContext().sessionErrorDetector; },
+  get onlineStatus() { return getContext().onlineStatus; },
+  get modelDebugLogger() { return getContext().modelDebugLogger; },
+  get mutationExecutor() { return getContext().mutationExecutor; },
+  get config() { return getContext().config; },
+  getModelMetadata: (name) => getContext().getModelMetadata(name),
+};
+
+/**
+ * Check if the sync engine has been initialized.
+ */
+export function isRuntimeInitialized(): boolean {
+  return _context !== null;
+}
+
+/**
+ * Reset context (for testing or cleanup).
+ */
+export function resetRuntime(): void {
+  _context = null;
+}
+
+/** Fallback context with no-op implementations */
+const _fallback: RuntimeContext = {
+  logger: noopLogger,
+  observability: noopObservability,
+  onlineStatus: browserOnlineStatus,
+  sessionErrorDetector: defaultSessionErrorDetector,
+  config: emptyConfig,
+  getModelMetadata: () => undefined,
+  mutationExecutor: {
+    commit: () => Promise.resolve({ lastSyncId: 0, status: 'confirmed' as const }),
+    executeCreate: () => Promise.resolve(),
+    executeUpdate: () => Promise.resolve(null),
+    executeDelete: () => Promise.resolve(),
+    executeArchive: () => Promise.resolve(),
+    executeUnarchive: () => Promise.resolve(),
+  },
+};

package/src/local/coordination/ClaimLog.ts

@@ -0,0 +1,39 @@
+/**
+ * Sync-engine compatibility adapter for the transaction layer's narrow claim
+ * log. The core log knows only claim/conflict events; this subclass supplies
+ * inert implementations for the client lifecycle hooks required by
+ * `ObservabilityProvider`, preserving `Ablo({ observability: new ClaimLog() })`
+ * without leaking bootstrap, storage, or WebSocket vocabulary into the core.
+ */
+
+import { ClaimLog as CoordinationClaimLog } from '@abloatai/transaction/coordination/trace';
+import type { ObservabilityProvider } from '../interfaces/index.js';
+
+export { formatClaim, formatConflict } from '@abloatai/transaction/coordination/trace';
+export type { ClaimLogEntry } from '@abloatai/transaction/coordination/trace';
+
+export class ClaimLog extends CoordinationClaimLog implements ObservabilityProvider {
+  // Client-lifecycle hooks the claim log has no notion of. Every body below is
+  // deliberately inert: the log records claims and conflicts, nothing else.
+  setContext(): void { /* inert */ }
+  setConnectionState(): void { /* inert */ }
+  breadcrumb(): void { /* inert */ }
+  captureRollback(): void { /* inert */ }
+  captureMutationFailure(): void { /* inert */ }
+  captureBootstrapFailure(): void { /* inert */ }
+  captureReconciliation(): void { /* inert */ }
+  captureDeltaRetryExhausted(): void { /* inert */ }
+  captureWebSocketError(): void { /* inert */ }
+  captureSelfHealing(): void { /* inert */ }
+  captureCommitZeroSyncId(): void { /* inert */ }
+
+  // Spans run their body untimed; the trailing `attributes` argument callers
+  // pass has nowhere to go here, so it is left off the signature.
+  startSpan<T>(_name: string, _op: string, fn: () => T): T {
+    return fn();
+  }
+
+  startSpanAsync<T>(_name: string, _op: string, fn: () => Promise<T>): Promise<T> {
+    return fn();
+  }
+}