@abloatai/ablo 0.34.1 → 0.36.0

package/dist/client/Ablo.js

@@ -17,978 +17,144 @@
  *     data: { status: 'ready' },
  *   });
  *   await sync.reports.delete({ id: reportId });
+ *
+ * This module is the composition root and the merge point, and only those.
+ * `Ablo` is three declarations sharing one name — the factory, the client
+ * type, and the `Ablo.*` namespace — and TypeScript merges declarations only
+ * within a single file, so the three have to sit together. Their bodies do
+ * not: the client's shape is `./abloClient`, the pass over the options bag is
+ * `./clientPrelude`, and the client this dispatches to is `./reactiveEngine`.
  */
-import { durableCommitOperationSchema, } from '../transactions/commitEnvelope.js';
-import { AbloAuthenticationError, AbloConnectionError, AbloValidationError, toAbloError, claimedError } from '../errors.js';
-import { initSyncEngine } from '../context.js';
-import { noopObservability, browserOnlineStatus, defaultSessionErrorDetector, noopAnalytics, } from '../SyncEngineContext.js';
-import { alwaysOnline } from '../adapters/alwaysOnline.js';
-import { validateAbloOptions } from './validateAbloOptions.js';
-import { InstanceCache } from '../InstanceCache.js';
-import {} from '../auth/index.js';
-import { mintSession } from './sessionMint.js';
-import { createAuthCredentialSource } from '../auth/credentialSource.js';
-import { createInternalComponents } from './createInternalComponents.js';
-import { resolveParticipantIdentity } from './identity.js';
-import { BaseSyncedStore } from '../BaseSyncedStore.js';
-import { createPresenceStream } from '../sync/createPresenceStream.js';
-import { createClaimStream } from '../sync/createClaimStream.js';
-import { awaitClaimGrant } from '../sync/awaitClaimGrant.js';
-import { createSnapshot } from '../sync/createSnapshot.js';
-import { createParticipantManager } from '../sync/participants.js';
+import { AbloValidationError } from '../transaction/errors.js';
+import { SyncWebSocket } from '../sync/SyncWebSocket.js';
 // Value import is cycle-safe: httpClient.js and httpTransport.js take the client
 // types from the `options`/`resourceTypes` leaves, never from this module.
