@abloatai/humans 0.37.0

package/dist/local/client/storeLifecycle.js

@@ -0,0 +1,236 @@
+/**
+ * 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 { resolveParticipantIdentity } from '@abloatai/transaction/auth/identity';
+import { AbloAuthenticationError, AbloConnectionError, toAbloError, } from '@abloatai/transaction/errors';
+/**
+ * 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(deps) {
+    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 = null;
+    let _refreshScheduler = null;
+    async function ready() {
+        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 = 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() {
+            _refreshScheduler?.dispose();
+            _refreshScheduler = null;
+        },
+    };
+}

package/dist/local/client/validateAbloOptions.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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 } 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 declare function validateAbloOptions(input: ValidateAbloOptionsInput): AbloError | null;

package/dist/local/client/validateAbloOptions.js

@@ -0,0 +1,43 @@
+/**
+ * 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';
+export function validateAbloOptions(input) {
+    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/dist/local/client/wsMutationExecutor.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 } from '../interfaces/index.js';
+import type { CommitAck } from '../sync/commitFrames.js';
+/**
+ * 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 declare function createDefaultMutationExecutor(getWs: () => {
+    sendCommit?: (operations: readonly MutationOperation[], clientTxId: string, timeoutMs?: number, reads?: readonly ReadDependency[] | null, track?: readonly TrackDependency[] | null) => Promise<CommitAck>;
+} | null): MutationExecutor;

package/dist/local/client/wsMutationExecutor.js

@@ -0,0 +1,72 @@
+/**
+ * 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 { 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) {
+    async function commit(operations, options) {
+        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.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/dist/local/context.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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';
+/**
+ * Install the caller-provided runtime dependencies. Must be called before any
+ * operation that reaches {@link getContext}.
+ */
+export declare function initRuntime(context: RuntimeContext): void;
+/**
+ * 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 declare function getContext(): RuntimeContext;
+/**
+ * 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 declare const globalRuntime: RuntimeContext;
+/**
+ * Check if the sync engine has been initialized.
+ */
+export declare function isRuntimeInitialized(): boolean;
+/**
+ * Reset context (for testing or cleanup).
+ */
+export declare function resetRuntime(): void;

package/dist/local/context.js

@@ -0,0 +1,81 @@
+/**
+ * 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 { noopLogger, noopObservability, browserOnlineStatus, defaultSessionErrorDetector, emptyConfig, } from './RuntimeContext.js';
+let _context = null;
+/**
+ * Install the caller-provided runtime dependencies. Must be called before any
+ * operation that reaches {@link getContext}.
+ */
+export function initRuntime(context) {
+    _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() {
+    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 = {
+    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() {
+    return _context !== null;
+}
+/**
+ * Reset context (for testing or cleanup).
+ */
+export function resetRuntime() {
+    _context = null;
+}
+/** Fallback context with no-op implementations */
+const _fallback = {
+    logger: noopLogger,
+    observability: noopObservability,
+    onlineStatus: browserOnlineStatus,
+    sessionErrorDetector: defaultSessionErrorDetector,
+    config: emptyConfig,
+    getModelMetadata: () => undefined,
+    mutationExecutor: {
+        commit: () => Promise.resolve({ lastSyncId: 0, status: 'confirmed' }),
+        executeCreate: () => Promise.resolve(),
+        executeUpdate: () => Promise.resolve(null),
+        executeDelete: () => Promise.resolve(),
+        executeArchive: () => Promise.resolve(),
+        executeUnarchive: () => Promise.resolve(),
+    },
+};

package/dist/local/coordination/ClaimLog.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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 declare class ClaimLog extends CoordinationClaimLog implements ObservabilityProvider {
+    setContext(): void;
+    setConnectionState(): void;
+    breadcrumb(): void;
+    captureRollback(): void;
+    captureMutationFailure(): void;
+    captureBootstrapFailure(): void;
+    captureReconciliation(): void;
+    captureDeltaRetryExhausted(): void;
+    captureWebSocketError(): void;
+    captureSelfHealing(): void;
+    captureCommitZeroSyncId(): void;
+    startSpan<T>(_name: string, _op: string, fn: () => T): T;
+    startSpanAsync<T>(_name: string, _op: string, fn: () => Promise<T>): Promise<T>;
+}

package/dist/local/coordination/ClaimLog.js

@@ -0,0 +1,32 @@
+/**
+ * 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';
+export { formatClaim, formatConflict } from '@abloatai/transaction/coordination/trace';
+export class ClaimLog extends CoordinationClaimLog {
+    // 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() { }
+    setConnectionState() { }
+    breadcrumb() { }
+    captureRollback() { }
+    captureMutationFailure() { }
+    captureBootstrapFailure() { }
+    captureReconciliation() { }
+    captureDeltaRetryExhausted() { }
+    captureWebSocketError() { }
+    captureSelfHealing() { }
+    captureCommitZeroSyncId() { }
+    // Spans run their body untimed; the trailing `attributes` argument callers
+    // pass has nowhere to go here, so it is left off the signature.
+    startSpan(_name, _op, fn) {
+        return fn();
+    }
+    startSpanAsync(_name, _op, fn) {
+        return fn();
+    }
+}