@abloatai/ablo 0.11.1 → 0.11.2

package/dist/client/Ablo.d.ts

@@ -28,7 +28,6 @@ import type { SyncWebSocket } from '../sync/SyncWebSocket.js';
 import type { SyncGroupInput } from '../schema/roles.js';
 import { type SyncStatus } from '../BaseSyncedStore.js';
 import type { ClaimStream, ClaimWaitOptions, PresenceStream, Snapshot } from '../types/streams.js';
-import type { ParticipantManager } from '../sync/participants.js';
 import type { ClaimHandle, Duration, Claim } from '../types/streams.js';
 import { type AbloApi, type AbloApiClientOptions, type AbloApiClaims } from './ApiClient.js';
 import { type AbloHttpClient, type AbloHttpClientOptions } from './httpClient.js';
@@ -77,35 +76,24 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      * usually pass nothing). A long-lived key needs no refresh; the client uses
      * it as-is.
      *
-     * Accepts a static string or an async `() => Promise<string>` resolver if you
-     * rotate keys out-of-band (resolved at bootstrap).
+     * Accepts a static string OR an async `() => Promise<string | null>` resolver
+     * — the single credential path. Use the resolver form for two cases:
      *
-     * Browser apps that mint a SHORT-LIVED per-user key (`ek_`) from a login can't
-     * ship a secret — those use {@link getToken} (or {@link authEndpoint}) instead,
-     * which the client refreshes for you. That's the only case that isn't "just
-     * `apiKey`".
-     */
-    apiKey?: string | ApiKeySetter | null | undefined;
-    /**
-     * Opt-in for the SHORT-LIVED per-user browser case: an async resolver for a
-     * fresh bearer (`ek_`/`rk_`) your backend minted for the signed-in user. The
-     * client calls it once before connect and then keeps the key fresh for you —
-     * a refresh timer ahead of expiry plus re-mint on OS-wake / network-online /
-     * tab-focus, and a reactive re-mint when a probe finds the key stale. You
-     * never call a refresh method (Supabase `autoRefreshToken` model).
+     *  - **Key rotation** (server): pull a fresh `sk_`/`pk_` from a vault on each
+     *    bootstrap (AWS STS, GCP IAM, Vault).
+     *  - **Short-lived per-user browser** auth: return the fresh `ek_`/`rk_` bearer
+     *    your backend minted for the signed-in user. The client mints once before
+     *    connect, then keeps it fresh for you — a refresh timer ahead of expiry
+     *    plus re-mint on OS-wake / network-online / tab-focus, and a reactive
+     *    re-mint when a probe finds the key stale. You never call a refresh method
+     *    (Supabase `autoRefreshToken` model).
      *
-     * Contract: resolve a token, resolve `null` when the login itself is gone
-     * (terminal → sign out), or THROW on a transient failure (→ back off, never
-     * sign out). Leave unset for the static-`apiKey` path.
-     */
-    getToken?: (() => Promise<string | null>) | undefined;
-    /**
-     * Convenience over {@link getToken}: a URL on YOUR backend that returns
-     * `{ token }`. The client POSTs to it (with cookies, so it's authed by the
-     * user's session) to mint + refresh the bearer. Ignored when `getToken` is
-     * set. Pure sugar — `getToken: () => fetch(url).then(r => r.json()).then(b => b.token)`.
+     * Resolver contract: resolve a token; resolve `null` when the login itself is
+     * gone (terminal → the client signs out / fails `ready()` with `session_expired`);
+     * or THROW on a transient failure (→ back off and retry, never sign out). A
+     * static string never refreshes — it is used as-is.
      */