-import { createAbloHttpClient, } from './httpClient.js';
-import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, rejectRemovedDatabaseUrlOption, warnIfCliKeyMismatch, } from './auth.js';
-import { shouldUseInMemoryPersistence } from './persistence.js';
-import { deriveConfigFromSchema } from './schemaConfig.js';
-import { registerModelsFromSchema } from './modelRegistration.js';
-import { createConsoleLogger, resolveLogLevel } from './consoleLogger.js';
-import { createDefaultMutationExecutor } from './wsMutationExecutor.js';
-export { computeFKDepthPriority } from './schemaConfig.js';
-import { createModelProxy } from './createModelProxy.js';
-import { assertWriteOptions } from './writeOptionsSchema.js';
-// `readProcessEnv` lives in `./auth` alongside the other resolvers
-// that read it. Re-exported there for use elsewhere in the file.
-// ── Auth normalization ─────────────────────────────────────────────────────
-/**
- * The single resolver the credential lifecycle needs: an async
- * `() => token | null`, or `null` when auth is static — a plain long-lived
- * `apiKey` string with no refresh, which is the common case.
- *
- * The short-lived per-user browser path passes a function `apiKey` (an
- * {@link ApiKeySetter}), and the SDK then drives the whole credential lifecycle
- * from it: mint-before-connect, the proactive refresh timer with its
- * wake/online/focus re-mint, and the reactive `credential_stale` re-mint. The
- * resolver follows the `ApiKeySetter` contract end to end: resolve a token,
- * resolve `null` when the login is gone (terminal — surfaces `session_expired`
- * and signs the user out), or throw on a transient failure (backs off, without
- * signing out).
- */
-function resolveCredentialResolver(apiKey) {
-    if (typeof apiKey === 'function')
-        return apiKey;
-    return null;
-}
+import { createAbloHttpClient, } from '../transaction/transport/httpClient.js';
+// Both halves of the plugin lifecycle: `resolvePlugins` turns the declared list
+// into a surface, `layerPluginSurface` merges that surface onto the built client.
+import { layerPluginSurface, resolvePlugins, } from '../transaction/plugin.js';
+import { noopLogger } from '../transaction/logger.js';
+import { humans } from './humans.js';
+import { kStoreCluster } from './storeCluster.js';
+import { createCoreClient } from './coreClient.js';
+import { buildReactiveEngine } from './reactiveEngine.js';
+import { resolveClientPrelude } from './clientPrelude.js';
 export function Ablo(options) {
     if (options.transport === 'http') {
-        return createAbloHttpClient(options);
-    }
-    const internalOptions = options;
-    const env = readProcessEnv();
-    const authInput = { options, env };
-    const configuredApiKey = resolveApiKey(authInput);
-    const configuredAuthToken = resolveAuthToken(authInput);
-    // The client owns its credential lifecycle (not the React layer): this resolver
-    // drives both the reactive re-mint (the connection's `credential_stale` state)
-    // and the proactive refresh timer with its wake/online/focus triggers. Null for
-    // the common static `apiKey` path, which needs no refresh.
-    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 schema = options.schema;
-    const url = resolveBaseURL(authInput);
-    // 1. Derive config from schema
-    // 1. Derive config from schema, then layer caller-supplied overrides on top.
-    //    `configOverrides` is a shallow merge: caller takes precedence per key.
-    const config = {
-        ...deriveConfigFromSchema(schema),
-        ...internalOptions.configOverrides,
-    };
-    // 2. Create the mutation executor and dispatcher.
-    //
-    //    The default executor sends `{ type: 'commit', ... }` over the engine's
-    //    WebSocket. The socket doesn't exist yet at this point (it's created later
-    //    when the store initializes), so the default takes a lazy getter that
-    //    resolves the live socket at commit time. `storeHolder` is captured by the
-    //    closure and assigned below once the store is built — JS closures close
-    //    over bindings, not values, so by the time the first commit fires the store
-    //    is live.
-    //
-    //    Caller-supplied executors are still honored for advanced cases (test
-    //    mocks, alternative transports), but apps should almost never need to
-    //    override the transport.
-    // Captured-by-reference binding — assigned below after BaseSyncedStore
-    // is constructed. The default executor's `getWs` closure reads it
-    // lazily at commit time.
-    // The store is created later with full generics (`Schema<S>`), so type
-    // it here as the same generic — narrower default doesn't accept it.
-    const storeHolder = { store: null };
-    const executor = internalOptions.mutationExecutor ??
-        createDefaultMutationExecutor(() => {
-            const ws = storeHolder.store?.getSyncWebSocket() ?? null;
-            return ws;
+        // Capabilities are declared above transport (ADR 0016): the plugin list
+        // is checked against the selected transport before anything is built, so
+        // a duplex-requiring plugin — humans() — on a request-response client
+        // fails right here, with a typed error naming the plugin, rather than as
+        // a subscription that never delivers.
+        const surface = resolvePlugins(options.plugins ?? [], { duplex: false }, {
+            logger: noopLogger,
+            options,
         });
-    // 3. Initialize SDK context (one call — hides all DI wiring).
-    //    Each provider can be overridden individually; the noop defaults
-    //    are preserved for the zero-config consumer path.
-    initSyncEngine({
+        return layerPluginSurface(createAbloHttpClient(options), surface);
+    }
+    // 1. One pass over the options bag settles the credential and its refresh
+    //    resolver, the base URL, the logger, and this participant's identity —
+    //    and fails on a misconfiguration before anything is constructed.
+    const prelude = resolveClientPrelude(options);
+    const { internalOptions, authCredentials, logger, url, participantId, kind } = prelude;
+    // 2. The connection, built here in the composition root — before the plugin
+    //    list resolves, so `PluginContext.transport` carries the instance a
+    //    plugin holds for the client's lifetime. It holds no socket until
+    //    `connect()`, and `deferConnect` keeps even that closed until the store
+    //    has seeded identity and read scope during `ready()` — the late-bound
+    //    values (`kind`, the credential, `syncGroups`, the resume cursor) are
+    //    seeded there, not here. Whether to build it is read off what the
+    //    listed plugins DECLARE — a plugin that requires a duplex transport
+    //    gets one to attach to — never off a plugin's name; interrogating the
+    //    assembly by id is the context's `hasPlugin`, a capability for
+    //    plugins, not a dispatch key for this root. The empty list builds
+    //    nothing here: the core client (`plugins: []`) constructs its own
+    //    feed, and no plugin runs on that path to read this one.
+    const pluginList = options.plugins ?? [humans()];
+    const transport = pluginList.some((plugin) => plugin.requires?.duplex === true)
+        ? new SyncWebSocket({
+            baseUrl: url,
+            kind,
+            getAuthToken: authCredentials.getAuthToken,
+            collaborationEvents: [...(internalOptions.collaborationEvents ?? [])],
+            syncGroups: [...(internalOptions.syncGroups ?? [])],
+            deferConnect: true,
+        })
+        : null;
+    // Resolve the capability list before anything heavy is constructed
+    // (ADR 0016). The two configuration gates — a duplicate id, a transport
+    // mismatch — fire here, while the stack still points at the caller's own
+    // setup. With no list given, the reactive materialiser is installed:
+    // today's default client. (Flipping the bare default to the stateless core
+    // is the mirror-flip step, decided with the published version identity —
+    // not here.) The context carries the host's resolved values — url,
+    // credential source, identity — so `humans().init` constructs the store
+    // cluster right here, during resolution.
+    const installedPlugins = resolvePlugins(pluginList, { duplex: true }, {
         logger,
-        observability: internalOptions.observability ?? noopObservability,
-        analytics: internalOptions.analytics ?? noopAnalytics,
-        sessionErrorDetector: internalOptions.sessionErrorDetector ?? defaultSessionErrorDetector,
-        onlineStatus: internalOptions.onlineStatus ??
-            (shouldUseInMemoryPersistence(options)
-                ? alwaysOnline()
-                : browserOnlineStatus),
-        config,
-        mutationExecutor: executor,
-    });
-    // 4. Create internal components (user never sees these). See
-    //    `./createInternalComponents.ts` for the construction order
-    //    and what each component does. Model registration happens
-    //    here (via `registerModelsFromSchema`, in `./modelRegistration.ts`)
-    //    because the schema-to-Model-class translation is client-construction
-    //    wiring that isn't worth pulling into the components module.
-    const { modelRegistry, objectPool, bootstrapHelper, database, syncClient, hydration, } = createInternalComponents({
-        schema,
-        url,
-        options: internalOptions,
-        auth: authCredentials,
-    });
-    registerModelsFromSchema(schema, modelRegistry);
-    // 5. BaseSyncedStore handles the initialization orchestration
-    //    (open DB → hydrate IDB → connect WS → fetch bootstrap → hydrate again →
-    //    ready) and exposes the observable `syncStatus` we expose on the engine.
-    //
-    //    Phase 2: pass the schema into the store so `deriveSyncPlanFromSchema`
-    //    can auto-populate version vector keys, FK indexes, and enrichment
-    //    rules from the declarative `belongsTo({ index, enrich })` annotations.
-    //    Consumers using class-based subclasses with `new SyncedStore(...)`
-    //    directly can pass explicit config arrays instead.
-    const store = new BaseSyncedStore({
-        syncClient,
-        database,
-        objectPool,
-        modelRegistry,
-        schema,
-        url,
-        auth: authCredentials,
-    });
-    // 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));
-    // Wire the store back into the default executor's lazy getter (see
-    // `storeHolder` above). The executor was constructed before the store
-    // existed; this late binding closes the loop so commits dispatch over
-    // the engine's WebSocket once it opens.
-    storeHolder.store = store;
-    // Bind this executor to this client's TransactionQueue. Without it, the queue
-    // resolves `mutationExecutor` from the module-level `getContext()`, which
-    // `initSyncEngine()` overwrites on every client construction. In multi-client
-    // flows (for example a worker plus a per-job peer) the second `initSyncEngine()`
-    // call would silently redirect the first client's queue through the second
-    // client's executor closure — and when the second client disposes, its
-    // `storeHolder.store` becomes null, so the first client's commits start throwing
-    // `ws_not_ready` forever.
-    syncClient.getTransactionQueue().setMutationExecutor(executor);
-    // Presence + claim streams — built eagerly so `engine.presence`
-    // and `engine.claims` return the same reference for the engine's
-    // lifetime. The transport doesn't exist yet (BaseSyncedStore.initialize
-    // creates it during ready()), so both streams are constructed in
-    // deferred-attach mode and wired after initialize() resolves below.
-    // Calls before attach mutate local state but skip the wire send.
-    // 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, but the local `self`
-    // entry uses the kind we know at construction.
-    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) ?? '';
-    const presenceStream = createPresenceStream({
-        participantId,
+        observability: internalOptions.observability,
+        // The raw options bag plus the host's resolved values, so plugins
+        // read configuration without re-deriving identity.
+        options,
+        ...(transport ? { transport } : {}),
+        participant: { id: participantId, kind },
         syncGroups: internalOptions.syncGroups ?? [],
-        // eslint-disable-next-line @typescript-eslint/no-deprecated -- local self-entry kind; server re-stamps isAgent from the authenticated identity
-        isAgent: internalOptions.kind === 'agent',
-    });
-    const claimStream = createClaimStream({ participantId });
-    const participantManager = createParticipantManager({
-        ready,
-        getTransport: () => store.getSyncWebSocket() ?? null,
-        presence: presenceStream,
-        claims: claimStream,
-        schema,
-    });
-    // 6. Validate options up front — fail loudly on obviously wrong inputs so
-    //    strangers don't get silent empty results. Validation errors are written
-    //    into `store.syncStatus` (the single source of truth).
-    // 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';
-    const _validationError = validateAbloOptions({
-        options: internalOptions,
         url,
-        configuredApiKey,
-        configuredAuthToken,
-    });
-    if (_validationError) {
-        logger.error(_validationError.message);
-        store.syncStatus.state = 'error';
-        store.syncStatus.error = _validationError;
-    }
-    // Deprecated identity overrides are a silent no-op under hosted cloud: when an
-    // `apiKey` is configured the SERVER derives participant kind + id from the
-    // key's scope, so `kind` / `agentId` passed here are ignored. Setting them and
-    // trusting them is the trap (you think you're an agent; the key says user).
-    // Warn loudly rather than removing the fields — `agentId` is still load-bearing
-    // on the self-hosted path (no apiKey; paired with `capabilityToken`).
-    // eslint-disable-next-line @typescript-eslint/no-deprecated -- reads the deprecated fields precisely to warn callers off them under a configured apiKey
-    if (configuredApiKey && (internalOptions.kind || internalOptions.agentId)) {
-        logger.warn('Ablo: `kind` / `agentId` are ignored when an `apiKey` is configured — ' +
-            'the server derives participant identity from the key’s scope. Remove ' +
-            'them (or mint a scoped session via `ablo.sessions.create({ agent })` ' +
-            'for a distinct agent identity). They apply only to the self-hosted ' +
-            '`capabilityToken` path.');
-    }
-    // 7. The ready() promise drives the BaseSyncedStore.initialize() generator
-    //    to completion. First call kicks off the initialization; subsequent
-    //    calls return the same promise (idempotent).
-    //
-    //    Status is tracked in store.syncStatus (MobX observable) — the single
-    //    source of truth. No duplicate closure variables.
-    let _readyPromise = null;
-    let _refreshScheduler = null;
-    /** Resolved account scope — set once identity resolution completes in
-     *  `ready()`; exposed as the readonly `ablo.organizationId` accessor. */
-    let _resolvedOrganizationId = 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 token = await credentialResolver();
-                    if (!token) {
-                        throw new AbloAuthenticationError('Auth resolver returned null before connect — the user is not signed in.', { code: 'auth_no_credentials' });
-                    }
-                    authCredentials.setAuthToken(token);
-                }
-                // 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, 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 });
-                }
-                _resolvedOrganizationId = accountScope;
-                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,
-                    teamIds,
-                    kind: participantKind,
-                    capabilityToken,
-                    syncGroups,
-                    bootstrapMode: resolvedBootstrapMode,
-                });
-                let current = gen.next();
-                while (!current.done) {
-                    const yielded = current.value;
-                    const resolved = yielded instanceof Promise ? await yielded : yielded;
-                    current = gen.next(resolved);
-                }
-                const result = current.value;
-                if (!result.success) {
-                    throw result.error
-                        ? toAbloError(result.error)
-                        : new AbloConnectionError('Sync engine initialization failed', {
-                            code: 'bootstrap_fetch_timeout',
-                        });
-                }
-                // Wire presence + claims to the now-open transport.
-                // `getSyncWebSocket()` returns non-null after a successful
-                // initialize() — the WS is created during the generator's
-                // connect step.
-                const ws = store.getSyncWebSocket();
-                if (ws) {
-                    presenceStream.attach(ws);
-                    claimStream.attach(ws);
-                }
-                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;
-    }
-    // 9. 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.
-        });
-    }
-    // 9b. waitForFlush — drains pending mutations using the store's
-    //     pendingChanges counter (already maintained by BaseSyncedStore based
-    //     on TransactionQueue events). Polls every 50ms; uses the existing
-    //     observable rather than introducing a new event channel.
-    async function waitForFlush(timeoutMs) {
-        const start = Date.now();
-        while (store.syncStatus.pendingChanges > 0) {
-            if (timeoutMs !== undefined && Date.now() - start > timeoutMs) {
-                throw new AbloConnectionError(`Flush timeout: ${store.syncStatus.pendingChanges} pending mutations after ${timeoutMs}ms`, { code: 'flush_timeout' });
-            }
-            await new Promise((resolve) => setTimeout(resolve, 50));
-        }
-    }
-    function createClientTxId(idempotencyKey) {
-        if (idempotencyKey && idempotencyKey.length > 0)
-            return idempotencyKey;
-        return typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
-            ? crypto.randomUUID()
-            : `tx_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
-    }
-    function normalizeCommitOperation(op, defaults, fenceToken) {
-        const type = op.action.toUpperCase();
-        const id = op.id ?? '';
-        return durableCommitOperationSchema.parse({
-            type,
-            model: op.model.toLowerCase(),
-            id,
-            input: op.data ?? undefined,
-            transactionId: op.transactionId ?? undefined,
-            readAt: op.readAt ?? defaults.readAt ?? undefined,
-            onStale: op.onStale ?? defaults.onStale ?? undefined,
-            // The batch's claim (if any) supplies one token for every op, mirroring
-            // how it supplies the batch `readAt`.
-            fenceToken: op.fenceToken ?? fenceToken ?? undefined,
-        });
-    }
-    function normalizeCommitOperations(commitOptions, fenceToken) {
-        if (commitOptions.operations.length === 0) {
-            throw new AbloValidationError('Commit requires a non-empty `operations` array.', { code: 'commit_operation_required' });
-        }
-        return commitOptions.operations.map((op) => normalizeCommitOperation(op, commitOptions, fenceToken));
-    }
-    function modelClaimFromActive(claim) {
-        return {
-            id: claim.id,
-            actor: claim.heldBy ?? "",
-            participantKind: claim.participantKind ?? "user",
-            description: claim.description,
-            field: claim.target.field,
-            status: 'active',
-            expiresAt: claim.expiresAt ?? 0,
-            target: {
-                model: claim.target.type,
-                id: claim.target.id,
-                path: claim.target.path,
-                range: claim.target.range,
-                field: claim.target.field,
-                meta: claim.target.meta,
-            },
-        };
-    }
-    function targetMatchesModel(target, claim) {
-        if (target.model &&
-            claim.target.type.toLowerCase() !== target.model.toLowerCase()) {
-            return false;
-        }
-        if (target.id && claim.target.id !== target.id)
-            return false;
-        if (target.field && claim.target.field !== target.field)
-            return false;
-        return true;
-    }
-    function listModelClaims(target) {
-        return claimStream.others
-            .filter((claim) => (target ? targetMatchesModel(target, claim) : true))
-            .map(modelClaimFromActive);
-    }
-    function waitForModelUnclaimed(target, options) {
-        if (listModelClaims(target).length === 0)
-            return Promise.resolve();
-        return new Promise((resolve, reject) => {
-            let settled = false;
-            let timeoutId;
-            let unsubscribe;
-            const cleanup = () => {
-                if (timeoutId)
-                    clearTimeout(timeoutId);
-                if (unsubscribe)
-                    unsubscribe();
-                options?.signal?.removeEventListener('abort', onAbort);
-            };
-            const finish = (fn) => {
-                if (settled)
-                    return;
-                settled = true;
-                cleanup();
-                fn();
-            };
-            const check = () => {
-                if (listModelClaims(target).length === 0) {
-                    finish(resolve);
-                }
-            };
-            const onAbort = () => {
-                finish(() => {
-                    reject(new AbloConnectionError('Claim wait aborted.', {
-                        code: 'claim_wait_aborted',
-                        cause: options?.signal?.reason,
-                    }));
-                });
-            };
-            if (options?.signal?.aborted) {
-                onAbort();
-                return;
-            }
-            unsubscribe = claimStream.onChange(check);
-            options?.signal?.addEventListener('abort', onAbort, { once: true });
-            if (options?.timeout != null) {
-                timeoutId = setTimeout(() => {
-                    finish(() => {
-                        reject(claimedError(target, listModelClaims(target), 'model_claimed_timeout'));
-                    });
-                }, options.timeout);
-            }
-        });
-    }
-    function wrapClaimHandle(claim, waited = false, fenceToken) {
-        const release = async () => {
-            claim.revoke?.();
-        };
-        // The token is server-stamped and arrives on the grant frame, so prefer
-        // the one `awaitClaimGrant` read there; fall back to any the local handle
-        // already carried (immediate, non-queued grants).
-        const resolvedFenceToken = fenceToken ?? claim.fenceToken;
-        return {
-            object: 'claim',
-            id: claim.id,
-            description: claim.description,
-            target: claim.target,
-            waited,
-            ...(resolvedFenceToken !== undefined ? { fenceToken: resolvedFenceToken } : {}),
-            release,
-            revoke: claim.revoke,
-            // The lease-control members are forwarded explicitly — this wrapper
-            // rebuilds the handle field by field, so anything not named here is
-            // silently dropped from the public claim.
-            heartbeat: claim.heartbeat,
-            [Symbol.asyncDispose]: release,
-        };
-    }
-    const publicClaims = Object.assign(claimStream, {
-        async create(claimOptions) {
-            await ready();
-            const claim = claimStream.claim({
-                type: claimOptions.target.model,
-                id: claimOptions.target.id,
-                path: claimOptions.target.path,
-                range: claimOptions.target.range,
-                field: claimOptions.target.field,
-                meta: claimOptions.target.meta,
-            }, {
-                description: claimOptions.description,
-                ttl: claimOptions.ttl,
-                queue: claimOptions.queue,
-            });
-            // With `queue`, the claim is only really *ours* once the server says
-            // so (`claim_acquired` if the target was free, `claim_granted` once
-            // we reach the head of the FIFO line). Block here on that grant so
-            // callers — chiefly `ablo.<model>.claim` — get a handle that already
-            // holds the lease, never a half-claimed one racing the queue.
-            let waited = false;
-            let fenceToken;
-            if (claimOptions.queue) {
-                const ws = store.getSyncWebSocket();
-                if (ws) {
-                    try {
-                        ({ waited, fenceToken } = await awaitClaimGrant(ws, claim.id, {
-                            timeoutMs: claimOptions.waitTimeoutMs,
-                            maxQueueDepth: claimOptions.maxQueueDepth,
-                        }));
-                    }
-                    catch (err) {
-                        // Gave up waiting (queue too deep, timed out, or lost) — abandon
-                        // the queued claim so we don't leave a phantom entry in the
-                        // line that would block or mislead other claimers.
-                        claim.revoke?.();
-                        throw err;
-                    }
-                }
-            }
-            return wrapClaimHandle(claim, waited, fenceToken);
-        },
-        list(target) {
-            return listModelClaims(target);
-        },
-        waitFor(target, options) {
-            return waitForModelUnclaimed(target, options);
-        },
+        auth: authCredentials,
     });
-    // Build the typed proxy — one property per model. Done after publicClaims
-    // exists so model clients can expose workflow helpers such as
-    // `ablo.files.edit(...)` without importing protocol wiring.
-    const modelProxies = {};
-    for (const [schemaKey, modelDef] of Object.entries(schema.models)) {
-        const registeredModelName = modelDef.typename ?? schemaKey;
-        modelProxies[schemaKey] = createModelProxy(schemaKey, registeredModelName, objectPool, syncClient, modelRegistry, hydration, {
-            createClaim: (claimOptions) => publicClaims.create(claimOptions),
-            createSnapshot: (modelKey, id) => createSnapshot({
-                pool: objectPool,
-                transport: store.getSyncWebSocket(),
-                // `position.readFloor` is the value claims and snapshots stamp as
-                // `readAt` (max of the pool-applied cursor and the acked
-                // watermark for our own writes — see sync/syncPosition.ts).
-                // Stamping a bare stream cursor made a claim taken right after
-                // an ack-confirmed write stale against that write's own delta.
-                // The socket/store cursors are persistence-gated and therefore
-                // never ahead of `applied` — no extra max() needed here.
-                getLastSyncId: () => syncClient.position.readFloor,
-                entities: { [modelKey]: id },
-            }),
-            queue: (target) => publicClaims.queueFor({ type: target.model, id: target.id }),
-            reorder: (target, order) => { publicClaims.reorder({ type: target.model, id: target.id }, order); },
-            state: (target) => {
-                // The live claim stream only tracks *open* (active) claims;
-                // terminal states (committed / expired / canceled) drop out of
-                // the list entirely — exactly the ephemeral coordination model.
-                // So a present entry is, by definition, `status: 'active'`.
-                const held = publicClaims.list({
-                    model: target.model,
-                    id: target.id,
-                })[0];
-                if (!held)
-                    return null;
-                return {
-                    object: 'claim',
-                    id: held.id,
-                    status: 'active',
-                    target: {
-                        type: held.target.model,
-                        id: held.target.id,
-                        ...(held.target.path ? { path: held.target.path } : {}),
-                        ...(held.target.range ? { range: held.target.range } : {}),
-                        ...(held.target.field ? { field: held.target.field } : {}),
-                        ...(held.target.meta ? { meta: held.target.meta } : {}),
-                    },
-                    description: held.description ?? 'editing',
-                    heldBy: held.actor,
-                    participantKind: held.participantKind,
-                    expiresAt: held.expiresAt,
-                };
-            },
-            waitFor: (target, waitOptions) => publicClaims.waitFor({ model: target.model, id: target.id }, waitOptions),
-            selfParticipantId: participantId,
-            selfParticipantKind: kind,
-            // Read-interest / write-intent enrolment for the typed surface.
-            // `enterScope`/`pinScope` resolve the `{ [schemaKey]: id }` scope
-            // through the same resolver the claim path uses, landing this client in
-            // the entity-scoped group the holder's claim presence fans out on.
-            // Returns the store promise so the claim write path can await pinScope
-            // before acquiring the lease (closing the subscribe-vs-broadcast race);
-            // read-interest callers (`retrieve`/`claim.state`) still `void` it and
-            // stay fire-and-forget. It's soft either way — the store swallows
-            // reconcile errors so read interest never makes a read reject or stall.
-            enterScope: (scope) => store.enterScope(scope),
-            pinScope: (scope) => store.pinScope(scope),
-            // `ablo.<model>.join(ids, { ttl })` performs a scoped participant join
-            // on this model's sync group(s). WebSocket only — `join` throws
-            // `AbloConnectionError` if the socket isn't ready.
-            createJoin: (modelKey, ids, options) => participantManager.join({
-                scope: { [modelKey]: ids },
-                ...(options?.ttl !== undefined ? { ttlSeconds: options.ttl } : {}),
-            }),
-        });
-    }
-    const commits = {
-        async create(commitOptions) {
-            await ready();
-            // Same runtime contract as the per-model writes — one schema.
-            assertWriteOptions({
-                idempotencyKey: commitOptions.idempotencyKey,
-                readAt: commitOptions.readAt,
-                onStale: commitOptions.onStale,
-                wait: commitOptions.wait,
-                claim: commitOptions.claim,
-            }, 'commits.create');
-            const clientTxId = createClientTxId(commitOptions.idempotencyKey);
-            // A claim handle supplies the batch stale-guard defaults — same
-            // semantics as `ablo.<model>.update({ id, data, claim })`, so the
-            // two write doors speak one claim vocabulary. Explicit options win.
-            const claim = commitOptions.claim ?? null;
-            const operations = normalizeCommitOperations({
-                ...commitOptions,
-                readAt: commitOptions.readAt ?? claim?.readAt ?? null,
-                onStale: commitOptions.onStale ?? (claim?.readAt !== undefined ? 'reject' : null),
-            }, claim?.fenceToken ?? null);
-            const wait = commitOptions.wait ?? 'confirmed';
-            // Route through the TransactionQueue's commit lane so the call
-            // tolerates WS disconnects: the envelope stays in memory until
-            // reconnect, mutationExecutor.commit() owns transport-level
-            // retry, and `mutation_log` server-side dedupes replays by
-            // clientTxId. Replaces the direct ws.sendCommit /
-            // sendCommitQueued path that threw synchronously on
-            // `ws.readyState !== OPEN`. The queue lives on the internal
-            // SyncClient we already hold from createInternalComponents —
-            // no need to leak an accessor through BaseSyncedStore.
-            const queue = syncClient.getTransactionQueue();
-            await queue.enqueueCommit(clientTxId, operations, {
-                ...(commitOptions.reads ? { reads: [...commitOptions.reads] } : {}),
-                ...(commitOptions.track ? { track: [...commitOptions.track] } : {}),
-            });
-            if (wait === 'queued') {
-                return { id: clientTxId, status: 'queued' };
-            }
-            const { lastSyncId, notifications, missingIds } = await queue.waitForCommitReceipt(clientTxId);
-            return {
-                id: clientTxId,
-                status: 'confirmed',
-                lastSyncId,
-                ...(notifications && notifications.length > 0 ? { notifications } : {}),
-                ...(missingIds && missingIds.length > 0 ? { missingIds } : {}),
-            };
-        },
-    };
-    /**
-     * The control-plane credential: always the original configured secret key.
-     * Never reads `authCredentials` — that holds the exchanged sync credential
-     * (a wide-scope `rk_` on the hosted path), which control-plane routes
-     * rightly refuse (e.g. the user-session mint is sk_-gated). Counterpart to
-     * `getAuthToken()`, which resolves the sync-plane token.
-     *
-     * The secret-key-only rule is enforced on the server; the credential-kind taxonomy
-     * (secret/restricted/ephemeral/publishable) lives in `auth/credentialPolicy`.
-     */
-    async function controlPlaneApiKey() {
-        return resolveApiKeyValue(configuredApiKey);
-    }
-    /**
-     * Resolve the control-plane context a session/agent mint needs (sk_ +
-     * bootstrap base URL + the schema-key→typename map the server gates on).
-     * Shared by `sessions.create` and `agents.create` so the two mint doors
-     * can never drift on how a token is minted. Throws if no `sk_` is present —
-     * minting is a backend-only operation.
-     */
-    async function buildMintContext(resource) {
-        const apiKey = await controlPlaneApiKey();
-        if (!apiKey) {
-            throw new AbloAuthenticationError(`${resource} requires a secret (sk_) API key — call it from your backend, not the browser.`, { code: 'apikey_missing' });
+    const humansSurface = installedPlugins.humans;
+    if (!humansSurface) {
+        // No materialiser requested. The empty list is the core client — the
+        // stateless surface plus the live feed, nothing else. A non-empty list
+        // without humans() has asked for a composition that does not exist yet
+        // (no other plugin is published), so it fails rather than guessing.
+        if ((options.plugins ?? []).length === 0) {
+            return layerPluginSurface(createCoreClient({
+                options,
+                baseUrl: url,
+                participantId,
+                kind,
+                syncGroups: internalOptions.syncGroups ?? [],
+                getAuthToken: authCredentials.getAuthToken,
+                logger,
+                observability: internalOptions.observability,
+            }), installedPlugins);
         }
-        return {
-            apiKey,
-            baseUrl: resolveBootstrapBaseUrl({
-                url,
-                bootstrapBaseUrl: internalOptions.bootstrapBaseUrl,
-            }),
-            ...(internalOptions.fetch ? { fetch: internalOptions.fetch } : {}),
-            // Map every `can` schema-key to the wire typename the server gates on, so a
-            // typename override (`documents` → `Document`) doesn't mint a capability
-            // the server then denies. See `MintSessionContext`.
-            modelTypenames: Object.fromEntries(Object.entries(schema.models).map(([key, def]) => [
-                key,
-                (def).typename ?? key,
-            ])),
-        };
-    }
-    const engine = {
-        ...modelProxies,
-        ready,
-        waitForFlush,
-        setAuthToken(token) {
-            // The single credential source is read lazily by bootstrap HTTP,
-            // lazy query HTTP, network probes, and WebSocket reconnect URL auth.
-            // Updating it here is enough for the next request/connect to use the
-            // refreshed token; no per-transport patching.
-            authCredentials.setAuthToken(token);
-            // A fresh credential is useless to a connection parked in offline /
-            // backoff / auth_blocked until the next probe trigger — so kick one now.
-            // Harmless while connected (the FSM ignores the nudge there).
-            store.nudgeReconnect();
-        },
-        async getAuthToken() {
-            // The live short-lived bearer (set via `setAuthToken` / `apiKey`-resolver refresh)
-            // is the canonical credential; fall back to a configured API key.
-            //
-            // This is the sync-plane token (bootstrap, WebSocket, query HTTP). Control-plane
-            // calls (sessions.create, datasource registration) never use it — they
-            // present the original secret key via `controlPlaneApiKey()` below. The
-            // split matters: after the startup exchange this resolver returns the
-            // derived wide-scope `rk_`, a credential the control-plane routes
-            // correctly refuse (an agent token must never mint humans).
-            return (authCredentials.getAuthToken() ??
-                (await resolveApiKeyValue(configuredApiKey)) ??
-                configuredAuthToken ??
-                null);
-        },
-        setCredentialRefresher(refresher) {
-            store.setCredentialRefresher(refresher);
-        },
-        // The org this client resolved to — null until `ready()` completes. Exposed
-        // as a property so integrators can read it programmatically.
-        get organizationId() {
-            return _resolvedOrganizationId;
-        },
-        nudgeReconnect() {
-            store.nudgeReconnect();
-        },
-        sessions: {
-            // A backend (holding `sk_`) mints a short-lived scoped token for one end
-            // user or one agent.
-            //
-            // Both arms authenticate with the original secret key
-            // (`controlPlaneApiKey()`), never the wide-scope `rk_` the startup exchange
-            // installed as the sync credential. A derived agent credential silently
-            // replacing the secret key on control-plane calls is how humans would get
-            // minted as agents — and correct attribution is the point.
-            async create(params) {
-                // Both mint paths (`{ user }` → /auth/ephemeral-keys → `ek_`,
-                // `{ agent, can }` → /auth/capability → scoped `rk_`) resolve their
-                // control-plane context through the shared `buildMintContext`, so this
-                // client, `agents.create`, and the stateless HTTP client can't drift on
-                // how a token is minted.
-                return mintSession(params, await buildMintContext('sessions.create'));
-            },
-        },
-        // Mint a scoped agent identity and hand back a connected client bound to it —
-        // `sessions.create({ agent })` plus a typed `Ablo({ schema, apiKey })` client,
-        // for agents that run in this (secret-key-holding) process. Omitting `id`
-        // yields a fresh uuid per call, so concurrent agents are distinct participants
-        // that queue behind each other (even when they share a `name`). Humans don't
-        // get a server-built client — ship them a token via `sessions.create({ user })`.
-        agents: {
-            async create(params) {
-                // Distinct participant by default: omit `id` → a fresh uuid, so even two
-                // agents that share a `name` are independent participants and queue
-                // behind one another. `name` is display only (→ userMeta.name); it never
-                // derives the id. Pass an explicit `id` only to re-attach an agent to
-                // its own held claims.
-                const id = params.id ?? globalThis.crypto.randomUUID();
-                const userMeta = params.name !== undefined ? { ...params.userMeta, name: params.name } : params.userMeta;
-                const sessionParams = {
-                    agent: { id },
-                    can: params.can,
-                    ...(params.syncGroups ? { syncGroups: params.syncGroups } : {}),
-                    ...(params.ttlSeconds !== undefined ? { ttlSeconds: params.ttlSeconds } : {}),
-                    ...(userMeta ? { userMeta } : {}),
-                };
-                // Re-mint the `rk_` on every resolver call so a long-lived agent client
-                // never hits token expiry; the `sk_` stays in this process — the child
-                // only ever sees its own short-lived `rk_`.
-                const mintToken = async () => (await mintSession(sessionParams, await buildMintContext('agents.create')))
-                    .token;
-                // Mint once up front so a bad key / denied scope throws HERE, not later
-                // inside the child's bootstrap; reuse that first token, re-mint on refresh.
-                let pending = await mintToken();
-                const apiKey = async () => {
-                    if (pending !== null) {
-                        const token = pending;
-                        pending = null;
-                        return token;
-                    }
-                    return mintToken();
-                };
-                return Ablo({ ...internalOptions, apiKey });
-            },
-        },
-        async dispose() {
-            _refreshScheduler?.dispose();
-            _refreshScheduler = null;
-            try {
-                await store.disconnect();
-            }
-            catch (err) {
-                // Best-effort teardown — a disposal hiccup isn't consumer-actionable → debug.
-                logger.debug('Error during sync engine disposal', { error: err.message });
-            }
-            presenceStream.dispose();
-            claimStream.dispose();
-            syncClient.dispose();
-        },
-        /**
-         * Destroy every IndexedDB database owned by this engine. Disconnects
-         * the WebSocket, releases timers, and deletes all `ablo_*` / `ablo-*`
-         * databases. Typically called on session expiry or explicit logout.
-         * Best-effort — errors from individual deletions are swallowed.
-         */
-        async purge() {
-            await store.purge();
-            syncClient.dispose();
-        },
-        /**
-         * Subscribe to session-error events. Fires when the server rejects
-         * the session (WebSocket close code 1008/4001/4003 or a session_error
-         * frame). Multiple subscribers supported; returns an unsubscribe
-         * function. Consumers typically use this to trigger auth-failed UI
-         * flows (e.g., redirect to sign-in). Does not automatically purge the
-         * IndexedDB — call `engine.purge()` from the listener if you need
-         * that behavior (the SDK's `<AbloProvider>` does this by default).
-         */
-        onSessionError(listener) {
-            return store.subscribeSessionError(listener);
-        },
-        onMutationFailure(listener) {
-            return store.subscribeMutationFailure(listener);
-        },
-        waitForConfirmation(modelName, modelId) {
-            return store.waitForConfirmation(modelName, modelId);
-        },
-        // Expose the store's MobX observable directly — single source of truth.
-        // React components using observer() will re-render automatically on
-        // any state change (syncing, error, offline, pendingChanges, progress).
-        get syncStatus() {
-            return store.syncStatus;
-        },
-        schema,
-        // ── Internal accessors for framework integration ─────────────────
-        // These expose internal components for consumers that need direct
-        // access (e.g., SyncEngineProvider wiring SyncContext, collaboration
-        // events accessing the WebSocket handle, demand loaders accessing
-        // the pool). Prefixed with _ to signal "internal but stable."
-        /** The BaseSyncedStore — implements SyncStoreContract for SyncContext.Provider. */
-        get _store() { return store; },
-        /** The InstanceCache — for demand loaders that need pool.createFromData(). */
-        get _pool() { return objectPool; },
-        /** The SyncWebSocket — for collaboration events (slide selection, cursors). */
-        get _ws() { return store.getSyncWebSocket() ?? null; },
-        /** Presence livestream — same socket as entity sync, no second
-         *  connection. Stable reference across the engine's lifetime. */
-        presence: presenceStream,
-        /** Claim livestream — same socket. Stable reference. */
-        claims: publicClaims,
-        commits,
-        /** Context-staleness snapshot — see `engine.snapshot(...)` JSDoc. */
-        snapshot(entities) {
-            return createSnapshot({
-                pool: objectPool,
-                transport: store.getSyncWebSocket(),
-                getLastSyncId: () => store.getSyncWebSocket()?.getLastSyncId() ?? store.lastSyncId ?? 0,
-                entities,
-            });
-        },
-    };
-    return engine;
+        throw new AbloValidationError('Add humans() to the plugins list, pass an empty list for the core client, ' +
+            'or leave plugins out to get the default.', { code: 'invalid_options', param: 'plugins' });
+    }
+    if (!humansSurface.presence) {
+        // A foreign plugin is squatting on the reserved 'humans' id — its surface
+        // is not the one this client is built from.
+        throw new AbloValidationError("The 'humans' plugin id is reserved for the SDK's own humans() plugin. " +
+            'Rename the custom plugin.', { code: 'invalid_options', param: 'plugins' });
+    }
+    if (!transport) {
+        // Unreachable: the humans surface exists only when the list contained
+        // 'humans', which is exactly the condition the transport was built under.
+        throw new AbloValidationError('The reactive client was selected but no connection was constructed.', { code: 'invalid_options', param: 'plugins' });
+    }
+    const cluster = humansSurface[kStoreCluster];
+    if (!cluster) {
+        // Unreachable on this path: the context above carries everything the
+        // cluster needs (connection, url, credential source, schema). A missing
+        // cluster means the context and the plugin disagree — say so rather
+        // than building a client with no store.
+        throw new AbloValidationError('The reactive client was selected but no store was constructed.', { code: 'invalid_options', param: 'plugins' });
+    }
+    // The reactive engine is the humans() capability: `init` constructed the
+    // store cluster (runtime, component graph, store) from the widened
+    // context; what remains here builds in `./reactiveEngine.ts`, fed the
+    // prelude plus the plugin's contributions. The host owns assembly;
+    // plugins declare and construct their own parts. A plugin surface that
+    // hands back a whole-client constructor inverts that relationship —
+    // tried and rejected (ADR 0016, follow-up 3b).
+    return layerPluginSurface(buildReactiveEngine({
+        ...prelude,
+        options,
+        transport,
+        presence: humansSurface.presence,
+        cluster,
+        createSibling: (siblingOptions) => Ablo(siblingOptions),
+    }), installedPlugins);
 }