@abloatai/ablo 0.7.0 → 0.9.0

package/dist/client/createModelProxy.js

@@ -7,13 +7,15 @@
  * testable in isolation and the constructor doesn't carry it.
  *
  * Each schema model gets one `ModelOperations<T, CreateInput>` —
- * exposes `retrieve`, `list`, `count`, `create`, `update`, `delete`,
- * `claim`, `claimState`, `queue`, `release`, `subscribe`, and `load`.
- * The factory returns a plain object; the client assembles the
- * `ablo.<model>` lookup table from these.
+ * exposes the async server reads `retrieve` / `list`, the synchronous
+ * local-graph snapshots `get` / `getAll` / `getCount`, the writes
+ * `create` / `update` / `delete`, the coordination namespace `claim`
+ * (`claim({ id })` plus `claim.state` / `claim.queue` / `claim.release` /
+ * `claim.reorder`), and `onChange`. The factory returns a plain object; the
+ * client assembles the `ablo.<model>` lookup table from these.
  */
 import { autorun } from 'mobx';
-import { AbloClaimedError, AbloValidationError } from '../errors.js';
+import { AbloClaimedError, AbloValidationError, toAbloError, } from '../errors.js';
 import { Model, modelAsRow } from '../Model.js';
 import { ModelScope } from '../types/index.js';
 const modelClientMeta = new WeakMap();
@@ -28,6 +30,22 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         throw new AbloValidationError(`Ablo: schema model "${schemaKey}" resolved to "${registeredModelName}", ` +
             'but no matching constructor was registered.', { code: 'model_not_registered' });
     }
+    // Last-line guarantee for the public surface: any rejection from a lower
+    // layer (transport timeout, IndexedDB failure, a third-party throw) is
+    // coerced to an AbloError before it reaches the consumer. The SDK's
+    // contract is that callers only ever catch tagged errors — `instanceof
+    // AbloError` / `e.type` always hold. Internal helpers stay unwrapped; only
+    // the methods exposed on `operations` are guarded.
+    const guard = (fn) => {
+        return async (...args) => {
+            try {
+                return await fn(...args);
+            }
+            catch (err) {
+                throw toAbloError(err);
+            }
+        };
+    };
     const load = async (options) => {
         const rows = await hydration.fetch(schemaKey, options);
         // The coordinator returns Model instances. ModelOperations is
@@ -43,9 +61,23 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         await syncClient.waitForConfirmation(model.getModelName(), model.id);
     };
     // Claims this proxy currently holds, keyed by entity id. Lets the flat
-    // `release(id)` and `update(id)` find the lease + snapshot a `claim(id)`
+    // `release({ id })` and `update({ id, data })` find the lease + snapshot a `claim({ id })`
     // took — no per-call handle. Released on dispose, explicit release, or TTL.
     const activeClaims = new Map();
+    const isClaimHandle = (value) => typeof value === 'object' &&
+        value !== null &&
+        value.object === 'claim' &&
+        typeof value.claimId === 'string' &&
+        typeof value.release === 'function';
+    const claimMeta = (options) => {
+        if (!options?.description)
+            return options?.meta;
+        return { ...(options.meta ?? {}), description: options.description };
+    };
+    const mutationOptions = (params) => {
+        const { id: _id, data: _data, claim: _claim, ...rest } = params;
+        return rest;
+    };
     const releaseClaim = async (id) => {
         const held = activeClaims.get(id);
         if (!held)
@@ -53,10 +85,11 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         activeClaims.delete(id);
         await held.lease.release();
     };
-    const takeClaim = async (id, options) => {
+    const takeClaim = async (params) => {
         if (!collaboration) {
             throw new AbloValidationError(`Model "${schemaKey}" cannot claim a row without collaboration wiring.`, { code: 'model_claim_not_configured' });
         }
+        const { id, ...options } = params;
         // Is someone ELSE already on this target? Read the local coordination
         // snapshot up front — it decides whether we'll need to re-read after the
         // claim (a free / already-mine target can't have changed under us).
@@ -91,6 +124,9 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                 model: schemaKey,
                 id,
                 ...(options?.field ? { field: options.field } : {}),
+                ...(options?.path ? { path: options.path } : {}),
+                ...(options?.range ? { range: options.range } : {}),
+                ...(claimMeta(options) ? { meta: claimMeta(options) } : {}),
             },
             action: options?.action ?? 'editing',
             ttl: options?.ttl,
@@ -106,34 +142,63 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         }
         const snapshot = collaboration.createSnapshot(schemaKey, id);
         activeClaims.set(id, { lease, snapshot });