-    authEndpoint?: string | undefined;
+    apiKey?: string | ApiKeySetter | null | undefined;
     /**
      * Direct-URL convenience connector: a connection string to your own Postgres
      * that Ablo can register for a dedicated tenant.
@@ -138,6 +126,9 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      * `AbloHttpClient<S>`, so stateful-only capabilities (`get`/`getAll`,
      * `onChange`) are compile errors rather than latent runtime gaps.
      *
+     * Note: session/credential minting (`sessions.create`) currently runs on the
+     * stateful (default) client, not the http client.
+     *
      * @default 'websocket'
      */
     transport?: 'websocket' | 'http' | undefined;
@@ -225,18 +216,6 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      * only for the advanced Model / Claim / Commit client.
      */
     schema: Schema<S>;
-    /**
-     * Short-lived-bearer resolver for the per-user browser path (mirrors the
-     * public {@link AbloOptions.getToken}). The client mints the first token
-     * before connect and refreshes it (timer + wake/online/focus) — see
-     * {@link resolveCredentialResolver}.
-     */
-    getToken?: (() => Promise<string | null>) | undefined;
-    /**
-     * Backend URL returning `{ token }`; sugar over {@link getToken}. Mirrors the
-     * public {@link AbloOptions.authEndpoint}.
-     */
-    authEndpoint?: string | undefined;
     /**
      * @deprecated Server derives participant kind from the apiKey's
      * scope. Pass apiKey only; this option will be removed once the
@@ -385,8 +364,8 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
  *   `create({ data })` / `update({ id, data })` / `delete({ id })` — writes
  *   `claim({ id })` — durable claim handle for coordinated writes
  */
