@abloatai/ablo 0.5.1 → 0.7.0

package/dist/client/createModelProxy.js

@@ -1,26 +1,26 @@
 /**
- * Per-model resource factory.
+ * Per-model client factory.
  *
- * Mirrors Anthropic SDK's `resources/messages.ts` / `resources/models.ts`
- * pattern: each resource has its own file, the client just instantiates
+ * Mirrors Anthropic SDK's per-endpoint module pattern: each model client
+ * has its own file, and the root client just instantiates
  * one per model. Extracted from `Ablo.ts` so the proxy logic is
  * testable in isolation and the constructor doesn't carry it.
  *
  * Each schema model gets one `ModelOperations<T, CreateInput>` —
  * exposes `retrieve`, `list`, `count`, `create`, `update`, `delete`,
- * `intent` (the coordination handle), `subscribe`, and `load`. The
- * factory returns a plain object; the client assembles the
+ * `claim`, `claimState`, `queue`, `release`, `subscribe`, and `load`.
+ * The factory returns a plain object; the client assembles the
  * `ablo.<model>` lookup table from these.
  */
 import { autorun } from 'mobx';
-import { AbloStaleContextError, AbloValidationError } from '../errors.js';
+import { AbloClaimedError, AbloValidationError } from '../errors.js';
 import { Model, modelAsRow } from '../Model.js';
 import { ModelScope } from '../types/index.js';
