@abloatai/ablo 0.11.0 → 0.11.2

package/dist/client/createModelProxy.js

@@ -18,6 +18,7 @@ import { autorun } from 'mobx';
 import { AbloClaimedError, AbloValidationError, formatClaimedErrorMessage, toAbloError, } from '../errors.js';
 import { descriptionFromMeta } from '../coordination/schema.js';
 import { Model, modelAsRow } from '../Model.js';
+import { toMs } from '../utils/duration.js';
 import { assertWriteOptions } from './writeOptionsSchema.js';
 import { ModelScope } from '../types/index.js';
 const modelClientMeta = new WeakMap();
@@ -75,7 +76,17 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
     // Claims this proxy currently holds, keyed by entity id. Lets the flat
     // `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
+    // `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
+    // TTL (a genuine epoch-ms expiry, not a fabricated watermark), defaulting to
+    // the server's keepalive lease window when no TTL was requested.
     const activeClaims = new Map();
+    // Server keepalive lease window (Hub `LEASE_RENEW_TTL_MS`). The fallback
+    // expiry estimate when a claim is taken without an explicit TTL.
+    const DEFAULT_LEASE_TTL_MS = 90_000;
     const isClaimHandle = (value) => typeof value === 'object' &&
         value !== null &&
         value.object === 'claim' &&
@@ -124,7 +135,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
     };
     const takeClaim = async (params) => {
         if (!collaboration) {
-            throw new AbloValidationError(`Model "${schemaKey}" cannot claim a row without collaboration wiring.`, { code: 'model_claim_not_configured' });
+            throw new AbloValidationError(`Model "${schemaKey}" was built without the collaboration runtime, so claim() is unavailable here. Claiming needs no per-model config — use the standard Ablo({ schema, apiKey }) client and every model is claimable.`, { code: 'model_claim_not_configured' });
         }
         const { id, ...options } = params;
         // Is someone ELSE already on this target? Read the local coordination
@@ -157,6 +168,14 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         if (!model) {
             throw new AbloValidationError(`Entity not found: ${registeredModelName}/${id}`, { code: 'entity_not_found' });
         }
+        // Write-intent: enter the entity scope BEFORE acquiring the lease so the
+        // holder's claim presence broadcasts to whoever is in this entity group —
+        // including a peer that subscribed just before us. Pinning before the
+        // lease (rather than after) closes the subscribe-vs-broadcast race: the
+        // server fans `broadcastPresenceChange` out at claim time, so we must be
+        // 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
         // fair FIFO queue — `queue: true` resolves only once the lease is genuinely
         // ours, blocking behind any current holder, with no TOCTOU gap (the server
@@ -194,7 +213,27 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             model = objectPool.get(id) ?? model;
         }
         const snapshot = collaboration.createSnapshot(schemaKey, id);
-        activeClaims.set(id, { lease, snapshot });
+        const action = options?.action ?? '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.
+        const selfTarget = {
+            type: wireModel,
+            id,
+            ...(options?.field ? { field: options.field } : {}),
+            ...(options?.path ? { path: options.path } : {}),
+            ...(options?.range ? { range: options.range } : {}),
+            ...(claimMeta(options) ? { meta: claimMeta(options) } : {}),
+        };
+        const expiresAt = Date.now() +
+            (options?.ttl !== undefined ? toMs(options.ttl) : DEFAULT_LEASE_TTL_MS);
+        activeClaims.set(id, {
+            lease,
+            snapshot,
+            target: selfTarget,
+            action,
+            expiresAt,
+        });
         const target = {
             model: schemaKey,
             id,
@@ -209,7 +248,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             claimId: lease.claimId,
             readAt: snapshot.stamp,
             target,
-            action: options?.action ?? 'editing',
+            action,
             ...(options?.description ? { description: options.description } : {}),
             data: modelAsRow(model),
             release,
@@ -226,6 +265,28 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
     // are the same object.
     const claimApi = Object.assign(guard(claim), {
         state(params) {
+            // Read-interest: a passive observer subscribing to a row's claim state
+            // must enter that row's entity scope, or it sits on `org:`/`user:`
+            // groups only and never receives the holder's entity-scoped claim
+            // presence. Soft + fire-and-forget — never blocks or rejects the read.
+            void collaboration?.enterScope?.({ [schemaKey]: params.id });
+            // Self-awareness: the server excludes a holder's OWN presence frames and
+            // the client skips them, so `observe` returns null for a row WE hold.
+            // Synthesize the active claim for self from the stored lease so the
+            // holder sees its own claim (the JSDoc contract on `claim.state`).
+            const own = activeClaims.get(params.id);
+            if (own) {
+                return {
+                    object: 'claim',
+                    id: own.lease.claimId,
+                    status: 'active',
+                    target: own.target,
+                    action: own.action,
+                    heldBy: collaboration?.selfParticipantId ?? '',
+                    participantKind: collaboration?.selfParticipantKind ?? 'user',
+                    expiresAt: own.expiresAt,
+                };
+            }
             return collaboration?.observe({ model: wireModel, id: params.id }) ?? null;
         },
         queue(params) {
@@ -241,6 +302,11 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
     });
     const operations = {
         retrieve: guard(async (params) => {
+            // Read-interest enrolment: READ a row → enter its entity scope, so a
+            // Node/agent client lands in the same group the holder's claim presence
+            // fans out on and `claim.state`/`claim.queue` report peers. Soft +
+            // fire-and-forget — never make the read reject or slower.
+            void collaboration?.enterScope?.({ [schemaKey]: params.id });
             const rows = await load({
                 ...params,
                 where: [['id', params.id]],
@@ -248,6 +314,9 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             });
             return rows[0];
         }),
+        // NB: no auto scope enrolment on bulk `list`/`getAll` — that would
+        // subscribe to an unbounded set of rows' entity groups. Bulk-list scope
+        // enrolment is a deliberate follow-up (a bounded, opt-in policy).
         list: guard(load),
         get(id) {
             return objectPool.get(id);
@@ -295,8 +364,14 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             let autoLease;
             if (claim && !isClaimHandle(claim)) {
                 if (!collaboration) {
-                    throw new AbloValidationError(`Model "${schemaKey}" cannot claim a row without collaboration wiring.`, { code: 'model_claim_not_configured' });
+                    throw new AbloValidationError(`Model "${schemaKey}" was built without the collaboration runtime, so claim() is unavailable here. Claiming needs no per-model config — use the standard Ablo({ schema, apiKey }) client and every model is claimable.`, { code: 'model_claim_not_configured' });
                 }
+                // Write-intent: enter the new row's entity scope BEFORE acquiring the
+                // create-claim so the holder's claim presence broadcasts to whoever is
+                // already in this entity group (closing the subscribe-vs-broadcast
+                // race — see `takeClaim`). Released with the lease in the `finally`
+                // below. Awaited for broadcast ordering; still soft.
+                await collaboration.pinScope?.({ [schemaKey]: id });
                 autoLease = await collaboration.createClaim({
                     target: {
                         model: wireModel,
@@ -434,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;