@abloatai/ablo 0.3.1 → 0.5.0

package/dist/client/Ablo.d.ts

@@ -5,7 +5,7 @@
  * bootstrap, offline queue, DI adapters) behind a single function call.
  *
  * Usage:
- *   import { Ablo } from '@ablo/sync-engine/client';
+ *   import { Ablo } from '@abloatai/ablo/client';
  *   import { schema } from './schema';
  *
  *   const sync = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
@@ -21,7 +21,7 @@ import { ObjectPool } from '../ObjectPool.js';
 import type { SyncStoreContract } from '../react/context.js';
 import type { SyncWebSocket } from '../sync/SyncWebSocket.js';
 import { type SyncStatus } from '../BaseSyncedStore.js';
-import type { IntentStream, PresenceStream, Snapshot } from '../types/streams.js';
+import type { IntentStream, IntentWaitOptions, PresenceStream, Snapshot } from '../types/streams.js';
 import type { ParticipantManager } from '../sync/participants.js';
 import type { ActiveIntent, Duration, TargetRange } from '../types/streams.js';
 import { type AbloApi, type AbloApiClientOptions, type AbloApiIntents } from './ApiClient.js';
@@ -48,34 +48,75 @@ export interface Turn {
  * `ApiKeySetter` exactly so any rotation pattern that works with
  * `@anthropic-ai/sdk` works here.
  *
- * Re-exported from `./auth` so existing import paths (`@ablo/sync-engine`)
+ * Re-exported from `./auth` so existing import paths (`@abloatai/ablo`)
  * keep resolving; the canonical definition lives there alongside the
  * resolvers that consume it.
  */
 export type { ApiKeySetter } from './auth.js';
 import type { ApiKeySetter } from './auth.js';
 import { type AbloPersistence } from './persistence.js';
+/**
+ * Options for `Ablo({...})`.
+ *
+ * The only required field is `schema`. The default path is one line:
+ *
+ * ```ts
+ * const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+ * ```
+ *
+ * `apiKey` itself defaults to `process.env.ABLO_API_KEY`, so in most
+ * server setups `Ablo({ schema })` is enough. Every other field is
+ * optional tuning (timeouts, retries, custom fetch, persistence) —
+ * if you're not sure whether you need one, you don't. Reach for them
+ * the way you'd reach for the equivalent option on the Stripe / OpenAI
+ * / Anthropic clients: rarely, and deliberately.
+ *
+ * @see https://docs.ablo.finance — full option reference
+ */
 export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
+    /**
+     * TypeScript schema defined with `defineSchema()`. Required — it's what
+     * makes `ablo.tasks.update(...)` typed. This is the one field you must
+     * pass; start here.
+     */
+    schema: Schema<S>;
     /**
      * API key used for authentication.
      *
      * Accepts a static string (`sk_live_...`) or an async function that
-     * resolves to one. Defaults to `process.env['ABLO_API_KEY']`.
+     * resolves to one. Defaults to `process.env['ABLO_API_KEY']`, so you
+     * usually don't pass this explicitly server-side.
      */
     apiKey?: string | ApiKeySetter | null | undefined;
+    /**
+     * Local persistence mode. Pass `indexeddb` only when you want offline
+     * queueing and a reload-surviving browser cache.
+     *
+     * @default 'volatile'
+     */
+    persistence?: AbloPersistence;
     /**
      * Bearer auth token. Hosted-cloud consumers pass `apiKey`; self-hosted
      * deployments may pass a bearer token minted by their own auth layer.
      */
     authToken?: string | null | undefined;
     /**
-     * Override the Ablo API base URL. Defaults to hosted production and reads
-     * `process.env['ABLO_BASE_URL']` if unset.
+     * Override the Ablo API base URL. Defaults to hosted production.
      */
     baseURL?: string | null | undefined;
-    /** Per-request timeout in milliseconds. */
+    /**
+     * Maximum time (ms) to wait for a single request before timing out.
+     * Timed-out requests are retried, so worst-case wait can exceed this.
+     *
+     * @default 600_000
+     */
     timeout?: number | undefined;
-    /** Number of retries for transient failures. */
+    /**
+     * Maximum retries on transient failure (network error / 5xx / 429).
+     * Honors `Retry-After`.
+     *
+     * @default 2
+     */
     maxRetries?: number | undefined;
     /** Custom fetch implementation for tests, proxies, or non-standard runtimes. */
     fetch?: typeof fetch | undefined;
@@ -89,16 +130,6 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      * key or a controlled server proxy.
      */
     dangerouslyAllowBrowser?: boolean | undefined;
-    /**
-     * TypeScript schema defined with `defineSchema()`. This enables typed
-     * resources such as `ablo.tasks.update(...)`.
-     */
-    schema: Schema<S>;
-    /**
-     * Local persistence mode. Defaults to `volatile`. Pass `indexeddb` only
-     * when you want offline queueing and a reload-surviving browser cache.
-     */
-    persistence?: AbloPersistence;
 }
 export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
     /**
@@ -118,7 +149,7 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
     apiKey?: string | ApiKeySetter | null | undefined;
     /**
      * Bearer auth token. Sent as `Authorization: Bearer <token>` on
-     * every request. Defaults to `process.env['ABLO_AUTH_TOKEN']`.
+     * every request.
      *
      * Use this for self-hosted deployments where your auth layer mints
      * cap tokens directly. Hosted-cloud consumers pass `apiKey` instead;
@@ -129,7 +160,6 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      * Override the default base URL. Defaults to
      * `wss://mesh.ablo.finance` for hosted production; pass an explicit
      * URL for self-hosted or staging (e.g. `wss://mesh-staging.ablo.finance`).
-     * Reads `process.env['ABLO_BASE_URL']` if unset.
      */
     baseURL?: string | null | undefined;
     /**
@@ -327,7 +357,7 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
  * deprecated aliases for one release cycle so consumers can migrate
  * without a flag day.
  */
