@abloatai/ablo 0.36.0 → 0.37.1

package/dist/client/reactiveEngine.js

@@ -1,688 +0,0 @@
-/**
- * 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;
-}