-export type { ModelCountOptions, ModelListOptions, ModelListScope, ModelLoadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, ClaimHandle, ModelOperations, } from './createModelProxy.js';
-import type { ModelOperations, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, ModelLoadOptions } from './createModelProxy.js';
+export type { LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, ClaimHandle, ModelOperations, } from './createModelProxy.js';
+import type { ModelOperations, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, ServerReadOptions } from './createModelProxy.js';
 export type ModelOperationAction = 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
 export type CommitWait = 'queued' | 'confirmed';
 export interface ModelRead<T = Record<string, unknown>> {
@@ -394,23 +373,15 @@ export interface ModelRead<T = Record<string, unknown>> {
     readonly stamp: number;
     readonly claims: readonly ModelClaim[];
 }
-export type IfClaimedPolicy = 'return' | 'wait' | 'fail';
+export type IfClaimedPolicy = 'return' | 'fail';
 export interface ClaimedOptions {
     /**
-     * What to do when another participant has claimed the target. `return`
-     * includes active claim metadata in the response, `wait` resolves after the
-     * claim clears, and `fail` throws `AbloClaimedError`.
+     * What to do when another participant has claimed the target: `return`
+     * includes active claim metadata in the response; `fail` throws
+     * `AbloClaimedError`. Waiting for a claim to clear is a claim-side concern —
+     * take `ablo.<model>.claim({ id })` (it queues fairly); reads never block.
      */
     readonly ifClaimed?: IfClaimedPolicy;
-    /** Max time to wait for peer claims to clear, in milliseconds. */
-    readonly claimedTimeout?: number;
-    /** HTTP API polling interval while waiting. WebSocket clients ignore it. */
-    readonly claimedPollInterval?: number;
-    /**
-     * Backpressure for `ifClaimed: 'wait'`: reject instead of waiting if the
-     * row's FIFO line is already `>= maxQueueDepth` deep.
-     */
-    readonly maxQueueDepth?: number;
 }
 export type { ClaimWaitOptions } from '../types/streams.js';
 export interface ModelReadOptions extends ClaimedOptions {
@@ -527,7 +498,7 @@ export interface ModelClient<T = Record<string, unknown>> {
      * `limit`. Present on the stateless protocol client; the store-backed
      * `.model(name)` accessor omits it (use the typed `ablo.<model>.list` there).
      */
-    list?(options?: ModelLoadOptions<T>): Promise<T[]>;
+    list?(options?: ServerReadOptions<T>): Promise<T[]>;
     create(params: ModelMutationOptions & {
         readonly data: Record<string, unknown>;
         readonly id?: string | null;
@@ -560,7 +531,7 @@ export interface CreateUserSessionParams {
         id: string;
     };
     /** Sync groups this session may subscribe to — typed (`'default'` or
-     *  `<namespace>:<id>`; build with `syncGroup.org()/user()/of()` from
+     *  `<namespace>:<id>`; build with `syncGroup(kind, id)` from
      *  `@abloatai/ablo/schema`). Omit for the server default:
      *  `[org:<your org>, user:<user.id>]`. */
     syncGroups?: readonly SyncGroupInput[];
@@ -585,7 +556,7 @@ export interface CreateAgentSessionParams<S extends SchemaRecord> {
         [M in keyof S & string]?: readonly SessionOperation[];
     };
     /** Sync groups this session may subscribe to — typed (`'default'` or
-     *  `<namespace>:<id>`; build with `syncGroup.org()/user()/of()` from
+     *  `<namespace>:<id>`; build with `syncGroup(kind, id)` from
      *  `@abloatai/ablo/schema`). Omit for the server default: the org
      *  anchor (`org:<your org>`) + the agent's own anchor. */
     syncGroups?: readonly SyncGroupInput[];
@@ -667,7 +638,7 @@ export type Ablo<S extends SchemaRecord> = {
      * Replace the bearer auth token used for the WebSocket upgrade and HTTP
      * requests, WITHOUT tearing down the engine. Use to push a refreshed
      * short-lived access key (the Stripe-style `ek_`/`rk_`) before it expires —
-     * `<AbloProvider>`'s `getToken` refresh loop calls this. Reuses the same
+     * the client's `apiKey`-resolver refresh loop calls this. Reuses the same
      * rotation path as the internal capability-token refresh; safe to call before
      * `ready()`. Also nudges a parked connection to re-probe with the new token.
      */
@@ -675,8 +646,8 @@ export type Ablo<S extends SchemaRecord> = {
     /**
      * Resolve the active bearer credential this engine authenticates with — the
      * live `ek_`/`rk_` the WebSocket and HTTP transports currently carry (kept
-     * fresh by the `getToken` refresh loop), falling back to a configured API
-     * key. Returns `null` when no credential is set yet. Use it to authenticate
+     * fresh by the `apiKey`-resolver refresh loop), falling back to a configured
+     * API key. Returns `null` when no credential is set yet. Use it to authenticate
      * a side-band request to the same server with the very token this client
      * already holds — no extra mint round-trip.
      */
@@ -685,10 +656,10 @@ export type Ablo<S extends SchemaRecord> = {
      * Register a re-mint hook for the short-lived access key. The connection
      * layer calls it WHEN it finds the key stale (a `credential_stale` probe) or
      * on an external nudge; the hook mints a fresh `ek_`/`rk_` from the still-valid
-     * login. Mirrors the `getToken` contract: resolve a token, resolve `null` when
-     * the login itself is gone (→ sign out), or THROW on a transient failure (→
-     * back off, never sign out). `<AbloProvider>` wires this from its
-     * `getToken`/`authEndpoint`. Safe to call before `ready()`.
+     * login. Mirrors the `apiKey`-resolver contract: resolve a token, resolve
+     * `null` when the login itself is gone (→ sign out), or THROW on a transient
+     * failure (→ back off, never sign out). The client wires this automatically
+     * from a function `apiKey`. Safe to call before `ready()`.
      */
     setCredentialRefresher(refresher: (() => Promise<string | null>) | null): void;
     /**
@@ -703,14 +674,15 @@ export type Ablo<S extends SchemaRecord> = {
      * Mint a short-lived, scoped **session token** for one end user — the
      * Stripe `ephemeralKeys.create` / Supabase session shape. Call this on YOUR
      * BACKEND (where the `sk_` secret key lives), then hand the returned
-     * `token` to that user's browser (typically via an authEndpoint the client
-     * fetches). The browser presents it as the bearer; the sync-server verifies
+     * `token` to that user's browser (typically via a token route the browser's
+     * `apiKey` resolver fetches). The browser presents it as the bearer; the sync-server verifies
      * it via `apiKeyProvider`.
      *
      * The browser must NEVER see the `sk_` key — only the per-user session token.
      *
      * Pass `{ user: { id } }` for a full-authority end-user session (mints `ek_`,
-     * `actor_kind: 'user'` attribution), or `{ agent: { id }, can: { tasks:
+     * `participantKind: 'user'` attribution, stored as `actor_kind` on the delta
+     * row), or `{ agent: { id }, can: { tasks:
      * ['update'] } }` for a scoped agent session (mints `rk_`); `can` is typed
      * against your schema's model names. Always authenticates with the original
      * `sk_` — never the client's exchanged sync credential.
@@ -822,24 +794,6 @@ export type Ablo<S extends SchemaRecord> = {
      * are schema-powered sugar over the same model write/read path.
      */
     model<T = Record<string, unknown>>(name: string): ModelClient<T>;
-    /**
-     * Canonical multiplayer participant surface. Joins a structured app
-     * target, derives the transport scope internally, opens a scoped
-     * claim on the existing WebSocket, and returns target-bound presence
-     * + claim helpers.
-     *
-     * ```ts
-     * const participant = await ablo.participants.join({
-     *   type: 'File',
-     *   id: 'src/foo.ts',
-     *   path: 'src/foo.ts',
-     *   range: { startLine: 10, endLine: 40 },
-     * });
-     * participant.presence.editing();
-     * const claim = participant.claims.claim('rewrite imports');
-     * ```
-     */
-    readonly participants: ParticipantManager;
     /**
      * Capture a context-staleness watermark over a set of entities.
      * Returns a flat snapshot with `stamp` (thread into writes as
@@ -991,9 +945,6 @@ export declare namespace Ablo {
     type ClaimLost = _Streams.ClaimLost;
     type Snapshot<TSchema extends _SchemaTypes.Schema = _SchemaTypes.Schema, K extends keyof TSchema['models'] = keyof TSchema['models']> = _Streams.Snapshot<TSchema, K>;
     namespace Auth {
-        type Principal = _Streams.Principal;
-        type Session = _Streams.SessionRef;
-        type Agent = _Streams.AgentRef;
         type Actor = _Streams.ParticipantRef;
     }
     namespace Participant {

package/dist/client/Ablo.js

@@ -27,7 +27,7 @@ import { initSyncEngine } from '../context.js';
 import { noopObservability, browserOnlineStatus, defaultSessionErrorDetector, noopAnalytics, } from '../SyncEngineContext.js';
 import { alwaysOnline } from '../adapters/alwaysOnline.js';
 import { validateAbloOptions } from './validateAbloOptions.js';
-import { exchangeApiKey, mintUserSessionKey } from '../auth/index.js';
+import { mintSession } from './sessionMint.js';
 import { createAuthCredentialSource } from '../auth/credentialSource.js';
 import { createInternalComponents } from './createInternalComponents.js';
 import { resolveParticipantIdentity } from './identity.js';
@@ -670,32 +670,20 @@ function createDefaultMutationDispatcher(executor) {
 // ── Auth normalization ─────────────────────────────────────────────────────
 /**
  * The one resolver the credential lifecycle needs: an async `() => token | null`,
- * or `null` when auth is static (a plain long-lived `apiKey` with no refresh —
- * the common case). Only the short-lived per-user path sets this, via `getToken`
- * (the primitive) or `authEndpoint` (sugar that POSTs for `{ token }`).
+ * or `null` when auth is static (a plain long-lived `apiKey` STRING with no
+ * refresh — the common case).
+ *
+ * The short-lived per-user browser path passes a FUNCTION `apiKey` (an
+ * `ApiKeySetter`): the SDK then drives the full credential lifecycle off it —
+ * mint-before-connect, the proactive refresh timer + wake/online/focus re-mint,
+ * and the reactive `credential_stale` re-mint. The resolver's contract is the
+ * `ApiKeySetter` contract end-to-end: resolve a token, resolve `null` when the
+ * login is gone (terminal → `session_expired` → sign out), or THROW on a
+ * transient failure (→ back off, never sign out).
  */
-function resolveCredentialResolver(options) {
-    if (options.getToken)
-        return options.getToken;
-    if (options.authEndpoint) {
-        const endpoint = options.authEndpoint;
-        const fetchImpl = options.fetch ?? globalThis.fetch;
-        return async () => {
-            // The endpoint lives on the consumer's OWN backend and is authed by the
-            // user's session cookie (hence `credentials: 'include'`); it returns the
-            // `ek_` to carry to the sync-server. A non-OK response is terminal
-            // (`null` → sign out), matching the `getToken` contract.
-            const res = await fetchImpl(endpoint, {
-                method: 'POST',
-                credentials: 'include',
-                headers: { 'Content-Type': 'application/json' },
-            });
-            if (!res.ok)
-                return null;
-            const body = (await res.json());
-            return body.token ?? null;
-        };
-    }
+function resolveCredentialResolver(apiKey) {
+    if (typeof apiKey === 'function')
+        return apiKey;
     return null;
 }
 export function Ablo(options) {
@@ -716,7 +704,7 @@ export function Ablo(options) {
     // drives both the reactive re-mint (FSM `credential_stale`) and the proactive
     // refresh timer + wake/online/focus triggers. Null for the common static
     // `apiKey` path — no refresh needed.
-    const credentialResolver = resolveCredentialResolver(options);
+    const credentialResolver = resolveCredentialResolver(configuredApiKey);
     const authCredentials = createAuthCredentialSource(internalOptions.capabilityToken ?? configuredAuthToken);
     const configuredDatabaseUrl = resolveDatabaseUrl(authInput);
     assertBrowserSafety({
@@ -900,7 +888,7 @@ export function Ablo(options) {
                 // WebSocket upgrade + bootstrap carry a valid bearer (no tokenless first
                 // connect that has to self-heal). Only when a refreshing resolver is
                 // wired AND no static credential is already present. Contract mirrors
-                // `getToken`: `null` ⇒ the login is gone (terminal — fail ready so the
+                // the `apiKey` resolver: `null` ⇒ the login is gone (terminal — fail ready so the
                 // app shows sign-in); a THROW ⇒ transient (rethrown; autoStart swallows
                 // and the lifecycle's online/wake triggers retry).
                 if (credentialResolver && !authCredentials.getAuthToken()) {
@@ -933,8 +921,9 @@ export function Ablo(options) {
                     kind,
                     configuredApiKey,
                     // Resolve identity against the LIVE token, not the construction-time
-                    // `configuredAuthToken`. Consumers using `getToken` (apps/web) never
-                    // pass `authToken` at construction — they call `setAuthToken()` before
+                    // `configuredAuthToken`. Consumers using a function `apiKey` (apps/web)
+                    // never pass `authToken` at construction — the lifecycle mints the
+                    // first `ek_`/`rk_` and calls `setAuthToken()` before
                     // `ready()`, which updates the shared credential source. Reading the frozen
                     // `configuredAuthToken` here made `/auth/identity` fire with no Bearer
                     // (→ `no_matching_provider` / `session_expired`) even though the JWT
@@ -1247,14 +1236,8 @@ export function Ablo(options) {
         const current = listModelClaims(target);
         if (current.length === 0)
             return;
-        if (policy === 'fail')
-            throw claimedError(target, current, 'model_claimed');
-        const queue = listModelClaimQueue(target);
-        if (options?.maxQueueDepth !== undefined &&
-            queue.length >= options.maxQueueDepth) {
-            throw claimedError(target, current, 'queue_too_deep');
-        }
-        await waitForModelUnclaimed(target, { timeout: options?.claimedTimeout });
+        // policy === 'fail' — gate the read only when the caller opts in.
+        throw claimedError(target, current, 'model_claimed');
     }
     function wrapClaimHandle(claim, waited = false) {
         const release = async () => {
@@ -1385,6 +1368,14 @@ export function Ablo(options) {
             // errors so read interest never makes a read reject or stall.
             enterScope: (scope) => store.enterScope(scope),
             pinScope: (scope) => store.pinScope(scope),
+            // `ablo.<model>.watch(ids, { ttl })` → a scoped participant join on
+            // this model's sync group(s). The model-scoped relocation of the old
+            // `ablo.participants.join({ scope: { <model>: ids } })`. WebSocket
+            // only — `join` throws AbloConnectionError if the socket isn't ready.
+            createWatch: (modelKey, ids, options) => participantManager.join({
+                scope: { [modelKey]: ids },
+                ...(options?.ttl !== undefined ? { ttlSeconds: options.ttl } : {}),
+            }),
         });
     }
     const commits = {
@@ -1544,6 +1535,9 @@ export function Ablo(options) {
      * (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 sk_-only rule is enforced server-side; the credential KIND taxonomy
+     * (secret/restricted/ephemeral/publishable) lives in `auth/credentialPolicy`.
      */
     async function controlPlaneApiKey() {
         return resolveApiKeyValue(configuredApiKey);
@@ -1564,7 +1558,7 @@ export function Ablo(options) {
             store.nudgeReconnect();
         },
         async getAuthToken() {
-            // The live short-lived bearer (set via `setAuthToken`/`getToken` refresh)
+            // 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, WS, query HTTP). Control-plane
@@ -1608,66 +1602,15 @@ export function Ablo(options) {
                     url,
                     bootstrapBaseUrl: internalOptions.bootstrapBaseUrl,
                 });
-                // Discriminate the union onto the server's TWO mint doors:
-                //   `{ user }`  → POST /auth/ephemeral-keys → `ek_` (sk_-gated; the
-                //                 user-session door). Routing this arm through
-                //                 /auth/capability is structurally impossible — that
-                //                 route rejects participantKind 'user' outright
-                //                 (`invalid_participant_kind`, the 2026-06-11 Pulse
-                //                 cascade: the SDK's own blessed pattern 403'd and
-                //                 integrators fell back to minting humans as agents).
-                //   `{ agent }` → POST /auth/capability → scoped `rk_`.
-                //                 `can: { tasks: ['update'] }` serializes to the wire
-                //                 allowlist (`tasks.update`); the Hub matches it
-                //                 against every registered alias of the model.
-                if (params.user) {
-                    const res = await mintUserSessionKey({
-                        apiKey,
-                        baseUrl,
-                        userId: params.user.id,
-                        ...(params.syncGroups ? { syncGroups: [...params.syncGroups] } : {}),
-                        ttlSeconds: params.ttlSeconds ?? 900,
-                        ...(internalOptions.fetch ? { fetch: internalOptions.fetch } : {}),
-                    });
-                    return {
-                        object: 'session',
-                        id: res.id,
-                        token: res.token,
-                        expiresAt: res.expiresAt,
-                        organizationId: res.organizationId,
-                        // The ephemeral mint stores scope on the key row; reshape its flat
-                        // response into the session resource's scope block.
-                        scope: {
-                            organizationId: res.organizationId,
-                            syncGroups: res.syncGroups,
-                            operations: [],
-                            participantKind: 'user',
-                            participantId: res.participantId,
-                        },
-                        userMeta: params.userMeta ?? { id: res.participantId },
-                    };
-                }
-                const operations = Object.entries(params.can).flatMap(([model, ops]) => (ops ?? []).map((op) => `${model.toLowerCase()}.${op}`));
-                const res = await exchangeApiKey({
+                // The two mint doors (`{ user }` → /auth/ephemeral-keys → `ek_`,
+                // `{ agent, can }` → /auth/capability → scoped `rk_`) live in the shared
+                // `mintSession` so this stateful client and the stateless HTTP client can
+                // never drift on how a token is minted.
+                return mintSession(params, {
                     apiKey,
                     baseUrl,
-                    participantKind: 'agent',
-                    participantId: params.agent.id,
-                    ...(params.syncGroups ? { syncGroups: [...params.syncGroups] } : {}),
-                    operations,
-                    ttlSeconds: params.ttlSeconds ?? 900,
-                    ...(params.userMeta ? { userMeta: params.userMeta } : {}),
                     ...(internalOptions.fetch ? { fetch: internalOptions.fetch } : {}),
                 });
-                return {
-                    object: 'session',
-                    id: res.capabilityId,
-                    token: res.token,
-                    expiresAt: res.expiresAt,
-                    organizationId: res.organizationId,
-                    scope: res.scope,
-                    userMeta: res.userMeta,
-                };
             },
         },
         async dispose() {
@@ -1736,9 +1679,6 @@ export function Ablo(options) {
         claims: publicClaims,
         commits,
         model,
-        /** Structured multiplayer participation — target-first, no
-     *  sync-group strings in the common path. */
-        participants: participantManager,
         /** Context-staleness snapshot — see `engine.snapshot(...)` JSDoc. */
         snapshot(entities) {
             return createSnapshot({

package/dist/client/ApiClient.d.ts

@@ -5,7 +5,8 @@
  * IndexedDB, no WebSocket. It maps the public Model / Claim / Commit
  * nouns directly to HTTP routes on sync-server.
  */
-import type { AbloOptions, CommitResource, ClaimCreateOptions, ClaimWaitOptions, ModelClient, ModelClaim, ModelTarget } from './Ablo.js';
+import type { AbloOptions, CommitResource, ClaimCreateOptions, ClaimWaitOptions, ModelClient, ModelClaim, ModelTarget, CreateSessionParams, AbloSession } from './Ablo.js';
+import type { SchemaRecord } from '../schema/schema.js';
 import type { ClaimHandle } from './createModelProxy.js';
 import type { Duration } from '../utils/duration.js';
 export type AbloApiClientOptions = Omit<AbloOptions, 'schema'> & {
@@ -133,5 +134,13 @@ export interface AbloApi {
      * server with the credential this client already holds — no re-mint.
      */
     getAuthToken(): Promise<string | null>;
+    /**
+     * Mint a short-lived scoped session — the Stripe `ephemeralKeys.create` shape.
+     * Minting is a control-plane HTTP call (no socket), so it lives on this stateless
+     * client too, not only the realtime one. `{ user }` → `ek_`, `{ agent, can }` → `rk_`.
+     */
+    readonly sessions: {
+        create(params: CreateSessionParams<SchemaRecord>): Promise<AbloSession>;
+    };
 }
 export declare function createProtocolClient(options: AbloApiClientOptions): AbloApi;

package/dist/client/ApiClient.js

@@ -9,6 +9,7 @@ import { AbloClaimedError, AbloAuthenticationError, AbloConnectionError, AbloVal
 import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, resolveDatabaseUrl, warnIfDatabaseUrlEnvIgnored, } from './auth.js';
 import { registerDataSource } from './registerDataSource.js';
 import { toSeconds } from '../utils/duration.js';
+import { mintSession } from './sessionMint.js';
 import { assertWriteOptions } from './writeOptionsSchema.js';
 const DEFAULT_AGENT_LEASE = '10m';
 export function createProtocolClient(options) {
@@ -228,20 +229,11 @@ export function createProtocolClient(options) {
         const policy = options?.ifClaimed ?? defaultPolicy;
         if (policy === 'return')
             return;
+        // policy === 'fail' — gate the read only when the caller opts in.
         const state = await listClaimState(target);
         if (state.active.length === 0)
             return;
-        if (policy === 'fail') {
-            throw claimedError(target, state.active, 'model_claimed');
-        }
-        if (options?.maxQueueDepth !== undefined &&
-            state.queue.length >= options.maxQueueDepth) {
-            throw claimedError(target, state.active, 'queue_too_deep');
-        }
-        await waitForNoClaims(target, {
-            timeout: options?.claimedTimeout,
-            pollInterval: options?.claimedPollInterval,
-        });
+        throw claimedError(target, state.active, 'model_claimed');
     }
     const commits = {
         async create(commitOptions) {
@@ -656,6 +648,22 @@ export function createProtocolClient(options) {
         claims,
         commits,
         model,
+        sessions: {
+            async create(params) {
+                // Stateless mint: the configured key IS the control-plane credential here
+                // (no startup `rk_` exchange runs on this client). Reuse the resolved base
+                // URL + fetch; the shared `mintSession` owns the two server doors.
+                const apiKey = await resolveApiKeyValue(configuredApiKey);
+                if (!apiKey) {
+                    throw new AbloAuthenticationError('sessions.create requires a secret (sk_) API key — call it from your backend, not the browser.', { code: 'apikey_missing' });
+                }
+                return mintSession(params, {
+                    apiKey,
+                    baseUrl: apiBaseUrl,
+                    ...(options.fetch ? { fetch: options.fetch } : {}),
+                });
+            },
+        },
         async getAuthToken() {
             // Mirror `authHeaders()`: a configured API key wins, else the
             // construction-time auth token. Resolve the (possibly async) key setter.

package/dist/client/auth.d.ts

@@ -12,13 +12,20 @@
  * explicit options so generated apps do not accrete hidden env knobs.
  */
 /**
- * Async callable that resolves to a fresh API key. Mirrors the shape
+ * Async callable that resolves the current credential. Mirrors the shape
  * Anthropic / OpenAI / Stripe ship — used for credential rotation
- * (e.g. AWS STS, GCP IAM, Vault). Re-exported from `./Ablo` so
- * existing import paths work; defined here so this module has no
- * circular dependency back to `Ablo.ts`.
+ * (e.g. AWS STS, GCP IAM, Vault) AND the short-lived per-user browser
+ * path (mint a fresh `ek_`/`rk_` from the signed-in session). Re-exported
+ * from `./Ablo` so existing import paths work; defined here so this module
+ * has no circular dependency back to `Ablo.ts`.
+ *
+ * Contract: resolve a token; resolve `null` when the login itself is gone
+ * (terminal → the credential lifecycle treats this as `session_expired` and
+ * signs out); or THROW on a transient failure (→ back off and retry, never
+ * sign out). A long-lived static `apiKey` string needs none of this — it is
+ * used as-is. This is the single credential resolver the SDK supports.
  */
-export type ApiKeySetter = () => Promise<string>;
+export type ApiKeySetter = () => Promise<string | null>;
 export interface AuthResolveInput {
     /**
      * The full options bag the caller passed to `Ablo()`. Resolvers

package/dist/client/auth.js

@@ -12,6 +12,7 @@
  * explicit options so generated apps do not accrete hidden env knobs.
  */
 import { AbloAuthenticationError } from '../errors.js';
+import { classifyCredentialKind } from '../auth/credentialPolicy.js';
 /**
  * Read `process.env` defensively. Works in browser (where `process`
  * is undefined), Node, and edge runtimes that expose a partial
@@ -137,7 +138,7 @@ export function assertBrowserSafety(input) {
     if (!input.dangerouslyAllowBrowser &&
         inBrowser &&
         typeof input.apiKey === 'string' &&
-        input.apiKey.startsWith('sk_')) {
+        classifyCredentialKind(input.apiKey) === 'secret') {
         throw new AbloAuthenticationError("It looks like you're running in a browser-like environment.\n\n" +
             'This is disabled by default — your secret API key would be ' +
             "exposed to every visitor's network tab. If you understand the risks " +