@abloatai/ablo 0.10.1 → 0.11.1

package/dist/client/createModelProxy.js

@@ -15,8 +15,10 @@
  * 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 { toMs } from '../utils/duration.js';
 import { assertWriteOptions } from './writeOptionsSchema.js';
 import { ModelScope } from '../types/index.js';
 const modelClientMeta = new WeakMap();
@@ -31,9 +33,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
@@ -74,7 +76,17 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
     // Claims this proxy currently holds, keyed by entity id. Lets the flat
     // `release({ id })` and `update({ id, data })` find the lease + snapshot a `claim({ id })`
     // took — no per-call handle. Released on dispose, explicit release, or TTL.
+    //
+    // `target` / `action` / `expiresAt` are kept alongside the lease so
+    // `claim.state` can synthesize a self-claim: the server excludes a holder's
+    // own presence frames, so the local proxy is the ONLY place that knows "I
+    // hold this." `expiresAt` is the client's best estimate from the requested
+    // TTL (a genuine epoch-ms expiry, not a fabricated watermark), defaulting to
+    // the server's keepalive lease window when no TTL was requested.
     const activeClaims = new Map();
+    // Server keepalive lease window (Hub `LEASE_RENEW_TTL_MS`). The fallback
+    // expiry estimate when a claim is taken without an explicit TTL.
+    const DEFAULT_LEASE_TTL_MS = 90_000;
     const isClaimHandle = (value) => typeof value === 'object' &&
         value !== null &&
         value.object === 'claim' &&
@@ -85,6 +97,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.
@@ -102,7 +135,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
     };
     const takeClaim = async (params) => {
         if (!collaboration) {
-            throw new AbloValidationError(`Model "${schemaKey}" cannot claim a row without collaboration wiring.`, { code: 'model_claim_not_configured' });
+            throw new AbloValidationError(`Model "${schemaKey}" was built without the collaboration runtime, so claim() is unavailable here. Claiming needs no per-model config — use the standard Ablo({ schema, apiKey }) client and every model is claimable.`, { code: 'model_claim_not_configured' });
         }
         const { id, ...options } = params;
         // Is someone ELSE already on this target? Read the local coordination
@@ -114,11 +147,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);
@@ -129,12 +168,20 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         if (!model) {
             throw new AbloValidationError(`Entity not found: ${registeredModelName}/${id}`, { code: 'entity_not_found' });
         }
+        // Write-intent: enter the entity scope BEFORE acquiring the lease so the
+        // holder's claim presence broadcasts to whoever is in this entity group —
+        // including a peer that subscribed just before us. Pinning before the
+        // lease (rather than after) closes the subscribe-vs-broadcast race: the
+        // server fans `broadcastPresenceChange` out at claim time, so we must be
+        // in the group when `createClaim` lands. Awaited because the broadcast
+        // ordering depends on it; still soft (the store swallows reconcile errors).
+        await collaboration.pinScope?.({ [schemaKey]: id });
         // 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({
