@abloatai/ablo 0.17.0 → 0.19.0

package/dist/sync/createClaimStream.d.ts

@@ -10,7 +10,7 @@
  *
  * Wire contract (apps/sync-server/src/hub/types.ts):
  *   • Outbound: `{ type: 'claim_begin', payload: { claimId,
- *       entityType, entityId, action, field?, estimatedMs? } }`
+ *       entityType, entityId, reason, field?, estimatedMs? } }`
  *   • Outbound: `{ type: 'claim_abandon', payload: { claimId,
  *       entityType?, entityId? } }`
  *   • Inbound (via presence): `event.activeClaims: Claim[]`
@@ -22,12 +22,19 @@
  * deletes.
  */
 import type { SyncWebSocket } from './SyncWebSocket.js';
-import type { ClaimStream } from '../types/streams.js';
+import type { ClaimOptions, Claim, ClaimStream, PresenceTarget } from '../types/streams.js';
 export interface ClaimStreamConfig {
     /** Identity used to filter our own active claims out of `others`. */
     participantId: string;
 }
 export interface AttachableClaimStream extends ClaimStream {
+    /**
+     * INTERNAL lease mint — sends the `claim_begin` frame and returns a held
+     * {@link Claim} (no row `data`; the model door reads the row and stamps it).
+     * Not part of the public `ClaimStream` surface: the only public way to take a
+     * claim is `ablo.<model>.claim({ id })`, which builds on this.
+     */
+    claim(target: PresenceTarget, opts?: ClaimOptions): Claim;
     attach(transport: SyncWebSocket): void;
     dispose(): void;
 }

package/dist/sync/createClaimStream.js

@@ -10,7 +10,7 @@
  *
  * Wire contract (apps/sync-server/src/hub/types.ts):
  *   • Outbound: `{ type: 'claim_begin', payload: { claimId,
- *       entityType, entityId, action, field?, estimatedMs? } }`
+ *       entityType, entityId, reason, field?, estimatedMs? } }`
  *   • Outbound: `{ type: 'claim_abandon', payload: { claimId,
  *       entityType?, entityId? } }`
  *   • Inbound (via presence): `event.activeClaims: Claim[]`
@@ -24,6 +24,11 @@
 import { asyncIteratorFrom } from '../utils/asyncIterator.js';
 import { toMs } from '../utils/duration.js';
 import { descriptionFromMeta, participantKindFromWire, } from '../coordination/schema.js';
