@abloatai/ablo 0.10.0 → 0.11.0

package/dist/client/ApiClient.d.ts

@@ -5,16 +5,17 @@
  * IndexedDB, no WebSocket. It maps the public Model / Claim / Commit
  * nouns directly to HTTP routes on sync-server.
  */
-import type { AbloOptions, CommitResource, IntentCreateOptions, IntentHandle, IntentWaitOptions, ModelClient, ModelClaim, ModelTarget } from './Ablo.js';
+import type { AbloOptions, CommitResource, ClaimCreateOptions, ClaimWaitOptions, ModelClient, ModelClaim, ModelTarget } from './Ablo.js';
+import type { ClaimHandle } from './createModelProxy.js';
 import type { Duration } from '../utils/duration.js';
 export type AbloApiClientOptions = Omit<AbloOptions, 'schema'> & {
     readonly schema?: null | undefined;
     readonly bootstrapBaseUrl?: string | undefined;
 };
-export interface AbloApiIntents {
-    create(options: IntentCreateOptions): Promise<IntentHandle>;
+export interface AbloApiClaims {
+    create(options: ClaimCreateOptions): Promise<ClaimHandle>;
     list(target?: Partial<ModelTarget>): Promise<readonly ModelClaim[]>;
-    waitFor(target: Partial<ModelTarget>, options?: IntentWaitOptions): Promise<void>;
+    waitFor(target: Partial<ModelTarget>, options?: ClaimWaitOptions): Promise<void>;
 }
 export type CapabilityParticipantKind = 'agent' | 'system';
 export interface CapabilityCreateBaseOptions {
@@ -121,7 +122,7 @@ export interface AbloApi {
     dispose(): Promise<void>;
     purge(): Promise<void>;
     readonly capabilities: CapabilityResource;
-    readonly intents: AbloApiIntents;
+    readonly claims: AbloApiClaims;
     readonly commits: CommitResource;
     model<T = Record<string, unknown>>(name: string): ModelClient<T>;
     /**

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, } 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,10 @@ export function createProtocolClient(options) {
     const authInput = { options, env };
     const configuredApiKey = resolveApiKey(authInput);
     const configuredAuthToken = resolveAuthToken(authInput);
+    const configuredDatabaseUrl = resolveDatabaseUrl(authInput);
     assertBrowserSafety({
         apiKey: configuredApiKey,
+        databaseUrl: configuredDatabaseUrl,
         dangerouslyAllowBrowser: options.dangerouslyAllowBrowser,
     });
     const fetchImpl = options.fetch ?? globalThis.fetch;
@@ -28,6 +31,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 +82,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 +108,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 +154,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 +167,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 +192,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 +235,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 +248,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 +265,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 +371,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 +414,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 +477,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 +496,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 +549,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 +580,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 +605,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 +645,12 @@ export function createProtocolClient(options) {
         };
     }
     return {
-        async ready() { },
+        ready,
         async waitForFlush() { },
         async dispose() { },
         async purge() { },
         capabilities,
-        intents,
+        claims,
         commits,
         model,
         async getAuthToken() {
@@ -639,10 +660,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/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,16 +121,16 @@ 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`.
@@ -191,7 +178,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 +204,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 +235,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.