-export type { ModelCountOptions, ModelListOptions, ModelListScope, ModelLoadOptions, ModelEditHandle, ModelEditOptions, ModelOperations, } from './createModelProxy.js';
+export type { ModelCountOptions, ModelListOptions, ModelListScope, ModelLoadOptions, ModelIntentAcquireOptions, ModelIntentHandle, ModelOperations, } from './createModelProxy.js';
 import type { ModelOperations } from './createModelProxy.js';
 export type ResourceOperationAction = 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
 export type CommitWait = 'queued' | 'confirmed';
@@ -366,11 +396,7 @@ export interface BusyOptions {
     /** HTTP API polling interval while waiting. WebSocket clients ignore it. */
     readonly busyPollInterval?: number;
 }
-export interface IntentWaitOptions {
-    readonly timeout?: number;
-    readonly pollInterval?: number;
-    readonly signal?: AbortSignal;
-}
+export type { IntentWaitOptions } from '../types/streams.js';
 export interface ResourceReadOptions extends BusyOptions {
 }
 export interface IntentCreateOptions {
@@ -816,7 +842,7 @@ export declare namespace Ablo {
         type Event = import('../source/index.js').SourceEvent;
         type EventsResult = import('../source/index.js').SourceEventsResult;
         type Scope = import('../source/index.js').SourceScope;
-        type Secret = import('../source/index.js').SourceSecret;
+        type ApiKey = import('../source/index.js').SourceApiKey;
         type Options<S extends _SchemaTypes.SchemaRecord = _SchemaTypes.SchemaRecord, TAuth = unknown> = import('../source/index.js').AbloSourceOptions<S, TAuth>;
         type ModelHandlers<Row, CreateInput, TAuth = unknown> = import('../source/index.js').SourceModelHandlers<Row, CreateInput, TAuth>;
         type SignatureVerificationResult = import('../source/index.js').SourceSignatureVerificationResult;

package/dist/client/Ablo.js

@@ -5,7 +5,7 @@
  * bootstrap, offline queue, DI adapters) behind a single function call.
  *
  * Usage:
- *   import { Ablo } from '@ablo/sync-engine/client';
+ *   import { Ablo } from '@abloatai/ablo/client';
  *   import { schema } from './schema';
  *
  *   const sync = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
@@ -1147,6 +1147,37 @@ export function Ablo(options) {
                 getLastSyncId: () => store.getSyncWebSocket()?.getLastSyncId() ?? store.lastSyncId ?? 0,
                 entities: { [modelKey]: 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,
+                    id: target.id,
+                })[0];
+                if (!held)
+                    return null;
+                return {
+                    object: 'intent',
+                    id: held.id,
+                    status: 'active',
+                    target: {
+                        type: held.target.resource,
+                        id: held.target.id,
+                        ...(held.target.path ? { path: held.target.path } : {}),
+                        ...(held.target.range ? { range: held.target.range } : {}),
+                        ...(held.target.field ? { field: held.target.field } : {}),
+                        ...(held.target.meta ? { meta: held.target.meta } : {}),
+                    },
+                    action: held.action,
+                    heldBy: held.actor,
+                    participantKind: held.participantKind,
+                    expiresAt: held.expiresAt,
+                };
+            },
+            waitFor: (target, waitOptions) => publicIntents.waitFor({ resource: target.resource, id: target.id }, waitOptions),
+            selfParticipantId: participantId,
         });
     }
     const commits = {

package/dist/client/auth.d.ts

@@ -7,9 +7,9 @@
  * with an actionable message — so the constructor reads as a
  * sequence of named decisions rather than a stream of `??`-chains.
  *
- * Precedence for every resolver: explicit option → environment
- * variable → built-in default. The same shape Anthropic, OpenAI,
- * and Stripe SDKs use.
+ * Customer-facing env surface is intentionally small: `ABLO_API_KEY`
+ * is the only environment fallback. Other routing/auth overrides are
+ * explicit options so generated apps do not accrete hidden env knobs.
  */
 /**
  * Async callable that resolves to a fresh API key. Mirrors the shape

package/dist/client/auth.js

@@ -7,9 +7,9 @@
  * with an actionable message — so the constructor reads as a
  * sequence of named decisions rather than a stream of `??`-chains.
  *
- * Precedence for every resolver: explicit option → environment
- * variable → built-in default. The same shape Anthropic, OpenAI,
- * and Stripe SDKs use.
+ * Customer-facing env surface is intentionally small: `ABLO_API_KEY`
+ * is the only environment fallback. Other routing/auth overrides are
+ * explicit options so generated apps do not accrete hidden env knobs.
  */
 import { AbloAuthenticationError } from '../errors.js';
 /**
@@ -25,11 +25,11 @@ export function resolveApiKey(input) {
     return input.options.apiKey ?? input.env.ABLO_API_KEY ?? null;
 }
 export function resolveAuthToken(input) {
-    return input.options.authToken ?? input.env.ABLO_AUTH_TOKEN ?? null;
+    return input.options.authToken ?? null;
 }
 export const ABLO_DEFAULT_BASE_URL = 'wss://mesh.ablo.finance';
 export function resolveBaseURL(input) {
-    return (input.options.baseURL ?? input.env.ABLO_BASE_URL ?? ABLO_DEFAULT_BASE_URL);
+    return input.options.baseURL ?? ABLO_DEFAULT_BASE_URL;
 }
 /**
  * Browser guard — apiKey is server-side-only by default. Same check

package/dist/client/createModelProxy.d.ts

@@ -8,9 +8,9 @@
  *
  * Each schema model gets one `ModelOperations<T, CreateInput>` —
  * exposes `retrieve`, `list`, `count`, `create`, `update`, `delete`,
- * `edit`,
- * `subscribe`, and `load`. The factory returns a plain object; the
- * client assembles `ablo.<model>` lookup table from these.
+ * `intent` (the coordination handle), `subscribe`, and `load`. The
+ * factory returns a plain object; the client assembles the
+ * `ablo.<model>` lookup table from these.
  */
 import type { MutationOptions } from '../interfaces/index.js';
 import type { ModelRegistry } from '../ModelRegistry.js';
@@ -19,7 +19,7 @@ import type { SyncClient } from '../SyncClient.js';
 import type { HydrationCoordinator } from '../sync/HydrationCoordinator.js';
 import type { LoadWhere } from '../query/types.js';
 import { ModelScope } from '../types/index.js';
-import type { Duration, Snapshot } from '../types/streams.js';
+import type { Duration, Intent, IntentStatus, IntentWaitOptions, Snapshot } from '../types/streams.js';
 export interface ModelResourceMeta {
     readonly key: string;
     readonly typename: string;
@@ -66,30 +66,7 @@ export interface ModelLoadOptions<T> {
      */
     expand?: readonly string[];
 }
-export interface ModelEditOptions<T = Record<string, unknown>> {
-    /**
-     * Human-readable activity shown to other participants while this handle
-     * is open. Examples: `editing`, `summarizing`, `rewriting`, `reviewing`.
-     */
-    activity?: string;
-    /** Optional field-level target for UI affordances such as busy badges. */
-    field?: keyof T & string;
-    /** Lease duration for the visible activity. Runtime death is cleaned up by TTL. */
-    ttl?: Duration;
-    /** Default wait mode for `handle.update(...)`. Defaults to `confirmed`. */
-    wait?: MutationOptions['wait'];
-}
-export interface ModelEditHandle<T> extends AsyncDisposable {
-    readonly id: string;
-    readonly intentId: string;
-    readonly activity: string;
-    readonly current: T;
-    readonly signal: AbortSignal;
-    update(data: Partial<T>, options?: MutationOptions): Promise<T>;
-    release(): Promise<void>;
-    revoke(): void;
-}
-export interface ModelIntentHandle {
+export interface IntentLeaseHandle {
     readonly id: string;
     release(): Promise<void>;
     revoke(): void;
@@ -103,8 +80,107 @@ export interface ModelCollaboration<T> {
         };
         action: string;
         ttl?: Duration;
-    }): Promise<ModelIntentHandle>;
+    }): Promise<IntentLeaseHandle>;
     createSnapshot(modelKey: string, id: string): Snapshot;
