@abloatai/ablo 0.11.0 → 0.11.2

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';
@@ -42,7 +42,7 @@ import { createProtocolClient, } from './ApiClient.js';
 // Value import is cycle-safe: httpClient.js only value-imports ApiClient.js,
 // which imports this module type-only.
 import { createAbloHttpClient, } from './httpClient.js';
-import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, resolveDatabaseUrl, } from './auth.js';
+import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, resolveDatabaseUrl, warnIfDatabaseUrlEnvIgnored, } from './auth.js';
 import { registerDataSource } from './registerDataSource.js';
 import { shouldUseInMemoryPersistence, } from './persistence.js';
 import { createModelProxy } from './createModelProxy.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({
@@ -725,6 +713,9 @@ export function Ablo(options) {
         dangerouslyAllowBrowser: options.dangerouslyAllowBrowser,
     });
     const { logger = consoleLogger } = internalOptions;
+    // Nudge (once) if a stray DATABASE_URL is in the env but `databaseUrl` wasn't
+    // passed — the env value is no longer auto-adopted (see resolveDatabaseUrl).
+    warnIfDatabaseUrlEnvIgnored(authInput, (m) => logger.warn(m));
     const schema = options.schema;
     const url = resolveBaseURL(authInput);
     // 1. Derive config from schema
