@abloatai/ablo 0.5.1 → 0.6.0

package/dist/client/Ablo.js

@@ -10,13 +10,13 @@
  *
  *   const sync = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
  *
- *   const tasks = sync.tasks.list({ where: { status: 'todo' } });
- *   await sync.tasks.create({ title: 'Fix bug' });
- *   await sync.tasks.update(taskId, { status: 'done' });
- *   await sync.tasks.delete(taskId);
+ *   const reports = sync.reports.list({ where: { status: 'todo' } });
+ *   await sync.reports.create({ title: 'Fix bug' });
+ *   await sync.reports.update(reportId, { status: 'ready' });
+ *   await sync.reports.delete(reportId);
  */
 import { z } from 'zod';
-import { AbloBusyError, AbloError, AbloConnectionError, AbloValidationError, translateHttpError } from '../errors.js';
+import { AbloClaimedError, AbloError, AbloConnectionError, AbloValidationError, translateHttpError } from '../errors.js';
 import { LoadStrategy, PropertyType } from '../types/index.js';
 import { initSyncEngine } from '../context.js';
 import { noopObservability, browserOnlineStatus, defaultSessionErrorDetector, noopAnalytics, } from '../SyncEngineContext.js';
@@ -28,6 +28,7 @@ import { Model } from '../Model.js';
 import { BaseSyncedStore } from '../BaseSyncedStore.js';
 import { createPresenceStream } from '../sync/createPresenceStream.js';
 import { createIntentStream } from '../sync/createIntentStream.js';
+import { awaitIntentGrant } from '../sync/awaitIntentGrant.js';
 import { createSnapshot } from '../sync/createSnapshot.js';
 import { createParticipantManager } from '../sync/participants.js';
 import { createProtocolClient, } from './ApiClient.js';