+    /**
+     * Current coordination state on a target — who (if anyone) holds it.
+     * Synchronous reactive snapshot read off the presence/intent stream;
+     * `null` when the target is free. The wiring site computes it because
+     * only it knows the local participant id (needed to distinguish "I
+     * hold it" from "someone else holds it").
+     */
+    observe(target: {
+        resource: string;
+        id: string;
+    }): Intent | null;
+    /**
+     * Resolve once no participant holds an active intent on the target.
+     * The contender's "wait until it's free" — delegates to the intent
+     * stream's `waitFor`.
+     */
+    waitFor(target: {
+        resource: string;
+        id: string;
+    }, options?: IntentWaitOptions): Promise<void>;
+    /**
+     * The local participant's id. Used to distinguish "I already hold this"
+     * from "someone else holds it" in `claimOrWait`.
+     */
+    readonly selfParticipantId: string;
+}
+/** Options for acquiring a per-model coordination intent. */
+export interface ModelIntentAcquireOptions {
+    /** Phase shown to others while held. Defaults to `'editing'`. */
+    action?: string;
+    /** Field-level target for busy badges. */
+    field?: string;
+    /** Lease duration; runtime death is cleaned up by TTL. */
+    ttl?: Duration;
+    /** Default wait mode for `handle.update(...)`. Defaults to `confirmed`. */
+    wait?: MutationOptions['wait'];
+}
+/**
+ * Per-entity coordination handle, returned synchronously by
+ * `ablo.<model>.intent(id)`. It lets humans and agents claim a row before
+ * they work on it, so two of them don't edit the same thing at once.
+ *
+ * The lifecycle reads like a sentence:
+ *
+ * ```ts
+ * const report = ablo.weatherReports.intent('weather_stockholm');
+ *
+ * if (report.current) await report.whenFree(); // someone's on it — wait
+ * await report.claim({ action: 'checking_weather' }); // it's mine now
+ * await report.update({ status: 'ready' });    // write, then auto-finish
+ * ```
+ *
+ * `current` is the live `Intent` (or `null` if free). `claim()` announces
+ * you're working so others yield. `whenFree()` waits for whoever holds it.
+ * `claimOrWait()` does both — claim, or wait your turn then claim — which
+ * is what you bind to an agent's write tool so it never reasons about
+ * coordination itself. `finish()`/`cancel()` give the claim back.
+ */
+export interface ModelIntentHandle<T> extends AsyncDisposable {
+    /** The target entity id this handle coordinates. */
+    readonly id: string;
+    /**
+     * Live coordination state on this target — `null` when free, otherwise
+     * the holder's `Intent` (who, what phase, until when). Reactive
+     * snapshot; pair with the model's `subscribe` for change notifications.
+     */
+    readonly current: Intent | null;
+    /** Convenience: `current?.status ?? 'idle'`. */
+    readonly status: IntentStatus | 'idle';
+    /**
+     * Claim this row so other participants yield while you work. Resolves
+     * once the claim is announced. Throws if someone else already holds it
+     * — call `whenFree()` first, or use `claimOrWait()` to do both.
+     */
+    claim(options?: ModelIntentAcquireOptions): Promise<void>;
+    /**
+     * Claim the row, or — if someone else holds it — wait for them to
+     * finish, re-read the (now-changed) row, then claim. The caller never
+     * branches on who holds it; it just gets the row safely. A claim you
+     * already hold is treated as yours and taken without waiting. Bind this
+     * to an agent's write-tool boundary.
+     */
+    claimOrWait(options?: ModelIntentAcquireOptions): Promise<void>;
+    /**
+     * Optimistic update guarded by the claim this handle holds. Rejects
+     * with `AbloStaleContextError` if the row changed under you, then
+     * auto-finishes. Call `claim()` first.
+     */
+    update(data: Partial<T>, options?: MutationOptions): Promise<T>;
+    /** Finish: give back a claim you hold once the work is committed. */
+    finish(): Promise<void>;
+    /**
+     * Wait until the row is free, then resolve. On resolution your cached
+     * copy may be stale — re-read before writing (the stale-context guard
+     * enforces this if you go through `claim()` + `update()`).
+     */
+    whenFree(options?: IntentWaitOptions): Promise<void>;
+    /** Cancel: drop a claim you hold without committing any work. */
+    cancel(): void;
 }
 export interface ModelOperations<T, CreateInput> {
     /**
@@ -135,10 +211,20 @@ export interface ModelOperations<T, CreateInput> {
     /** Delete an entity by id — optimistic, offline-first (see `create`). */
     delete(id: string, options?: MutationOptions): Promise<void>;
     /**
-     * Start a model-scoped activity lease for long-running AI or background work.
-     * Other participants can see the activity until `update`, `release`, or TTL.
+     * Coordination accessor for one entity — the same `ablo.<model>(id)`
+     * shape as `create`/`update`/`retrieve`, but on the coordination plane
+     * (ephemeral, TTL'd, never persisted). Returns a handle synchronously:
+     * read `.current` to see who's editing, `claim()` to take it, `update()`
+     * to write under the claim, `whenFree()` to wait for a holder to finish.
+     *
+     * ```ts
+     * const lock = ablo.slide.intent(slideId);
+     * if (lock.current) await lock.whenFree();   // someone's editing — wait
+     * await lock.claim({ action: 'editing' });
+     * await lock.update({ title: 'New' });       // auto-finishes
+     * ```
      */
-    edit(id: string, options?: ModelEditOptions<T>): Promise<ModelEditHandle<T>>;
+    intent(id: string): ModelIntentHandle<T>;
     /** Subscribe to changes (callback called on every change). */
     subscribe(callback: (entities: T[]) => void, options?: ModelListOptions<T>): () => void;
     /**

package/dist/client/createModelProxy.js

@@ -8,9 +8,9 @@
  *
  * Each schema model gets one `ModelOperations<T, CreateInput>` —
  * exposes `retrieve`, `list`, `count`, `create`, `update`, `delete`,
- * `edit`,
- * `subscribe`, and `load`. The factory returns a plain object; the
- * client assembles `ablo.<model>` lookup table from these.
+ * `intent` (the coordination handle), `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';
@@ -111,54 +111,96 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             syncClient.delete(model, options);
             await waitForMutation(model, options);
         },
-        async edit(id, options) {
-            if (!collaboration) {
-                throw new AbloValidationError(`Model "${schemaKey}" cannot start edit activity without collaboration wiring.`, { code: 'model_edit_not_configured' });
-            }
-            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 activity = options?.activity ?? 'editing';
-            const snapshot = collaboration.createSnapshot(schemaKey, id);
-            const intent = await collaboration.createIntent({
-                target: {
-                    resource: schemaKey,
-                    id,
-                    ...(options?.field ? { field: options.field } : {}),
-                },
-                action: activity,
-                ttl: options?.ttl,
-            });
+        intent(id) {
+            const target = { resource: schemaKey, id };
+            let acquired = null;
+            let snapshot = null;
             let released = false;
-            const revoke = () => {
+            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;
-                snapshot.signal.removeEventListener('abort', revoke);
-                intent.revoke();
+                if (snapshot)
+                    snapshot.signal.removeEventListener('abort', cancel);
+                acquired?.revoke();
             };
-            const release = async () => {
+            // 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;
-                snapshot.signal.removeEventListener('abort', revoke);
-                await intent.release();
+                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);
             };
-            snapshot.signal.addEventListener('abort', revoke, { once: true });
             const handle = {
                 id,
-                intentId: intent.id,
-                activity,
-                current: modelAsRow(model),
-                signal: snapshot.signal,
+                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(`Edit context is stale for ${schemaKey}/${id}. Re-read the row and retry.`, {
+                        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,
@@ -166,20 +208,21 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                     }
                     try {
                         return await operations.update(id, data, {
-                            wait: options?.wait ?? 'confirmed',
+                            wait: acquireWait ?? 'confirmed',
                             readAt: snapshot.stamp,
                             onStale: 'reject',
                             ...updateOptions,
-                            intent,
+                            intent: acquired,
                         });
                     }
                     finally {
-                        await release();
+                        await finish();
                     }
                 },
-                release,
-                revoke,
-                [Symbol.asyncDispose]: release,
+                finish,
+                whenFree,
+                cancel,
+                [Symbol.asyncDispose]: finish,
             };
             return handle;
         },

package/dist/client/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @ablo/sync-engine/client — Consumer API
+ * @abloatai/ablo/client — Consumer API
  *
  * The one-liner entry point for external consumers.
  *
@@ -7,7 +7,7 @@
  * when you want the realtime sync engine with typed model proxies.
  *
  * ```ts
- * import { Ablo } from '@ablo/sync-engine/client';
+ * import { Ablo } from '@abloatai/ablo/client';
  * import { schema } from './schema';
  *
  * const ablo = Ablo({
@@ -20,7 +20,7 @@
  * ```
  *
  * For headless agents (workers, bots), pass `kind: 'agent'` plus a
- * Biscuit `capabilityToken`:
+ * restricted (`rk_`) API key as `capabilityToken`:
  *
  * ```ts
  * const bot = Ablo({

package/dist/client/index.js

@@ -1,5 +1,5 @@
 /**
- * @ablo/sync-engine/client — Consumer API
+ * @abloatai/ablo/client — Consumer API
  *
  * The one-liner entry point for external consumers.
  *
@@ -7,7 +7,7 @@
  * when you want the realtime sync engine with typed model proxies.
  *
  * ```ts
- * import { Ablo } from '@ablo/sync-engine/client';
+ * import { Ablo } from '@abloatai/ablo/client';
  * import { schema } from './schema';
  *
  * const ablo = Ablo({
@@ -20,7 +20,7 @@
  * ```
  *
  * For headless agents (workers, bots), pass `kind: 'agent'` plus a
- * Biscuit `capabilityToken`:
+ * restricted (`rk_`) API key as `capabilityToken`:
  *
  * ```ts
  * const bot = Ablo({

package/dist/config/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @ablo/sync-engine/config — App initialization
+ * @abloatai/ablo/config — App initialization
  *
  * One-time setup at app boot. Provides DI interface types
  * and the initSyncEngine() function to wire real implementations.