@@ -897,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()) {
@@ -930,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
@@ -1244,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 () => {
@@ -1370,6 +1356,26 @@ export function Ablo(options) {
             },
             waitFor: (target, waitOptions) => publicClaims.waitFor({ model: target.model, id: target.id }, waitOptions),
             selfParticipantId: participantId,
+            selfParticipantKind: kind,
+            // Read-interest / write-intent enrolment for the typed surface.
+            // `enterScope`/`pinScope` resolve the `{ [schemaKey]: id }` scope
+            // through the SAME resolver the claim path uses, landing this client in
+            // the entity-scoped group the holder's claim presence fans out on.
+            // Return the store promise so the claim write path can AWAIT pinScope
+            // BEFORE acquiring the lease (closing the subscribe-vs-broadcast race);
+            // read-interest callers (`retrieve`/`claim.state`) still `void` it and
+            // stay fire-and-forget. SOFT either way — the store swallows reconcile
+            // errors so read interest never makes a read reject or stall.
+            enterScope: (scope) => store.enterScope(scope),
+            pinScope: (scope) => store.pinScope(scope),
+            // `ablo.<model>.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 = {
@@ -1529,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);
@@ -1549,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
@@ -1593,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() {
@@ -1721,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

@@ -6,9 +6,10 @@
  * nouns directly to HTTP routes on sync-server.
  */
 import { AbloClaimedError, AbloAuthenticationError, AbloConnectionError, AbloValidationError, claimedError, translateHttpError, } from '../errors.js';
-import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, resolveDatabaseUrl, } from './auth.js';
+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) {
@@ -17,6 +18,9 @@ export function createProtocolClient(options) {
     const configuredApiKey = resolveApiKey(authInput);
     const configuredAuthToken = resolveAuthToken(authInput);
     const configuredDatabaseUrl = resolveDatabaseUrl(authInput);
+    // Nudge (once) if a stray DATABASE_URL is in the env but `databaseUrl` wasn't
+    // passed — no logger on this path, so the helper falls back to console.warn.
+    warnIfDatabaseUrlEnvIgnored(authInput);
     assertBrowserSafety({
         apiKey: configuredApiKey,
         databaseUrl: configuredDatabaseUrl,
@@ -225,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) {
@@ -653,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
@@ -45,12 +52,17 @@ export declare function resolveAuthToken(input: AuthResolveInput): string | null
 /**
  * Resolve the direct-URL connector's Postgres connection string.
  *
- * The default Data Source path should not call this: the customer keeps
- * `DATABASE_URL` in their app and exposes `dataSource(...)`. This helper exists
- * only for the opt-in direct connector where Ablo registers a dedicated tenant
- * database. Returns null for Ablo-managed storage.
+ * `databaseUrl` is an EXPLICIT, opt-in option: Ablo registers a dedicated
+ * tenant database only when the caller passes it to `Ablo(...)`. It is NOT
+ * read from `process.env.DATABASE_URL` — per this module's invariant
+ * (`ABLO_API_KEY` is the only environment fallback), an app's `DATABASE_URL`
+ * (commonly set for Prisma/Drizzle/docker) must never silently flip the client
+ * into connection-string mode. The default Data Source path keeps `DATABASE_URL`
+ * in the app and exposes `dataSource(...)`; that path leaves this null.
+ * `warnIfDatabaseUrlEnvIgnored` nudges callers who set the env but omitted the option.
  */
 export declare function resolveDatabaseUrl(input: AuthResolveInput): string | null;
+export declare function warnIfDatabaseUrlEnvIgnored(input: AuthResolveInput, warn?: (message: string) => void): void;
 export declare const ABLO_HOSTED_API_DOMAIN = "api.abloatai.com";
 export declare const ABLO_HOSTED_HTTP_BASE_URL = "https://api.abloatai.com";
 export declare const ABLO_DEFAULT_BASE_URL = "https://api.abloatai.com";

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
@@ -30,13 +31,48 @@ export function resolveAuthToken(input) {
 /**
  * Resolve the direct-URL connector's Postgres connection string.
  *
- * The default Data Source path should not call this: the customer keeps
- * `DATABASE_URL` in their app and exposes `dataSource(...)`. This helper exists
- * only for the opt-in direct connector where Ablo registers a dedicated tenant
- * database. Returns null for Ablo-managed storage.
+ * `databaseUrl` is an EXPLICIT, opt-in option: Ablo registers a dedicated
+ * tenant database only when the caller passes it to `Ablo(...)`. It is NOT
+ * read from `process.env.DATABASE_URL` — per this module's invariant
+ * (`ABLO_API_KEY` is the only environment fallback), an app's `DATABASE_URL`
+ * (commonly set for Prisma/Drizzle/docker) must never silently flip the client
+ * into connection-string mode. The default Data Source path keeps `DATABASE_URL`
+ * in the app and exposes `dataSource(...)`; that path leaves this null.
+ * `warnIfDatabaseUrlEnvIgnored` nudges callers who set the env but omitted the option.
  */
 export function resolveDatabaseUrl(input) {
-    return input.options.databaseUrl ?? input.env.DATABASE_URL ?? null;
+    return input.options.databaseUrl ?? null;
+}
+/**
+ * One-time migration nudge for the dropped `DATABASE_URL` env fallback.
+ *
+ * Earlier versions silently adopted `process.env.DATABASE_URL` when `databaseUrl`
+ * was not passed, registering a direct connector behind the caller's back — which
+ * surprised any app that keeps `DATABASE_URL` for another tool (Prisma, Drizzle,
+ * docker-compose) and, on localhost, tried to register a database Ablo's cloud
+ * cannot reach. The env value is now ignored; this points the developer at the
+ * explicit option instead of flipping their mode for them. Warns once per process
+ * so it never spams, and falls back to `console.warn` when no logger is supplied
+ * (the `transport: 'api'` client has none).
+ */
+let warnedDatabaseUrlEnvIgnored = false;
+export function warnIfDatabaseUrlEnvIgnored(input, warn) {
+    if (warnedDatabaseUrlEnvIgnored)
+        return;
+    if (input.options.databaseUrl != null)
+        return;
+    const envUrl = input.env.DATABASE_URL;
+    if (typeof envUrl !== 'string' || envUrl.length === 0)
+        return;
+    warnedDatabaseUrlEnvIgnored = true;
+    const message = 'Found DATABASE_URL in the environment but `databaseUrl` was not passed to Ablo(...). ' +
+        'Ablo no longer auto-adopts DATABASE_URL — the environment value is ignored. ' +
+        'To register your Postgres directly, pass `databaseUrl: process.env.DATABASE_URL` explicitly; ' +
+        'otherwise ignore this (the hosted sandbox and signed Data Source endpoints need no databaseUrl).';
+    if (warn)
+        warn(message);
+    else if (typeof console !== 'undefined')
+        console.warn('[sync]', message);
 }
 export const ABLO_HOSTED_API_DOMAIN = 'api.abloatai.com';
 export const ABLO_HOSTED_HTTP_BASE_URL = `https://${ABLO_HOSTED_API_DOMAIN}`;
@@ -102,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 " +

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: {
@@ -136,6 +143,39 @@ export interface ModelCollaboration<T> {
      * from "someone else holds it" in `claimOrWait`.
      */
     readonly selfParticipantId: string;
+    /**
+     * The local participant's kind (`'user' | 'agent' | 'system'`). Used to
+     * stamp the synthesized self-claim returned from `claim.state` when the
+     * LOCAL proxy holds the lease (server presence frames exclude one's own
+     * claims, so the holder must build its own view).
+     */
+    readonly selfParticipantKind?: 'user' | 'agent' | 'system';
+    /**
+     * Subscribe the connection to a scope's sync group(s) (read-interest).
+     * The typed surface calls this on single-entity reads/claim observation so
+     * a Node/agent client lands in the SAME entity-scoped group the holder's
+     * claim presence fans out on — otherwise a peer subscribed only to
+     * `org:`/`user:` groups never sees claim broadcasts. Fire-and-forget and
+     * SOFT: read interest is best-effort and must never make a read reject or
+     * stall (see `AreaOfInterestManager.reconcile`). Optional so minimal test
+     * doubles can omit it. Forwards to `BaseSyncedStore.enterScope`.
+     */
+    enterScope?(scope: Record<string, string>): void | Promise<void>;
+    /**
+     * Pin a scope's sync group(s) (write-intent / prominence): a row this
+     * client holds an active claim on stays subscribed regardless of
+     * navigation. Same fire-and-forget, soft semantics as `enterScope`.
+     * 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'`. */
@@ -251,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 {
@@ -268,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
@@ -291,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
@@ -304,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.
@@ -345,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>;