+        const lease = await collaboration.createClaim({
             target: {
                 model: wireModel,
                 id,
@@ -151,9 +198,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.
@@ -166,7 +213,27 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             model = objectPool.get(id) ?? model;
         }
         const snapshot = collaboration.createSnapshot(schemaKey, id);
-        activeClaims.set(id, { lease, snapshot });
+        const action = options?.action ?? 'editing';
+        // The self-claim's `EntityRef` mirrors what a peer's `claim.state` would
+        // report (`observe` maps `held.target.model` → `type`), so a holder and a
+        // peer see the SAME target.type for one row — the wire model token.
+        const selfTarget = {
+            type: wireModel,
+            id,
+            ...(options?.field ? { field: options.field } : {}),
+            ...(options?.path ? { path: options.path } : {}),
+            ...(options?.range ? { range: options.range } : {}),
+            ...(claimMeta(options) ? { meta: claimMeta(options) } : {}),
+        };
+        const expiresAt = Date.now() +
+            (options?.ttl !== undefined ? toMs(options.ttl) : DEFAULT_LEASE_TTL_MS);
+        activeClaims.set(id, {
+            lease,
+            snapshot,
+            target: selfTarget,
+            action,
+            expiresAt,
+        });
         const target = {
             model: schemaKey,
             id,
@@ -178,10 +245,10 @@ 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',
+            action,
             ...(options?.description ? { description: options.description } : {}),
             data: modelAsRow(model),
             release,
@@ -198,6 +265,28 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
     // are the same object.
     const claimApi = Object.assign(guard(claim), {
         state(params) {
+            // Read-interest: a passive observer subscribing to a row's claim state
+            // must enter that row's entity scope, or it sits on `org:`/`user:`
+            // groups only and never receives the holder's entity-scoped claim
+            // presence. Soft + fire-and-forget — never blocks or rejects the read.
+            void collaboration?.enterScope?.({ [schemaKey]: params.id });
+            // Self-awareness: the server excludes a holder's OWN presence frames and
+            // the client skips them, so `observe` returns null for a row WE hold.
+            // Synthesize the active claim for self from the stored lease so the
+            // holder sees its own claim (the JSDoc contract on `claim.state`).
+            const own = activeClaims.get(params.id);
+            if (own) {
+                return {
+                    object: 'claim',
+                    id: own.lease.claimId,
+                    status: 'active',
+                    target: own.target,
+                    action: own.action,
+                    heldBy: collaboration?.selfParticipantId ?? '',
+                    participantKind: collaboration?.selfParticipantKind ?? 'user',
+                    expiresAt: own.expiresAt,
+                };
+            }
             return collaboration?.observe({ model: wireModel, id: params.id }) ?? null;
         },
         queue(params) {
@@ -213,6 +302,11 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
     });
     const operations = {
         retrieve: guard(async (params) => {
+            // Read-interest enrolment: READ a row → enter its entity scope, so a
+            // Node/agent client lands in the same group the holder's claim presence
+            // fans out on and `claim.state`/`claim.queue` report peers. Soft +
+            // fire-and-forget — never make the read reject or slower.
+            void collaboration?.enterScope?.({ [schemaKey]: params.id });
             const rows = await load({
                 ...params,
                 where: [['id', params.id]],
@@ -220,6 +314,9 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             });
             return rows[0];
         }),
+        // NB: no auto scope enrolment on bulk `list`/`getAll` — that would
+        // subscribe to an unbounded set of rows' entity groups. Bulk-list scope
+        // enrolment is a deliberate follow-up (a bounded, opt-in policy).
         list: guard(load),
         get(id) {
             return objectPool.get(id);
@@ -267,9 +364,15 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             let autoLease;
             if (claim && !isClaimHandle(claim)) {
                 if (!collaboration) {
-                    throw new AbloValidationError(`Model "${schemaKey}" cannot claim a row without collaboration wiring.`, { code: 'model_claim_not_configured' });
+                    throw new AbloValidationError(`Model "${schemaKey}" was built without the collaboration runtime, so claim() is unavailable here. Claiming needs no per-model config — use the standard Ablo({ schema, apiKey }) client and every model is claimable.`, { code: 'model_claim_not_configured' });
                 }
-                autoLease = await collaboration.createIntent({
+                // Write-intent: enter the new row's entity scope BEFORE acquiring the
+                // create-claim so the holder's claim presence broadcasts to whoever is
+                // already in this entity group (closing the subscribe-vs-broadcast
+                // race — see `takeClaim`). Released with the lease in the `finally`
+                // below. Awaited for broadcast ordering; still soft.
+                await collaboration.pinScope?.({ [schemaKey]: id });
+                autoLease = await collaboration.createClaim({
                     target: {
                         model: wireModel,
                         id,
@@ -299,8 +402,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 +439,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 +454,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 +489,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 +501,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(),
 });