@abloatai/ablo 0.11.1 → 0.12.0

package/dist/client/createModelProxy.d.ts

@@ -19,6 +19,7 @@ import type { ModelRegistry } from '../ModelRegistry.js';
 import type { ObjectPool } from '../ObjectPool.js';
 import type { SyncClient } from '../SyncClient.js';
 import type { HydrationCoordinator } from '../sync/HydrationCoordinator.js';
+import type { JoinedParticipant } from '../sync/participants.js';
 import type { LoadWhere } from '../query/types.js';
 import { ModelScope } from '../types/index.js';
 import type { Duration, Claim, ClaimHandle, ClaimWaitOptions, Snapshot, TargetRange } from '../types/streams.js';
@@ -28,7 +29,10 @@ export interface ModelClientMeta {
 }
 export declare function getModelClientMeta(modelClient: unknown): ModelClientMeta | undefined;
 export type ModelListScope = ModelScope | 'live' | 'archived' | 'all';
-export interface ModelListOptions<T> {
+/** Options for the sync LOCAL-pool reads `get`/`getAll`/`onChange` (JS
+ *  `filter`, equality `where`, lifecycle `state`). The local-reactive axis;
+ *  contrast {@link ServerReadOptions} (the async server axis). */
+export interface LocalReadOptions<T> {
     where?: Partial<T>;
     /** Arbitrary local predicate. Applied after `where`. */
     filter?: (entity: T) => boolean;
@@ -42,8 +46,11 @@ export interface ModelListOptions<T> {
      *  sync-group `scope`. */
     state?: ModelListScope;
 }
-export type ModelCountOptions<T> = Pick<ModelListOptions<T>, 'where' | 'filter' | 'state'>;
-export interface ModelLoadOptions<T> {
+export type LocalCountOptions<T> = Pick<LocalReadOptions<T>, 'where' | 'filter' | 'state'>;
+/** Options for the async SERVER reads `retrieve`/`list` (operator `where` DSL,
+ *  `type`, `expand`). The server-async axis; contrast {@link LocalReadOptions}
+ *  (the local-reactive axis). */
+export interface ServerReadOptions<T> {
     /**
      * Filter for the lookup. Accepts:
      *   - object form: `{ name: 'foo' }` (equality, array values → `IN`)
@@ -71,8 +78,8 @@ export interface ModelLoadOptions<T> {
     expand?: readonly string[];
 }
 /** Options for the single-row async server read `retrieve({ id })`. A subset of
- *  {@link ModelLoadOptions} — `where`/`limit`/`orderBy` are fixed by the id. */
-export type ModelRetrieveOptions = Pick<ModelLoadOptions<unknown>, 'type' | 'expand'>;
+ *  {@link ServerReadOptions} — `where`/`limit`/`orderBy` are fixed by the id. */
+export type ServerRetrieveOptions = Pick<ServerReadOptions<unknown>, 'type' | 'expand'>;
 export interface ModelCollaboration<T> {
     createClaim(options: {
         target: {
@@ -83,7 +90,8 @@ export interface ModelCollaboration<T> {
             range?: TargetRange;
             meta?: Record<string, unknown>;
         };
-        action: string;
+        /** Human-readable phase (`'editing'`); wire field is `action`. */
+        reason: string;
         ttl?: Duration;
         /**
          * Block on the server's fair FIFO queue when the target is held, rather
@@ -161,10 +169,19 @@ export interface ModelCollaboration<T> {
      * Forwards to `BaseSyncedStore.pinScope`.
      */
     pinScope?(scope: Record<string, string>): void | Promise<void>;
+    /**
+     * Open a presence/claim subscription on this model's sync group(s) and
+     * return the live participant handle. Backs `ablo.<model>.watch(ids)` —
+     * the relocation of the old `ablo.participants.join({ scope })`. WebSocket
+     * only (presence needs a socket); absent on non-ws constructions, in which
+     * case the proxy throws a clear error. Forwards to `participantManager.join`.
+     */
+    createWatch?(modelKey: string, ids: string | readonly string[], options?: WatchOptions): Promise<JoinedParticipant>;
 }
 export interface ClaimTargetOptions<T = Record<string, unknown>> {
-    /** Phase shown to observers while held. Defaults to `'editing'`. */
-    action?: string;
+    /** Human-readable phase shown to observers while held. Defaults to
+     *  `'editing'`. The same word on every claim surface; wire field is `action`. */
+    reason?: string;
     /** Peer-visible explanation of the work being performed. */
     description?: string;
     /** Field-level target, for fine-grained claimed-state badges. */
@@ -184,8 +201,14 @@ export interface ClaimTargetOptions<T = Record<string, unknown>> {
      * `AbloClaimedError` instead of waiting (claim-or-skip). Use `false` for
      * work-distribution dedup ("if someone else has this job, skip it") where
      * waiting would mean double-processing.
+     *
+     * Named `queue` to match every other claim surface (low-level
+     * `claims.claim`, HTTP `claim.create`, and the wire). The high-level typed
+     * claim defaults it ON because it serializes writers; the low-level lease
+     * and HTTP default it OFF — they return/resolve immediately and can't
+     * transparently wait for a grant.
      */
-    wait?: boolean;
+    queue?: boolean;
     /**
      * Backpressure: willing to queue, but not behind too many. If the server
      * reports `position >= maxQueueDepth` when we join the line, reject with
@@ -211,7 +234,7 @@ export interface ClaimReorderParams<T = Record<string, unknown>> extends ClaimLo
  * ```ts
  * const claim = await ablo.weatherReports.claim({
  *   id: 'report_stockholm',
- *   action: 'forecasting',
+ *   reason: 'forecasting',
  *   description: 'Fetching current weather before writing the forecast.',
  * });
  * try {
@@ -243,7 +266,7 @@ export type ClaimOptions<T = Record<string, unknown>> = ClaimTargetOptions<T>;
  *   data: { title },
  *   claim: {
  *     field: 'title',
- *     action: 'renaming',
+ *     reason: 'renaming',
  *     description: 'Renaming the task to match the project brief.',
  *   },
  * });
@@ -276,7 +299,7 @@ export interface ClaimApi<T> {
     /** Release a manual claim handle early. Single-write claims auto-release. */
     release(params: ClaimLookupParams<T> | ClaimHandle<T>): Promise<void>;
 }
-export interface ModelRetrieveParams extends ModelRetrieveOptions {
+export interface ModelRetrieveParams extends ServerRetrieveOptions {
     readonly id: string;
 }
 export interface ModelCreateParams<T, CreateInput> extends MutationOptions {
@@ -293,6 +316,15 @@ export interface ModelDeleteParams<T> extends MutationOptions {
     readonly id: string;
     readonly claim?: ClaimHandle<T> | ClaimTargetOptions<T> | null;
 }
+/** Options for the WebSocket-only `ablo.<model>.watch(ids, options?)`. */
+export interface WatchOptions {
+    /**
+     * Lease TTL for the underlying presence claim — the participant
+     * auto-releases after this if the holder dies. Compact duration string
+     * (`'5m'`) or ms number, mirroring the claim `ttl`.
+     */
+    ttl?: Duration;
+}
 export interface ModelOperations<T, CreateInput> {
     /**
      * Read a single entity by id from the **server** — async. Resolves through
@@ -316,7 +348,7 @@ export interface ModelOperations<T, CreateInput> {
      * Mirrors `stripe.customers.list({...})` — network-backed. For a synchronous
      * read of the local graph use `getAll(...)`.
      */
-    list(options?: ModelLoadOptions<T>): Promise<T[]>;
+    list(options?: ServerReadOptions<T>): Promise<T[]>;
     /**
      * Synchronous snapshot of a single entity from the **local graph** — no
      * network. Returns `undefined` when the row isn't resident (cold hosted
@@ -329,9 +361,9 @@ export interface ModelOperations<T, CreateInput> {
      * no network round-trip. Empty until `retrieve`/`list`/bootstrap has warmed
      * the graph.
      */
-    getAll(options?: ModelListOptions<T>): T[];
+    getAll(options?: LocalReadOptions<T>): T[];
     /** Count entities in the **local graph** (synchronous, no network). */
-    getCount(options?: ModelCountOptions<T>): number;
+    getCount(options?: LocalCountOptions<T>): number;
     /**
      * Create a new entity — **optimistic, offline-first**. Resolves once
      * the mutation is queued locally, not when the server confirms.
@@ -355,7 +387,7 @@ export interface ModelOperations<T, CreateInput> {
      * ```ts
      * const claim = await ablo.weatherReports.claim({
      *   id: 'report_stockholm',
-     *   action: 'forecasting',
+     *   reason: 'forecasting',
      *   description: 'Fetching fresh weather before updating the report.',
      * });
      * const weather = await getWeather(claim.data.location);
@@ -370,7 +402,22 @@ export interface ModelOperations<T, CreateInput> {
      * ```
      */
     claim: ClaimApi<T>;
+    /**
+     * Subscribe this client to the sync group(s) for one or more rows of this
+     * model and get a live participant handle back — presence (`.peers`), the
+     * scoped claim stream (`.claims`), and `.leave()` / `await using` disposal.
+     *
+     * The model-scoped relocation of the former `ablo.participants.join({
+     * scope: { <model>: ids } })`. WebSocket only — presence needs a socket, so
+     * this is absent on HTTP clients and throws on any non-ws construction.
+     *
+     * ```ts
+     * await using participant = await ablo.slides.watch(slideIds, { ttl: '5m' });
+     * participant.peers; // who else is here
+     * ```
+     */
+    watch(ids: string | readonly string[], options?: WatchOptions): Promise<JoinedParticipant>;
     /** Listen for changes (callback called on every change). */
-    onChange(callback: (entities: T[]) => void, options?: ModelListOptions<T>): () => void;
+    onChange(callback: (entities: T[]) => void, options?: LocalReadOptions<T>): () => void;
 }
 export declare function createModelProxy<T, C>(schemaKey: string, registeredModelName: string, objectPool: ObjectPool, syncClient: SyncClient, registry: ModelRegistry, hydration: HydrationCoordinator, collaboration?: ModelCollaboration<T>): ModelOperations<T, C>;

package/dist/client/createModelProxy.js

@@ -77,7 +77,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
     // `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.
     //
-    // `target` / `action` / `expiresAt` are kept alongside the lease so
+    // `target` / `reason` / `expiresAt` are kept alongside the lease so
     // `claim.state` can synthesize a self-claim: the server excludes a holder's
     // own presence frames, so the local proxy is the ONLY place that knows "I
     // hold this." `expiresAt` is the client's best estimate from the requested
@@ -103,7 +103,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             id: claim.id,
             actor: claim.heldBy,
             participantKind: claim.participantKind,
-            action: claim.action,
+            reason: claim.reason,
             ...(description ? { description } : {}),
             field: claim.target.field,
             status: claim.status,
@@ -143,8 +143,8 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         // claim (a free / already-mine target can't have changed under us).
         const held = collaboration.observe({ model: wireModel, id });
         const contended = !!held && held.heldBy !== collaboration.selfParticipantId;
-        const failFast = options?.wait === false;
-        // Fail-fast (`wait: false`): if another participant already holds it,
+        const failFast = options?.queue === false;
+        // Fail-fast (`queue: false`): if another participant already holds it,
         // reject now instead of queuing. Best-effort at the client (a racing
         // claim not yet synced into our snapshot slips through here) — the
         // commit-time claim guard is the authoritative backstop that rejects
@@ -176,7 +176,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         // in the group when `createClaim` lands. Awaited because the broadcast
         // ordering depends on it; still soft (the store swallows reconcile errors).
         await collaboration.pinScope?.({ [schemaKey]: id });
-        // Acquire the lease. Default (`wait` !== false) goes through the server's
+        // Acquire the lease. Default (`queue` !== false) goes through the server's
         // fair FIFO queue — `queue: true` resolves only once the lease is genuinely
         // ours, blocking behind any current holder, with no TOCTOU gap (the server
         // orders contenders). Fail-fast skips the queue: we already rejected an
@@ -190,7 +190,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                 ...(options?.range ? { range: options.range } : {}),
                 ...(claimMeta(options) ? { meta: claimMeta(options) } : {}),
             },
-            action: options?.action ?? 'editing',
+            reason: options?.reason ?? 'editing',
             ttl: options?.ttl,
             queue: !failFast,
             maxQueueDepth: options?.maxQueueDepth,
@@ -213,7 +213,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             model = objectPool.get(id) ?? model;
         }
         const snapshot = collaboration.createSnapshot(schemaKey, id);
-        const action = options?.action ?? 'editing';
+        const reason = options?.reason ?? 'editing';
         // The self-claim's `EntityRef` mirrors what a peer's `claim.state` would
         // report (`observe` maps `held.target.model` → `type`), so a holder and a
         // peer see the SAME target.type for one row — the wire model token.
@@ -231,7 +231,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             lease,
             snapshot,
             target: selfTarget,
-            action,
+            reason,
             expiresAt,
         });
         const target = {
@@ -248,7 +248,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             claimId: lease.claimId,
             readAt: snapshot.stamp,
             target,
-            action,
+            reason,
             ...(options?.description ? { description: options.description } : {}),
             data: modelAsRow(model),
             release,
@@ -281,7 +281,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                     id: own.lease.claimId,
                     status: 'active',
                     target: own.target,
-                    action: own.action,
+                    reason: own.reason,
                     heldBy: collaboration?.selfParticipantId ?? '',
                     participantKind: collaboration?.selfParticipantKind ?? 'user',
                     expiresAt: own.expiresAt,
@@ -381,9 +381,9 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                         ...(claim.range ? { range: claim.range } : {}),
                         ...(claimMeta(claim) ? { meta: claimMeta(claim) } : {}),
                     },
-                    action: claim.action ?? 'creating',
+                    reason: claim.reason ?? 'creating',
                     ttl: claim.ttl,
-                    queue: claim.wait !== false,
+                    queue: claim.queue !== false,
                     maxQueueDepth: claim.maxQueueDepth,
                 });
             }
@@ -509,6 +509,12 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         // `claim` is a callable namespace (take a claim) carrying the coordination
         // readers (`claim.state` / `claim.queue` / `claim.release` / `claim.reorder`).
         claim: claimApi,
+        watch: guard((ids, options) => {
+            if (!collaboration?.createWatch) {
+                throw new AbloValidationError(`Model "${schemaKey}" was built without a WebSocket runtime, so watch() is unavailable here. Presence needs a live socket — use the standard Ablo({ schema, apiKey }) client (not the HTTP transport).`, { code: 'model_watch_not_configured' });
+            }
+            return collaboration.createWatch(schemaKey, ids, options);
+        }),
         onChange(callback, options) {
             return autorun(() => {
                 const entities = this.getAll(options);

package/dist/client/httpClient.d.ts

@@ -23,8 +23,8 @@
  * surface as the browser client — typed proxies, stateless transport.
  */
 import { type AbloApiClientOptions } from './ApiClient.js';
-import type { CommitReceipt, CommitResource, HttpClaimApi, ModelRead, ModelReadOptions } from './Ablo.js';
-import type { ModelCreateParams, ModelDeleteParams, ModelLoadOptions, ModelRetrieveParams, ModelUpdateParams } from './createModelProxy.js';
+import type { CommitReceipt, CommitResource, HttpClaimApi, ModelRead, ModelReadOptions, CreateSessionParams, AbloSession } from './Ablo.js';
+import type { ModelCreateParams, ModelDeleteParams, ServerReadOptions, 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. */
@@ -36,10 +36,16 @@ export interface AbloHttpClientOptions<S extends SchemaRecord> extends Omit<Ablo
  * 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.
+ *
+ * Read-shape asymmetry (by design, not a gap): `retrieve(...)` returns a
+ * `ModelRead<T>` envelope `{ data, stamp, claims }` — the stateless client has no
+ * local graph, so the watermark/claims the stateful client reads from its pool
+ * must ride inline on the read (an agent needs the `stamp` to do a stale-guarded
+ * write; there is no `snapshot()` to fetch it from). `list(...)` returns a bare `T[]`.
  */
 export interface HttpModelClient<T, C = T> {
     retrieve(params: ModelRetrieveParams & ModelReadOptions): Promise<ModelRead<T>>;
-    list(options?: ModelLoadOptions<T>): Promise<T[]>;
+    list(options?: ServerReadOptions<T>): Promise<T[]>;
     create(params: ModelCreateParams<T, C>): Promise<CommitReceipt>;
     update(params: ModelUpdateParams<C>): Promise<CommitReceipt>;
     delete(params: ModelDeleteParams<T>): Promise<CommitReceipt>;
@@ -61,6 +67,14 @@ export type AbloHttpClient<S extends SchemaRecord> = {
     dispose(): Promise<void>;
     /** Resolve the bearer credential this client authenticates with (see `AbloApi.getAuthToken`). */
     getAuthToken(): Promise<string | null>;
+    /**
+     * Mint a short-lived scoped session (Stripe ephemeral-key shape). Minting is a
+     * stateless control-plane call, so — unlike `get`/`getAll`/`onChange` — it IS
+     * available on the HTTP client. `{ user }` → `ek_`, `{ agent, can }` → `rk_`.
+     */
+    readonly sessions: {
+        create(params: CreateSessionParams<S>): Promise<AbloSession>;
+    };
     /** String-keyed model accessor (for dynamic model names). */
     model<T = Record<string, unknown>>(name: string): HttpModelClient<T>;
 };

package/dist/client/httpClient.js

@@ -38,6 +38,7 @@ const PROTOCOL_MEMBERS = new Set([
     'commits',
     'model',
     'getAuthToken',
+    'sessions',
 ]);
 /**
  * Stateless, typed HTTP client. Each `client.<model>` resolves to the protocol

package/dist/client/identity.js

@@ -21,137 +21,153 @@
  */
 import { AbloAuthenticationError } from '../errors.js';
 import { exchangeApiKey } from '../auth/index.js';
+import { mintUserSessionKey } from '../auth/index.js';
 import { resolveIdentity } from '../auth/index.js';
 import { createRefreshScheduler, } from '../auth/index.js';
+import { resolveCredential, } from '../auth/credentialPolicy.js';
 import { resolveApiKeyValue, resolveBootstrapBaseUrl } from './auth.js';
 export async function resolveParticipantIdentity(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({
-            apiKeyValue,
-            configuredApiKey,
-            url,
-            kind,
-            options,
-            bootstrapHelper,
-            auth,
-            logger,
-        });
-    }
-    // Branch 2: self-derived (capability token present, identity unknown)
-    if (!internalOptions.organizationId ||
-        (kind === 'agent' ? !options.agentId : !options.user?.id)) {
-        // 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({
+    // 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,
+    });
+    // `internalOptions.organizationId` + a caller-supplied participant id is the
+    // legacy explicit path: the caller already knows its own identity, so no
+    // server round-trip is needed.
+    const hasExplicitIdentity = internalOptions.organizationId != null &&
+        (kind === 'agent' ? options.agentId != null : options.user?.id != null);
+    // The connect-time credential ROUTING decision lives in `credentialPolicy`:
+    // classify the apiKey (sk_/ek_/rk_/pk_) and route. The hosted exchange is the
+    // one mint the policy performs (delegating to the injected `exchangeApiKey`);
+    // every other route just hands back the bearer to use. We then switch on the
+    // resolved `kind` below to wire up scope + the refresh scheduler.
+    const cred = await resolveCredential({
+        apiKeyValue,
+        configuredApiKey,
+        capabilityToken: options.capabilityToken,
+        authToken: configuredAuthToken,
+        hasExplicitIdentity,
+    }, {
+        primitives: {
+            exchangeApiKey,
+            mintUserSessionKey,
+            resolveIdentity,
+            resolveApiKeyValue,
+        },
+        exchangeArgs: {
             baseUrl,
-            authToken: initialCapToken,
-        });
-        // Merge caller-passed syncGroups with server-resolved ones rather
-        // than letting the server's response silently overwrite. Browser
-        // consumers (apps/web's SyncEngineProvider) compose
-        // `['default', 'org:${orgId}', 'user:${userId}', ...team:]` from
-        // the resolved session and pass it via `<AbloProvider syncGroups>`;
-        // before this merge, Branch 2 dropped that set on the floor in
-        // favor of `/auth/identity`'s response, which is empty for
-        // cookie-auth users today (apps/sync-server/src/routes/auth.ts only
-        // populates from `effectiveSyncGroups`, the cap-narrowed list).
-        // Empty syncGroups → server bootstrap falls back to `['default']`
-        // → no deltas fan out → live updates appear only on hard reload.
-        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(initialCapToken);
-        return {
-            userId: identity.participantId,
-            accountScope: identity.accountScope,
-            teamIds: undefined,
-            capabilityToken: initialCapToken,
-            syncGroups: mergedSyncGroups,
-            participantKind: identity.participantKind,
-            refreshScheduler: null,
-        };
+            participantKind: (kind === 'agent' ? 'agent' : 'system'),
+            participantId: options.agentId ?? options.user?.id,
+            wideScope: true,
+            ttlSeconds: 3600,
+        },
+    });
+    switch (cred.kind) {
+        case 'publishable':
+            // `pk_` — a long-lived, browser-safe, READ-ONLY project key. Used DIRECTLY
+            // as the bearer and NEVER exchanged for a short-lived capability — so it
+            // never expires and there is nothing to refresh. 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.
+            return resolveViaIdentity({
+                bearer: cred.getBearer,
+                baseUrl,
+                options,
+                bootstrapHelper,
+                auth,
+            });
+        case 'exchange':
+            // Hosted-cloud (`sk_`): the policy exchanged the apiKey for a capability
+            // token; here we apply the returned scope and set up the refresh scheduler.
+            return resolveHosted({
+                cred,
+                configuredApiKey,
+                baseUrl,
+                kind,
+                options,
+                bootstrapHelper,
+                auth,
+                logger,
+            });
+        case 'pre-minted':
+            // Self-derived: a pre-minted `ek_`/`rk_` bearer or an explicit capability
+            // token authenticates `/auth/identity` directly (no exchange, no refresh).
+            return resolveViaIdentity({
+                bearer: cred.getBearer,
+                baseUrl,
+                options,
+                bootstrapHelper,
+                auth,
+            });
+        case 'explicit': {
+            // Legacy explicit (self-hosted, pre-Phase-3 — caller knows its own
+            // organizationId + user/agentId).
+            const userId = kind === 'agent' ? options.agentId : options.user.id;
+            const accountScope = internalOptions.organizationId;
+            bootstrapHelper.setCacheScope(accountScope);
+            bootstrapHelper.setSyncGroups(options.syncGroups);
+            auth.setAuthToken(cred.getBearer);
+            return {
+                userId,
+                accountScope,
+                teamIds: kind === 'user' ? options.user?.teamIds : undefined,
+                capabilityToken: cred.getBearer,
+                syncGroups: options.syncGroups,
+                participantKind: kind,
+                refreshScheduler: null,
+            };
+        }
     }
-    // Branch 3: legacy explicit (self-hosted, pre-Phase-3 — caller knows
-    // its own organizationId + user/agentId).
-    const userId = kind === 'agent' ? options.agentId : options.user.id;
-    const accountScope = internalOptions.organizationId;
-    bootstrapHelper.setCacheScope(accountScope);
-    bootstrapHelper.setSyncGroups(options.syncGroups);
-    auth.setAuthToken(initialCapToken);
+}
+/**
+ * Shared `/auth/identity` resolution for the `pk_` (publishable) and pre-minted
+ * (`ek_`/`rk_` or explicit cap token) routes: the bearer is used as-is, the
+ * server resolves the identity, and caller-passed syncGroups are MERGED with the
+ * server-resolved set.
+ */
+async function resolveViaIdentity(input) {
+    const { bearer, baseUrl, options, bootstrapHelper, auth } = input;
+    const identity = await resolveIdentity({ baseUrl, authToken: bearer });
+    // Merge caller-passed syncGroups with server-resolved ones rather than letting
+    // the server's response silently overwrite. Browser consumers (apps/web's
+    // SyncEngineProvider) compose `['default', 'org:${orgId}', 'user:${userId}',
+    // ...team:]` from the resolved session and pass it via `<AbloProvider
+    // syncGroups>`; before this merge, the self-derived path dropped that set on
+    // the floor in favor of `/auth/identity`'s response, which is empty for
+    // cookie-auth users today (apps/sync-server/src/routes/auth.ts only populates
+    // from `effectiveSyncGroups`, the cap-narrowed list). Empty syncGroups →
+    // server bootstrap falls back to `['default']` → no deltas fan out → live
+    // updates appear only on hard reload.
+    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(bearer);
     return {
-        userId,
-        accountScope,
-        teamIds: kind === 'user' ? options.user?.teamIds : undefined,
-        capabilityToken: initialCapToken,
-        syncGroups: options.syncGroups,
-        participantKind: kind,
+        userId: identity.participantId,
+        accountScope: identity.accountScope,
+        teamIds: undefined,
+        capabilityToken: bearer,
+        syncGroups: mergedSyncGroups,
+        participantKind: identity.participantKind,
         refreshScheduler: null,
     };
 }
 async function resolveHosted(input) {
-    // Pure managed-cloud shape: `Ablo({schema, apiKey})`. Server returns
-    // scope + userMeta; SDK populates internals.
-    const baseUrl = resolveBootstrapBaseUrl({
-        url: input.url,
-        bootstrapBaseUrl: input.options.bootstrapBaseUrl,
-    });
+    // Pure managed-cloud shape: `Ablo({schema, apiKey})`. The credential policy
+    // already exchanged the apiKey (delegating to `exchangeApiKey`); here we apply
+    // the returned scope + userMeta and stand up the refresh scheduler.
+    const { exchange } = input.cred;
+    const baseUrl = input.baseUrl;
+    // The refresh path re-runs `exchangeApiKey` with a freshly-resolved apiKey, so
+    // it needs the same argument bag the policy used for the initial exchange.
     const exchangeArgs = {
         baseUrl,
         participantKind: (input.kind === 'agent' ? 'agent' : 'system'),
@@ -159,10 +175,6 @@ async function resolveHosted(input) {
         wideScope: true,
         ttlSeconds: 3600,
     };
-    const exchange = await exchangeApiKey({
-        ...exchangeArgs,
-        apiKey: input.apiKeyValue,
-    });
     input.bootstrapHelper.setCacheScope(exchange.scope.organizationId);
     input.bootstrapHelper.setSyncGroups(exchange.scope.syncGroups);
     input.auth.setAuthToken(exchange.token);

package/dist/client/index.d.ts

@@ -29,7 +29,7 @@
  * });
  * ```
  */
-export { Ablo, computeFKDepthPriority, type AbloOptions, type InternalAbloOptions, type ClaimedOptions, type IfClaimedPolicy, type ClaimWaitOptions, type ModelCountOptions, type ModelListOptions, type ModelListScope, type ModelLoadOptions, type ModelOperations, type ModelReadOptions, } from './Ablo.js';
+export { Ablo, computeFKDepthPriority, type AbloOptions, type InternalAbloOptions, type ClaimedOptions, type IfClaimedPolicy, type ClaimWaitOptions, type LocalCountOptions, type LocalReadOptions, type ModelListScope, type ServerReadOptions, type ModelOperations, type ModelReadOptions, } from './Ablo.js';
 export { ABLO_DEFAULT_BASE_URL, ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_URL, normalizeAbloHostedBaseUrl, } from './auth.js';
 export type { AbloPersistence } from './persistence.js';
 export type { AbloApi, AbloApiClientOptions, AbloApiClaims, Capability, CapabilityCreateOptions, CapabilityParticipantKind, CapabilityRecord, CapabilityResource, CapabilityRevocation, CapabilityScope, } from './ApiClient.js';