@abloatai/ablo 0.26.0 → 0.28.0

package/dist/types/streams.d.ts

@@ -1,20 +1,20 @@
 /**
- * Multiplayer stream types.
+ * The types for real-time multiplayer coordination.
  *
- * Ablo treats humans and agents as participants on live application
- * entities. Participants announce what they are reading or editing,
- * claim before writing, and capture context watermarks before
- * long-running AI work. The customer keeps their own schema, agent
- * stack, tools, prompts, and product policy; the sync engine provides
- * the shared coordination substrate.
+ * Ablo treats people and AI agents alike as participants working on live
+ * application entities. A participant announces what it is reading or editing,
+ * claims an entity before writing to it, and captures a context snapshot before
+ * starting long-running AI work. You keep your own schema, agent stack, tools,
+ * prompts, and product rules; this package provides the shared coordination
+ * layer underneath.
  */
 import type { InferModel, Schema } from '../schema/schema.js';
 import type { TargetRange, OnStaleMode, WireClaim, ClaimRejection, PresenceKind, ParticipantKind } from '../coordination/schema.js';
 export type { TargetRange, OnStaleMode, WireClaim, ClaimRejection, PresenceKind, ParticipantKind };
 /**
- * Any JSON-serializable value. Used where the SDK accepts free-form
- * metadata that will be persisted / transported as JSON — avoids
- * `unknown` drift while preserving flexibility.
+ * Any JSON-serializable value. Used where the SDK accepts free-form metadata
+ * that is stored or transported as JSON — more precise than `unknown` while
+ * still allowing any JSON shape.
  */
 export type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
     readonly [key: string]: JsonValue;
