@abloatai/ablo 0.29.2 → 0.30.0

package/dist/client/createModelProxy.js

@@ -12,7 +12,6 @@
  */
 import { autorun } from 'mobx';
 import { AbloClaimedError, AbloStaleContextError, AbloValidationError, formatClaimedErrorMessage, toAbloError, } from '../errors.js';
-import { descriptionFromMeta } from '../coordination/schema.js';
 import { reconcileFunctionalUpdate, } from './functionalUpdate.js';
 import { Model, modelAsRow } from '../Model.js';
 import { toMs } from '../utils/duration.js';
@@ -77,7 +76,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
     // `claim({ id })` took, without a per-call handle. Released on dispose,
     // explicit release, or TTL expiry.
     //
-    // `target`, `reason`, and `expiresAt` are kept alongside the lease so
+    // `target`, `description`, and `expiresAt` are kept alongside the lease so
     // `claim.state` can synthesize a self-claim: the server excludes a holder's
     // own presence frames, so this proxy is the only place that knows the client
     // holds the row. `expiresAt` is the client's best estimate from the requested
@@ -94,19 +93,13 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         value.object === 'claim' &&
         typeof value.id === 'string' &&
         typeof value.release === 'function';
-    const claimMeta = (options) => {
-        if (!options?.description)
-            return options?.meta;
-        return { ...(options.meta ?? {}), description: options.description };
-    };
+    const claimMeta = (options) => options?.meta;
     const claimContextFromClaim = (claim) => {
-        const description = claim.description ?? descriptionFromMeta(claim.target.meta);
         return {
             id: claim.id,
             actor: claim.heldBy,
             participantKind: claim.participantKind,
-            reason: claim.reason,
-            ...(description ? { description } : {}),
+            description: claim.description,
             field: claim.target.field,
             status: claim.status,
             expiresAt: claim.expiresAt,
@@ -192,7 +185,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                 ...(options.range ? { range: options.range } : {}),
                 ...(claimMeta(options) ? { meta: claimMeta(options) } : {}),
             },
-            reason: options.reason ?? 'editing',
+            description: options.description ?? 'editing',
             ttl: options.ttl,
             queue: !failFast,
             maxQueueDepth: options.maxQueueDepth,
@@ -215,7 +208,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             model = objectPool.get(id) ?? model;
         }
         const snapshot = collaboration.createSnapshot(schemaKey, id);
-        const reason = options.reason ?? 'editing';
+        const description = options.description ?? 'editing';
         // The self-claim's `ClaimTarget` mirrors what a peer's `claim.state` would
         // report (`state` maps `held.target.model` to `type`), so a holder and a
         // peer see the same `target.type` for one row — the wire model token.
@@ -233,7 +226,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             lease,
             snapshot,
             target: selfTarget,
-            reason,
+            description,
             expiresAt,
         });
         const target = {
@@ -281,9 +274,11 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             object: 'claim',
             id: lease.id,
             readAt: snapshot.stamp,
+            // The fencing token the server minted for this grant, forwarded from the
+            // lease so writes taken under this handle carry it (Option B).
+            ...(lease.fenceToken !== undefined ? { fenceToken: lease.fenceToken } : {}),
             target,
-            reason,
-            ...(options.description ? { description: options.description } : {}),
+            description,
             data: modelAsRow(model),
             release,
             revoke: () => {
@@ -293,12 +288,153 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             [Symbol.asyncDispose]: release,
         };
     };