-const modelResourceMeta = new WeakMap();
-export function getModelResourceMeta(resource) {
-    if (typeof resource !== 'object' || resource === null)
+const modelClientMeta = new WeakMap();
+export function getModelClientMeta(modelClient) {
+    if (typeof modelClient !== 'object' || modelClient === null)
         return undefined;
-    return modelResourceMeta.get(resource);
+    return modelClientMeta.get(modelClient);
 }
 export function createModelProxy(schemaKey, registeredModelName, objectPool, syncClient, registry, hydration, collaboration) {
     const ModelClass = registry.getModelByName(registeredModelName);
@@ -42,12 +42,99 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         await syncClient.syncNow();
         await syncClient.waitForConfirmation(model.getModelName(), model.id);
     };
+    // Claims this proxy currently holds, keyed by entity id. Lets the flat
+    // `release(id)` and `update(id)` find the lease + snapshot a `claim(id)`
+    // took — no per-call handle. Released on dispose, explicit release, or TTL.
+    const activeClaims = new Map();
+    const releaseClaim = async (id) => {
+        const held = activeClaims.get(id);
+        if (!held)
+            return;
+        activeClaims.delete(id);
+        await held.lease.release();
+    };
+    const takeClaim = async (id, options) => {
+        if (!collaboration) {
+            throw new AbloValidationError(`Model "${schemaKey}" cannot claim a row without collaboration wiring.`, { code: 'model_claim_not_configured' });
+        }
+        // Is someone ELSE already on this target? Read the local coordination
+        // snapshot up front — it decides whether we'll need to re-read after the
+        // claim (a free / already-mine target can't have changed under us).
+        const held = collaboration.observe({ model: schemaKey, id });
+        const contended = !!held && held.heldBy !== collaboration.selfParticipantId;
+        const failFast = options?.wait === false;
+        // Fail-fast (`wait: false`): if another participant already holds it,
+        // reject now instead of queuing. Best-effort at the client (a racing
+        // claim not yet synced into our snapshot slips through here) — the
+        // commit-time intent guard is the authoritative backstop that rejects
+        // the loser's first write. For work-distribution dedup that's exactly
+        // right: don't wait (that would double-process), skip.
+        if (failFast && contended) {
+            throw new AbloClaimedError(`${registeredModelName}/${id} is held by ${held?.heldBy ?? 'another participant'}.`, { code: 'entity_claimed' });
+        }
+        // Ensure the row exists locally before claiming.
+        let model = objectPool.get(id);
+        if (!model) {
+            await load({ where: { id } });
+            model = objectPool.get(id);
+        }
+        if (!model) {
+            throw new AbloValidationError(`Entity not found: ${registeredModelName}/${id}`, { code: 'entity_not_found' });
+        }
+        // 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
+        // orders contenders). Fail-fast skips the queue: we already rejected an
+        // observed conflict above, so this just records our lease.
+        const lease = await collaboration.createIntent({
+            target: {
+                model: schemaKey,
+                id,
+                ...(options?.field ? { field: options.field } : {}),
+            },
+            action: options?.action ?? 'editing',
+            ttl: options?.ttl,
+            queue: !failFast,
+            maxQueueDepth: options?.maxQueueDepth,
+        });
+        // Only when we actually waited behind another holder can the row have
+        // changed underneath us — re-read so the claimed snapshot reflects what
+        // they committed before releasing.
+        if (contended && !failFast) {
+            await load({ where: { id } });
+            model = objectPool.get(id) ?? model;
+        }
+        const snapshot = collaboration.createSnapshot(schemaKey, id);
+        activeClaims.set(id, { lease, snapshot });
+        const row = modelAsRow(model);
+        // `await using` calls this on scope exit; releases the claim.
+        Object.defineProperty(row, Symbol.asyncDispose, {
+            value: () => releaseClaim(id),
+            enumerable: false,
+            configurable: true,
+        });
+        return row;
+    };
+    function claim(id, a, b) {
+        if (typeof a === 'function') {
+            return (async () => {
+                const row = await takeClaim(id, b);
+                try {
+                    return await a(row);
+                }
+                finally {
+                    await releaseClaim(id);
+                }
+            })();
+        }
+        return takeClaim(id, a);
+    }
     const operations = {
         retrieve(id) {
             return objectPool.get(id);
         },
         list(options) {
-            const all = objectPool.getByType(ModelClass, (options?.scope ?? ModelScope.live));
+            const all = objectPool.getByType(ModelClass, (options?.state ?? ModelScope.live));
             let result = all;
             if (options?.where) {
                 const where = options.where;
@@ -99,9 +186,21 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             const model = objectPool.get(id);
             if (!model)
                 throw new AbloValidationError(`Entity not found: ${registeredModelName}/${id}`, { code: 'entity_not_found' });
+            // If we hold a claim on this row, guard the write with its snapshot
+            // watermark + lease so it's stale-rejected and attributed to the claim.
+            const claimed = activeClaims.get(id);
+            const effective = claimed
+                ? {
+                    wait: 'confirmed',
+                    readAt: claimed.snapshot.stamp,
+                    onStale: 'reject',
+                    intent: claimed.lease,
+                    ...options,
+                }
+                : options;
             model.updateFromData(data);
-            syncClient.update(model, options);
-            await waitForMutation(model, options);
+            syncClient.update(model, effective);
+            await waitForMutation(model, effective);
             return modelAsRow(model);
         },
         async delete(id, options) {
@@ -111,122 +210,23 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             syncClient.delete(model, options);
             await waitForMutation(model, options);
         },
-        intent(id) {
-            const target = { resource: schemaKey, id };
-            let acquired = null;
-            let snapshot = null;
-            let released = false;
-            let acquireWait;
-            // Public `cancel()` — drop the claim without committing. Calls the
-            // lower-level lease handle's `revoke()` (a different API; leave it).
-            const cancel = () => {
-                if (released)
-                    return;
-                released = true;
-                if (snapshot)
-                    snapshot.signal.removeEventListener('abort', cancel);
-                acquired?.revoke();
-            };
-            // Public `finish()` — give the claim back after committing. Calls the
-            // lower-level lease handle's `release()` (a different API; leave it).
-            const finish = async () => {
-                if (released)
-                    return;
-                released = true;
-                if (snapshot)
-                    snapshot.signal.removeEventListener('abort', cancel);
-                await acquired?.release();
-            };
-            const whenFree = async (options) => {
-                if (!collaboration)
-                    return;
-                await collaboration.waitFor(target, options);
-            };
-            const claim = async (options) => {
-                if (!collaboration) {
-                    throw new AbloValidationError(`Model "${schemaKey}" cannot claim an intent without collaboration wiring.`, { code: 'model_intent_not_configured' });
-                }
-                if (acquired)
-                    return;
-                acquireWait = options?.wait;
-                // Load the row so update() has a snapshot to guard against.
-                let model = objectPool.get(id);
-                if (!model) {
-                    await load({ where: { id } });
-                    model = objectPool.get(id);
-                }
-                if (!model) {
-                    throw new AbloValidationError(`Entity not found: ${registeredModelName}/${id}`, { code: 'entity_not_found' });
-                }
-                const snap = collaboration.createSnapshot(schemaKey, id);
-                snap.signal.addEventListener('abort', cancel, { once: true });
-                snapshot = snap;
-                released = false;
-                acquired = await collaboration.createIntent({
-                    target: {
-                        resource: schemaKey,
-                        id,
-                        ...(options?.field ? { field: options.field } : {}),
-                    },
-                    action: options?.action ?? 'editing',
-                    ttl: options?.ttl,
-                });
-            };
-            const claimOrWait = async (options) => {
-                if (!collaboration) {
-                    throw new AbloValidationError(`Model "${schemaKey}" cannot claim an intent without collaboration wiring.`, { code: 'model_intent_not_configured' });
-                }
-                const held = collaboration.observe(target);
-                // A foreign holder: wait for them to finish, then re-read before
-                // claiming. Our own claim (or a free target) goes straight to claim.
-                if (held && held.heldBy !== collaboration.selfParticipantId) {
-                    await whenFree();
-                    await load({ where: { id } });
-                }
-                await claim(options);
-            };
-            const handle = {
-                id,
-                get current() {
-                    return collaboration?.observe(target) ?? null;
-                },
-                get status() {
-                    return collaboration?.observe(target)?.status ?? 'idle';
-                },
-                claim,
-                claimOrWait,
-                async update(data, updateOptions) {
-                    if (!acquired || !snapshot) {
-                        throw new AbloValidationError(`Call claim() before update() on ablo.${schemaKey}.intent(${id}).`, { code: 'intent_not_acquired' });
-                    }
-                    if (snapshot.signal.aborted) {
-                        throw new AbloStaleContextError(`Intent context is stale for ${schemaKey}/${id}. Re-read the row and retry.`, {
-                            code: 'edit_context_stale',
-                            readAt: snapshot.stamp,
-                            cause: snapshot.signal.reason,
-                        });
-                    }
-                    try {
-                        return await operations.update(id, data, {
-                            wait: acquireWait ?? 'confirmed',
-                            readAt: snapshot.stamp,
-                            onStale: 'reject',
-                            ...updateOptions,
-                            intent: acquired,
-                        });
-                    }
-                    finally {
-                        await finish();
-                    }
-                },
-                finish,
-                whenFree,
-                cancel,
-                [Symbol.asyncDispose]: finish,
+        claim,
+        claimState(id) {
+            return collaboration?.observe({ model: schemaKey, id }) ?? null;
+        },
+        queue(id) {
+            return {
+                object: 'list',
+                data: collaboration?.queue({ model: schemaKey, id }) ?? [],
             };
-            return handle;
         },
-        subscribe(callback, options) {
+        reorder(id, order) {
+            collaboration?.reorder({ model: schemaKey, id }, order);
+        },
+        release(id) {
+            return releaseClaim(id);
+        },
+        onChange(callback, options) {
             return autorun(() => {
                 const entities = this.list(options);
                 callback(entities);
@@ -234,7 +234,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         },
         load,
     };
-    modelResourceMeta.set(operations, {
+    modelClientMeta.set(operations, {
         key: schemaKey,
         typename: registeredModelName,
     });

package/dist/client/index.d.ts

@@ -15,22 +15,21 @@
  *   apiKey: process.env.ABLO_API_KEY,
  * });
  *
- * const tasks = ablo.tasks.list({ where: { status: 'todo' } });
- * await ablo.tasks.create({ title: 'New task' });
+ * const reports = ablo.weatherReports.list({ where: { status: 'pending' } });
+ * await ablo.weatherReports.create({ location: 'Stockholm', status: 'pending' });
  * ```
  *
- * For headless agents (workers, bots), pass `kind: 'agent'` plus a
- * restricted (`rk_`) API key as `capabilityToken`:
+ * For headless agents (workers, bots), pass the same schema and an API key
+ * scoped for that server runtime:
  *
  * ```ts
  * const bot = Ablo({
  *   schema,
  *   apiKey: process.env.ABLO_API_KEY,
- *   kind: 'agent',
  * });
  * ```
  */
-export { Ablo, computeFKDepthPriority, type AbloOptions, type InternalAbloOptions, type BusyOptions, type BusyPolicy, type IntentWaitOptions, type ModelCountOptions, type ModelListOptions, type ModelListScope, type ModelLoadOptions, type ModelOperations, type ResourceReadOptions, } from './Ablo.js';
+export { Ablo, computeFKDepthPriority, type AbloOptions, type InternalAbloOptions, type ClaimedOptions, type IfClaimedPolicy, type IntentWaitOptions, type ModelCountOptions, type ModelListOptions, type ModelListScope, type ModelLoadOptions, type ModelOperations, type ModelReadOptions, } from './Ablo.js';
 export type { AbloPersistence } from './persistence.js';
-export type { AbloApi, AbloApiClientOptions, AbloApiIntents, Agent, AgentIntentInput, AgentIntentOptions, AgentOptions, AgentResourceClient, AgentResourceReadOptions, AgentResourceMutationOptions, AgentRunContext, AgentRunDone, AgentRunFailed, AgentRunCancelled, AgentRunOptions, AgentRunResult, AgentRunStatus, Capability, CapabilityCreateOptions, CapabilityParticipantKind, CapabilityRecord, CapabilityResource, CapabilityRevocation, CapabilityScope, Task, TaskCloseOptions, TaskCloseResult, TaskCreateOptions, TaskResource, } from './ApiClient.js';
+export type { AbloApi, AbloApiClientOptions, AbloApiIntents, Agent, AgentIntentInput, AgentIntentOptions, AgentOptions, AgentModelClient, AgentModelReadOptions, AgentModelMutationOptions, AgentRunContext, AgentRunDone, AgentRunFailed, AgentRunCancelled, AgentRunOptions, AgentRunResult, AgentRunStatus, Capability, CapabilityCreateOptions, CapabilityParticipantKind, CapabilityRecord, CapabilityResource, CapabilityRevocation, CapabilityScope, Task, TaskCloseOptions, TaskCloseResult, TaskCreateOptions, TaskResource, } from './ApiClient.js';
 export type { EngineParticipant, JoinedParticipant, ParticipantJoinOptions, ParticipantManager, ParticipantScope, ParticipantStatus, ScopedIntents, ScopedPresence, } from '../sync/participants.js';

package/dist/client/index.js

@@ -15,18 +15,17 @@
  *   apiKey: process.env.ABLO_API_KEY,
  * });
  *
- * const tasks = ablo.tasks.list({ where: { status: 'todo' } });
- * await ablo.tasks.create({ title: 'New task' });
+ * const reports = ablo.weatherReports.list({ where: { status: 'pending' } });
+ * await ablo.weatherReports.create({ location: 'Stockholm', status: 'pending' });
  * ```
  *
- * For headless agents (workers, bots), pass `kind: 'agent'` plus a
- * restricted (`rk_`) API key as `capabilityToken`:
+ * For headless agents (workers, bots), pass the same schema and an API key
+ * scoped for that server runtime:
  *
  * ```ts
  * const bot = Ablo({
  *   schema,
  *   apiKey: process.env.ABLO_API_KEY,
- *   kind: 'agent',
  * });
  * ```
  */

package/dist/client/validateAbloOptions.js

@@ -15,11 +15,11 @@ export function validateAbloOptions(input) {
     const kind = options.kind ?? 'user';
     if (!url) {
         return new Error('Ablo: `url` is required. Pass the sync server URL, e.g. ' +
-            `Ablo({ baseURL: 'wss://sync.ablo.dev', schema, user })`);
+            `Ablo({ baseURL: 'wss://sync.abloatai.com', schema, user })`);
     }
-    // Schema is optional for the resource-first API:
-    //   Ablo({ apiKey }).resource('clauses').retrieve(...)
-    // Passing a schema only enables typed model sugar (`ablo.tasks.update(...)`).
+    // Schema is optional for the model-first API:
+    //   Ablo({ apiKey }).model('clauses').retrieve(...)
+    // Passing a schema only enables typed model sugar (`ablo.weatherReports.update(...)`).
     if (!configuredApiKey &&
         !configuredAuthToken &&
         !options.capabilityToken &&
@@ -37,7 +37,7 @@ export function validateAbloOptions(input) {
     if (!configuredApiKey && !configuredAuthToken && kind === 'agent' && !options.capabilityToken) {
         return new Error('Ablo: provide either `apiKey` (hosted cloud — SDK exchanges internally) ' +
             'or `capabilityToken` (self-hosted — your auth layer mints + hands in). ' +
-            'See https://ablo.dev/docs/api-keys for the full pattern.');
+            'See https://abloatai.com/docs/api-keys for the full pattern.');
     }
     return null;
 }

package/dist/coordination/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `@abloatai/ablo/coordination` — the canonical wire schema for the three
+ * coordination layers (presence, pessimistic claims, optimistic stale-context).
+ * See `./schema.ts` for the model and the per-layer schemas.
+ */
+export * from './schema.js';

package/dist/coordination/index.js

@@ -0,0 +1,6 @@
+/**
+ * `@abloatai/ablo/coordination` — the canonical wire schema for the three
+ * coordination layers (presence, pessimistic claims, optimistic stale-context).
+ * See `./schema.ts` for the model and the per-layer schemas.
+ */
+export * from './schema.js';