@@ -22,14 +22,14 @@ export type JsonValue = string | number | boolean | null | readonly JsonValue[]
 import type { ParticipantRef } from './participant.js';
 export type { ParticipantRef } from './participant.js';
 /**
- * Whether the human explicitly approved a change. Open-source
- * consumers that don't track approval keep `auto` as the default.
+ * Whether a person explicitly approved a change. If you don't track approval,
+ * leave it at the default of `'auto'`.
  */
 export type ConfirmationState = 'auto' | 'previewed' | 'approved' | 'required_human_approval' | 'auto_historical';
 /**
- * Wire-shape of a single sync delta. Carries the dual-attribution
- * fields (`actor`, `onBehalfOf`, `capabilityId`, `confirmationState`,
- * `causedByTaskId`) that the audit substrate stamps onto each row.
+ * The wire shape of a single change on the sync stream. Alongside the change
+ * itself, it carries attribution fields — `actor`, `onBehalfOf`,
+ * `capabilityId`, and `confirmationState` — recorded on each row for auditing.
  */
 export interface AgentDelta {
     id: number;
@@ -38,38 +38,40 @@ export interface AgentDelta {
     modelId: string;
     data: Record<string, unknown>;
     previousData?: Record<string, unknown>;
-    /** Who DID the action. */
+    /** Who performed the action. */
     actor?: ParticipantRef | null;
-    /** On WHOSE AUTHORITY the actor acted. */
+    /** The participant on whose authority the actor acted. */
     onBehalfOf?: ParticipantRef | null;
-    /** Capability that authorized this commit. */
+    /** The capability that authorized this commit. */
     capabilityId?: string | null;
-    /** Whether the human explicitly approved the change. */
+    /** Whether a person explicitly approved the change. */
     confirmationState?: ConfirmationState | null;
-    /** Agent-task id that caused this commit, if any. Dormant on new client
-     *  writes (turns/tasks removed); may hold historical values. */
+    /** The id of the agent task that caused this commit, if any. */
     causedByTaskId?: string | null;
     createdAt: string;
 }
 /**
- * Flat snapshot view returned from `participant.snapshot(...)`.
+ * A flat, point-in-time view of application data returned by
+ * `participant.snapshot(...)`. Capture it before long-running AI work, then
+ * detect whether the data changed underneath while that work ran.
  *
- *   - Per-model buckets: `snap.<modelName>[id] → entity` — typed from
- *     the schema via `InferModel`, NOT `unknown`. So
- *     `snap.clauses[clauseId].text` has `string` (or whatever Zod
- *     inferred from the model's shape).
- *   - `stamp` — opaque version marker; thread into writes as
- *     `{ readAt: snap.stamp }` so the server can reject stale writes.
- *   - `signal` — AbortSignal that fires if any captured entity
- *     receives a delta during the window. Pass into the LLM call so
- *     mid-generation invalidations abort the token stream instead of
- *     completing against a dead snapshot.
- *   - `onChange(fn)` — callback form for non-abort use cases (logging,
- *     UI flags, partial regeneration). Returns an unsubscribe.
+ *   - Per-model buckets: `snap.<modelName>[id]` returns the entity, typed from
+ *     your schema (via `InferModel`) rather than as `unknown` — so, for
+ *     example, `snap.clauses[clauseId].text` is a `string`.
+ *   - `stamp` — an opaque version marker. Thread it into writes as
+ *     `{ readAt: snap.stamp }` so the server can reject a write made against
+ *     stale data.
+ *   - `signal` — an `AbortSignal` that fires if any captured entity receives a
+ *     change during the window. Pass it into your LLM call so a mid-generation
+ *     change aborts the token stream instead of completing against a snapshot
+ *     that is no longer current.
+ *   - `onChange(fn)` — a callback alternative to `signal` for cases that don't
+ *     abort, such as logging, UI flags, or partial regeneration. Returns an
+ *     unsubscribe function.
  *
- * The per-model buckets collide with the three concurrency fields if
- * you name a model `stamp` / `signal` / `onChange`. We throw at
- * snapshot time with a clear error so the mistake is loud.
+ * The per-model buckets share the object with `stamp`, `signal`, and
+ * `onChange`, so naming a model `stamp`, `signal`, or `onChange` collides.
+ * Snapshot creation throws a clear error in that case.
  */
 export type Snapshot<TSchema extends Schema = Schema, ModelName extends keyof TSchema['models'] = keyof TSchema['models']> = {
     readonly stamp: number;
@@ -84,15 +86,14 @@ export interface ContextChange {
     readonly severity: 'semantic' | 'metadata';
 }
 /**
- * Mutation-time staleness mode. Passed on every write that follows a
- * snapshot. Defaults to `'reject'` when `readAt` is provided without
- * `onStale`.
+ * The staleness mode for a write that follows a snapshot. When `readAt` is
+ * provided without an `onStale` mode, it defaults to `'reject'`.
  */
 /**
- * A pointer to one entity, optionally narrowed to a structured
- * subtarget. `type` and `id` are customer schema vocabulary; `path`,
- * `range`, `field`, and `meta` are generic coordination hints for
- * products like code editors, document editors, and design tools.
+ * A pointer to one entity, optionally narrowed to a part of it. `type` and `id`
+ * come from your schema; `path`, `range`, `field`, and `meta` are
+ * general-purpose hints for finer-grained coordination in tools like code
+ * editors, document editors, and design tools.
  */
 export interface ClaimTarget {
     readonly type: string;
@@ -103,33 +104,31 @@ export interface ClaimTarget {
     readonly meta?: Record<string, unknown>;
 }
 /**
- * A pointer to one entity the participant is acting on. Either a
- * typed `ClaimTarget` (`{ type, id, ... }`), or a tuple
- * `['Clause', 'cl_3']` for ergonomic inline use. The verb methods
- * below accept both.
+ * A pointer to the entity a participant is acting on. Either a
+ * {@link ClaimTarget} object or a `[type, id]` tuple such as `['Clause', 'cl_3']`
+ * for concise inline use. The verb methods below accept either form.
  */
 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.
+ * A reactive, always-on stream of what every participant is doing. Each
+ * participant has one, and it stays current for as long as the connection is
+ * open.
  */
 export interface PresenceStream {
     /**
-     * This participant's own broadcast state. Mirrors what every other
-     * participant sees for this one. Read-only from the owner's side —
-     * mutate via `update(...)` below.
+     * This participant's own broadcast state — the same thing every other
+     * participant sees for it. Read-only here; change it through `update(...)`.
      */
     readonly self: Peer;
     /**
-     * Push a new activity to the livestream. Synchronous — the sync
-     * engine ships the frame on the already-open WebSocket; there's
-     * no request-response round-trip to wait on. Callers update as
-     * often as state meaningfully changes (on read, on generate-start,
-     * on partial-output, on write, on done).
+     * Broadcast a new activity. Synchronous — the frame ships on the already-open
+     * connection, with no request-response round-trip to await. Call it as often
+     * as the activity meaningfully changes: on read, on generation start, on
+     * partial output, on write, on done.
      *
-     * Prefer the verb methods below (`editing`, `viewing`, ...) for
-     * canonical actions — they read as one-line sentences and don't
-     * force the caller to remember the action-string vocabulary.
+     * For the common actions, prefer the verb methods below (`editing`,
+     * `viewing`, and so on): they read as one line and save you from remembering
+     * the action strings.
      */
     update(activity: Activity): void;
     /** Participant is actively modifying this entity. */
@@ -141,23 +140,21 @@ export interface PresenceStream {
     /** Participant has stepped away from any specific entity. */
     idle(): void;
     /**
-     * Reactive view of every OTHER participant's current activity on
-     * this participant's sync groups. Reads return the current snapshot;
-     * pair with `onChange(listener)` below to get notified on changes.
+     * A reactive view of every other participant's current activity on this
+     * participant's sync groups. Reading it returns the current snapshot; pair it
+     * with `onChange(listener)` below to be notified when it changes.
      *
-     * An LLM pipeline can include `presence.others` in its system prompt
-     * so the model literally reasons with knowledge of what other
-     * agents are doing right now: "copy-bot is generating a new title
-     * for slide 5; don't duplicate that work."
+     * You can drop `presence.others` into an LLM's system prompt so the model
+     * reasons about what other agents are doing right now — for example,
+     * "copy-bot is generating a new title for slide 5; don't duplicate that work."
      */
     readonly others: readonly Peer[];
     /** Subset of `others` filtered to a specific sync group. */
     othersIn(syncGroup: string): readonly Peer[];
     /**
-     * Framework-agnostic reactivity primitive. Register a callback that
-     * fires every time `others` / `othersIn(...)` content changes (a
-     * peer joined, left, or updated its activity). Returns an
-     * unsubscribe fn.
+     * A framework-agnostic reactivity hook. Register a callback that fires
+     * whenever `others` or `othersIn(...)` changes — a peer joined, left, or
+     * updated its activity. Returns a function that unsubscribes.
      *
      * React binding:
      * ```ts
@@ -179,9 +176,9 @@ export interface PresenceStream {
      */
     onChange(listener: () => void): () => void;
     /**
-     * Async-iterable view of the peer roster. Each iteration yields the
-     * current `others` snapshot on every mutation — so the consumer
-     * sees the world as it changes without registering a callback.
+     * An async-iterable view of the peer roster. Each iteration yields the
+     * current `others` snapshot whenever it changes, so you can watch the world
+     * update without registering a callback.
      *
      * ```ts
      * for await (const peers of participant.presence) {
@@ -190,24 +187,20 @@ export interface PresenceStream {
      * }
      * ```
      *
-     * Each `for await` creates an independent iterator — two loops on
-     * the same stream both see every update; they don't steal values
-     * from each other. Breaking out of the loop (or throwing) tears
-     * down the underlying subscription cleanly via the iterator's
-     * `return()` hook.
+     * Each `for await` gets an independent iterator — two loops on the same
+     * stream both see every update rather than stealing values from each other.
+     * Breaking out of the loop, or throwing, tears the subscription down cleanly.
      */
     [Symbol.asyncIterator](): AsyncIterableIterator<readonly Peer[]>;
 }
 /**
- * What a participant is currently doing. This is BOTH the SDK and the
- * wire shape — Ablo broadcasts presence on the same WebSocket frame
- * format (`presence_update`) the sync-server has always accepted, so
- * the canonical activity type and the wire activity field are one and
- * the same.
+ * What a participant is currently doing. This type is both the SDK shape and
+ * the wire shape: a presence broadcast on the `presence_update` frame carries
+ * exactly these fields.
  *
- * Every activity is about a single entity-in-focus. Agents that reason
- * over multiple entities call `presence.update(...)` whenever focus
- * shifts; other participants see the transition in real time.
+ * Every activity is about one entity in focus. An agent working across several
+ * entities calls `presence.update(...)` each time its focus shifts, and other
+ * participants see the change in real time.
  */
 export interface Activity {
     /** Entity type the participant is focused on (e.g. "Slide", "Document"). */
@@ -232,34 +225,26 @@ export interface Activity {
     /** Human-readable detail — "slide 3", "cell A1:B5", etc. */
     readonly detail?: string;
     /**
-     * Backpressure signal — load factor in `[0.0, 1.0]`. When set,
-     * orchestrator agents reading peer activity can route work around
-     * overloaded fleet members. Convention: `0.0` = idle, `1.0` = at
-     * capacity, intermediate values = "I have headroom but prefer not."
-     * Optional — agents that don't participate in load-aware routing
-     * leave this unset; orchestrators ignore them in load calculations.
-     * Hub treats it opaquely.
+     * A backpressure signal in the range `[0.0, 1.0]`. When set, orchestrator
+     * agents reading peer activity can route work away from busy participants:
+     * `0.0` means idle, `1.0` means at capacity, and values in between mean "I
+     * have headroom but would rather not." Optional — agents that don't take part
+     * in load-aware routing leave it unset, and orchestrators ignore them when
+     * balancing load. The server passes it through without interpreting it.
      */
     readonly loadFactor?: number;
     /**
-     * Backpressure gate — explicit signal for new work assignments.
-     * Defaults to true when unset (everyone accepts work by default).
-     * Set false during graceful shutdown, capacity exhaustion, or when
-     * the agent is committed to a long-running step it cannot preempt.
-     * Orchestrators MUST treat false as "skip this peer for new work,"
-     * and SHOULD treat true with high `loadFactor` as "available but
-     * deprioritize."
+     * A backpressure gate for new work assignments. It defaults to `true` when
+     * unset, so everyone accepts work by default. Set it to `false` during
+     * graceful shutdown, at capacity, or while committed to a long step that
+     * can't be interrupted. Orchestrators should skip a peer showing `false`, and
+     * treat `true` with a high `loadFactor` as available but lower priority.
      */
     readonly acceptingNewWork?: boolean;
 }
 /**
- * One participant's live state as seen by everyone else in scope.
- *
- * This is the canonical engine vocabulary. The server's older wire
- * frame still emits `userId` / `isAgent` / `updatedAt`; those names
- * are deprecated and translated at the inbound boundary
- * (`createPresenceStream`) into the names below. New code reads and
- * writes this shape only.
+ * One participant's live state as seen by everyone else in scope — its
+ * identity, sync groups, current {@link Activity}, and any open claims.
  */
 export interface Peer {
     readonly participantKind: ParticipantKind;
@@ -269,7 +254,7 @@ export interface Peer {
     readonly activity: Activity;
     /** Server timestamp of the most recent frame from this participant. */
     readonly lastActive: string;
-    /** Pending-mutation claims this participant has declared. */
+    /** The claims this participant currently holds. */
     readonly activeClaims?: readonly Claim[];
 }
 /** Outbound `presence_update` payload. */
@@ -279,31 +264,28 @@ export interface PresenceUpdatePayload {
     readonly isAgent?: boolean;
 }
 /**
- * Claim broadcasts — "I'm about to do X on Y." Broadcasts flow on
- * the same WS as presence, so every participant sees them in real
- * time. Cooperative mutex: the claim doesn't enforce exclusion; it
- * announces. Other agents observe and yield. This is cheaper and
- * more flexible than a central lock table and composes with presence.
+ * A claim is a broadcast that says "I'm about to work on this entity." Claims
+ * travel on the same connection as presence, so every participant sees them in
+ * real time. They are cooperative rather than enforced: a claim announces
+ * intent, and other agents observe it and yield. This is lighter and more
+ * flexible than a central lock table and composes with presence.
  */
 /**
- * Options common to every verb-style claim announcement
- * (`claims.analyzing`, `.drafting`, etc.).
- *
- * The one required field is the *target* — everything else is a
- * sensible default. Prefer the verb methods in `ClaimStream` below
- * (`analyzing(entity, { ttl: '3m' })`) over the raw `announce(...)`
- * escape hatch.
+ * The options shared by every verb-style claim announcement
+ * (`claims.analyzing`, `claims.drafting`, and so on). The only required piece
+ * is the target; everything else has a sensible default. Prefer the verb
+ * methods on {@link ClaimStream} — for example `analyzing(entity, { ttl: '3m' })`
+ * — over the raw `announce(...)` call.
  */
 export interface ClaimLeaseOptions {
     /**
-     * How long before the server auto-expires this claim if the
-     * participant doesn't finish the work. Accepts either a number (in
-     * seconds — back-compat with `ttlSeconds`) or a duration string:
-     * `'500ms'`, `'30s'`, `'3m'`, `'24h'`.
+     * How long before the server auto-expires this claim if the participant
+     * hasn't finished. Accepts a number of seconds or a duration string such as
+     * `'500ms'`, `'30s'`, `'3m'`, or `'24h'`.
      */
     readonly ttl?: Duration;
 }
-/** Re-export of the duration helper shape. See `./duration.ts`. */
+/** The duration value type used by `ttl`, re-exported for convenience. */
 export type Duration = import('../utils/duration.js').Duration;
 export interface ClaimOptions extends ClaimLeaseOptions {
     /**
@@ -320,69 +302,65 @@ export interface ClaimOptions extends ClaimLeaseOptions {
      */
     readonly description?: string;
     /**
-     * Join the server's fair FIFO queue on contention instead of being
-     * rejected. The grant arrives asynchronously (`claim_acquired` if the
-     * target was free, `claim_granted` once promoted to the head of the line).
-     * The low-level `claim` returns its handle immediately regardless; callers
-     * that need to *wait* for the grant use the awaiting wrappers
-     * (`ablo.<model>.claim`), which pair this flag with `awaitClaimGrant`.
+     * On contention, join the server's fair first-in-first-out queue instead of
+     * being rejected. The grant then arrives asynchronously — immediately if the
+     * target was free, or once you reach the head of the line. To wait for the
+     * grant, use `ablo.<model>.claim`, which pairs this flag with the wait.
      */
     readonly queue?: boolean;
 }
 export interface ClaimStream {
     /**
-     * Reactive view of every other participant's active claims.
-     * Reads return the current snapshot; pair with `subscribe(...)`
-     * below to get notified on change.
+     * A reactive view of every other participant's active claims. Reading it
+     * returns the current snapshot; pair it with `onChange(...)` to be notified
+     * when it changes.
      */
     readonly others: readonly Claim[];
     /**
-     * Reactive view of the wait queue on one target — the FIFO line of
-     * `status: 'queued'` claims behind the current holder, each with its
-     * `reason`, `heldBy`, and `position`. Synced from the server's per-entity
-     * `claim_queue` frame; empty when no one's waiting. Pair with
-     * `subscribe(...)` for change notifications.
+     * A reactive view of the wait queue on one target — the ordered line of
+     * queued claims behind the current holder, each carrying its `reason`,
+     * `heldBy`, and `position`. Empty when no one is waiting. Pair it with
+     * `onChange(...)` for change notifications.
      */
     queueFor(target: PresenceTarget): readonly Claim[];
     /**
-     * Re-rank the wait queue on a target — move the listed waiters to the front
-     * in the given order; unlisted waiters keep their relative FIFO order behind
-     * them. Pass the `Claim[]` from `queueFor(target)` in the order you want
-     * (each `Claim` carries its `heldBy` + `id`). Privileged: the server gates
-     * it (a participant lacking the `claim.reorder` capability is denied), so
-     * this is fire-and-forget — the new order arrives reactively via `queueFor`.
+     * Re-rank the wait queue on a target: move the listed waiters to the front in
+     * the given order, leaving the rest in their existing relative order behind
+     * them. Pass the claims from `queueFor(target)` in the order you want. This
+     * is privileged — the server rejects a participant that lacks the
+     * `claim.reorder` capability — and fire-and-forget: the new order arrives
+     * reactively through `queueFor`.
      */
     reorder(target: PresenceTarget, order: readonly Claim[]): void;
     /**
-     * Framework-agnostic reactivity. Same contract as
-     * `PresenceStream.subscribe` — register a listener fired on every
-     * change (announce / revoke / TTL expiry received from the server),
-     * returns an unsubscribe fn. Use `useSyncExternalStore` in React or
-     * `autorun` in MobX.
+     * A framework-agnostic reactivity hook, with the same contract as
+     * {@link PresenceStream.onChange}: register a listener that fires on every
+     * change — a claim announced, revoked, or expired — and returns a function
+     * that unsubscribes. Use `useSyncExternalStore` in React or `autorun` in
+     * MobX.
      */
     onChange(listener: () => void): () => void;
     /**
-     * Observe server-side claim rejections. Fires when the server
-     * rejects an `claims.writing(...)` / `announce(...)` call because
-     * another participant already holds an open claim on the same
-     * target (cooperative mutex → enforced at the server boundary).
+     * Observe claims the server rejected. Fires when a claim you tried to take is
+     * refused because another participant already holds an open claim on the same
+     * target.
      *
-     * Use this to surface conflicts to the user:
+     * Use it to surface conflicts to the user:
      * ```ts
      * participant.claims.onRejected((r) => {
      *   toast.error(`${r.heldBy} is editing — try again in a moment`);
      * });
      * ```
      *
-     * Returns an unsubscribe fn.
+     * Returns a function that unsubscribes.
      */
     onRejected(listener: (rejection: ClaimRejection) => void): () => void;
     /**
-     * Observe LOSING an claim you held — distinct from `onRejected` (a claim the
-     * server refused). Fires on the server's `claim_lost` frame, carrying why:
-     * `'preempted'` (a privileged participant evicted you) or `'expired'` (your
-     * TTL lapsed). Lets a holder react — re-plan vs re-claim — instead of
-     * silently discovering the lease gone via presence.
+     * Observe losing a claim you held — distinct from `onRejected`, which is a
+     * claim the server refused to grant. Fires when the server reports the loss,
+     * carrying why: `'preempted'` (a privileged participant evicted you) or
+     * `'expired'` (your lease lapsed). This lets a holder react — re-plan or
+     * re-claim — rather than discovering the lease gone through presence.
      *
      * ```ts
      * participant.claims.onLost((lost) => {
@@ -391,12 +369,12 @@ export interface ClaimStream {
      * });
      * ```
      *
-     * Returns an unsubscribe fn.
+     * Returns a function that unsubscribes.
      */
     onLost(listener: (lost: ClaimLost) => void): () => void;
     /**
-     * Async-iterable view of everyone else's open claims. Each
-     * iteration yields the current snapshot on every mutation.
+     * An async-iterable view of everyone else's open claims. Each iteration
+     * yields the current snapshot whenever it changes.
      *
      * ```ts
      * for await (const openClaims of participant.claims) {
@@ -407,11 +385,12 @@ export interface ClaimStream {
     [Symbol.asyncIterator](): AsyncIterableIterator<readonly Claim[]>;
 }
 /**
- * You LOST an claim you were HOLDING — distinct from `ClaimRejection` (a
- * claim the server refused you). Delivered via `onLost`.
+ * A notification that you lost a claim you were holding — distinct from
+ * {@link ClaimRejection}, which is a claim the server refused to grant.
+ * Delivered through `onLost`.
  */
 export interface ClaimLost {
-    /** The held claim's id that you just lost. */
+    /** The id of the claim you just lost. */
     readonly claimId: string;
     /**
      * How you lost it. `'preempted'`: a privileged participant (one holding the
@@ -432,10 +411,10 @@ export interface ClaimLost {
     };
 }
 /**
- * Every lifecycle state of a coordination claim, in one enum.
- * `active` = the current holder (the lock). `queued` = waiting in the FIFO
- * line behind the holder (carries `position`). The terminal states drop the
- * claim from the synced set.
+ * Every lifecycle state of a claim. `active` is the current holder — the lock
+ * itself. `queued` is waiting in line behind the holder and carries a
+ * `position`. The remaining states are terminal and drop the claim from the
+ * synced set.
  */
 export type ClaimStatus = 'active' | 'queued' | 'committed' | 'expired' | 'canceled';
 /** Options for waiting on a target to become free. */
@@ -449,10 +428,9 @@ export interface Claim<T = Record<string, unknown>> {
     /** This claim's id. */
     readonly id: string;
     /**
-     * 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.
+     * The claim's lifecycle state. `active` is the holder — the lock; `queued` is
+     * waiting in line and carries a `position`. It is optional on shapes derived
+     * from a presence frame, where a present entry is `active` by construction.
      */
     readonly status?: ClaimStatus;
     /** What is being coordinated. */
@@ -478,8 +456,9 @@ export interface Claim<T = Record<string, unknown>> {
     /** Epoch-ms the server auto-expires it if the holder doesn't finish. */
     readonly expiresAt?: number;
     /**
-     * Seconds remaining until auto-expiry — an OUTPUT countdown (plain `number`),
-     * distinct from the input `ttl: Duration` (`'3m'`) you pass when claiming.
+     * The seconds remaining until auto-expiry — a countdown output as a plain
+     * number, distinct from the `ttl: Duration` (such as `'3m'`) you pass in when
+     * claiming.
      */
     readonly ttlSeconds?: number;
     /**
@@ -488,36 +467,70 @@ export interface Claim<T = Record<string, unknown>> {
      */
     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.
+     * True when the grant arrived only after waiting in the server's queue — the
+     * reliable signal that the row may have changed while you waited. 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.
+     * The sync watermark at which `data` was read. A write made under this claim
+     * uses it as the `readAt` staleness 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
+     * Release the lease. Present only on a claim you hold (returned by
      * `ablo.<model>.claim`); absent on observed peer claims.
      */
-    release?(): Promise<void>;
+    release?: () => Promise<void>;
     /** Synchronously abandon the lease. Present only on a claim you hold. */
-    revoke?(): void;
+    revoke?: () => void;
+    /**
+     * Extend the lease past the liveness window — the "still working" signal
+     * for long-running tasks. Resolving means the lease is still yours, now
+     * good until the returned `expiresAt`; a lease that lapsed (and may have
+     * been granted to the next in line) rejects with an
+     * {@link ../errors.js AbloClaimedError} carrying code `claim_lost`, so the
+     * failed beat doubles as the loss notification. Each beat's extension is
+     * clamped server-side — hold a long task by beating on a cadence (pass
+     * `heartbeat` when claiming to have the SDK do this for you), not by
+     * asking once for a huge window. Present only on a claim you hold.
+     */
+    heartbeat?: (options?: Duration | ClaimHeartbeatOptions) => Promise<ClaimHeartbeat>;
     /** Auto-release on `await using` scope exit. Present only on a held claim. */
     [Symbol.asyncDispose]?(): PromiseLike<void>;
 }
+/** Options for one beat — a bare {@link Duration} is shorthand for `{ ttl }`. */
+export interface ClaimHeartbeatOptions {
+    /** Requested extension from now; the server clamps it and never shortens. */
+    readonly ttl?: Duration;
+    /**
+     * Lightweight progress the beat carries along (`{ pages: 42, of: 100 }`) —
+     * becomes the claim's peer-visible `meta.progress` (last beat wins) and
+     * dies with the lease. Durable checkpoints belong in the data itself:
+     * write a row, and every subscriber already sees it.
+     */
+    readonly details?: Record<string, unknown>;
+}
+/** The resolved value of a successful {@link Claim.heartbeat} — the lease is
+ *  still yours, now good until `expiresAt` (epoch milliseconds). */
+export interface ClaimHeartbeat {
+    readonly expiresAt: number;
+    /**
+     * How many participants wait in line behind this lease — cooperative-yield
+     * pressure. A worker that can checkpoint may release early when others
+     * wait. Absent when the server predates the field.
+     */
+    readonly queueDepth?: number;
+}
 /**
- * A claim you HOLD — the resolved value of `ablo.<model>.claim(...)`. Same
- * composition pattern as {@link PresenceTarget}: a `Claim<T>` with the
- * lease-control members made `Required` (they're optional on the base because it
- * also models observed peer claims, which lack them). Narrowing the return type
- * is what makes `await using held = await ablo.x.claim(...)` typecheck —
- * `Claim<T>`'s optional `[Symbol.asyncDispose]` is not assignable to
+ * A claim you hold — the resolved value of `ablo.<model>.claim(...)`. It is a
+ * {@link Claim} with the lease-control members (`data`, `release`, `revoke`,
+ * and the async-dispose hook) made required; they are optional on the base
+ * because that shape also models observed peer claims, which lack them. Making
+ * them required is what lets `await using held = await ablo.x.claim(...)`
+ * typecheck, since `Claim`'s optional dispose hook is not assignable to
  * `AsyncDisposable`.
  */
-export type HeldClaim<T = Record<string, unknown>> = Claim<T> & Required<Pick<Claim<T>, 'data' | 'release' | 'revoke' | typeof Symbol.asyncDispose>>;
+export type HeldClaim<T = Record<string, unknown>> = Claim<T> & Required<Pick<Claim<T>, 'data' | 'release' | 'revoke' | 'heartbeat' | typeof Symbol.asyncDispose>>;