-    const claim = (params) => takeClaim(params);
+    // The row-free sibling of `takeClaim`: locks a key by id alone, for a row that
+    // lives only in the customer's own database and was never synced into Ablo.
+    // Everything about the lease — the fail-fast contention check, the scope pin,
+    // the `createClaim` grant, the heartbeat wiring, and the `activeClaims`
+    // bookkeeping — is identical; what's dropped is the object-pool `load` (and its
+    // `entity_not_found` throw), the post-grant re-read, and the `.data` field,
+    // since there is no local row to hydrate or return.
+    const takeRowFreeClaim = async (id, options) => {
+        if (!collaboration) {
+            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' });
+        }
+        // Is someone else already on this target? Read the local coordination
+        // snapshot up front so a `queue: false` caller can reject before announcing
+        // a claim the server would refuse.
+        const held = collaboration.state({ model: wireModel, id });
+        const contended = !!held && held.heldBy !== collaboration.selfParticipantId;
+        const failFast = options.queue === false;
+        // Fail-fast (`queue: false`): reject now if a holder is already visible.
+        // Best-effort at the client — a row this participant never synced usually
+        // carries no local claim state either, so a peer gets the deterministic
+        // rejection only once it has observed the holder (entered the row's entity
+        // scope). The server's queue is the backstop for the queuing path.
+        if (failFast && contended) {
+            const claim = claimContextFromClaim(held);
+            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] });
+        }
+        // Enter the entity scope before acquiring the lease so the holder's claim
+        // presence broadcasts to everyone in this entity group — the same ordering
+        // the row-bearing path relies on. No pool `load` and no `entity_not_found`
+        // throw: the row lives only in the customer's database, so there is nothing
+        // to hydrate here and nothing to re-read after the grant.
+        await collaboration.pinScope?.({ [schemaKey]: id });
+        const lease = await collaboration.createClaim({
+            target: {
+                model: wireModel,
+                id,
+                ...(options.field ? { field: options.field } : {}),
+                ...(options.path ? { path: options.path } : {}),
+                ...(options.range ? { range: options.range } : {}),
+                ...(claimMeta(options) ? { meta: claimMeta(options) } : {}),
+            },
+            description: options.description ?? 'editing',
+            ttl: options.ttl,
+            queue: !failFast,
+            maxQueueDepth: options.maxQueueDepth,
+        });
+        // A watermark-only snapshot: `createSnapshot` still reads the engine's
+        // current `lastSyncId` even though the pool holds no row (the bucket is
+        // empty). It costs nothing extra and gives a write taken under this lease a
+        // real `readAt` to guard against changes since the lease was acquired.
+        const snapshot = collaboration.createSnapshot(schemaKey, id);
+        const description = options.description ?? 'editing';
+        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 ttlMs = options.ttl !== undefined ? toMs(options.ttl) : DEFAULT_LEASE_TTL_MS;
+        const expiresAt = Date.now() + ttlMs;
+        activeClaims.set(id, {
+            lease,
+            snapshot,
+            target: selfTarget,
+            description,
+            expiresAt,
+        });
+        const target = {
+            type: schemaKey,
+            id,
+            ...(options.field ? { field: options.field } : {}),
+            ...(options.path ? { path: options.path } : {}),
+            ...(options.range ? { range: options.range } : {}),
+            ...(claimMeta(options) ? { meta: claimMeta(options) } : {}),
+        };
+        // A beat resolves with the server's extended expiry; keep the local
+        // self-claim estimate in step so `claim.state` renders the real window.
+        const heartbeat = async (beatOptions) => {
+            if (!lease.heartbeat) {
+                throw new AbloValidationError('This claim handle has no heartbeat wiring, which the standard Ablo({ schema, apiKey }) client provides on every claim. This appears only when a claim is minted through an internal path that predates heartbeats.', { code: 'claim_not_wired' });
+            }
+            const resolved = resolveHeartbeatOptions(beatOptions);
+            const beat = await lease.heartbeat({
+                ttl: resolved.ttl ?? options.ttl,
+                ...(resolved.details !== undefined ? { details: resolved.details } : {}),
+            });
+            const held = activeClaims.get(id);
+            if (held)
+                held.expiresAt = beat.expiresAt;
+            options.onHeartbeat?.(beat);
+            return beat;
+        };
+        const stopHeartbeatLoop = options.heartbeat
+            ? startClaimHeartbeatLoop({
+                beat: () => heartbeat(),
+                intervalMs: heartbeatCadenceMs(ttlMs, options.heartbeat),
+                ...(options.onHeartbeatLost
+                    ? { onLost: options.onHeartbeatLost }
+                    : {}),
+            })
+            : undefined;
+        const release = () => {
+            stopHeartbeatLoop?.();
+            return releaseClaim(id);
+        };
+        return {
+            object: 'claim',
+            id: lease.id,
+            readAt: snapshot.stamp,
+            // Forward the grant's fencing token so writes under this row-free lease
+            // carry it (Option B), exactly as the row-bearing claim does.
+            ...(lease.fenceToken !== undefined ? { fenceToken: lease.fenceToken } : {}),
+            target,
+            description,
+            release,
+            revoke: () => {
+                void release();
+            },
+            heartbeat,
+            [Symbol.asyncDispose]: release,
+        };
+    };
+    // `claim` overloads on its first argument: an options object claims a synced
+    // row and resolves to a HeldClaim (carrying `.data`); a bare id claims a key
+    // whose row Ablo doesn't hold and resolves to a HeldLease (no `.data`). Both
+    // route their throws through `toAbloError` via the guarded takers, so the
+    // two-signature shape survives — wrapping the dispatcher itself in `guard`
+    // would collapse the overloads to one.
+    const guardedTakeClaim = guard(takeClaim);
+    const guardedTakeRowFreeClaim = guard(takeRowFreeClaim);
+    function claim(arg, opts) {
+        return typeof arg === 'string'
+            ? guardedTakeRowFreeClaim(arg, opts ?? {})
+            : guardedTakeClaim(arg);
+    }
     // `claim` is a callable namespace: invoke it to take a claim, reach its
     // members to read/steer the coordination plane. Attach the readers to the
