@abloatai/ablo 0.11.1 → 0.11.2

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: {
@@ -161,6 +168,14 @@ 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'`. */
@@ -276,7 +291,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 +308,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 +340,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 +353,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.
@@ -370,7 +394,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

@@ -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';

package/dist/client/sessionMint.d.ts

@@ -0,0 +1,15 @@
+import type { SchemaRecord } from '../schema/schema.js';
+import type { AbloSession, CreateSessionParams } from './Ablo.js';
+/** The resolved control-plane context a mint needs. `fetch` is optional — the
+ *  auth helpers fall back to the runtime global when omitted. */
+export interface MintSessionContext {
+    readonly apiKey: string;
+    readonly baseUrl: string;
+    readonly fetch?: typeof fetch;
+}
+/**
+ * Mint a session token from an already-resolved `sk_` credential + base URL.
+ * Discriminates the `{ user }` / `{ agent }` union onto the server's two mint
+ * doors and reshapes each flat response into the `AbloSession` resource.
+ */
+export declare function mintSession<S extends SchemaRecord>(params: CreateSessionParams<S>, ctx: MintSessionContext): Promise<AbloSession>;

package/dist/client/sessionMint.js

@@ -0,0 +1,86 @@
+/**
+ * `mintSession` — the ONE implementation behind `sessions.create`, shared by the
+ * stateful `Ablo` client and the stateless protocol / HTTP client so the two can
+ * never drift on HOW a token is minted.
+ *
+ * Minting is a pure control-plane HTTP call (no socket, no synced pool): a backend
+ * holding a secret `sk_` exchanges it for a short-lived scoped token — `ek_` for an
+ * `{ user }` session (full end-user authority) or `rk_` for an `{ agent }` session
+ * (scoped to exactly the operations named in `can`). The two arms map to the
+ * server's two mint doors:
+ *
+ *   `{ user }`  → POST /auth/ephemeral-keys → `ek_`. 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 where
+ *                 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.
+ *
+ * The caller supplies the resolved control-plane credential + base URL in `ctx`;
+ * WHICH key to use (the original `sk_`, never a derived `rk_` the startup exchange
+ * may have installed) is the caller's concern — see the two call sites.
+ *
+ * Type-only imports of `CreateSessionParams` / `AbloSession` keep this module a
+ * leaf (no runtime cycle back to `Ablo.ts`): at runtime it depends on `auth` +
+ * `schema` only.
+ */
+import { exchangeApiKey, mintUserSessionKey } from '../auth/index.js';
+/**
+ * Mint a session token from an already-resolved `sk_` credential + base URL.
+ * Discriminates the `{ user }` / `{ agent }` union onto the server's two mint
+ * doors and reshapes each flat response into the `AbloSession` resource.
+ */
+export async function mintSession(params, ctx) {
+    const { apiKey, baseUrl } = ctx;
+    if (params.user) {
+        const res = await mintUserSessionKey({
+            apiKey,
+            baseUrl,
+            userId: params.user.id,
+            ...(params.syncGroups ? { syncGroups: [...params.syncGroups] } : {}),
+            ttlSeconds: params.ttlSeconds ?? 900,
+            ...(ctx.fetch ? { fetch: ctx.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({
+        apiKey,
+        baseUrl,
+        participantKind: 'agent',
+        participantId: params.agent.id,
+        ...(params.syncGroups ? { syncGroups: [...params.syncGroups] } : {}),
+        operations,
+        ttlSeconds: params.ttlSeconds ?? 900,
+        ...(params.userMeta ? { userMeta: params.userMeta } : {}),
+        ...(ctx.fetch ? { fetch: ctx.fetch } : {}),
+    });
+    return {
+        object: 'session',
+        id: res.capabilityId,
+        token: res.token,
+        expiresAt: res.expiresAt,
+        organizationId: res.organizationId,
+        scope: res.scope,
+        userMeta: res.userMeta,
+    };
+}

package/dist/errorCodes.d.ts

@@ -156,6 +156,7 @@ export declare const ERROR_CODES: {
     readonly model_claimed: ErrorCodeSpec;
     readonly model_claimed_timeout: ErrorCodeSpec;
     readonly model_claim_not_configured: ErrorCodeSpec;
+    readonly model_watch_not_configured: ErrorCodeSpec;
     readonly stale_context: ErrorCodeSpec;
     readonly idempotency_conflict: ErrorCodeSpec;
     readonly idempotency_key_too_long: ErrorCodeSpec;
@@ -195,6 +196,7 @@ export declare const ERROR_CODES: {
     readonly schema_scope_kind_invalid: ErrorCodeSpec;
     readonly schema_field_not_camelcase: ErrorCodeSpec;
     readonly schema_field_consecutive_caps: ErrorCodeSpec;
+    readonly schema_reserved_field: ErrorCodeSpec;
     readonly schema_grants_shape_invalid: ErrorCodeSpec;
     readonly schema_grants_identifier_unsafe: ErrorCodeSpec;
     readonly schema_grants_relation_kind: ErrorCodeSpec;

package/dist/errorCodes.js

@@ -159,6 +159,7 @@ export const ERROR_CODES = {
     model_claimed: wire('claim', 409, false, 'The model instance is claimed by another participant.'),
     model_claimed_timeout: wire('claim', 409, false, 'Timed out waiting for a model claim to clear.'),
     model_claim_not_configured: client('claim', 'Claiming requires the collaboration runtime, which the standard Ablo({ schema, apiKey }) client wires up for every model automatically — there is no per-model claim configuration to add. This appears only when a model proxy is constructed directly without that runtime (an internal/advanced path).'),
+    model_watch_not_configured: client('claim', 'watch() opens a presence/claim subscription and needs a live WebSocket, so it is unavailable on the HTTP transport and on model proxies built without a socket. Use the standard Ablo({ schema, apiKey }) client (default WebSocket transport).'),
     // ── stale context / idempotency (409) ──────────────────────────────
     stale_context: wire('conflict', 409, true, 'The write carried a readAt watermark that is now stale; re-read and retry.'),
     idempotency_conflict: wire('conflict', 409, false, 'The same Idempotency-Key was reused with a different request body.'),
@@ -210,6 +211,7 @@ export const ERROR_CODES = {
     schema_scope_kind_invalid: wire('schema', 400, false, 'A scope kind in the schema is invalid.'),
     schema_field_not_camelcase: wire('schema', 400, false, 'A schema field name is not camelCase.'),
     schema_field_consecutive_caps: wire('schema', 400, false, 'A schema field name has consecutive capital letters.'),
+    schema_reserved_field: client('schema', 'A model redeclared a reserved base field (id, createdAt, updatedAt, organizationId, createdBy) that the SDK provides automatically.'),
     schema_grants_shape_invalid: wire('schema', 400, false, 'A grants declaration has an invalid shape.'),
     schema_grants_identifier_unsafe: wire('schema', 400, false, 'A grants declaration referenced an unsafe identifier.'),
     schema_grants_relation_kind: wire('schema', 400, false, 'A grants relation referenced an invalid kind.'),