@abloatai/ablo 0.10.1 → 0.11.1

package/dist/client/ApiClient.js

@@ -5,8 +5,9 @@
  * IndexedDB, no WebSocket. It maps the public Model / Claim / Commit
  * nouns directly to HTTP routes on sync-server.
  */
-import { AbloClaimedError, AbloAuthenticationError, AbloConnectionError, AbloValidationError, translateHttpError, } from '../errors.js';
-import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, } from './auth.js';
+import { AbloClaimedError, AbloAuthenticationError, AbloConnectionError, AbloValidationError, claimedError, translateHttpError, } from '../errors.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 { assertWriteOptions } from './writeOptionsSchema.js';
 const DEFAULT_AGENT_LEASE = '10m';
@@ -15,8 +16,13 @@ export function createProtocolClient(options) {
     const authInput = { options, env };
     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,
         dangerouslyAllowBrowser: options.dangerouslyAllowBrowser,
     });
     const fetchImpl = options.fetch ?? globalThis.fetch;
@@ -28,6 +34,28 @@ export function createProtocolClient(options) {
         url,
         bootstrapBaseUrl: options.bootstrapBaseUrl,
     }).replace(/\/+$/, '');
+    let readyPromise = null;
+    async function ready() {
+        if (readyPromise)
+            return readyPromise;
+        readyPromise = (async () => {
+            if (!configuredDatabaseUrl)
+                return;
+            await registerDataSource({
+                baseUrl: apiBaseUrl,
+                apiKey: await resolveApiKeyValue(configuredApiKey),
+                databaseUrl: configuredDatabaseUrl,
+                ...(options.fetch ? { fetchImpl: options.fetch } : {}),
+            });
+        })();
+        try {
+            await readyPromise;
+        }
+        catch (error) {
+            readyPromise = null;
+            throw error;
+        }
+    }
     async function authHeaders() {
         const apiKey = await resolveApiKeyValue(configuredApiKey);
         const token = apiKey ?? configuredAuthToken;
@@ -57,6 +85,7 @@ export function createProtocolClient(options) {
         return target.toString();
     }
     async function requestJson(path, init) {
+        await ready();
         const { idempotencyKey, ...requestInit } = init;
         const headers = await authHeaders();
         if (idempotencyKey)
@@ -82,7 +111,7 @@ export function createProtocolClient(options) {
             ? crypto.randomUUID()
             : `tx_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
     }
-    function createIntentId() {
+    function createClaimId() {
         return typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
             ? `int_${crypto.randomUUID()}`
             : `int_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
@@ -128,7 +157,7 @@ export function createProtocolClient(options) {
         }
         return inputOperations.map((op) => normalizeCommitOperation(op, commitOptions));
     }
-    async function listIntents(target) {
+    async function listClaims(target) {
         const state = await listClaimState(target);
         return state.active;
     }
@@ -141,24 +170,16 @@ export function createProtocolClient(options) {
         if (target?.field)
             params.set('field', target.field);
         const suffix = params.toString();
-        const body = await requestJson(`/v1/intents${suffix ? `?${suffix}` : ''}`, { method: 'GET' });
+        const body = await requestJson(`/v1/claims${suffix ? `?${suffix}` : ''}`, { method: 'GET' });
         return {
-            active: body.intents ?? [],
+            active: body.claims ?? [],
             queue: body.queue ?? [],
         };
     }
-    function claimedError(target, claims, code) {
-        const label = [target.model, target.id, target.field].filter(Boolean).join('/');
-        const holder = claims[0];
-        const suffix = holder
-            ? ` held by ${holder.actor} (${holder.action})`
-            : ' held by another participant';
-        return new AbloClaimedError(`Model row is claimed: ${label || 'target'}${suffix}.`, { code, claims });
-    }
     function delay(ms, signal) {
         if (signal?.aborted) {
-            return Promise.reject(new AbloConnectionError('Intent wait aborted.', {
-                code: 'intent_wait_aborted',
+            return Promise.reject(new AbloConnectionError('Claim wait aborted.', {
+                code: 'claim_wait_aborted',
                 cause: signal.reason,
             }));
         }
@@ -174,28 +195,28 @@ export function createProtocolClient(options) {
             }
             function onAbort() {
                 cleanup();
-                reject(new AbloConnectionError('Intent wait aborted.', {
-                    code: 'intent_wait_aborted',
+                reject(new AbloConnectionError('Claim wait aborted.', {
+                    code: 'claim_wait_aborted',
                     cause: signal?.reason,
                 }));
             }
             signal?.addEventListener('abort', onAbort, { once: true });
         });
     }
-    async function waitForNoIntents(target, options) {
+    async function waitForNoClaims(target, options) {
         const startedAt = Date.now();
         const pollInterval = options?.pollInterval;
         for (;;) {
-            const intents = await listIntents(target);
-            if (intents.length === 0)
+            const claims = await listClaims(target);
+            if (claims.length === 0)
                 return;
             if (pollInterval == null) {
                 throw new AbloValidationError('Cannot wait for claims over the HTTP client without `pollInterval`. ' +
                     'Use the schema client for event-driven claim waits, pass `ifClaimed: "return"`, ' +
-                    'or provide an explicit poll interval for this runtime.', { code: 'intent_wait_poll_interval_required' });
+                    'or provide an explicit poll interval for this runtime.', { code: 'claim_wait_poll_interval_required' });
             }
             if (options?.timeout != null && Date.now() - startedAt >= options.timeout) {
-                throw claimedError(target, intents, 'model_claimed_timeout');
+                throw claimedError(target, claims, 'model_claimed_timeout');
             }
             const remaining = options?.timeout == null
                 ? pollInterval
@@ -217,7 +238,7 @@ export function createProtocolClient(options) {
             state.queue.length >= options.maxQueueDepth) {
             throw claimedError(target, state.active, 'queue_too_deep');
         }
-        await waitForNoIntents(target, {
+        await waitForNoClaims(target, {
             timeout: options?.claimedTimeout,
             pollInterval: options?.claimedPollInterval,
         });
@@ -230,7 +251,7 @@ export function createProtocolClient(options) {
                 readAt: commitOptions.readAt,
                 onStale: commitOptions.onStale,
                 wait: commitOptions.wait,
-                intent: commitOptions.intent,
+                claim: commitOptions.claim,
             }, 'commits.create');
             const clientTxId = createClientTxId(commitOptions.idempotencyKey);
             // Same claim vocabulary as the WS client's `commits.create`: a handle
@@ -247,7 +268,7 @@ export function createProtocolClient(options) {
                 body: JSON.stringify({
                     clientTxId,
                     idempotencyKey: clientTxId,
-                    intent: normalizeIntentId(commitOptions.intent) ?? claim?.claimId,
+                    claim: normalizeClaimId(commitOptions.claimRef) ?? claim?.claimId,
                     operations,
                 }),
             });
@@ -353,39 +374,42 @@ export function createProtocolClient(options) {
             return capabilities.create(options);
         },
     };
-    const intents = {
-        async create(intentOptions) {
-            const intentId = createIntentId();
-            const body = await requestJson('/v1/intents', {
+    const claims = {
+        async create(claimOptions) {
+            const claimId = createClaimId();
+            const body = await requestJson('/v1/claims', {
                 method: 'POST',
                 body: JSON.stringify({
-                    intentId,
-                    target: intentOptions.target,
-                    action: intentOptions.action,
-                    ttl: intentOptions.ttl,
-                    queue: intentOptions.queue,
+                    claimId,
+                    target: claimOptions.target,
+                    action: claimOptions.action,
+                    ttl: claimOptions.ttl,
+                    queue: claimOptions.queue,
                 }),
             });
-            // The fair-queue grant is PUSHED over a WebSocket (`intent_granted`),
+            // The fair-queue grant is PUSHED over a WebSocket (`claim_granted`),
             // which this stateless HTTP client doesn't hold. Returning a handle here
             // would be a phantom holder — a lease we can't confirm is ours. So a
             // queued response is surfaced as a typed claimed signal; callers that need
             // to *wait* in line use the realtime (WS-backed) `ablo.<model>.claim`.
             if (body.status === 'queued') {
-                throw new AbloClaimedError(`Target ${intentOptions.target.model}/${intentOptions.target.id} is held; ` +
+                throw new AbloClaimedError(`Target ${claimOptions.target.model}/${claimOptions.target.id} is held; ` +
                     `queued at position ${body.position ?? 0}. The HTTP client can't await ` +
-                    `the grant (no socket) — use the realtime client to wait in line.`, { code: 'intent_queued' });
+                    `the grant (no socket) — use the realtime client to wait in line.`, { code: 'claim_queued' });
             }
-            const id = body.intent?.id ?? intentId;
+            const id = body.claim?.id ?? claimId;
             let released = false;
             const release = async () => {
                 if (released)
                     return;
                 released = true;
-                await requestJson(`/v1/intents/${encodeURIComponent(id)}`, { method: 'DELETE' });
+                await requestJson(`/v1/claims/${encodeURIComponent(id)}`, { method: 'DELETE' });
             };
             return {
-                id,
+                object: 'claim',
+                claimId: id,
+                action: claimOptions.action,
+                target: claimOptions.target,
                 release,
                 revoke: () => {
                     void release().catch(() => { });
@@ -393,9 +417,9 @@ export function createProtocolClient(options) {
                 [Symbol.asyncDispose]: release,
             };
         },
-        list: listIntents,
+        list: listClaims,
         waitFor(target, options) {
-            return waitForNoIntents(target, options);
+            return waitForNoClaims(target, options);
         },
     };
     async function listModel(modelName, options) {
@@ -456,7 +480,7 @@ export function createProtocolClient(options) {
             readAt: options.readAt,
             onStale: options.onStale,
             wait: options.wait,
-            intent: options.intent,
+            claim: options.claim,
         }, `${modelName} ${action}`);
         const clientTxId = createClientTxId(options?.idempotencyKey);
         const encModel = encodeURIComponent(modelName);
@@ -475,7 +499,7 @@ export function createProtocolClient(options) {
         const readAt = options?.readAt ?? claimHandle?.readAt;
         const requestBody = {
             idempotencyKey: clientTxId,
-            intent: normalizeIntentId(options?.intent) ?? claimHandle?.claimId,
+            claim: normalizeClaimId(options?.claimRef) ?? claimHandle?.claimId,
             onStale: options?.onStale ?? (claimHandle?.readAt !== undefined ? 'reject' : undefined),
             readAt,
         };
@@ -528,9 +552,9 @@ export function createProtocolClient(options) {
             });
             if (body.status === 'queued') {
                 throw new AbloClaimedError(`Target ${name}/${params.id} is held; queued at position ${body.position ?? 0}. ` +
-                    `The HTTP client cannot await the grant without a WebSocket.`, { code: 'intent_queued' });
+                    `The HTTP client cannot await the grant without a WebSocket.`, { code: 'claim_queued' });
             }
-            return body.intent?.id ?? body.id ?? body.intentId ?? createIntentId();
+            return body.claim?.id ?? body.id ?? body.claimId ?? createClaimId();
         };
         const releaseClaim = (params) => requestJson(claimPath(isClaimHandle(params) ? params.target.id : params.id), { method: 'DELETE' }).then(() => undefined);
         async function claimImpl(params) {
@@ -559,23 +583,23 @@ export function createProtocolClient(options) {
                 [Symbol.asyncDispose]: release,
             };
         }
-        const intentsForEntity = async (params) => requestJson(`/v1/intents?model=${encodeURIComponent(name)}&id=${encodeURIComponent(params.id)}${params.field ? `&field=${encodeURIComponent(params.field)}` : ''}`, { method: 'GET' });
+        const claimsForEntity = async (params) => requestJson(`/v1/claims?model=${encodeURIComponent(name)}&id=${encodeURIComponent(params.id)}${params.field ? `&field=${encodeURIComponent(params.field)}` : ''}`, { method: 'GET' });
         const claim = Object.assign(claimImpl, {
             release: releaseClaim,
             state: async (params) => {
-                const res = await intentsForEntity(params);
-                return res.intents?.[0] ?? null;
+                const res = await claimsForEntity(params);
+                return res.claims?.[0] ?? null;
             },
             queue: async (params) => {
-                const res = await intentsForEntity(params);
+                const res = await claimsForEntity(params);
                 return { object: 'list', data: res.queue ?? [] };
             },
             reorder: async (params) => {
                 await requestJson(`${claimPath(params.id)}/reorder`, {
                     method: 'POST',
-                    // The reorder route's payload is `{ heldBy, intentId }[]` — Intent's id
-                    // IS the intentId.
-                    body: JSON.stringify({ order: params.order.map((i) => ({ heldBy: i.heldBy, intentId: i.id })) }),
+                    // The reorder route's payload is `{ heldBy, claimId }[]` — Claim's id
+                    // IS the claimId.
+                    body: JSON.stringify({ order: params.order.map((i) => ({ heldBy: i.heldBy, claimId: i.id })) }),
                 });
             },
         });
@@ -584,11 +608,11 @@ export function createProtocolClient(options) {
             if (!claimInput)
                 return run(input);
             if (isClaimHandle(claimInput)) {
-                return run({ ...input, intent: { id: claimInput.claimId }, claim: undefined });
+                return run({ ...input, claimRef: { id: claimInput.claimId }, claim: undefined });
             }
             const claimId = await acquireClaim({ id, ...claimInput });
             try {
-                return await run({ ...input, intent: { id: claimId }, claim: undefined });
+                return await run({ ...input, claimRef: { id: claimId }, claim: undefined });
             }
             finally {
                 await releaseClaim({ id }).catch(() => { });
@@ -624,12 +648,12 @@ export function createProtocolClient(options) {
         };
     }
     return {
-        async ready() { },
+        ready,
         async waitForFlush() { },
         async dispose() { },
         async purge() { },
         capabilities,
-        intents,
+        claims,
         commits,
         model,
         async getAuthToken() {
@@ -639,10 +663,10 @@ export function createProtocolClient(options) {
         },
     };
 }
-function normalizeIntentId(intent) {
-    if (typeof intent === 'string')
-        return intent;
-    return intent?.id;
+function normalizeClaimId(claim) {
+    if (typeof claim === 'string')
+        return claim;
+    return claim?.id;
 }
 function parseBody(bodyText) {
     if (bodyText.length === 0)

package/dist/client/auth.d.ts

@@ -45,12 +45,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

@@ -30,13 +30,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}`;

package/dist/client/createModelProxy.d.ts

@@ -21,7 +21,7 @@ import type { SyncClient } from '../SyncClient.js';
 import type { HydrationCoordinator } from '../sync/HydrationCoordinator.js';
 import type { LoadWhere } from '../query/types.js';
 import { ModelScope } from '../types/index.js';
-import type { Duration, Intent, IntentWaitOptions, Snapshot, TargetRange } from '../types/streams.js';
+import type { Duration, Claim, ClaimHandle, ClaimWaitOptions, Snapshot, TargetRange } from '../types/streams.js';
 export interface ModelClientMeta {
     readonly key: string;
     readonly typename: string;
@@ -73,21 +73,8 @@ export interface ModelLoadOptions<T> {
 /** 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'>;
-export interface IntentLeaseHandle {
-    readonly id: string;
-    /**
-     * True when the grant came AFTER waiting in the server's FIFO line
-     * (`intent_granted`) — the authoritative "the row may have changed
-     * underneath us" signal. The local `observe()` snapshot can't stand in
-     * for this: intent fan-out is entity-scoped, so org-wide subscriptions
-     * (the default hosted client) never see peers' claims at all.
-     */
-    readonly waited?: boolean;
-    release(): Promise<void>;
-    revoke(): void;
-}
 export interface ModelCollaboration<T> {
-    createIntent(options: {
+    createClaim(options: {
         target: {
             model: string;
             id: string;
@@ -106,11 +93,11 @@ export interface ModelCollaboration<T> {
         queue?: boolean;
         /** Reject (don't wait) if the queue is already this deep when we join. */
         maxQueueDepth?: number;
-    }): Promise<IntentLeaseHandle>;
+    }): Promise<ClaimHandle>;
     createSnapshot(modelKey: string, id: string): Snapshot;
     /**
      * Current coordination state on a target — who (if anyone) holds it.
-     * Synchronous reactive snapshot read off the presence/intent stream;
+     * Synchronous reactive snapshot read off the presence/claim stream;
      * `null` when the target is free. The wiring site computes it because
      * only it knows the local participant id (needed to distinguish "I
      * hold it" from "someone else holds it").
@@ -118,15 +105,15 @@ export interface ModelCollaboration<T> {
     observe(target: {
         model: string;
         id: string;
-    }): Intent | null;
+    }): Claim | null;
     /**
-     * The reactive wait queue on a target — the FIFO line of queued intents
-     * behind the holder. Synchronous snapshot off the synced intent stream.
+     * The reactive wait queue on a target — the FIFO line of queued claims
+     * behind the holder. Synchronous snapshot off the synced claim stream.
      */
     queue(target: {
         model: string;
         id: string;
-    }): readonly Intent[];
+    }): readonly Claim[];
     /**
      * Re-rank the wait queue on a target (privileged — server-gated). `order` is
      * the desired front-of-line ordering, taken from `queue(target)`.
@@ -134,21 +121,46 @@ export interface ModelCollaboration<T> {
     reorder(target: {
         model: string;
         id: string;
-    }, order: readonly Intent[]): void;
+    }, order: readonly Claim[]): void;
     /**
-     * Resolve once no participant holds an active intent on the target.
-     * The contender's "wait until it's free" — delegates to the intent
+     * Resolve once no participant holds an active claim on the target.
+     * The contender's "wait until it's free" — delegates to the claim
      * stream's `waitFor`.
      */
     waitFor(target: {
         model: string;
         id: string;
-    }, options?: IntentWaitOptions): Promise<void>;
+    }, options?: ClaimWaitOptions): Promise<void>;
     /**
      * The local participant's id. Used to distinguish "I already hold this"
      * 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>;
 }
 export interface ClaimTargetOptions<T = Record<string, unknown>> {
     /** Phase shown to observers while held. Defaults to `'editing'`. */
@@ -191,7 +203,7 @@ export interface ClaimLookupParams<T = Record<string, unknown>> {
     readonly field?: string;
 }
 export interface ClaimReorderParams<T = Record<string, unknown>> extends ClaimLookupParams<T> {
-    readonly order: readonly Intent[];
+    readonly order: readonly Claim[];
 }
 /**
  * A claim handle: the held entity data plus an explicit release hook, so
@@ -217,32 +229,7 @@ export interface ClaimReorderParams<T = Record<string, unknown>> extends ClaimLo
  * `ablo.<model>.update({ id, data, claim })` verb — the handle carries the
  * lease id and snapshot watermark for attribution + stale protection.
  */
-export interface ClaimHandle<T = Record<string, unknown>> extends AsyncDisposable {
-    readonly object: 'claim';
-    readonly claimId: string;
-    /**
-     * Sync watermark of the held snapshot (`data` was read at this stamp).
-     * Writes that carry the handle — `update({ id, data, claim })` or
-     * `commits.create({ claim, ... })` — use it as the `readAt` stale guard,
-     * so a concurrent commit between snapshot and write is rejected instead
-     * of clobbered. Optional for wire/duck-type compat with externally
-     * constructed handles.
-     */
-    readonly readAt?: number;
-    readonly target: {
-        readonly model: string;
-        readonly id: string;
-        readonly field?: string;
-        readonly path?: string;
-        readonly range?: TargetRange;
-        readonly meta?: Record<string, unknown>;
-    };
-    readonly action: string;
-    readonly description?: string;
-    readonly data: T;
-    release(): Promise<void>;
-    revoke(): void;
-}
+export type { ClaimHandle };
 export type ClaimOptions<T = Record<string, unknown>> = ClaimTargetOptions<T>;
 /**
  * The coordination surface for a model, exposed as a callable namespace.
@@ -273,14 +260,14 @@ export interface ClaimApi<T> {
      * Current holder for a row, or `null` when free. Use this for UI badges and
      * preflight checks, not for the normal write path.
      */
-    state(params: ClaimLookupParams<T>): Intent | null;
+    state(params: ClaimLookupParams<T>): Claim | null;
     /**
      * FIFO wait line behind the current holder. Advanced: useful for operator
      * UIs and schedulers.
      */
     queue(params: ClaimLookupParams<T>): {
         readonly object: 'list';
-        readonly data: readonly Intent[];
+        readonly data: readonly Claim[];
     };
     /**
      * Re-rank the wait line. Advanced and permission-gated.