-    // guarded callable so `ablo.<model>.claim(...)` and `ablo.<model>.claim.state(...)`
+    // callable so `ablo.<model>.claim(...)` and `ablo.<model>.claim.state(...)`
     // are the same object.
-    const claimApi = Object.assign(guard(claim), {
+    const claimApi = Object.assign(claim, {
         state(params) {
             // Read interest: a passive observer of a row's claim state must enter that
             // row's entity scope, or it sits only on broader `org:`/`user:` groups and
@@ -316,7 +452,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                     id: own.lease.id,
                     status: 'active',
                     target: own.target,
-                    reason: own.reason,
+                    description: own.description,
                     heldBy: collaboration?.selfParticipantId ?? '',
                     participantKind: collaboration?.selfParticipantKind ?? 'user',
                     expiresAt: own.expiresAt,
@@ -416,7 +552,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                         ...(claim.range ? { range: claim.range } : {}),
                         ...(claimMeta(claim) ? { meta: claimMeta(claim) } : {}),
                     },
-                    reason: claim.reason ?? 'creating',
+                    description: claim.description ?? 'creating',
                     ttl: claim.ttl,
                     queue: claim.queue !== false,
                     maxQueueDepth: claim.maxQueueDepth,
@@ -540,6 +676,9 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                                 wait: 'confirmed',
                                 readAt: handle.readAt,
                                 onStale: 'reject',
+                                ...(handle.fenceToken !== undefined
+                                    ? { fenceToken: handle.fenceToken }
+                                    : {}),
                             }
                             : {}),
                         ...opts,
@@ -589,6 +728,9 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                     readAt: claimed.snapshot.stamp,
                     onStale: 'reject',
                     claimRef: { id: claimed.lease.id },
+                    ...(claimed.lease.fenceToken !== undefined
+                        ? { fenceToken: claimed.lease.fenceToken }
+                        : {}),
                     ...opts,
                 }
                 : {

package/dist/client/httpClient.d.ts

@@ -60,7 +60,7 @@ 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>>;
 } & {
-    /** Runs one-time setup, such as registering a configured `databaseUrl` data source, before the client is used. It also runs lazily ahead of the first request, so calling it yourself is optional. */
+    /** Runs one-time setup (durable-outbox scope resolution and replay) before the client is used. It also runs lazily ahead of the first request, so calling it yourself is optional. */
     ready(): Promise<void>;
     /** Replays every pending durable HTTP write in seal order and waits for settlement. */
     waitForFlush(): Promise<void>;