+import { getContext } from '../context.js';
+/** Readable target for the coordination trace: `documents:abc` / `documents:abc.title`. */
+function claimLabel(type, id, field) {
+    return field ? `${type}:${id}.${field}` : `${type}:${id}`;
+}
 export function createClaimStream(config, transport = null) {
     const { participantId } = config;
     // ── State: others' open claims, keyed by claimId ───────────────
@@ -37,6 +42,9 @@ export function createClaimStream(config, transport = null) {
     const queueByEntity = new Map();
     const entityKey = (type, id) => `${type}:${id}`;
     const EMPTY_QUEUE = Object.freeze([]);
+    // Last queue position we logged per own-claim, so advancing in line is traced
+    // once per change (not re-logged on every server re-fan of the same line).
+    const lastLoggedQueuePos = new Map();
     // ── Subscribers ──────────────────────────────────────────────────
     const listeners = new Set();
     const rejectionListeners = new Set();
@@ -96,7 +104,9 @@ export function createClaimStream(config, transport = null) {
                     continue;
                 const description = descriptionFromMeta(claim.meta);
                 activeByClaimId.set(claim.claimId, {
+                    object: 'claim',
                     id: claim.claimId,
+                    status: 'active',
                     heldBy: event.userId,
                     participantKind: participantKindFromWire(event.participantKind, event.isAgent),
                     target: {
@@ -107,10 +117,10 @@ export function createClaimStream(config, transport = null) {
                         field: claim.field,
                         meta: claim.meta,
                     },
-                    reason: claim.action,
+                    reason: claim.reason,
                     ...(description ? { description } : {}),
                     ttlSeconds: Math.max(0, Math.floor((claim.expiresAt - Date.now()) / 1000)),
-                    announcedAt: claim.declaredAt,
+                    createdAt: claim.declaredAt,
                     expiresAt: claim.expiresAt,
                 });
                 mutated = true;
@@ -122,6 +132,12 @@ export function createClaimStream(config, transport = null) {
         unsubs.push(t.subscribe('claim_rejected', (rejection) => {
             if (!rejection.claimId)
                 return;
+            if (ownClaims.has(rejection.claimId)) {
+                const tgt = rejection.target
+                    ? claimLabel(rejection.target.entityType, rejection.target.entityId, rejection.target.field)
+                    : rejection.claimId;
+                getContext().logger.info(`claim: rejected ${tgt}${rejection.heldBy ? ` — held by ${rejection.heldBy}` : ''}`, { claimId: rejection.claimId, reason: rejection.reason });
+            }
             // Drop the rejected own-claim so reconnect doesn't re-announce
             // a claim the server already rejected (would just spam both
             // sides with conflicts).
@@ -141,6 +157,10 @@ export function createClaimStream(config, transport = null) {
             const lost = payload;
             if (!lost.claimId)
                 return;
+            if (ownClaims.has(lost.claimId)) {
+                const c = ownClaims.get(lost.claimId);
+                getContext().logger.info(`claim: lost ${c ? claimLabel(c.entityType, c.entityId, c.field) : lost.claimId} (preempted or expired)`, { claimId: lost.claimId });
+            }
             // Drop the lost own-claim so reconnect doesn't re-announce a lease we
             // no longer hold.
             ownClaims.delete(lost.claimId);
@@ -166,6 +186,16 @@ export function createClaimStream(config, transport = null) {
                 queueByEntity.delete(key);
             else
                 queueByEntity.set(key, Object.freeze([...line]));
+            // If WE are in this line, trace our position (the "agent queued behind a
+            // claim" moment) — once per position change, so advancing is visible.
+            const ourIndex = line.findIndex((c) => ownClaims.has(c.id));
+            if (ourIndex >= 0) {
+                const ourId = line[ourIndex].id;
+                if (lastLoggedQueuePos.get(ourId) !== ourIndex) {
+                    lastLoggedQueuePos.set(ourId, ourIndex);
+                    getContext().logger.info(`claim: queued for ${claimLabel(p.target.type, p.target.id)} — position ${ourIndex + 1} of ${line.length}, waiting`, { claimId: ourId });
+                }
+            }
             notifyListeners();
         }));
         // (3) On reconnect, re-announce every open self-claim — the
@@ -192,8 +222,7 @@ export function createClaimStream(config, transport = null) {
                 entityId: claim.entityId,
                 path: claim.path,
                 range: claim.range,
-                // Wire field stays `action` (coordination schema); source is `reason`.
-                action: claim.reason,
+                reason: claim.reason,
                 field: claim.field,
                 meta: claim.meta,
                 estimatedMs: claim.estimatedMs,
@@ -251,6 +280,9 @@ export function createClaimStream(config, transport = null) {
         };
         ownClaims.set(claimId, claim);
         sendBegin(claimId, claim);
+        // Coordination trace (info): the creator can SEE their human/agent claims.
+        getContext().logger.info(`claim: requesting ${claimLabel(claim.entityType, claim.entityId, claim.field)} for "${claim.reason}"` +
+            (claim.queue ? ' (will queue if contended)' : ''), { claimId });
         let revoked = false;
         const revoke = () => {
             if (revoked)
@@ -258,13 +290,15 @@ export function createClaimStream(config, transport = null) {
             revoked = true;
             ownClaims.delete(claimId);
             sendAbandon(claimId, claim);
+            getContext().logger.info(`claim: released ${claimLabel(claim.entityType, claim.entityId, claim.field)}`, { claimId });
         };
         return {
             object: 'claim',
-            claimId,
+            id: claimId,
+            status: 'active',
             reason: args.reason,
             target: {
-                model: args.entityType,
+                type: args.entityType,
                 id: args.entityId,
                 path: args.path,
                 range: args.range,

package/dist/sync/participants.d.ts

@@ -1,12 +1,13 @@
 import type { SyncWebSocket } from './SyncWebSocket.js';
 import type { Schema, SchemaRecord } from '../schema/schema.js';
-import type { ActiveClaim, Activity, EntityRef, ClaimHandle, ClaimStream, Peer, PresenceStream, PresenceTarget } from '../types/streams.js';
+import type { Claim, Activity, ClaimTarget, ClaimStream, Peer, PresenceStream, PresenceTarget } from '../types/streams.js';
+import type { AttachableClaimStream } from './createClaimStream.js';
 /**
  * Scope accepted by participant APIs. The normal SDK shape is an
  * entity target (`{ type, id }`). Raw sync-group strings remain an
  * advanced transport escape hatch.
  */
-export type ParticipantScope = EntityRef | readonly EntityRef[] | string | readonly string[] | {
+export type ParticipantScope = ClaimTarget | readonly ClaimTarget[] | string | readonly string[] | {
     readonly syncGroup: string;
 } | {
     readonly syncGroups: readonly string[];
@@ -44,7 +45,7 @@ export interface ParticipantJoinOptions {
 }
 export interface ScopedPresence {
     readonly self: Peer;
-    readonly focus: EntityRef | null;
+    readonly focus: ClaimTarget | null;
     readonly others: ReadonlyArray<Peer>;
     update(activity: Activity): void;
     reading(detail?: string): void;
@@ -66,15 +67,15 @@ export interface ScopedClaimOptions {
     readonly ttl?: import('../types/streams.js').Duration;
 }
 export interface ScopedClaims {
-    readonly focus: EntityRef | null;
-    readonly others: ReadonlyArray<ActiveClaim>;
+    readonly focus: ClaimTarget | null;
+    readonly others: ReadonlyArray<Claim>;
     /**
      * Claim an exclusive claim on the participant's focus target (or
      * an explicit override via `opts.target`). Single verb — the old
      * `editing / writing / announce / claim(reason, opts)` overloads
      * collapsed into this one method.
      */
-    claim(opts?: ScopedClaimOptions): ClaimHandle;
+    claim(opts?: ScopedClaimOptions): Claim;
     onRejected(listener: Parameters<ClaimStream['onRejected']>[0]): () => void;
     onChange(listener: () => void): () => void;
 }
@@ -84,14 +85,14 @@ export interface ParticipantFocusOptions {
 }
 export interface JoinedParticipant {
     /** Current exact thing this participant is reading/editing. */
-    readonly target: EntityRef | null;
-    readonly focusTarget: EntityRef | null;
+    readonly target: ClaimTarget | null;
+    readonly focusTarget: ClaimTarget | null;
     /** Transport scopes this participant is joined to for visibility/fan-out. */
     readonly syncGroups: readonly string[];
     readonly presence: ScopedPresence;
     readonly claims: ScopedClaims;
     readonly peers: ReadonlyArray<Peer>;
-    readonly activeClaims: ReadonlyArray<ActiveClaim>;
+    readonly activeClaims: ReadonlyArray<Claim>;
     focus(target: PresenceTarget, options?: ParticipantFocusOptions): JoinedParticipant;
     leave(): void;
     [Symbol.asyncDispose](): Promise<void>;
@@ -104,11 +105,11 @@ export interface ParticipantManagerConfig {
     readonly ready: () => Promise<void>;
     readonly getTransport: () => SyncWebSocket | null;
     readonly presence: PresenceStream;
-    readonly claims: ClaimStream;
+    readonly claims: AttachableClaimStream;
     readonly schema?: Schema<SchemaRecord>;
 }
 export declare function createParticipantManager(config: ParticipantManagerConfig): ParticipantManager;
 export declare function resolveParticipantSyncGroups(scope: ParticipantScope | undefined, schema?: Schema<SchemaRecord>): string[];
-export declare function syncGroupFromEntityRef(ref: EntityRef, schema?: Schema<SchemaRecord>): string;
+export declare function syncGroupFromEntityRef(ref: ClaimTarget, schema?: Schema<SchemaRecord>): string;
 export declare function parseParticipantTtlSeconds(value: number | string | null | undefined): number | undefined;
 export declare function createParticipantClaimId(): string;

package/dist/sync/participants.js

@@ -220,20 +220,20 @@ function createJoinedParticipant(args) {
         ownHandles.add(handle);
         return {
             object: 'claim',
-            claimId: handle.claimId,
+            id: handle.id,
             reason: handle.reason,
             target: handle.target,
             async release() {
                 ownHandles.delete(handle);
-                await handle.release();
+                await handle.release?.();
             },
             revoke() {
                 ownHandles.delete(handle);
-                handle.revoke();
+                handle.revoke?.();
             },
             [Symbol.asyncDispose]: async () => {
                 ownHandles.delete(handle);
-                await handle[Symbol.asyncDispose]();
+                await handle[Symbol.asyncDispose]?.();
             },
         };
     };
@@ -262,7 +262,7 @@ function createJoinedParticipant(args) {
             return;
         left = true;
         for (const handle of Array.from(ownHandles)) {
-            handle.revoke();
+            handle.revoke?.();
             ownHandles.delete(handle);
         }
         args.presence.idle();

package/dist/transactions/TransactionQueue.d.ts

@@ -125,6 +125,7 @@ interface TransactionQueueConfig {
 }
 export declare class TransactionQueue extends EventEmitter {
     private store;
+    private lastPermanentErrorSig?;
     private _mutationExecutor;
     private get mutationExecutor();
     private executionQueue;

package/dist/transactions/TransactionQueue.js

@@ -199,6 +199,12 @@ class TransactionStore {
 }
 export class TransactionQueue extends EventEmitter {
     store = new TransactionStore();
+    // Signature of the last permanent-error we logged at `warn`. A `create`
+    // whose id already exists (`unique_violation`) is a permanent rejection
+    // that the offline queue re-drives on every reconnect/bootstrap — without
+    // this, the identical cause prints on a loop. We log the first occurrence
+    // and demote exact repeats to `debug`.
+    lastPermanentErrorSig;
     // Per-instance executor binding. Set by `setMutationExecutor(...)` from the
     // owning Ablo right after construction. Falls back to `getContext()` only
     // when unset (preserves legacy tests / SDK consumers that haven't migrated).
@@ -470,6 +476,9 @@ export class TransactionQueue extends EventEmitter {
         // promise always settles, regardless of which path produced the
         // terminal state.
         this.on('transaction:completed', (tx) => {
+            // Any successful write clears the permanent-error dedup, so a genuine
+            // recurrence after recovery warns again instead of staying demoted.
+            this.lastPermanentErrorSig = undefined;
             const r = this.confirmationResolvers.get(tx.id);
             if (r) {
                 this.confirmationResolvers.delete(tx.id);
@@ -1254,7 +1263,12 @@ export class TransactionQueue extends EventEmitter {
                             return undefined;
                         };
                         const diagnostics = readDiagnostics(error);
-                        getContext().logger.warn('[TransactionQueue] Batch commit rejected', {
+                        // Mechanic-level breadcrumb. Every batch rejection — transient
+                        // (reconnect retries it) or permanent (`handleFailure` logs the
+                        // authoritative `warn` with the same typed cause) — passes
+                        // through here. Logging it at `warn` made one rejected write
+                        // surface three identical dumps; keep it at `debug`.
+                        getContext().logger.debug('[TransactionQueue] Batch commit rejected', {
                             batchSize: batchOps.length,
                             models: batchOps.map(({ op }) => `${op.type}:${op.model}`),
                             errorType: abloErr?.type ?? error?.name,
@@ -1768,7 +1782,7 @@ export class TransactionQueue extends EventEmitter {
             // expiry (AbloAuthenticationError).
             try {
                 const abloErr = error instanceof AbloError ? error : undefined;
-                getContext().logger.warn('[TransactionQueue] Permanent error - rolling back', {
+                const details = {
                     txId: transaction.id.slice(0, 8),
                     type: transaction.type,
                     model: transaction.modelName,
@@ -1779,7 +1793,30 @@ export class TransactionQueue extends EventEmitter {
                     requestId: abloErr?.requestId,
                     message: error?.message,
                     inputKeys: transaction.data ? Object.keys(transaction.data) : undefined,
-                });
+                };
+                // A `create` whose id already exists is the benign idempotency case:
+                // "this row is already there." It's the least alarming permanent
+                // error, so it doesn't warrant a `warn` — `info` keeps it visible
+                // without crying wolf. Everything else (FK violation, auth expiry,
+                // server 500) stays at `warn`.
+                const isBenignIdempotent = transaction.type === 'create' &&
+                    (abloErr?.code === 'unique_violation' ||
+                        abloErr?.type === 'AbloIdempotencyError');
+                // Demote exact repeats (same write rejected for the same reason on
+                // each reconnect replay) to `debug` so the loop logs once.
+                const sig = `${details.type}:${details.model}:${details.modelId}:${details.errorCode ?? details.errorType}`;
+                const isRepeat = sig === this.lastPermanentErrorSig;
+                this.lastPermanentErrorSig = sig;
+                const logger = getContext().logger;
+                if (isRepeat) {
+                    logger.debug('[TransactionQueue] Permanent error - rolling back (repeat)', details);
+                }
+                else if (isBenignIdempotent) {
+                    logger.info('[TransactionQueue] Write skipped — row already exists', details);
+                }
+                else {
+                    logger.warn('[TransactionQueue] Permanent error - rolling back', details);
+                }
             }
             catch { }
             // Mark as failed immediately and rollback

package/dist/types/streams.d.ts

@@ -100,7 +100,7 @@ export interface ContextChange {
  * `range`, `field`, and `meta` are generic coordination hints for
  * products like code editors, document editors, and design tools.
  */
-export interface EntityRef {
+export interface ClaimTarget {
     readonly type: string;
     readonly id: string;
     readonly path?: string;
@@ -110,11 +110,11 @@ export interface EntityRef {
 }
 /**
  * A pointer to one entity the participant is acting on. Either a
- * typed `EntityRef` (`{ type, id, ... }`), or a tuple
+ * typed `ClaimTarget` (`{ type, id, ... }`), or a tuple
  * `['Clause', 'cl_3']` for ergonomic inline use. The verb methods
  * below accept both.
  */
-export type PresenceTarget = EntityRef | readonly [type: string, id: string];
+export type PresenceTarget = ClaimTarget | readonly [type: string, id: string];
 /**
  * Reactive livestream of what every multiplayer participant is doing.
  * Every participant gets one; it's always on, always current.
@@ -336,27 +336,12 @@ export interface ClaimOptions extends ClaimLeaseOptions {
     readonly queue?: boolean;
 }
 export interface ClaimStream {
-    /**
-     * Claim an exclusive claim on a target. Returns a handle — call
-     * `.revoke()` to cancel, let it expire via TTL, or use `await using`
-     * (TC39 explicit resource management) to auto-revoke on scope exit.
-     *
-     * Server rejects via `claim_rejected` when another participant
-     * already holds a claim on the same target. Default `reason` is
-     * `'editing'`; pass `{reason: 'writing'}` (or any string) to override.
-     *
-     * The frame ships on the open WS immediately. One method, one shape —
-     * the verb shortcuts (`editing`, `writing`, `announce`) and the
-     * scoped `claim(reason, opts)` overload were collapsed into this
-     * single primitive.
-     */
-    claim(target: PresenceTarget, opts?: ClaimOptions): ClaimHandle;
     /**
      * Reactive view of every other participant's active claims.
      * Reads return the current snapshot; pair with `subscribe(...)`
      * below to get notified on change.
      */
-    readonly others: ReadonlyArray<ActiveClaim>;
+    readonly others: ReadonlyArray<Claim>;
     /**
      * Reactive view of the wait queue on one target — the FIFO line of
      * `status: 'queued'` claims behind the current holder, each with its
@@ -425,7 +410,7 @@ export interface ClaimStream {
      * }
      * ```
      */
-    [Symbol.asyncIterator](): AsyncIterableIterator<ReadonlyArray<ActiveClaim>>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<ReadonlyArray<Claim>>;
 }
 /**
  * You LOST an claim you were HOLDING — distinct from `ClaimRejection` (a
@@ -452,95 +437,6 @@ export interface ClaimLost {
         readonly meta?: Record<string, unknown>;
     };
 }
-export interface ClaimDeclaration {
-    readonly target: EntityRef;
-    /** Human-readable reason — "rewriting title" / "restyling chart". */
-    readonly reason: string;
-    /**
-     * Seconds remaining until the server auto-expires this claim. An OUTPUT
-     * field carrying a concrete countdown, so it's a plain `number` — distinct
-     * from the input `ttl: Duration` (`'3m'`) you pass when announcing. Computed
-     * from `expiresAt - now`.
-     */
-    readonly ttlSeconds?: number;
-}
-/**
- * Handle returned from `announce(...)` / `analyzing(...)` / etc.
- *
- * Implements `Symbol.asyncDispose` so callers can write:
- *
- * ```ts
- * {
- *   await using work = participant.claims.analyzing(clause, { ttl: '3m' });
- *   // ... do the work; claim auto-revokes when the block exits
- * }
- * ```
- */
-/**
- * THE one claim handle. Returned by every claim door — the typed
- * `ablo.<model>.claim({ id })` (rich: `data`/`readAt`/`target` populated) and
- * the low-level `participant.claims.claim()` lease (minimal: `claimId` +
- * `revoke`/`release`). Row-level fields are optional precisely because the
- * low-level lease has no row snapshot; the model door fills them in.
- *
- * Implements `Symbol.asyncDispose` so callers can `await using claim = ...`
- * and have it auto-release on scope exit.
- */
-export interface ClaimHandle<T = Record<string, unknown>> extends AsyncDisposable {
-    readonly object: 'claim';
-    readonly claimId: string;
-    /**
-     * True when the grant came AFTER waiting in the server's FIFO line
-     * (`claim_granted`) — the authoritative "the row may have changed under us"
-     * signal. Absent for an immediate grant or a non-queued lease.
-     */
-    readonly waited?: boolean;
-    /**
-     * Sync watermark of the held snapshot (`data` was read at this stamp). Writes
-     * carrying the handle use it as the `readAt` stale guard. Present for
-     * model-scoped claims; absent for low-level leases.
-     */
-    readonly readAt?: number;
-    readonly target: {
-        readonly model: string;
-        readonly id: string;
-        readonly field?: string;
-        readonly path?: string;
-        readonly range?: TargetRange;
-        readonly meta?: Record<string, unknown>;
-    };
-    /**
-     * The human-readable phase this claim represents — `'editing'`, `'writing'`,
-     * `'forecasting'`. The SAME word on every claim surface (inputs and outputs);
-     * distinct from the CRUD operation (`CommitOperationInput.action`). Defaults
-     * to `'editing'`. Serialized on the wire as `action`.
-     */
-    readonly reason: string;
-    readonly description?: string;
-    /** Row snapshot — populated by `ablo.<model>.claim`; absent on low-level leases. */
-    readonly data?: T;
-    release(): Promise<void>;
-    revoke(): void;
-}
-export interface ActiveClaim extends ClaimDeclaration {
-    readonly id: string;
-    readonly heldBy: string;
-    /**
-     * Whether the holding participant is a user (session), an agent, or a
-     * system actor. First-class field so UIs can style "agent editing X"
-     * differently from "user editing X" without string-parsing `heldBy`.
-     * Canonical `'user' | 'agent' | 'system'` — the presence/claim stream
-     * derives the value from the boolean `isAgent` wire flag (so it produces
-     * only `'user'`/`'agent'`), but the type stays the full union it shares
-     * with the HTTP claim surface and lease store.
-     */
-    readonly participantKind: ParticipantKind;
-    readonly description?: string;
-    /** Epoch-ms the claim was announced. */
-    readonly announcedAt: number;
-    /** Epoch-ms the server auto-expires it. */
-    readonly expiresAt: number;
-}
 /**
  * Every lifecycle state of a coordination claim, in one enum.
  * `active` = the current holder (the lock). `queued` = waiting in the FIFO
@@ -554,44 +450,70 @@ export interface ClaimWaitOptions {
     readonly pollInterval?: number;
     readonly signal?: AbortSignal;
 }
-/**
- * The coordination state of one entity. Self-describing on the wire via
- * `object: 'claim'`. Existence with `status: 'active'` *is* the lock;
- * the fields *are* the awareness ("agent X is editing this until Y").
- *
- * Deliberately omits a Stripe-style `next_action`: a contender's only
- * response is "wait until free, then re-read", and the runtime performs
- * that uniformly — `claim` serializes behind the holder via the server
- * FIFO queue (or low-level `claims.waitFor` to wait without claiming), and the
- * stale-context guard forces the re-read. Encoding a constant instruction
- * the engine always takes would be the kind of ceremony this object exists
- * to remove.
- */
-export interface Claim {
+export interface Claim<T = Record<string, unknown>> {
     readonly object: 'claim';
+    /** This claim's id. */
     readonly id: string;
-    readonly status: ClaimStatus;
+    /**
+     * Lifecycle state. `active` = the holder (the lock); `queued` = waiting in
+     * the FIFO line (carries `position`). Optional on shapes derived from a
+     * presence frame that don't carry it — a present entry is `active` by
+     * construction.
+     */
+    readonly status?: ClaimStatus;
     /** What is being coordinated. */
-    readonly target: EntityRef;
-    /** Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. The same
-     *  field on every claim surface; distinct from the CRUD operation. Serialized
-     *  on the wire as `action`. */
+    readonly target: ClaimTarget;
+    /**
+     * Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. The same
+     * field on every claim surface; distinct from the CRUD operation. Defaults to
+     * `'editing'`.
+     */
     readonly reason: string;
     /** Peer-visible explanation of the work being performed. */
     readonly description?: string;
-    /** Participant holding it. */
-    readonly heldBy: string;
-    readonly participantKind: ParticipantKind;
+    /** Participant holding it. Absent on a handle you hold for yourself. */
+    readonly heldBy?: string;
     /**
-     * Epoch-ms the holder opened it. Optional until the lease wire carries
-     * it — derived shapes (e.g. mapped from a presence frame) may omit it.
+     * Whether the holder is a user (session), agent, or system actor — so UIs
+     * style "agent editing X" vs "user editing X" without string-parsing
+     * `heldBy`. Present on observed claims; absent on your own fresh handle.
      */
+    readonly participantKind?: ParticipantKind;
+    /** Epoch-ms the holder opened it. */
     readonly createdAt?: number;
     /** Epoch-ms the server auto-expires it if the holder doesn't finish. */
-    readonly expiresAt: number;
+    readonly expiresAt?: number;
+    /**
+     * Seconds remaining until auto-expiry — an OUTPUT countdown (plain `number`),
+     * distinct from the input `ttl: Duration` (`'3m'`) you pass when claiming.
+     */
+    readonly ttlSeconds?: number;
     /**
      * 0-based place in the FIFO line — present only when `status: 'queued'`
-     * (`0` = next in line behind the holder). Absent for the active holder.
+     * (`0` = next behind the holder). Absent for the active holder.
      */
     readonly position?: number;
+    /**
+     * True when the grant came AFTER waiting in the server's FIFO line
+     * (`claim_granted`) — the authoritative "the row may have changed under us"
+     * signal. Absent for an immediate (uncontended) grant.
+     */
+    readonly waited?: boolean;
+    /**
+     * Sync watermark of the held snapshot (`data` was read at this stamp). Writes
+     * carrying the claim use it as the `readAt` stale guard. Present on a claim
+     * you hold.
+     */
+    readonly readAt?: number;
+    /** Row snapshot under the lease — present on a claim you hold. */
+    readonly data?: T;
+    /**
+     * Release the lease. Present only on a claim you HOLD (returned by
+     * `ablo.<model>.claim`); absent on observed peer claims.
+     */
+    release?(): Promise<void>;
+    /** Synchronously abandon the lease. Present only on a claim you hold. */
+    revoke?(): void;
+    /** Auto-release on `await using` scope exit. Present only on a held claim. */
+    [Symbol.asyncDispose]?(): PromiseLike<void>;
 }

package/dist/wire/errorEnvelope.d.ts

@@ -8,6 +8,19 @@ export interface ErrorEnvelope {
     readonly message: string;
     readonly doc_url?: string;
     readonly request_id?: string;
+    /** Aggregate field-level failures — so one 4xx can report EVERY invalid input
+     *  at once (schema push, batch commit, CLI-arg validation) instead of failing
+     *  on the first. `param` stays the single-field convenience case. (RFC 9457
+     *  `errors[]` / JSON:API `errors[]` / Google `BadRequest.fieldViolations[]`.) */
+    readonly errors?: ReadonlyArray<{
+        readonly code?: string;
+        readonly message: string;
+        readonly param?: string;
+    }>;
+    /** Typed-details slot: `AbloError.toJSON()` spreads its `details` (e.g.
+     *  `missingIds`, `conflicts`, `retryAfterSeconds`) as top-level members.
+     *  Consumers MUST ignore members they don't recognize (forward-compat). */
+    readonly [key: string]: unknown;
 }
 /** {@link AbloError} subclass → default HTTP status. The subclass is chosen to
  *  match status semantics (a validation error is a 400, a permission error a

package/docs/coordination.md

@@ -25,6 +25,22 @@ one answer to "how do two agents not clobber each other" — then covers the
 (`claim` · `claim.state` · `claim.queue` · `claim.release` · [writing under a
 claim](#writing-under-a-claim)), and the [errors](#errors) you can catch.
 
+> **Before anything else: one identity per agent.** Coordination excludes
+> *participants*, and a participant **is the key**, not the client object. The
+> server derives identity from the credential's scope — so **N clients sharing
+> one `sk_`/`ek_` are one participant**: they all see the same `heldBy`, never
+> queue behind each other, and a "second" claimer silently re-takes the lease it
+> already holds (no mutual exclusion). To get real per-agent exclusion, mint a
+> **distinct scoped `rk_` per agent** and bind a client to it:
+>
+> ```ts
+> const { token } = await ablo.sessions.create({ agent: { id: `agent-${i}` } }); // rk_
+> const agent = Ablo({ schema, apiKey: token }); // this agent's own participant
+> ```
+>
+> Now `agent-0` holds while `agent-1`/`agent-2` queue in FIFO order and drain in
+> turn. See [sessions](./sessions.md#agent-sessions-rk_) for the minting flow.
+
 ---
 
 ## The model — three layers, one decision