@abloatai/ablo 0.34.1 → 0.36.0

package/dist/client/reactiveEngine.js

@@ -0,0 +1,688 @@
+/**
+ * The reactive engine assembly (ADR 0016). `Ablo({ ... })` resolves auth and
+ * capabilities; `humans().init` constructs the store cluster; the lifecycle
+ * — first mint, identity, ready() — lives in `./storeLifecycle.ts`. What
+ * remains here is assembly around those parts: the claim stream and
+ * participant manager, options validation, the typed model proxies, and the
+ * commit/claim/session resources — composed into the reactive client.
+ *
+ * Extracted from the factory so the composition root stays a root: resolve,
+ * dispatch, return. The remaining assembly converts to decoration of a
+ * host-built core client with the per-model surface split — the cut's own
+ * design step (docs/plans/package-split.md).
+ */
+import { durableCommitOperationSchema, } from '../transaction/transactions/settlement/commitEnvelope.js';
+import { AbloAuthenticationError, AbloConnectionError, AbloValidationError, claimedError } from '../transaction/errors.js';
+import { batchFence, fenceTokenFor, modelTarget, streamTarget, subTarget, } from '../transaction/coordination/index.js';
+import { validateAbloOptions } from './validateAbloOptions.js';
+import { mintSession } from '../transaction/auth/sessionMint.js';
+import { modelWireNames } from '../transaction/auth/capability.js';
+import { startStoreLifecycle } from './storeLifecycle.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 { resolveApiKeyValue, resolveBootstrapBaseUrl } from '../transaction/auth/apiKey.js';
+import { createModelProxy } from './createModelProxy.js';
+import { assertWriteOptions } from '../transaction/resources/writeOptionsSchema.js';
+export function buildReactiveEngine(inputs) {
+    const { options, internalOptions, url, logger, configuredApiKey, configuredAuthToken, credentialResolver, authCredentials, transport, participantId, kind, presence, cluster, createSibling, } = inputs;
+    const schema = options.schema;
+    // The store cluster — this client's runtime, the component graph, the
+    // registered models, and the store — was constructed by `humans().init`
+    // from the widened plugin context (see `./storeCluster.ts`). The engine
+    // assembles around it.
+    const { runtime, components, store } = cluster;
+    const { modelRegistry, objectPool, bootstrapHelper, database, syncClient, hydration, } = components;
+    // Self identity, late-bound the same way the connection's values are: the
+    // construction-time guess seeds it (correct on the self-hosted path, empty
+    // on the hosted path), and `ready()` overwrites it with what identity
+    // resolution derives from the credential's scope. The model proxies read
+    // it through getters, so the is-this-claim-mine checks always compare
+    // against the resolved identity.
+    let selfParticipantId = participantId;
+    let selfParticipantKind = kind;
+    // Presence + claim streams — the same reference for the engine's lifetime,
+    // attached to the connection at construction (it exists — the host built
+    // it; sends before the socket opens are dropped by the transport's
+    // send-during-reconnect contract, and each stream re-announces on
+    // `connected`). The presence stream is the humans() plugin's contribution,
+    // built and attached by its `init` (ADR 0016); the claim stream is core
+    // coordination, so the root constructs it regardless of the list. Both
+    // filter own echoes by participant id, seeded in `ready()` alongside the
+    // locals above.
+    const presenceStream = presence;
+    const claimStream = createClaimStream({ participantId, logger }, transport);
+    // 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).
+    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 lifecycle — first mint, identity resolution, credential refresh,
+    //    and the idempotent ready() driving store.initialize() — is the
+    //    materialiser's own (`./storeLifecycle.ts`); the engine wires it with
+    //    the prelude's credential slice and seeds its own state through the
+    //    callback: the self locals (read by the model proxies' getters) and
+    //    the streams' own-echo filters, before the store ever connects.
+    /** Resolved account scope — seeded once identity resolution completes;
+     *  exposed as the readonly `ablo.organizationId` accessor. */
+    let _resolvedOrganizationId = null;
+    const lifecycle = startStoreLifecycle({
+        cluster,
+        schema,
+        internalOptions,
+        authCredentials,
+        credentialResolver,
+        configuredApiKey,
+        configuredAuthToken,
+        url,
+        kind,
+        logger,
+        validationError: _validationError,
+        onIdentityResolved: ({ userId, participantKind, accountScope, syncGroups }) => {
+            selfParticipantId = userId;
+            selfParticipantKind = participantKind;
+            _resolvedOrganizationId = accountScope;
+            presenceStream.setParticipant({
+                id: userId,
+                kind: participantKind,
+                syncGroups: [...syncGroups],
+            });
+            claimStream.setParticipant({ id: userId });
+        },
+    });
+    const ready = lifecycle.ready;
+    const participantManager = createParticipantManager({
+        ready,
+        transport,
+        presence: presenceStream,
+        claims: claimStream,
+        schema,
+    });
+    // 9b. waitForFlush — drains pending mutations using the store's
+    //     pendingChanges counter (already maintained by BaseSyncedStore based
+    //     on MutationQueue 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, fence) {
+        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,
+            fenceToken: op.fenceToken ?? fenceTokenFor(fence, op.model, op.id ?? null) ?? undefined,
+        });
+    }
+    function normalizeCommitOperations(commitOptions, fence) {
+        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, fence));
+    }
+    function modelClaimFromActive(claim) {
+        const target = {
+            ...modelTarget(claim.target),
+            ...subTarget(claim.target),
+        };
+        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,
+            // The claim's metadata read as the open record it is on the wire, so a
+            // key the coordinator wrote — a heartbeat's `progress` — is readable.
+            // `target.meta` is the same bag under the shape the program declared,
+            // and a declared shape has no member for something the holder did not
+            // write.
+            ...(target.meta !== undefined ? { meta: 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;
+            const cleanup = () => {
+                if (timeoutId)
+                    clearTimeout(timeoutId);
+                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 abortError = () => new AbloConnectionError('Claim wait aborted.', {
+                code: 'claim_wait_aborted',
+                cause: options?.signal?.reason,
+            });
+            const onAbort = () => {
+                finish(() => { reject(abortError()); });
+            };
+            // Answered before the subscription, the listener, and the timer exist,
+            // so there is nothing for `cleanup` to undo — and nothing that would
+            // read `unsubscribe` ahead of the line that binds it.
+            if (options?.signal?.aborted) {
+                reject(abortError());
+                return;
+            }
+            const 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 = () => {
+            claim.revoke?.();
+            return Promise.resolve();
+        };
+        // 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({
+                ...streamTarget(claimOptions.target),
+                ...subTarget(claimOptions.target),
+            }, {
+                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) {
+                try {
+                    ({ waited, fenceToken } = await awaitClaimGrant(transport, claim.id, {
+                        timeoutMs: claimOptions.waitTimeoutMs,
+                        maxQueueDepth: claimOptions.maxQueueDepth,
+                        signal: claimOptions.signal,
+                        logger,
+                    }));
+                }
+                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);
+        },
+    });
+    /**
+     * One held claim, as the public claim-state object.
+     *
+     * The live claim stream only tracks *open* 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 claimStateOf = (held) => {
+        if (!held)
+            return null;
+        return {
+            object: 'claim',
+            id: held.id,
+            status: 'active',
+            target: {
+                ...streamTarget(held.target),
+                ...subTarget(held.target),
+            },
+            description: held.description ?? 'editing',
+            heldBy: held.actor,
+            participantKind: held.participantKind,
+            expiresAt: held.expiresAt,
+            // Carried, not dropped: the coordinator writes a heartbeat's `details`
+            // into `meta.progress` on the holder's record so an observer can see
+            // what a long hold is doing. It reached `ModelClaim` and stopped here,
+            // which left the beat writable and unreadable — a channel with a setter
+            // and no getter. `target.meta` beside it stays the declared shape; this
+            // is the open record, because a declared shape has no member for a key
+            // the holder did not write.
+            ...(held.meta !== undefined ? { meta: held.meta } : {}),
+        };
+    };
+    // 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,
+                // `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 logPosition.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(streamTarget(target)),
+            reorder: (target, order) => { publicClaims.reorder(streamTarget(target), order); },
+            // One row can have several holders — sub-row claims on disjoint
+            // targets are all granted — so `state` and `holders` read the same
+            // list and differ only in how much of it they answer with. The
+            // projection lives here once: two copies of it would drift the
+            // moment a field is added to one caller's answer.
+            state: (target) => claimStateOf(publicClaims.list(modelTarget(target))[0]),
+            holders: (target) => publicClaims
+                .list(modelTarget(target))
+                .map((held) => claimStateOf(held))
+                .filter((claim) => claim !== null),
+            waitFor: (target, waitOptions) => publicClaims.waitFor(modelTarget(target), waitOptions),
+            // Getters, not copies: identity is late-bound (seeded in `ready()`),
+            // and the contended / heldBy checks must compare against whoever
+            // this client resolved to, not the construction-time guess.
+            get selfParticipantId() { return selfParticipantId; },
+            get selfParticipantKind() { return selfParticipantKind; },
+            // 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.
+            // `ttl` passes straight through — both surfaces spell the lease the
+            // same way now, so there is no rename here to make a field's name
+            // disagree with the value it carries.
+            createJoin: (modelKey, ids, options) => participantManager.join({
+                scope: { [modelKey]: ids },
+                ...(options?.ttl !== undefined ? { ttl: options.ttl } : {}),
+            }),
+        }, 
+        // The client-wide `wait` default; a per-call `wait` still wins.
+        internalOptions.wait);
+    }
+    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),
+            }, batchFence(claim?.target, claim?.fenceToken));
+            const wait = commitOptions.wait ?? 'confirmed';
+            // Route through the MutationQueue'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.getMutationQueue();
+            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' });
+        }
+        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. Derived from this client's schema by the one rule
+            // the HTTP client and the mint route also read. See `MintSessionContext`.
+            modelTypenames: modelWireNames(schema.models),
+        };
+    }
+    const engine = {
+        ...modelProxies,
+        ready,
+        waitForFlush,
+        /** Durable frame subscription — delegates to the store's registry, which
+         *  re-attaches across socket rebuilds. */
+        subscribe: (event, handler) => store.subscribe(event, handler),
+        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 createSibling({ ...internalOptions, apiKey });
+            },
+        },
+        async dispose() {
+            lifecycle.dispose();
+            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);
+        },
+        onCommitLatency(listener) {
+            return store.subscribeCommitLatency(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 (selection, cursors). */
+        get _ws() { return store.getSyncWebSocket(); },
+        /** 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,
+                getLastSyncId: () => transport.getLastSyncId(),
+                entities,
+            });
+        },
+    };
+    return engine;
+}