@@ -581,7 +582,8 @@ function createDefaultMutationExecutor(getWs) {
                 ? crypto.randomUUID()
                 : `tx_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`);
         try {
-            return await ws.sendCommit(operations, clientTxId, options?.timeout, options?.causedByTaskId);
+            return await ws.sendCommit(operations, clientTxId, undefined, // use sendCommit's built-in 15s default; no per-call override
+            options?.causedByTaskId);
         }
         catch (err) {
             // Wrap transport-level failures as connection errors so the
@@ -965,7 +967,7 @@ export function Ablo(options) {
             ? crypto.randomUUID()
             : `tx_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
     }
-    function createResourceId() {
+    function createModelId() {
         return typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
             ? crypto.randomUUID()
             : `id_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
@@ -976,15 +978,15 @@ export function Ablo(options) {
         return intent?.id;
     }
     function normalizeCommitOperation(op, defaults) {
-        const resource = op.resource ?? op.target?.resource;
-        if (!resource) {
-            throw new AbloValidationError('Commit operation requires `resource` or `target.resource`.', { code: 'commit_operation_resource_required' });
+        const model = op.model ?? op.target?.model;
+        if (!model) {
+            throw new AbloValidationError('Commit operation requires `model` or `target.model`.', { code: 'commit_operation_model_required' });
         }
         const type = op.action.toUpperCase();
         const id = op.id ?? op.target?.id ?? '';
         return {
             type,
-            model: resource.toLowerCase(),
+            model: model.toLowerCase(),
             id,
             input: op.data ?? undefined,
             transactionId: op.transactionId ?? undefined,
@@ -1004,16 +1006,17 @@ export function Ablo(options) {
         }
         return inputOperations.map((op) => normalizeCommitOperation(op, commitOptions));
     }
-    function resourceIntentFromActive(intent) {
+    function modelClaimFromActive(intent) {
         return {
             id: intent.id,
             actor: intent.heldBy,
             participantKind: intent.participantKind,
             action: intent.reason,
             field: intent.target.field,
+            status: 'active',
             expiresAt: intent.expiresAt,
             target: {
-                resource: intent.target.type,
+                model: intent.target.type,
                 id: intent.target.id,
                 path: intent.target.path,
                 range: intent.target.range,
@@ -1022,9 +1025,29 @@ export function Ablo(options) {
             },
         };
     }
-    function targetMatchesResource(target, intent) {
-        if (target.resource &&
-            intent.target.type.toLowerCase() !== target.resource.toLowerCase()) {
+    function modelClaimFromQueued(intent) {
+        return {
+            id: intent.id,
+            actor: intent.heldBy,
+            participantKind: intent.participantKind,
+            action: intent.action,
+            field: intent.target.field,
+            status: 'queued',
+            position: intent.position,
+            expiresAt: intent.expiresAt,
+            target: {
+                model: intent.target.type,
+                id: intent.target.id,
+                path: intent.target.path,
+                range: intent.target.range,
+                field: intent.target.field,
+                meta: intent.target.meta,
+            },
+        };
+    }
+    function targetMatchesModel(target, intent) {
+        if (target.model &&
+            intent.target.type.toLowerCase() !== target.model.toLowerCase()) {
             return false;
         }
         if (target.id && intent.target.id !== target.id)
@@ -1033,21 +1056,29 @@ export function Ablo(options) {
             return false;
         return true;
     }
-    function listResourceIntents(target) {
+    function listModelClaims(target) {
         return intentStream.others
-            .filter((intent) => (target ? targetMatchesResource(target, intent) : true))
-            .map(resourceIntentFromActive);
+            .filter((intent) => (target ? targetMatchesModel(target, intent) : true))
+            .map(modelClaimFromActive);
     }
-    function busyError(target, intents, code) {
-        const label = [target.resource, target.id, target.field].filter(Boolean).join('/');
-        const holder = intents[0];
+    function listModelClaimQueue(target) {
+        if (!target?.model || !target.id)
+            return [];
+        return publicIntents
+            .queueFor({ type: target.model, id: target.id })
+            .filter((intent) => (target.field ? intent.target.field === target.field : true))
+            .map(modelClaimFromQueued);
+    }
+    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 AbloBusyError(`Resource is busy: ${label || 'target'}${suffix}.`, { code, intents });
+        return new AbloClaimedError(`Model row is claimed: ${label || 'target'}${suffix}.`, { code, claims });
     }
-    function waitForResourceIdle(target, options) {
-        if (listResourceIntents(target).length === 0)
+    function waitForModelUnclaimed(target, options) {
+        if (listModelClaims(target).length === 0)
             return Promise.resolve();
         return new Promise((resolve, reject) => {
             let settled = false;
@@ -1068,7 +1099,7 @@ export function Ablo(options) {
                 fn();
             };
             const check = () => {
-                if (listResourceIntents(target).length === 0) {
+                if (listModelClaims(target).length === 0) {
                     finish(resolve);
                 }
             };
@@ -1082,25 +1113,30 @@ export function Ablo(options) {
                 onAbort();
                 return;
             }
-            unsubscribe = intentStream.subscribe(check);
+            unsubscribe = intentStream.onChange(check);
             options?.signal?.addEventListener('abort', onAbort, { once: true });
             if (options?.timeout != null) {
                 timeoutId = setTimeout(() => {
-                    finish(() => reject(busyError(target, listResourceIntents(target), 'resource_busy_timeout')));
+                    finish(() => reject(claimedError(target, listModelClaims(target), 'model_claimed_timeout')));
                 }, options.timeout);
             }
         });
     }
-    async function applyBusyPolicy(target, options) {
-        const policy = options?.ifBusy ?? 'return';
+    async function applyClaimedPolicy(target, options) {
+        const policy = options?.ifClaimed ?? 'return';
         if (policy === 'return')
             return;
-        const current = listResourceIntents(target);
+        const current = listModelClaims(target);
         if (current.length === 0)
             return;
         if (policy === 'fail')
-            throw busyError(target, current, 'resource_busy');
-        await waitForResourceIdle(target, { timeout: options?.busyTimeout });
+            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 });
     }
     function wrapIntentHandle(claim) {
         const release = async () => {
@@ -1117,24 +1153,51 @@ export function Ablo(options) {
         async create(intentOptions) {
             await ready();
             const claim = intentStream.claim({
-                type: intentOptions.target.resource,
+                type: intentOptions.target.model,
                 id: intentOptions.target.id,
                 path: intentOptions.target.path,
                 range: intentOptions.target.range,
                 field: intentOptions.target.field,
                 meta: intentOptions.target.meta,
-            }, { reason: intentOptions.action, ttl: intentOptions.ttl });
+            }, {
+                reason: intentOptions.action,
+                ttl: intentOptions.ttl,
+                queue: intentOptions.queue,
+            });
+            // With `queue`, the claim is only really *ours* once the server says
+            // so (`intent_acquired` if the target was free, `intent_granted` once
+            // we reach the head of the FIFO line). Block here on that grant so
+            // callers — chiefly `ablo.<model>.claim` — get a handle that already
+            // holds the lease, never a half-claimed one racing the queue.
+            if (intentOptions.queue) {
+                const ws = store.getSyncWebSocket();
+                if (ws) {
+                    try {
+                        await awaitIntentGrant(ws, claim.id, {
+                            timeoutMs: intentOptions.waitTimeoutMs,
+                            maxQueueDepth: intentOptions.maxQueueDepth,
+                        });
+                    }
+                    catch (err) {
+                        // Gave up waiting (queue too deep, timed out, or lost) — abandon
+                        // the queued intent so we don't leave a phantom entry in the
+                        // line that would block or mislead other claimers.
+                        claim.revoke();
+                        throw err;
+                    }
+                }
+            }
             return wrapIntentHandle(claim);
         },
         list(target) {
-            return listResourceIntents(target);
+            return listModelClaims(target);
         },
         waitFor(target, options) {
-            return waitForResourceIdle(target, options);
+            return waitForModelUnclaimed(target, options);
         },
     });
     // Build the typed proxy — one property per model. Done after publicIntents
-    // exists so model resources can expose workflow helpers such as
+    // exists so model clients can expose workflow helpers such as
     // `ablo.files.edit(...)` without importing protocol wiring.
     const modelProxies = {};
     for (const [schemaKey, modelDef] of Object.entries(schema.models)) {
@@ -1147,13 +1210,14 @@ export function Ablo(options) {
                 getLastSyncId: () => store.getSyncWebSocket()?.getLastSyncId() ?? store.lastSyncId ?? 0,
                 entities: { [modelKey]: id },
             }),
+            queue: (target) => publicIntents.queueFor({ type: target.model, id: target.id }),
             observe: (target) => {
                 // The live intent stream only tracks *open* (active) claims;
                 // terminal states (committed / expired / canceled) drop out of
                 // the list entirely — exactly the ephemeral coordination model.
                 // So a present entry is, by definition, `status: 'active'`.
                 const held = publicIntents.list({
-                    resource: target.resource,
+                    model: target.model,
                     id: target.id,
                 })[0];
                 if (!held)
@@ -1163,7 +1227,7 @@ export function Ablo(options) {
                     id: held.id,
                     status: 'active',
                     target: {
-                        type: held.target.resource,
+                        type: held.target.model,
                         id: held.target.id,
                         ...(held.target.path ? { path: held.target.path } : {}),
                         ...(held.target.range ? { range: held.target.range } : {}),
@@ -1176,7 +1240,7 @@ export function Ablo(options) {
                     expiresAt: held.expiresAt,
                 };
             },
-            waitFor: (target, waitOptions) => publicIntents.waitFor({ resource: target.resource, id: target.id }, waitOptions),
+            waitFor: (target, waitOptions) => publicIntents.waitFor({ model: target.model, id: target.id }, waitOptions),
             selfParticipantId: participantId,
         });
     }
@@ -1208,8 +1272,8 @@ export function Ablo(options) {
             return { id: clientTxId, status: 'confirmed', lastSyncId };
         },
     };
-    async function retrieveResource(resourceName, id, options) {
-        await applyBusyPolicy({ resource: resourceName, id }, options);
+    async function retrieveModel(modelName, id, options) {
+        await applyClaimedPolicy({ model: modelName, id }, options);
         await ready();
         const res = await fetchImpl(`${bootstrapHelper.baseUrl}/sync/query`, {
             method: 'POST',
@@ -1218,7 +1282,7 @@ export function Ablo(options) {
             body: JSON.stringify({
                 queries: [
                     {
-                        model: resourceName,
+                        model: modelName,
                         where: [['id', '=', id]],
                         limit: 1,
                     },
@@ -1236,14 +1300,14 @@ export function Ablo(options) {
             }
         }
         if (!res.ok) {
-            throw translateHttpError(res.status, body || `Resource retrieve failed: ${res.status} ${res.statusText}`, res.headers.get('x-request-id') ?? undefined);
+            throw translateHttpError(res.status, body || `Model retrieve failed: ${res.status} ${res.statusText}`, res.headers.get('x-request-id') ?? undefined);
         }
         const parsed = body;
         const slot = parsed.results?.[0];
         const rows = Array.isArray(slot) ? slot : [];
         const data = rows[0];
         if (!data) {
-            throw new AbloValidationError(`Resource not found: ${resourceName}/${id}`, { code: 'resource_not_found' });
+            throw new AbloValidationError(`Model row not found: ${modelName}/${id}`, { code: 'model_not_found' });
         }
         const stamp = typeof parsed.lastSyncId === 'number'
             ? parsed.lastSyncId
@@ -1251,28 +1315,27 @@ export function Ablo(options) {
         return {
             data,
             stamp,
-            intents: listResourceIntents({ resource: resourceName, id }),
+            claims: listModelClaims({ model: modelName, id }),
         };
     }
-    function resource(name) {
+    function model(name) {
         return {
             retrieve(id, options) {
-                return retrieveResource(name, id, options);
+                return retrieveModel(name, id, options);
             },
             async create(data, mutationOptions) {
-                const id = mutationOptions?.id ?? createResourceId();
-                await applyBusyPolicy({ resource: name, id }, mutationOptions);
+                const id = mutationOptions?.id ?? createModelId();
+                await applyClaimedPolicy({ model: name, id }, mutationOptions);
                 return commits.create({
                     intent: mutationOptions?.intent,
                     idempotencyKey: mutationOptions?.idempotencyKey,
                     readAt: mutationOptions?.readAt,
                     onStale: mutationOptions?.onStale,
                     wait: mutationOptions?.wait,
-                    timeout: mutationOptions?.timeout,
                     operations: [
                         {
                             action: 'create',
-                            resource: name,
+                            model: name,
                             id,
                             data,
                         },
@@ -1280,18 +1343,17 @@ export function Ablo(options) {
                 });
             },
             async update(id, data, mutationOptions) {
-                await applyBusyPolicy({ resource: name, id }, mutationOptions);
+                await applyClaimedPolicy({ model: name, id }, mutationOptions);
                 return commits.create({
                     intent: mutationOptions?.intent,
                     idempotencyKey: mutationOptions?.idempotencyKey,
                     readAt: mutationOptions?.readAt,
                     onStale: mutationOptions?.onStale,
                     wait: mutationOptions?.wait,
-                    timeout: mutationOptions?.timeout,
                     operations: [
                         {
                             action: 'update',
-                            resource: name,
+                            model: name,
                             id,
                             data,
                         },
@@ -1299,18 +1361,17 @@ export function Ablo(options) {
                 });
             },
             async delete(id, mutationOptions) {
-                await applyBusyPolicy({ resource: name, id }, mutationOptions);
+                await applyClaimedPolicy({ model: name, id }, mutationOptions);
                 return commits.create({
                     intent: mutationOptions?.intent,
                     idempotencyKey: mutationOptions?.idempotencyKey,
                     readAt: mutationOptions?.readAt,
                     onStale: mutationOptions?.onStale,
                     wait: mutationOptions?.wait,
-                    timeout: mutationOptions?.timeout,
                     operations: [
                         {
                             action: 'delete',
-                            resource: name,
+                            model: name,
                             id,
                         },
                     ],
@@ -1387,7 +1448,7 @@ export function Ablo(options) {
         /** Intent livestream — same socket. Stable reference. */
         intents: publicIntents,
         commits,
-        resource,
+        model,
         /** Structured multiplayer participation — target-first, no
      *  sync-group strings in the common path. */
         participants: participantManager,

package/dist/client/ApiClient.d.ts

@@ -2,10 +2,10 @@
  * Stateless API client for `Ablo({ apiKey })`.
  *
  * This is the hosted-API product surface: no schema, no object pool, no
- * IndexedDB, no WebSocket. It maps the public Resource / Intent / Commit
+ * IndexedDB, no WebSocket. It maps the public Model / Claim / Commit
  * nouns directly to HTTP routes on sync-server.
  */
-import type { AbloOptions, CommitReceipt, CommitResource, IntentCreateOptions, IntentHandle, IntentWaitOptions, ResourceClient, ResourceIntent, ResourceMutationOptions, ResourceReadOptions, ResourceRead, ResourceTarget, Turn } from './Ablo.js';
+import type { AbloOptions, CommitReceipt, CommitResource, IntentCreateOptions, IntentHandle, IntentWaitOptions, ModelClient, ModelClaim, ModelMutationOptions, ModelReadOptions, ModelRead, ModelTarget, Turn } from './Ablo.js';
 import type { Duration } from '../utils/duration.js';
 export type AbloApiClientOptions = Omit<AbloOptions, 'schema'> & {
     readonly schema?: null | undefined;
@@ -13,8 +13,8 @@ export type AbloApiClientOptions = Omit<AbloOptions, 'schema'> & {
 };
 export interface AbloApiIntents {
     create(options: IntentCreateOptions): Promise<IntentHandle>;
-    list(target?: Partial<ResourceTarget>): Promise<readonly ResourceIntent[]>;
-    waitFor(target: Partial<ResourceTarget>, options?: IntentWaitOptions): Promise<void>;
+    list(target?: Partial<ModelTarget>): Promise<readonly ModelClaim[]>;
+    waitFor(target: Partial<ModelTarget>, options?: IntentWaitOptions): Promise<void>;
 }
 export type CapabilityParticipantKind = 'agent' | 'system';
 export interface CapabilityCreateBaseOptions {
@@ -157,28 +157,28 @@ export interface AgentIntentOptions {
     readonly action: string;
     readonly field?: string;
     readonly ttl?: Duration;
-    readonly target?: Partial<ResourceTarget>;
+    readonly target?: Partial<ModelTarget>;
 }
 export type AgentIntentInput = string | AgentIntentOptions;
-export interface AgentResourceReadOptions extends ResourceReadOptions {
+export interface AgentModelReadOptions extends ModelReadOptions {
 }
-export interface AgentResourceMutationOptions extends Omit<ResourceMutationOptions, 'intent'> {
+export interface AgentModelMutationOptions extends Omit<ModelMutationOptions, 'intent'> {
     readonly intent?: AgentIntentInput | {
         readonly id: string;
     } | null;
 }
-export interface AgentResourceClient<T = Record<string, unknown>> {
-    retrieve(id: string, options?: AgentResourceReadOptions): Promise<ResourceRead<T>>;
-    create(data: Record<string, unknown>, options?: AgentResourceMutationOptions & {
+export interface AgentModelClient<T = Record<string, unknown>> {
+    retrieve(id: string, options?: AgentModelReadOptions): Promise<ModelRead<T>>;
+    create(data: Record<string, unknown>, options?: AgentModelMutationOptions & {
         readonly id?: string | null;
     }): Promise<CommitReceipt>;
-    update(id: string, data: Record<string, unknown>, options?: AgentResourceMutationOptions): Promise<CommitReceipt>;
-    delete(id: string, options?: AgentResourceMutationOptions): Promise<CommitReceipt>;
+    update(id: string, data: Record<string, unknown>, options?: AgentModelMutationOptions): Promise<CommitReceipt>;
+    delete(id: string, options?: AgentModelMutationOptions): Promise<CommitReceipt>;
 }
 export interface AgentRunContext {
     readonly task: Task;
     readonly ablo: AbloApi;
-    resource<T = Record<string, unknown>>(name: string): AgentResourceClient<T>;
+    model<T = Record<string, unknown>>(name: string): AgentModelClient<T>;
 }
 export interface Agent {
     readonly id: string;
@@ -194,7 +194,7 @@ export interface AbloApi {
     readonly intents: AbloApiIntents;
     readonly commits: CommitResource;
     agent(id: string, options: AgentOptions): Agent;
-    resource<T = Record<string, unknown>>(name: string): ResourceClient<T>;
+    model<T = Record<string, unknown>>(name: string): ModelClient<T>;
     beginTurn(options: TaskCreateOptions): Promise<Turn>;
 }
 export declare function createProtocolClient(options: AbloApiClientOptions): AbloApi;