-        const row = modelAsRow(model);
-        // `await using` calls this on scope exit; releases the claim.
-        Object.defineProperty(row, Symbol.asyncDispose, {
-            value: () => releaseClaim(id),
-            enumerable: false,
-            configurable: true,
-        });
-        return row;
+        const target = {
+            model: schemaKey,
+            id,
+            ...(options?.field ? { field: options.field } : {}),
+            ...(options?.path ? { path: options.path } : {}),
+            ...(options?.range ? { range: options.range } : {}),
+            ...(claimMeta(options) ? { meta: claimMeta(options) } : {}),
+        };
+        const release = () => releaseClaim(id);
+        return {
+            object: 'claim',
+            claimId: lease.id,
+            target,
+            action: options?.action ?? 'editing',
+            ...(options?.description ? { description: options.description } : {}),
+            data: modelAsRow(model),
+            release,
+            revoke: () => {
+                void release();
+            },
+            [Symbol.asyncDispose]: release,
+        };
     };
-    function claim(id, a, b) {
-        if (typeof a === 'function') {
-            return (async () => {
-                const row = await takeClaim(id, b);
-                try {
-                    return await a(row);
-                }
-                finally {
-                    await releaseClaim(id);
-                }
-            })();
-        }
-        return takeClaim(id, a);
-    }
+    const claim = (params) => takeClaim(params);
+    // `claim` is a callable namespace: invoke it to take a claim, reach its
+    // members to read/steer the coordination plane. Attach the readers to the
+    // guarded callable so `ablo.<model>.claim(...)` and `ablo.<model>.claim.state(...)`
+    // are the same object.
+    const claimApi = Object.assign(guard(claim), {
+        state(params) {
+            return collaboration?.observe({ model: schemaKey, id: params.id }) ?? null;
+        },
+        queue(params) {
+            return {
+                object: 'list',
+                data: collaboration?.queue({ model: schemaKey, id: params.id }) ?? [],
+            };
+        },
+        reorder(params) {
+            collaboration?.reorder({ model: schemaKey, id: params.id }, params.order);
+        },
+        release: guard((params) => releaseClaim(isClaimHandle(params) ? params.target.id : params.id)),
+    });
     const operations = {
-        retrieve(id) {
+        retrieve: guard(async (params) => {
+            const rows = await load({
+                ...params,
+                where: { id: params.id },
+                limit: 1,
+            });
+            return rows[0];
+        }),
+        list: guard(load),
+        get(id) {
             return objectPool.get(id);
         },
-        list(options) {
+        getAll(options) {
             const all = objectPool.getByType(ModelClass, (options?.state ?? ModelScope.live));
             let result = all;
             if (options?.where) {
@@ -166,73 +231,143 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                 result = result.slice(0, options.limit);
             return result;
         },
-        count(options) {
-            return this.list(options).length;
+        getCount(options) {
+            return this.getAll(options).length;
         },
-        async create(data, options) {
-            // TODO(options-persistence): stash `options` alongside the
+        create: guard(async (params) => {
+            // TODO(options-persistence): stash `params` alongside the
             // queued transaction so idempotencyKey survives offline flush.
+            const id = params.id ?? Model.generateId();
+            const opts = mutationOptions(params);
+            const claim = params.claim;
+            let autoLease;
+            if (claim && !isClaimHandle(claim)) {
+                if (!collaboration) {
+                    throw new AbloValidationError(`Model "${schemaKey}" cannot claim a row without collaboration wiring.`, { code: 'model_claim_not_configured' });
+                }
+                autoLease = await collaboration.createIntent({
+                    target: {
+                        model: schemaKey,
+                        id,
+                        ...(claim.field ? { field: claim.field } : {}),
+                        ...(claim.path ? { path: claim.path } : {}),
+                        ...(claim.range ? { range: claim.range } : {}),
+                        ...(claimMeta(claim) ? { meta: claimMeta(claim) } : {}),
+                    },
+                    action: claim.action ?? 'creating',
+                    ttl: claim.ttl,
+                    queue: claim.wait !== false,
+                    maxQueueDepth: claim.maxQueueDepth,
+                });
+            }
             const model = new ModelClass({
-                id: Model.generateId(),
-                ...data,
+                id,
+                ...params.data,
                 createdAt: new Date(),
                 updatedAt: new Date(),
             });
-            syncClient.add(model, options);
-            await waitForMutation(model, options);
-            return modelAsRow(model);
-        },
-        async update(id, data, options) {
+            const effective = {
+                ...opts,
+                ...(autoLease ? { intent: autoLease } : {}),
+                ...(isClaimHandle(claim) ? { intent: { id: claim.claimId } } : {}),
+            };
+            try {
+                syncClient.add(model, effective);
+                await waitForMutation(model, effective);
+                return modelAsRow(model);
+            }
+            finally {
+                await autoLease?.release().catch(() => { });
+            }
+        }),
+        update: guard(async (params) => {
+            const autoClaim = params.claim && !isClaimHandle(params.claim) ? params.claim : null;
+            if (autoClaim) {
+                const handle = await takeClaim({ ...autoClaim, id: params.id });
+                try {
+                    return await operations.update({ ...params, claim: handle });
+                }
+                finally {
+                    await handle.release();
+                }
+            }
+            const { id } = params;
             const model = objectPool.get(id);
             if (!model)
                 throw new AbloValidationError(`Entity not found: ${registeredModelName}/${id}`, { code: 'entity_not_found' });
             // If we hold a claim on this row, guard the write with its snapshot
             // watermark + lease so it's stale-rejected and attributed to the claim.
             const claimed = activeClaims.get(id);
+            const opts = mutationOptions(params);
+            const handleIntent = isClaimHandle(params.claim)
+                ? { id: params.claim.claimId }
+                : undefined;
             const effective = claimed
                 ? {
                     wait: 'confirmed',
                     readAt: claimed.snapshot.stamp,
                     onStale: 'reject',
                     intent: claimed.lease,
-                    ...options,
+                    ...opts,
                 }
-                : options;
-            model.updateFromData(data);
+                : {
+                    ...opts,
+                    ...(handleIntent ? { intent: handleIntent } : {}),
+                };
+            // Local user update: `applyChanges` keeps change tracking ON so
+            // the edited fields land in `modifiedProperties` and actually get
+            // sent to the server. (`updateFromData` is the hydration path and
+            // would discard the tracking → empty `input: {}` no-op mutation.)
+            model.applyChanges(params.data);
             syncClient.update(model, effective);
             await waitForMutation(model, effective);
             return modelAsRow(model);
-        },
-        async delete(id, options) {
+        }),
+        delete: guard(async (params) => {
+            const autoClaim = params.claim && !isClaimHandle(params.claim) ? params.claim : null;
+            if (autoClaim) {
+                const handle = await takeClaim({ ...autoClaim, id: params.id });
+                try {
+                    await operations.delete({ ...params, claim: handle });
+                }
+                finally {
+                    await handle.release();
+                }
+                return;
+            }
+            const { id } = params;
             const model = objectPool.get(id);
             if (!model)
                 throw new AbloValidationError(`Entity not found: ${registeredModelName}/${id}`, { code: 'entity_not_found' });
-            syncClient.delete(model, options);
-            await waitForMutation(model, options);
-        },
-        claim,
-        claimState(id) {
-            return collaboration?.observe({ model: schemaKey, id }) ?? null;
-        },
-        queue(id) {
-            return {
-                object: 'list',
-                data: collaboration?.queue({ model: schemaKey, id }) ?? [],
-            };
-        },
-        reorder(id, order) {
-            collaboration?.reorder({ model: schemaKey, id }, order);
-        },
-        release(id) {
-            return releaseClaim(id);
-        },
+            const claimed = activeClaims.get(id);
+            const opts = mutationOptions(params);
+            const handleIntent = isClaimHandle(params.claim)
+                ? { id: params.claim.claimId }
+                : undefined;
+            const effective = claimed
+                ? {
+                    wait: 'confirmed',
+                    readAt: claimed.snapshot.stamp,
+                    onStale: 'reject',
+                    intent: claimed.lease,
+                    ...opts,
+                }
+                : {
+                    ...opts,
+                    ...(handleIntent ? { intent: handleIntent } : {}),
+                };
+            syncClient.delete(model, effective);
+            await waitForMutation(model, effective);
+        }),
+        // `claim` is a callable namespace (take a claim) carrying the coordination
+        // readers (`claim.state` / `claim.queue` / `claim.release` / `claim.reorder`).
+        claim: claimApi,
         onChange(callback, options) {
             return autorun(() => {
-                const entities = this.list(options);
+                const entities = this.getAll(options);
                 callback(entities);
             });
         },
-        load,
     };
     modelClientMeta.set(operations, {
         key: schemaKey,

package/dist/client/httpClient.d.ts

@@ -0,0 +1,71 @@
+/**
+ * `createAbloHttpClient` — a STATELESS, typed HTTP client for server-side actors
+ * (agents, workers, serverless), modelled on `@liveblocks/node` / the Stripe
+ * server SDK / Netflix Conductor workers: it talks to Ablo over plain HTTP with
+ * the credential as identity, and holds **no WebSocket and no connection state**.
+ *
+ * Why this exists (docs/plans/agent-transport-event-driven.md): the stateful
+ * `Ablo({ schema })` client is for INTERACTIVE participants — it opens a
+ * WebSocket and seeds its identity (userId/orgId) during the connect/bootstrap
+ * step, then routes writes through a `TransactionQueue` that drops mutations
+ * until that identity exists. A reactive agent has no socket, so that identity is
+ * never seeded and writes drop. The proven fix (unanimous across Liveblocks,
+ * Stripe, PlanetScale, Conductor, Better Auth) is NOT to de-socket the stateful
+ * client — it's a separate stateless client where the credential carries identity
+ * and the SERVER resolves it per request.
+ *
+ * Ablo already has that stateless surface: `Ablo({ schema: null })` returns the
+ * protocol client (`createProtocolClient` → `AbloApi`), which commits via
+ * `POST /v1/commits` and reads via the HTTP `ApiClient`, authenticating with the
+ * Bearer token on every request. Its only ergonomic gap is that model access is
+ * string-keyed (`api.model('slides')`) rather than typed (`api.slides`). This
+ * wraps it in a typed proxy facade so server code gets the SAME `client.<model>`
+ * surface as the browser client — typed proxies, stateless transport.
+ */
+import { type AbloApiClientOptions, type TaskCreateOptions } from './ApiClient.js';
+import type { CommitReceipt, CommitResource, HttpClaimApi, ModelRead, ModelReadOptions, Turn } from './Ablo.js';
+import type { ModelCreateParams, ModelDeleteParams, ModelLoadOptions, ModelRetrieveParams, ModelUpdateParams } from './createModelProxy.js';
+import type { Schema, SchemaRecord, InferModel, InferCreate } from '../schema/schema.js';
+export interface AbloHttpClientOptions<S extends SchemaRecord> extends Omit<AbloApiClientOptions, 'schema'> {
+    /** The schema — used for TYPING only (typed model proxies); never sent or used at runtime. */
+    readonly schema: Schema<S>;
+}
+/**
+ * The per-model HTTP surface — exactly what a stateless client can do over
+ * request/response: reads (`retrieve`/`list`), writes (`create`/`update`/`delete`),
+ * and the durable-lease claim plane (`claim` — acquire/hold/release). It does NOT
+ * include `get`/`getAll`/`getCount` (local synced-pool reads) or `onChange` (live
+ * subscription); those need the stateful plane and are absent BY TYPE here.
+ */
+export interface HttpModelClient<T, C = T> {
+    retrieve(params: ModelRetrieveParams & ModelReadOptions): Promise<ModelRead<T>>;
+    list(options?: ModelLoadOptions<T>): Promise<T[]>;
+    create(params: ModelCreateParams<T, C>): Promise<CommitReceipt>;
+    update(params: ModelUpdateParams<C>): Promise<CommitReceipt>;
+    delete(params: ModelDeleteParams<T>): Promise<CommitReceipt>;
+    claim: HttpClaimApi<T>;
+}
+/**
+ * The honest type of the stateless HTTP client: typed model proxies (the
+ * request/response subset) + `commits` + `beginTurn` + `dispose`. Reaching for a
+ * stateful-only capability (`get`/`getAll`/`getCount`, `onChange`,
+ * `claim.state`/`queue`/`reorder`) is a COMPILE error here, not a latent runtime
+ * `undefined` — the type matches what the transport can actually do.
+ */
+export type AbloHttpClient<S extends SchemaRecord> = {
+    readonly [K in keyof S & string]: HttpModelClient<InferModel<Schema<S>, K>, InferCreate<Schema<S>, K>>;
+} & {
+    readonly commits: CommitResource;
+    beginTurn(options: TaskCreateOptions): Promise<Turn>;
+    dispose(): Promise<void>;
+    /** Resolve the bearer credential this client authenticates with (see `AbloApi.getAuthToken`). */
+    getAuthToken(): Promise<string | null>;
+    /** String-keyed model accessor (for dynamic model names). */
+    model<T = Record<string, unknown>>(name: string): HttpModelClient<T>;
+};
+/**
+ * Stateless, typed HTTP client. Each `client.<model>` resolves to the protocol
+ * client's `model(name)`; `commits`, `beginTurn`, `tasks`, `dispose`, etc. pass
+ * through. No socket is ever opened; identity is the Bearer credential.
+ */
+export declare function createAbloHttpClient<S extends SchemaRecord>(options: AbloHttpClientOptions<S>): AbloHttpClient<S>;

package/dist/client/httpClient.js

@@ -0,0 +1,69 @@
+/**
+ * `createAbloHttpClient` — a STATELESS, typed HTTP client for server-side actors
+ * (agents, workers, serverless), modelled on `@liveblocks/node` / the Stripe
+ * server SDK / Netflix Conductor workers: it talks to Ablo over plain HTTP with
+ * the credential as identity, and holds **no WebSocket and no connection state**.
+ *
+ * Why this exists (docs/plans/agent-transport-event-driven.md): the stateful
+ * `Ablo({ schema })` client is for INTERACTIVE participants — it opens a
+ * WebSocket and seeds its identity (userId/orgId) during the connect/bootstrap
+ * step, then routes writes through a `TransactionQueue` that drops mutations
+ * until that identity exists. A reactive agent has no socket, so that identity is
+ * never seeded and writes drop. The proven fix (unanimous across Liveblocks,
+ * Stripe, PlanetScale, Conductor, Better Auth) is NOT to de-socket the stateful
+ * client — it's a separate stateless client where the credential carries identity
+ * and the SERVER resolves it per request.
+ *
+ * Ablo already has that stateless surface: `Ablo({ schema: null })` returns the
+ * protocol client (`createProtocolClient` → `AbloApi`), which commits via
+ * `POST /v1/commits` and reads via the HTTP `ApiClient`, authenticating with the
+ * Bearer token on every request. Its only ergonomic gap is that model access is
+ * string-keyed (`api.model('slides')`) rather than typed (`api.slides`). This
+ * wraps it in a typed proxy facade so server code gets the SAME `client.<model>`
+ * surface as the browser client — typed proxies, stateless transport.
+ */
+import { createProtocolClient, } from './ApiClient.js';
+/**
+ * Members of the underlying `AbloApi` that pass straight through the facade.
+ * Deliberately EXCLUDES the resource names that collide with common schema model
+ * names — `tasks`, `intents`, `capabilities`, `agent` — so `client.tasks` resolves
+ * to the schema model `tasks`, not the protocol `TaskResource`. Only lifecycle +
+ * the genuinely-protocol methods an agent uses pass through.
+ */
+const PROTOCOL_MEMBERS = new Set([
+    'ready',
+    'waitForFlush',
+    'dispose',
+    'purge',
+    'commits',
+    'beginTurn',
+    'model',
+    'getAuthToken',
+]);
+/**
+ * Stateless, typed HTTP client. Each `client.<model>` resolves to the protocol
+ * client's `model(name)`; `commits`, `beginTurn`, `tasks`, `dispose`, etc. pass
+ * through. No socket is ever opened; identity is the Bearer credential.
+ */
+export function createAbloHttpClient(options) {
+    // The schema is type-level only; the protocol client is schema-agnostic.
+    const { schema: _schema, ...rest } = options;
+    const api = createProtocolClient({ ...rest, schema: null });
+    const facade = new Proxy(api, {
+        get(target, prop) {
+            if (typeof prop !== 'string')
+                return Reflect.get(target, prop);
+            // Real protocol members pass through unchanged.
+            if (PROTOCOL_MEMBERS.has(prop) && prop in target)
+                return Reflect.get(target, prop);
+            // Anything else is a typed model accessor → the string-keyed protocol model
+            // (which implements retrieve/list/create/update/delete/claim — every method
+            // `HttpModelClient` declares).
+            return api.model(prop);
+        },
+    });
+    // One boundary cast — and now an HONEST one: `AbloHttpClient<S>` declares only
+    // what `api.model()` + the passed-through protocol members actually implement,
+    // so there is no method on this type that fails at runtime.
+    return facade;
+}

package/dist/client/identity.d.ts

@@ -22,6 +22,7 @@
 import { type RefreshScheduler } from '../auth/index.js';
 import type { BootstrapHelper } from '../sync/BootstrapHelper.js';
 import type { SyncLogger } from '../interfaces/index.js';
+import type { AuthCredentialSource } from '../auth/credentialSource.js';
 import type { ApiKeySetter } from './auth.js';
 export interface IdentityResolveInput {
     readonly options: {
@@ -42,13 +43,8 @@ export interface IdentityResolveInput {
     readonly configuredApiKey: string | ApiKeySetter | null;
     readonly configuredAuthToken: string | null;
     readonly bootstrapHelper: BootstrapHelper;
+    readonly auth: AuthCredentialSource;
     readonly logger: SyncLogger;
-    /**
-     * Called when the hosted-cloud refresh scheduler rotates the
-     * capability token — caller forwards the new token to the live
-     * WebSocket via `ws.setCapabilityToken(...)`.
-     */
-    readonly applyRotatedToken: (token: string) => void;
 }
 export interface ResolvedIdentity {
     readonly userId: string;

package/dist/client/identity.js

@@ -23,11 +23,43 @@ import { AbloAuthenticationError } from '../errors.js';
 import { exchangeApiKey } from '../auth/index.js';
 import { resolveIdentity } from '../auth/index.js';
 import { createRefreshScheduler, } from '../auth/index.js';
-import { resolveApiKeyValue } from './auth.js';
+import { resolveApiKeyValue, resolveBootstrapBaseUrl } from './auth.js';
 export async function resolveParticipantIdentity(input) {
-    const { options, internalOptions, url, kind, configuredApiKey, configuredAuthToken, bootstrapHelper, logger, applyRotatedToken, } = input;
+    const { options, internalOptions, url, kind, configuredApiKey, configuredAuthToken, bootstrapHelper, auth, logger, } = input;
     const apiKeyValue = await resolveApiKeyValue(configuredApiKey);
     const initialCapToken = options.capabilityToken ?? configuredAuthToken ?? undefined;
+    // Branch 0: publishable key (`pk_`) — a long-lived, browser-safe, READ-ONLY
+    // project key. Unlike a secret `sk_` (Branch 1), it is used DIRECTLY as the
+    // bearer and is NEVER exchanged for a short-lived capability — so it never
+    // expires and there is nothing to refresh (no `credential_stale`, no
+    // wake-from-sleep re-mint). The sync-server's `apiKeyProvider` resolves the
+    // org + read-only scope from the key itself; we still call `/auth/identity`
+    // (authenticated by the `pk_` bearer) to learn the account scope + syncGroups
+    // for the bootstrap cache. Plain `startsWith` check because the `keys` module
+    // is node-only (`node:crypto`) and must not enter the browser bundle.
+    if (apiKeyValue && apiKeyValue.startsWith('pk_') && !options.capabilityToken) {
+        const baseUrl = resolveBootstrapBaseUrl({
+            url,
+            bootstrapBaseUrl: options.bootstrapBaseUrl,
+        });
+        const identity = await resolveIdentity({ baseUrl, authToken: apiKeyValue });
+        const callerGroups = options.syncGroups ?? [];
+        const mergedSyncGroups = callerGroups.length > 0
+            ? [...new Set([...callerGroups, ...identity.syncGroups])]
+            : identity.syncGroups;
+        bootstrapHelper.setCacheScope(identity.accountScope);
+        bootstrapHelper.setSyncGroups(mergedSyncGroups);
+        auth.setAuthToken(apiKeyValue);
+        return {
+            userId: identity.participantId,
+            accountScope: identity.accountScope,
+            teamIds: undefined,
+            capabilityToken: apiKeyValue,
+            syncGroups: mergedSyncGroups,
+            participantKind: identity.participantKind,
+            refreshScheduler: null,
+        };
+    }
     // Branch 1: hosted-cloud (apiKey only, no caller-supplied capability token)
     if (apiKeyValue && !options.capabilityToken) {
         return resolveHosted({
@@ -37,14 +69,33 @@ export async function resolveParticipantIdentity(input) {
             kind,
             options,
             bootstrapHelper,
+            auth,
             logger,
-            applyRotatedToken,
         });
     }
     // Branch 2: self-derived (capability token present, identity unknown)
     if (!internalOptions.organizationId ||
         (kind === 'agent' ? !options.agentId : !options.user?.id)) {
-        const baseUrl = options.bootstrapBaseUrl ?? `${url.replace(/^ws/, 'http')}/api`;
+        // Fail fast on the missing-credential case. We're here because there's no
+        // apiKey (Branch 1) and the identity isn't caller-supplied (Branch 3), so
+        // `initialCapToken` is the only thing that can authenticate the
+        // `/auth/identity` call. When it's absent — the common cause being
+        // `getToken()` resolving to `null` (no/expired session, see
+        // `getSyncCapabilityToken`) — the request can only come back as the server's
+        // opaque `identity_resolve_failed: no_matching_provider`. Surface the real
+        // condition locally instead: `session_expired` is the registered,
+        // re-authenticate-able code, and we never make a doomed round-trip.
+        if (!initialCapToken) {
+            throw new AbloAuthenticationError('No auth token available to resolve identity — the session token is ' +
+                'missing or expired. Ensure `getToken()` returns a valid token, or ' +
+                'pass `apiKey` / `capabilityToken`.', { code: 'session_expired' });
+        }
+        // Single source of truth for the http(s) base — coerces ws/wss → http/https
+        // even when `bootstrapBaseUrl` is an explicit override (see auth.ts).
+        const baseUrl = resolveBootstrapBaseUrl({
+            url,
+            bootstrapBaseUrl: options.bootstrapBaseUrl,
+        });
         const identity = await resolveIdentity({
             baseUrl,
             authToken: initialCapToken,
@@ -66,7 +117,7 @@ export async function resolveParticipantIdentity(input) {
             : identity.syncGroups;
         bootstrapHelper.setCacheScope(identity.accountScope);
         bootstrapHelper.setSyncGroups(mergedSyncGroups);
-        bootstrapHelper.setAuthToken(initialCapToken);
+        auth.setAuthToken(initialCapToken);
         return {
             userId: identity.participantId,
             accountScope: identity.accountScope,
@@ -83,7 +134,7 @@ export async function resolveParticipantIdentity(input) {
     const accountScope = internalOptions.organizationId;
     bootstrapHelper.setCacheScope(accountScope);
     bootstrapHelper.setSyncGroups(options.syncGroups);
-    bootstrapHelper.setAuthToken(initialCapToken);
+    auth.setAuthToken(initialCapToken);
     return {
         userId,
         accountScope,
@@ -97,8 +148,10 @@ export async function resolveParticipantIdentity(input) {
 async function resolveHosted(input) {
     // Pure managed-cloud shape: `Ablo({schema, apiKey})`. Server returns
     // scope + userMeta; SDK populates internals.
-    const baseUrl = input.options.bootstrapBaseUrl ??
-        `${input.url.replace(/^ws/, 'http')}/api`;
+    const baseUrl = resolveBootstrapBaseUrl({
+        url: input.url,
+        bootstrapBaseUrl: input.options.bootstrapBaseUrl,
+    });
     const exchangeArgs = {
         baseUrl,
         participantKind: (input.kind === 'agent' ? 'agent' : 'system'),
@@ -112,7 +165,7 @@ async function resolveHosted(input) {
     });
     input.bootstrapHelper.setCacheScope(exchange.scope.organizationId);
     input.bootstrapHelper.setSyncGroups(exchange.scope.syncGroups);
-    input.bootstrapHelper.setAuthToken(exchange.token);
+    input.auth.setAuthToken(exchange.token);
     // Cap tokens have a server-set TTL (3600s by default). Without
     // proactive refresh the WS would either get force-closed at expiry
     // or fail its next reconnect with 401. The scheduler re-mints
@@ -132,8 +185,7 @@ async function resolveHosted(input) {
                 ...exchangeArgs,
                 apiKey: freshApiKey,
             });
-            input.bootstrapHelper.setAuthToken(next.token);
-            input.applyRotatedToken(next.token);
+            input.auth.setAuthToken(next.token);
             return { expiresAtMs: Date.parse(next.expiresAt) };
         },
         onError: (err) => {