@abloatai/ablo 0.10.0 → 0.11.0

package/dist/client/createModelProxy.js

@@ -15,7 +15,8 @@
  * client assembles the `ablo.<model>` lookup table from these.
  */
 import { autorun } from 'mobx';
-import { AbloClaimedError, AbloValidationError, toAbloError, } from '../errors.js';
+import { AbloClaimedError, AbloValidationError, formatClaimedErrorMessage, toAbloError, } from '../errors.js';
+import { descriptionFromMeta } from '../coordination/schema.js';
 import { Model, modelAsRow } from '../Model.js';
 import { assertWriteOptions } from './writeOptionsSchema.js';
 import { ModelScope } from '../types/index.js';
@@ -31,9 +32,9 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         throw new AbloValidationError(`Ablo: schema model "${schemaKey}" resolved to "${registeredModelName}", ` +
             'but no matching constructor was registered.', { code: 'model_not_registered' });
     }
-    // The coordination plane (claims/intents) must speak the SAME wire dialect
+    // The coordination plane (claims/claims) must speak the SAME wire dialect
     // as the commit plane: the lowercased TYPENAME (`task`), not the schema key
-    // (`tasks`). The server's commit-time intent guard probes the lease store
+    // (`tasks`). The server's commit-time claim guard probes the lease store
     // with the commit op's model name; a lease recorded under the schema key
     // never collides with it — which silently disarmed the guard for every
     // model whose schema key differs from its typename (i.e. nearly all of
@@ -85,6 +86,27 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             return options?.meta;
         return { ...(options.meta ?? {}), description: options.description };
     };
+    const claimContextFromClaim = (claim) => {
+        const description = claim.description ?? descriptionFromMeta(claim.target.meta);
+        return {
+            id: claim.id,
+            actor: claim.heldBy,
+            participantKind: claim.participantKind,
+            action: claim.action,
+            ...(description ? { description } : {}),
+            field: claim.target.field,
+            status: claim.status,
+            expiresAt: claim.expiresAt,
+            target: {
+                model: claim.target.type,
+                id: claim.target.id,
+                path: claim.target.path,
+                range: claim.target.range,
+                field: claim.target.field,
+                meta: claim.target.meta,
+            },
+        };
+    };
     const mutationOptions = (params) => {
         const { id: _id, data: _data, claim: _claim, ...rest } = params;
         // THE write-options schema — runtime twin of the compile-time params.
@@ -114,11 +136,17 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         // 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
+        // commit-time claim 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' });
+            const claim = held ? claimContextFromClaim(held) : undefined;
+            throw new AbloClaimedError(formatClaimedErrorMessage({
+                targetLabel: `${registeredModelName}/${id}`,
+                heldBy: held?.heldBy,
+                claim,
+                fallback: `${registeredModelName}/${id} is held by ${held?.heldBy ?? 'another participant'}.`,
+            }), { code: 'entity_claimed', claims: claim ? [claim] : undefined });
         }
         // Ensure the row exists locally before claiming.
         let model = objectPool.get(id);
