@abloatai/ablo 0.5.1 → 0.7.0

package/dist/client/ApiClient.js

@@ -2,10 +2,10 @@
  * Stateless API client for `Ablo({ apiKey })`.
  *
  * This is the hosted-API product surface: no schema, no object pool, no
- * IndexedDB, no WebSocket. It maps the public Resource / Intent / Commit
+ * IndexedDB, no WebSocket. It maps the public Model / Claim / Commit
  * nouns directly to HTTP routes on sync-server.
  */
-import { AbloBusyError, AbloAuthenticationError, AbloConnectionError, AbloValidationError, translateHttpError, } from '../errors.js';
+import { AbloClaimedError, AbloAuthenticationError, AbloConnectionError, AbloValidationError, translateHttpError, } from '../errors.js';
 import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, } from './auth.js';
 import { toSeconds } from '../utils/duration.js';
 const DEFAULT_AGENT_LEASE = '10m';
@@ -87,7 +87,7 @@ export function createProtocolClient(options) {
             ? `int_${crypto.randomUUID()}`
             : `int_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
     }
-    function createResourceId() {
+    function createModelId() {
         return typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
             ? crypto.randomUUID()
             : `id_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
@@ -163,19 +163,25 @@ export function createProtocolClient(options) {
         return {
             task,
             ablo: agentClient,
-            resource(name) {
-                return createAgentResourceClient(agentClient, name);
+            model(name) {
+                return createAgentModelClient(agentClient, name);
             },
         };
     }
-    function createAgentResourceClient(agentClient, name) {
-        const base = agentClient.resource(name);
+    function createAgentModelClient(agentClient, name) {
+        const base = agentClient.model(name);
         return {
             retrieve(id, options) {
-                return base.retrieve(id, withAgentBusyDefault(options));
+                // Reads are never blocked by a claim (coordination.md): a claim
+                // serializes WRITERS, not readers. So — unlike the create/update/
+                // delete paths below — retrieve does NOT apply the agent claimed
+                // default; options pass through and the read path's `'return'`
+                // default keeps a claimed row readable. A caller can still opt into
+                // gating with an explicit `ifClaimed` (developer's choice).
+                return base.retrieve(id, options);
             },
             create(data, mutationOptions) {
-                const id = mutationOptions?.id ?? createResourceId();
+                const id = mutationOptions?.id ?? createModelId();
                 return withAgentIntent(agentClient, name, id, mutationOptions, (commitIntent) => base.create(data, {
                     ...stripAgentRuntimeOptions(mutationOptions),
                     id,
@@ -196,20 +202,20 @@ export function createProtocolClient(options) {
             },
         };
     }
-    async function withAgentIntent(agentClient, resourceName, id, mutationOptions, commit) {
+    async function withAgentIntent(agentClient, modelName, id, mutationOptions, commit) {
         const intentInput = mutationOptions?.intent;
         const targetOverride = intentInput != null && typeof intentInput === 'object' && !isIntentHandleRef(intentInput)
             ? intentInput.target ?? {}
             : {};
         const target = {
             ...targetOverride,
-            resource: targetOverride.resource ?? resourceName,
+            model: targetOverride.model ?? modelName,
             id: targetOverride.id ?? id,
             ...(intentInput != null && typeof intentInput === 'object' && !isIntentHandleRef(intentInput) && intentInput.field
                 ? { field: intentInput.field }
                 : {}),
         };
-        await applyBusyPolicy(target, withAgentBusyDefault(mutationOptions), 'wait');
+        await applyClaimedPolicy(target, withAgentClaimedDefault(mutationOptions), 'wait');
         if (intentInput == null || isIntentHandleRef(intentInput)) {
             return commit(intentInput);
         }
@@ -229,14 +235,14 @@ export function createProtocolClient(options) {
         }
     }
     function normalizeCommitOperation(op, defaults) {
-        const resource = op.resource ?? op.target?.resource;
-        if (!resource) {
-            throw new AbloValidationError('Commit operation requires `resource` or `target.resource`.', { code: 'commit_operation_resource_required' });
+        const model = op.model ?? op.target?.model;
+        if (!model) {
+            throw new AbloValidationError('Commit operation requires `model` or `target.model`.', { code: 'commit_operation_model_required' });
         }
         const id = op.id ?? op.target?.id ?? null;
         return {
             action: op.action,
-            resource,
+            model,
             id,
             data: op.data ?? null,
             transactionId: op.transactionId ?? null,
@@ -257,24 +263,31 @@ export function createProtocolClient(options) {
         return inputOperations.map((op) => normalizeCommitOperation(op, commitOptions));
     }
     async function listIntents(target) {
+        const state = await listClaimState(target);
+        return state.active;
+    }
+    async function listClaimState(target) {
         const params = new URLSearchParams();
-        if (target?.resource)
-            params.set('resource', target.resource);
+        if (target?.model)
+            params.set('model', target.model);
         if (target?.id)
             params.set('id', target.id);
         if (target?.field)
             params.set('field', target.field);
         const suffix = params.toString();
         const body = await requestJson(`/v1/intents${suffix ? `?${suffix}` : ''}`, { method: 'GET' });
-        return body.intents ?? [];
+        return {
+            active: body.intents ?? [],
+            queue: body.queue ?? [],
+        };
     }
-    function busyError(target, intents, code) {
-        const label = [target.resource, target.id, target.field].filter(Boolean).join('/');
-        const holder = intents[0];
+    function claimedError(target, claims, code) {
+        const label = [target.model, target.id, target.field].filter(Boolean).join('/');
+        const holder = claims[0];
         const suffix = holder
             ? ` held by ${holder.actor} (${holder.action})`
             : ' held by another participant';
-        return new AbloBusyError(`Resource is busy: ${label || 'target'}${suffix}.`, { code, intents });
+        return new AbloClaimedError(`Model row is claimed: ${label || 'target'}${suffix}.`, { code, claims });
     }
     function delay(ms, signal) {
         if (signal?.aborted) {
@@ -311,12 +324,12 @@ export function createProtocolClient(options) {
             if (intents.length === 0)
                 return;
             if (pollInterval == null) {
-                throw new AbloValidationError('Cannot wait for intents over the schema-less HTTP client without `pollInterval`. ' +
-                    'Use the schema client for event-driven intent waits, pass `ifBusy: "return"`, ' +
+                throw new AbloValidationError('Cannot wait for claims over the HTTP client without `pollInterval`. ' +
+                    'Use the schema client for event-driven claim waits, pass `ifClaimed: "return"`, ' +
                     'or provide an explicit poll interval for this runtime.', { code: 'intent_wait_poll_interval_required' });
             }
             if (options?.timeout != null && Date.now() - startedAt >= options.timeout) {
-                throw busyError(target, intents, 'resource_busy_timeout');
+                throw claimedError(target, intents, 'model_claimed_timeout');
             }
             const remaining = options?.timeout == null
                 ? pollInterval
@@ -324,18 +337,23 @@ export function createProtocolClient(options) {
             await delay(remaining, options?.signal);
         }
     }
-    async function applyBusyPolicy(target, options, defaultPolicy = 'return') {
-        const policy = options?.ifBusy ?? defaultPolicy;
+    async function applyClaimedPolicy(target, options, defaultPolicy = 'return') {
+        const policy = options?.ifClaimed ?? defaultPolicy;
         if (policy === 'return')
             return;
-        const intents = await listIntents(target);
-        if (intents.length === 0)
+        const state = await listClaimState(target);
+        if (state.active.length === 0)
             return;
-        if (policy === 'fail')
-            throw busyError(target, intents, 'resource_busy');
+        if (policy === 'fail') {
+            throw claimedError(target, state.active, 'model_claimed');
+        }
+        if (options?.maxQueueDepth !== undefined &&
+            state.queue.length >= options.maxQueueDepth) {
+            throw claimedError(target, state.active, 'queue_too_deep');
+        }
         await waitForNoIntents(target, {
-            timeout: options?.busyTimeout,
-            pollInterval: options?.busyPollInterval,
+            timeout: options?.claimedTimeout,
+            pollInterval: options?.claimedPollInterval,
         });
     }
     const commits = {
@@ -480,8 +498,19 @@ export function createProtocolClient(options) {
                     target: intentOptions.target,
                     action: intentOptions.action,
                     ttl: intentOptions.ttl,
+                    queue: intentOptions.queue,
                 }),
             });
+            // The fair-queue grant is PUSHED over a WebSocket (`intent_granted`),
+            // which this stateless HTTP client doesn't hold. Returning a handle here
+            // would be a phantom holder — a lease we can't confirm is ours. So a
+            // queued response is surfaced as a typed claimed signal; callers that need
+            // to *wait* in line use the realtime (WS-backed) `ablo.<model>.claim`.
+            if (body.status === 'queued') {
+                throw new AbloClaimedError(`Target ${intentOptions.target.model}/${intentOptions.target.id} is held; ` +
+                    `queued at position ${body.position ?? 0}. The HTTP client can't await ` +
+                    `the grant (no socket) — use the realtime client to wait in line.`, { code: 'intent_queued' });
+            }
             const id = body.intent?.id ?? intentId;
             let released = false;
             const release = async () => {
@@ -504,40 +533,39 @@ export function createProtocolClient(options) {
             return waitForNoIntents(target, options);
         },
     };
-    async function retrieveResource(resourceName, id, options) {
-        await applyBusyPolicy({ resource: resourceName, id }, options);
-        const query = await requestJson(`/v1/resources/${encodeURIComponent(resourceName)}/${encodeURIComponent(id)}`, {
+    async function retrieveModel(modelName, id, options) {
+        await applyClaimedPolicy({ model: modelName, id }, options);
+        const query = await requestJson(`/v1/models/${encodeURIComponent(modelName)}/${encodeURIComponent(id)}`, {
             method: 'GET',
         });
         const data = query.data;
         if (!data) {
-            throw new AbloValidationError(`Resource not found: ${resourceName}/${id}`, { code: 'resource_not_found' });
+            throw new AbloValidationError(`Model row not found: ${modelName}/${id}`, { code: 'model_not_found' });
         }
         return {
             data,
             stamp: query.stamp ?? 0,
-            intents: query.intents ?? [],
+            claims: query.claims ?? [],
         };
     }
-    function resource(name) {
+    function model(name) {
         return {
             retrieve(id, options) {
-                return retrieveResource(name, id, options);
+                return retrieveModel(name, id, options);
             },
             async create(data, mutationOptions) {
-                const id = mutationOptions?.id ?? createResourceId();
-                await applyBusyPolicy({ resource: name, id }, mutationOptions);
+                const id = mutationOptions?.id ?? createModelId();
+                await applyClaimedPolicy({ model: name, id }, mutationOptions);
                 return commits.create({
                     intent: mutationOptions?.intent,
                     idempotencyKey: mutationOptions?.idempotencyKey,
                     readAt: mutationOptions?.readAt,
                     onStale: mutationOptions?.onStale,
                     wait: mutationOptions?.wait,
-                    timeout: mutationOptions?.timeout,
                     operations: [
                         {
                             action: 'create',
-                            resource: name,
+                            model: name,
                             id,
                             data,
                         },
@@ -545,18 +573,17 @@ export function createProtocolClient(options) {
                 });
             },
             async update(id, data, mutationOptions) {
-                await applyBusyPolicy({ resource: name, id }, mutationOptions);
+                await applyClaimedPolicy({ model: name, id }, mutationOptions);
                 return commits.create({
                     intent: mutationOptions?.intent,
                     idempotencyKey: mutationOptions?.idempotencyKey,
                     readAt: mutationOptions?.readAt,
                     onStale: mutationOptions?.onStale,
                     wait: mutationOptions?.wait,
-                    timeout: mutationOptions?.timeout,
                     operations: [
                         {
                             action: 'update',
-                            resource: name,
+                            model: name,
                             id,
                             data,
                         },
@@ -564,18 +591,17 @@ export function createProtocolClient(options) {
                 });
             },
             async delete(id, mutationOptions) {
-                await applyBusyPolicy({ resource: name, id }, mutationOptions);
+                await applyClaimedPolicy({ model: name, id }, mutationOptions);
                 return commits.create({
                     intent: mutationOptions?.intent,
                     idempotencyKey: mutationOptions?.idempotencyKey,
                     readAt: mutationOptions?.readAt,
                     onStale: mutationOptions?.onStale,
                     wait: mutationOptions?.wait,
-                    timeout: mutationOptions?.timeout,
                     operations: [
                         {
                             action: 'delete',
-                            resource: name,
+                            model: name,
                             id,
                         },
                     ],
@@ -592,7 +618,7 @@ export function createProtocolClient(options) {
         tasks,
         intents,
         commits,
-        resource,
+        model,
         agent: createAgent,
         async beginTurn(turnOptions) {
             const task = await tasks.create(turnOptions);
@@ -620,16 +646,16 @@ function normalizeIntentId(intent) {
         return intent;
     return intent?.id;
 }
-function withAgentBusyDefault(options) {
+function withAgentClaimedDefault(options) {
     return {
-        ifBusy: 'fail',
+        ifClaimed: 'fail',
         ...(options ?? {}),
     };
 }
 function stripAgentRuntimeOptions(options) {
     if (!options)
         return undefined;
-    const { intent: _intent, ifBusy: _ifBusy, busyTimeout: _busyTimeout, busyPollInterval: _busyPollInterval, ...rest } = options;
+    const { intent: _intent, ifClaimed: _ifClaimed, claimedTimeout: _claimedTimeout, claimedPollInterval: _claimedPollInterval, maxQueueDepth: _maxQueueDepth, ...rest } = options;
     return rest;
 }
 function isIntentHandleRef(input) {

package/dist/client/createInternalComponents.d.ts

@@ -7,9 +7,8 @@
  * the previous one, so the construction order matters; isolating it
  * here means `Ablo.ts` doesn't need to know the dependency order.
  *
- * Mirrors the pattern Anthropic uses: their client constructor
- * imports each `Resource` class and wires it. Ours wires the
- * sync-engine components instead.
+ * Mirrors the pattern Anthropic uses: their client constructor wires
+ * endpoint modules. Ours wires the sync-engine components instead.
  */
 import { Database } from '../Database.js';
 import { ModelRegistry } from '../ModelRegistry.js';

package/dist/client/createInternalComponents.js

@@ -7,9 +7,8 @@
  * the previous one, so the construction order matters; isolating it
  * here means `Ablo.ts` doesn't need to know the dependency order.
  *
- * Mirrors the pattern Anthropic uses: their client constructor
- * imports each `Resource` class and wires it. Ours wires the
- * sync-engine components instead.
+ * Mirrors the pattern Anthropic uses: their client constructor wires
+ * endpoint modules. Ours wires the sync-engine components instead.
  */
 import { Database } from '../Database.js';
 import { ModelRegistry, setActiveRegistry } from '../ModelRegistry.js';

package/dist/client/createModelProxy.d.ts

@@ -1,15 +1,15 @@
 /**
- * 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 type { MutationOptions } from '../interfaces/index.js';
@@ -19,12 +19,12 @@ 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, Intent, IntentStatus, IntentWaitOptions, Snapshot } from '../types/streams.js';
-export interface ModelResourceMeta {
+import type { Duration, Intent, IntentWaitOptions, Snapshot } from '../types/streams.js';
+export interface ModelClientMeta {
     readonly key: string;
     readonly typename: string;
 }
-export declare function getModelResourceMeta(resource: unknown): ModelResourceMeta | undefined;
+export declare function getModelClientMeta(modelClient: unknown): ModelClientMeta | undefined;
 export type ModelListScope = ModelScope | 'live' | 'archived' | 'all';
 export interface ModelListOptions<T> {
     where?: Partial<T>;
@@ -35,10 +35,12 @@ export interface ModelListOptions<T> {
     };
     limit?: number;
     offset?: number;
-    /** Lifecycle scope. Defaults to live rows. */
-    scope?: ModelListScope;
+    /** Lifecycle filter — `live` (default), `archived`, or `all`. Named `state`
+     *  (GitHub's open/closed/all precedent) so it doesn't collide with the
+     *  sync-group `scope`. */
+    state?: ModelListScope;
 }
-export type ModelCountOptions<T> = Pick<ModelListOptions<T>, 'where' | 'filter' | 'scope'>;
+export type ModelCountOptions<T> = Pick<ModelListOptions<T>, 'where' | 'filter' | 'state'>;
 export interface ModelLoadOptions<T> {
     /**
      * Filter for the lookup. Accepts:
@@ -74,12 +76,20 @@ export interface IntentLeaseHandle {
 export interface ModelCollaboration<T> {
     createIntent(options: {
         target: {
-            resource: string;
+            model: string;
             id: string;
             field?: string;
         };
         action: string;
         ttl?: Duration;
+        /**
+         * Block on the server's fair FIFO queue when the target is held, rather
+         * than failing. Resolves only once the lease is genuinely ours (the head
+         * of the line). `takeClaim` sets this so writers serialize on contention.
+         */
+        queue?: boolean;
+        /** Reject (don't wait) if the queue is already this deep when we join. */
+        maxQueueDepth?: number;
     }): Promise<IntentLeaseHandle>;
     createSnapshot(modelKey: string, id: string): Snapshot;
     /**
@@ -90,16 +100,32 @@ export interface ModelCollaboration<T> {
      * hold it" from "someone else holds it").
      */
     observe(target: {
-        resource: string;
+        model: string;
         id: string;
     }): Intent | null;
+    /**
+     * The reactive wait queue on a target — the FIFO line of queued intents
+     * behind the holder. Synchronous snapshot off the synced intent stream.
+     */
+    queue(target: {
+        model: string;
+        id: string;
+    }): readonly Intent[];
+    /**
+     * Re-rank the wait queue on a target (privileged — server-gated). `order` is
+     * the desired front-of-line ordering, taken from `queue(target)`.
+     */
+    reorder(target: {
+        model: string;
+        id: string;
+    }, order: readonly Intent[]): void;
     /**
      * 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;
+        model: string;
         id: string;
     }, options?: IntentWaitOptions): Promise<void>;
     /**
@@ -108,80 +134,45 @@ export interface ModelCollaboration<T> {
      */
     readonly selfParticipantId: string;
 }
-/** Options for acquiring a per-model coordination intent. */
-export interface ModelIntentAcquireOptions {
-    /** Phase shown to others while held. Defaults to `'editing'`. */
+/** Options for `claim(id, …)`. */
+export interface ClaimOptions {
+    /** Phase shown to observers while held. Defaults to `'editing'`. */
     action?: string;
-    /** Field-level target for busy badges. */
+    /** Field-level target, for fine-grained claimed-state badges. */
     field?: string;
-    /** Lease duration; runtime death is cleaned up by TTL. */
+    /** Crash-cleanup TTL — the claim auto-releases if the holder dies. */
     ttl?: Duration;
-    /** Default wait mode for `handle.update(...)`. Defaults to `confirmed`. */
-    wait?: MutationOptions['wait'];
+    /**
+     * On contention: `true` (default) queues behind the current holder and
+     * resolves once it's yours (claim-or-wait). `false` is fail-fast — if
+     * another participant already holds the row, reject immediately with
+     * `AbloClaimedError` instead of waiting (claim-or-skip). Use `false` for
+     * work-distribution dedup ("if someone else has this job, skip it") where
+     * waiting would mean double-processing.
+     */
+    wait?: boolean;
+    /**
+     * Backpressure: willing to queue, but not behind too many. If the server
+     * reports `position >= maxQueueDepth` when we join the line, reject with
+     * `AbloClaimedError('queue_too_deep')` instead of waiting. Omit to wait
+     * however deep the queue is.
+     */
+    maxQueueDepth?: number;
 }
 /**
- * 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:
+ * A claimed row: the entity's data plus an async-dispose hook, so
  *
  * ```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
+ * await ablo.weatherReports.claim('report_stockholm', async (report) => {
+ *   await ablo.weatherReports.update(report.id, { status: 'ready' });
+ * });
  * ```
  *
- * `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.
+ * releases the claim when the callback returns or throws. Read it like any row
+ * (`report.location`); write it through the flat `ablo.<model>.update(report.id, …)`
+ * verb — there is no method chaining on the claim.
  */
-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 type ClaimedRow<T> = T & AsyncDisposable;
 export interface ModelOperations<T, CreateInput> {
     /**
      * Retrieve a single entity by id from the local pool. Synchronous.
@@ -211,22 +202,57 @@ export interface ModelOperations<T, CreateInput> {
     /** Delete an entity by id — optimistic, offline-first (see `create`). */
     delete(id: string, options?: MutationOptions): Promise<void>;
     /**
-     * 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.
+     * Claim a row so other writers wait or are rejected until you're done.
+     * Reads stay open by default. Prefer the callback form for ordinary held
+     * work; it releases when the callback returns or throws. The `await using`
+     * form is also available for wider lexical scopes.
+     *
+     * ```ts
+     * await ablo.weatherReports.claim('report_stockholm', async (report) => {
+     *   const weather = await getWeather(report.location);
+     *   await ablo.weatherReports.update(report.id, { forecast: weather });
+     * });
+     * ```
+     */
+    claim(id: string, options?: ClaimOptions): Promise<ClaimedRow<T>>;
+    claim<R>(id: string, work: (row: ClaimedRow<T>) => Promise<R> | R, options?: ClaimOptions): Promise<R>;
+    /**
+     * Read who's coordinating on a row — the current holder (who, phase,
+     * until when), or `null` when free. Synchronous and reactive; for
+     * observers/UI. Never blocks.
+     */
+    claimState(id: string): Intent | null;
+    /**
+     * The wait queue on a row — who's lined up behind the holder and what each
+     * intends. Reactive snapshot (synced from the server, like `activity`);
+     * returns a Stripe-style list envelope, FIFO order, empty when no one waits.
+     *
+     * ```ts
+     * const { data } = ablo.decks.queue('deck_1');
+     * // → [{ heldBy: 'agent:summarizer', action: 'editing', position: 0 }, …]
+     * ```
+     */
+    queue(id: string): {
+        readonly object: 'list';
+        readonly data: readonly Intent[];
+    };
+    /**
+     * Re-rank the wait queue on a record — move waiters to the front in the
+     * given order. Pass the `Intent[]` from `queue(id).data`, reordered. A
+     * privileged operation: the server gates it (the caller needs the
+     * `intent.reorder` capability), so it's fire-and-forget — the new order
+     * arrives reactively through `queue(id)`.
      *
      * ```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
+     * const { data } = ablo.decks.queue('deck_1');
+     * ablo.decks.reorder('deck_1', [data[2], data[0], data[1]]); // promote #2
      * ```
      */
-    intent(id: string): ModelIntentHandle<T>;
-    /** Subscribe to changes (callback called on every change). */
-    subscribe(callback: (entities: T[]) => void, options?: ModelListOptions<T>): () => void;
+    reorder(id: string, order: readonly Intent[]): void;
+    /** Release a claim you hold early. Usually implicit (scope exit). */
+    release(id: string): Promise<void>;
+    /** Listen for changes (callback called on every change). */
+    onChange(callback: (entities: T[]) => void, options?: ModelListOptions<T>): () => void;
     /**
      * Load matching rows into the local graph if they are not already
      * present. Single-flight: concurrent calls with the same args share