@@ -134,7 +162,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         // 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({
+        const lease = await collaboration.createClaim({
             target: {
                 model: wireModel,
                 id,
@@ -151,9 +179,9 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         // 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. Two signals, either suffices:
-        //   - `lease.waited` — the server granted via `intent_granted`, i.e. we
+        //   - `lease.waited` — the server granted via `claim_granted`, i.e. we
         //     provably queued behind a holder. Authoritative; works even when
-        //     the local snapshot is blind (intent fan-out is entity-scoped, so
+        //     the local snapshot is blind (claim fan-out is entity-scoped, so
         //     org-wide-subscribed clients never observe peers' claims).
         //   - `contended` — the local snapshot saw a holder up front. Kept for
         //     the no-queue paths where no grant frame exists.
@@ -178,7 +206,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         const release = () => releaseClaim(id);
         return {
             object: 'claim',
-            claimId: lease.id,
+            claimId: lease.claimId,
             readAt: snapshot.stamp,
             target,
             action: options?.action ?? 'editing',
@@ -269,7 +297,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                 if (!collaboration) {
                     throw new AbloValidationError(`Model "${schemaKey}" cannot claim a row without collaboration wiring.`, { code: 'model_claim_not_configured' });
                 }
-                autoLease = await collaboration.createIntent({
+                autoLease = await collaboration.createClaim({
                     target: {
                         model: wireModel,
                         id,
@@ -299,8 +327,8 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             });
             const effective = {
                 ...opts,
-                ...(autoLease ? { intent: autoLease } : {}),
-                ...(isClaimHandle(claim) ? { intent: { id: claim.claimId } } : {}),
+                ...(autoLease ? { claim: autoLease } : {}),
+                ...(isClaimHandle(claim) ? { claim: { id: claim.claimId } } : {}),
             };
             try {
                 syncClient.add(model, effective);
@@ -336,7 +364,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                     wait: 'confirmed',
                     readAt: claimed.snapshot.stamp,
                     onStale: 'reject',
-                    intent: claimed.lease,
+                    claimRef: { id: claimed.lease.claimId },
                     ...opts,
                 }
                 : {
@@ -351,7 +379,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                         }
                         : {}),
                     ...opts,
-                    ...(handle ? { intent: { id: handle.claimId } } : {}),
+                    ...(handle ? { claim: { id: handle.claimId } } : {}),
                 };
             // Local user update: `applyChanges` keeps change tracking ON so
             // the edited fields land in `modifiedProperties` and actually get
@@ -386,7 +414,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                     wait: 'confirmed',
                     readAt: claimed.snapshot.stamp,
                     onStale: 'reject',
-                    intent: claimed.lease,
+                    claimRef: { id: claimed.lease.claimId },
                     ...opts,
                 }
                 : {
@@ -398,7 +426,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                         }
                         : {}),
                     ...opts,
-                    ...(handle ? { intent: { id: handle.claimId } } : {}),
+                    ...(handle ? { claim: { id: handle.claimId } } : {}),
                 };
             syncClient.delete(model, effective);
             await waitForMutation(model, effective);

package/dist/client/httpClient.d.ts

@@ -55,6 +55,8 @@ export interface HttpModelClient<T, C = T> {
 export type AbloHttpClient<S extends SchemaRecord> = {
     readonly [K in keyof S & string]: HttpModelClient<InferModel<Schema<S>, K>, InferCreate<Schema<S>, K>>;
 } & {
+    /** Register `databaseUrl` when configured. Also runs lazily before the first request. */
+    ready(): Promise<void>;
     readonly commits: CommitResource;
     dispose(): Promise<void>;
     /** Resolve the bearer credential this client authenticates with (see `AbloApi.getAuthToken`). */

package/dist/client/httpClient.js

@@ -26,7 +26,7 @@ import { createProtocolClient, } from './ApiClient.js';
 /**
  * Members of the underlying `AbloApi` that pass straight through the facade.
  * Deliberately EXCLUDES the resource names that collide with common schema model
- * names — `tasks`, `intents`, `capabilities`, `agent` — so `client.tasks` resolves
+ * names — `tasks`, `claims`, `capabilities`, `agent` — so `client.tasks` resolves
  * to the schema model `tasks`, not the protocol `TaskResource`. Only lifecycle +
  * the genuinely-protocol methods an agent uses pass through.
  */

package/dist/client/index.d.ts

@@ -29,8 +29,8 @@
  * });
  * ```
  */
-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 { Ablo, computeFKDepthPriority, type AbloOptions, type InternalAbloOptions, type ClaimedOptions, type IfClaimedPolicy, type ClaimWaitOptions, type ModelCountOptions, type ModelListOptions, type ModelListScope, type ModelLoadOptions, type ModelOperations, type ModelReadOptions, } from './Ablo.js';
 export { ABLO_DEFAULT_BASE_URL, ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_URL, normalizeAbloHostedBaseUrl, } from './auth.js';
 export type { AbloPersistence } from './persistence.js';
-export type { AbloApi, AbloApiClientOptions, AbloApiIntents, Capability, CapabilityCreateOptions, CapabilityParticipantKind, CapabilityRecord, CapabilityResource, CapabilityRevocation, CapabilityScope, } from './ApiClient.js';
-export type { EngineParticipant, JoinedParticipant, ParticipantJoinOptions, ParticipantManager, ParticipantScope, ParticipantStatus, ScopedIntents, ScopedPresence, } from '../sync/participants.js';
+export type { AbloApi, AbloApiClientOptions, AbloApiClaims, Capability, CapabilityCreateOptions, CapabilityParticipantKind, CapabilityRecord, CapabilityResource, CapabilityRevocation, CapabilityScope, } from './ApiClient.js';
+export type { EngineParticipant, JoinedParticipant, ParticipantJoinOptions, ParticipantManager, ParticipantScope, ParticipantStatus, ScopedClaims, ScopedPresence, } from '../sync/participants.js';

package/dist/client/writeOptionsSchema.d.ts

@@ -10,8 +10,8 @@
  * bottom so the two can never silently diverge.
  *
  * Validation-only by design: callers keep their ORIGINAL options object.
- * Zod's parse output strips unknown keys, and the `intent` slot legally
- * carries live handles (`IntentLeaseHandle` / claim leases) whose
+ * Zod's parse output strips unknown keys, and the `claim` slot legally
+ * carries live handles (`ClaimHandle` / claim leases) whose
  * `release`/`revoke` functions must survive — so we assert, never replace.
  */
 import { z } from 'zod';
@@ -25,8 +25,8 @@ export declare const writeOptionsSchema: z.ZodObject<{
     idempotencyKey: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     label: z.ZodOptional<z.ZodString>;
     wait: z.ZodOptional<z.ZodEnum<{
-        confirmed: "confirmed";
         queued: "queued";
+        confirmed: "confirmed";
     }>>;
     readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
@@ -35,7 +35,7 @@ export declare const writeOptionsSchema: z.ZodObject<{
         flag: "flag";
         merge: "merge";
     }>>>;
-    intent: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    claim: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
         id: z.ZodString;
     }, z.core.$loose>]>>>;
     causedByTaskId: z.ZodOptional<z.ZodNullable<z.ZodString>>;

package/dist/client/writeOptionsSchema.js

@@ -10,8 +10,8 @@
  * bottom so the two can never silently diverge.
  *
  * Validation-only by design: callers keep their ORIGINAL options object.
- * Zod's parse output strips unknown keys, and the `intent` slot legally
- * carries live handles (`IntentLeaseHandle` / claim leases) whose
+ * Zod's parse output strips unknown keys, and the `claim` slot legally
+ * carries live handles (`ClaimHandle` / claim leases) whose
  * `release`/`revoke` functions must survive — so we assert, never replace.
  */
 import { z } from 'zod';
@@ -28,9 +28,9 @@ export const writeOptionsSchema = z.object({
     readAt: z.number().int().nonnegative().nullish(),
     /** What the server does when the target moved past `readAt`. */
     onStale: onStaleModeSchema.nullish(),
-    /** Claim/intent attribution — an id, or a live lease handle (loose: the
+    /** Claim/claim attribution — an id, or a live lease handle (loose: the
      *  handle's `release`/`revoke` functions ride along untouched). */
-    intent: z.union([z.string(), z.looseObject({ id: z.string() })]).nullish(),
+    claim: z.union([z.string(), z.looseObject({ id: z.string() })]).nullish(),
     /** Dormant wire-compat field; always `null` from current clients. */
     causedByTaskId: z.string().nullish(),
 });