@abloatai/ablo 0.26.0 → 0.28.0

package/dist/client/createModelProxy.d.ts

@@ -1,38 +1,36 @@
 /**
- * Per-model client factory.
+ * Builds the typed client for a single schema model — the object reached as
+ * `ablo.<model>`.
  *
- * 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 the async server reads `retrieve` / `list`, the synchronous
- * local-graph snapshots `get` / `getAll` / `getCount`, the writes
- * `create` / `update` / `delete`, the coordination namespace `claim`
- * (`claim({ id })` plus `claim.state` / `claim.queue` / `claim.release` /
- * `claim.reorder`), and `onChange`. The factory returns a plain object; the
- * client assembles the `ablo.<model>` lookup table from these.
+ * Each schema model gets one {@link ModelOperations}: the async server reads
+ * `retrieve` and `list`, the synchronous local-graph snapshots `get`, `getAll`,
+ * and `getCount`, the writes `create`, `update`, and `delete`, the coordination
+ * namespace `claim` (callable as `claim({ id })`, plus `claim.state`,
+ * `claim.queue`, `claim.release`, and `claim.reorder`), `watch`, and `onChange`.
+ * The factory returns a plain object; the client assembles the `ablo.<model>`
+ * lookup table from one of these per model.
  */
+import { AbloClaimedError } from '../errors.js';
 import { type ModelUpdater, type ContentionOptions } from './functionalUpdate.js';
 import type { MutationOptions } from '../interfaces/index.js';
 import type { ModelRegistry } from '../ModelRegistry.js';
-import type { ObjectPool } from '../ObjectPool.js';
+import type { InstanceCache } from '../InstanceCache.js';
 import type { SyncClient } from '../SyncClient.js';
-import type { HydrationCoordinator } from '../sync/HydrationCoordinator.js';
+import type { OnDemandLoader } from '../sync/OnDemandLoader.js';
 import type { JoinedParticipant } from '../sync/participants.js';
 import type { LoadWhere } from '../query/types.js';
 import { ModelScope } from '../types/index.js';
-import type { Duration, Claim, HeldClaim, ClaimWaitOptions, Snapshot, TargetRange } from '../types/streams.js';
+import type { Duration, Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, ClaimWaitOptions, Snapshot, TargetRange } from '../types/streams.js';
 export interface ModelClientMeta {
     readonly key: string;
     readonly typename: string;
 }
 export declare function getModelClientMeta(modelClient: unknown): ModelClientMeta | undefined;
 export type ModelListScope = ModelScope | 'live' | 'archived' | 'all';
-/** Options for the sync LOCAL-pool reads `get`/`getAll`/`onChange` (JS
- *  `filter`, equality `where`, lifecycle `state`). The local-reactive axis;
- *  contrast {@link ServerReadOptions} (the async server axis). */
+/** Options for the synchronous local-pool reads `get`, `getAll`, and
+ *  `onChange` — a JavaScript `filter`, an equality `where`, and a lifecycle
+ *  `state`. This is the local, reactive axis; contrast {@link ServerReadOptions},
+ *  the asynchronous server axis. */
 export interface LocalReadOptions<T> {
     where?: Partial<T>;
     /** Arbitrary local predicate. Applied after `where`. */
@@ -42,23 +40,22 @@ export interface LocalReadOptions<T> {
     };
     limit?: number;
     offset?: number;
-    /** 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`. */
+    /** Lifecycle filter — `live` (the default), `archived`, or `all`. Named
+     *  `state` so it does not collide with the sync-group `scope`. */
     state?: ModelListScope;
 }
 export type LocalCountOptions<T> = Pick<LocalReadOptions<T>, 'where' | 'filter' | 'state'>;
-/** Options for the async SERVER reads `retrieve`/`list` (operator `where` DSL,
- *  `type`, `expand`). The server-async axis; contrast {@link LocalReadOptions}
- *  (the local-reactive axis). */
+/** Options for the asynchronous server reads `retrieve` and `list` — the
+ *  operator `where` filter, `type`, and `expand`. This is the server axis;
+ *  contrast {@link LocalReadOptions}, the local, reactive axis. */
 export interface ServerReadOptions<T> {
     /**
-     * Filter for the lookup. Accepts:
-     *   - object form: `{ name: 'foo' }` (equality, array values → `IN`)
-     *   - tuple form: `[['name', 'ILIKE', '%Goldman%']]` for operators
+     * Filter for the lookup. Accepts two forms:
+     *   - object form — `{ name: 'foo' }`: equality, where an array value means `IN`
+     *   - tuple form — `[['name', 'ILIKE', '%Goldman%']]`: explicit operators
      *
-     * See `LoadWhere<T>` in `query/types.ts`. For OR semantics, run two
-     * `list()` calls and union — the wire protocol is AND-only.
+     * See {@link LoadWhere} for the full grammar. The wire protocol matches on AND
+     * only; for OR semantics, run two `list()` calls and union the results.
      */
     where?: LoadWhere<T>;
     orderBy?: {
@@ -151,36 +148,33 @@ export interface ModelCollaboration<T> {
      */
     readonly selfParticipantId: string;
     /**
-     * The local participant's kind (`'user' | 'agent' | 'system'`). Used to
-     * stamp the synthesized self-claim returned from `claim.state` when the
-     * LOCAL proxy holds the lease (server presence frames exclude one's own
-     * claims, so the holder must build its own view).
+     * The local participant's kind (`'user' | 'agent' | 'system'`). Used to stamp
+     * the synthesized self-claim returned from `claim.state` when this client
+     * holds the lease: server presence frames exclude a holder's own claims, so
+     * the holder builds its own view.
      */
     readonly selfParticipantKind?: 'user' | 'agent' | 'system';
     /**
-     * Subscribe the connection to a scope's sync group(s) (read-interest).
-     * The typed surface calls this on single-entity reads/claim observation so
-     * a Node/agent client lands in the SAME entity-scoped group the holder's
-     * claim presence fans out on — otherwise a peer subscribed only to
-     * `org:`/`user:` groups never sees claim broadcasts. Fire-and-forget and
-     * SOFT: read interest is best-effort and must never make a read reject or
-     * stall (see `AreaOfInterestManager.reconcile`). Optional so minimal test
-     * doubles can omit it. Forwards to `BaseSyncedStore.enterScope`.
+     * Subscribes the connection to a scope's sync group(s) — read interest. The
+     * typed surface calls this on single-entity reads and claim observation so a
+     * client lands in the same entity-scoped group the holder's claim presence
+     * fans out on; a peer subscribed only to broader `org:` or `user:` groups
+     * would otherwise never see claim broadcasts. Fire-and-forget and best-effort:
+     * read interest must never make a read reject or stall. Optional so minimal
+     * test doubles can omit it.
      */
     enterScope?(scope: Record<string, string>): void | Promise<void>;
     /**
-     * Pin a scope's sync group(s) (write-intent / prominence): a row this
-     * client holds an active claim on stays subscribed regardless of
-     * navigation. Same fire-and-forget, soft semantics as `enterScope`.
-     * Forwards to `BaseSyncedStore.pinScope`.
+     * Pins a scope's sync group(s) — write intent: a row this client holds an
+     * active claim on stays subscribed regardless of navigation. Same
+     * fire-and-forget, best-effort semantics as `enterScope`.
      */
     pinScope?(scope: Record<string, string>): void | Promise<void>;
     /**
-     * Open a presence/claim subscription on this model's sync group(s) and
-     * return the live participant handle. Backs `ablo.<model>.watch(ids)` —
-     * the relocation of the old `ablo.participants.join({ scope })`. WebSocket
-     * only (presence needs a socket); absent on non-ws constructions, in which
-     * case the proxy throws a clear error. Forwards to `participantManager.join`.
+     * Opens a presence and claim subscription on this model's sync group(s) and
+     * returns the live participant handle. Backs `ablo.<model>.watch(ids)`.
+     * WebSocket only, since presence needs a live socket; it is absent on other
+     * client constructions, where the proxy throws a clear error.
      */
     createWatch?(modelKey: string, ids: string | readonly string[], options?: WatchOptions): Promise<JoinedParticipant>;
 }
@@ -201,28 +195,50 @@ export interface ClaimTargetOptions<T = Record<string, unknown>> {
     /** Crash-cleanup TTL — the claim auto-releases if the holder dies. */
     ttl?: Duration;
     /**
-     * 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.
+     * Behavior under contention. `true` (the default) queues behind the current
+     * holder and resolves once the row is yours. `false` is fail-fast: if another
+     * participant already holds the row, it rejects immediately with
+     * {@link AbloClaimedError} instead of waiting. Use `false` to deduplicate
+     * distributed work ("if someone else has this job, skip it"), where waiting
+     * would mean double-processing.
      *
-     * Named `queue` to match every other claim surface — `ablo.<model>.claim`
-     * on both the WS and HTTP clients (take-a-claim is the callable `claim({ id
-     * })` on both; the HTTP reads are just awaited) and the wire. The high-level
-     * typed claim defaults it ON because it serializes writers; the low-level
-     * lease and HTTP default it OFF — they return/resolve immediately and can't
-     * transparently wait for a grant.
+     * The high-level typed claim defaults this on because it serializes writers;
+     * the low-level lease and the HTTP client default it off, since they resolve
+     * immediately and cannot transparently wait for a grant.
      */
     queue?: 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.
+     * Backpressure: queue, but not behind too many others. If the server reports a
+     * position at or beyond `maxQueueDepth` when the client joins the line, it
+     * rejects with {@link AbloClaimedError} (`queue_too_deep`) instead of waiting.
+     * Omit to wait however deep the queue is.
      */
     maxQueueDepth?: number;
+    /**
+     * Keep the lease alive for the duration of real work by beating on a
+     * cadence — the pattern for background workers whose task outlives the
+     * crash-cleanup TTL. `true` beats every third of the TTL (so two beats can
+     * fail before the lease is at risk, and a crashed worker's lease still
+     * lapses within one beat window); a duration such as `'2m'` sets the
+     * cadence explicitly. The loop stops on release. A beat answered with a
+     * definitive loss stops the loop and calls {@link onHeartbeatLost}; you can
+     * also beat manually with `held.heartbeat()`.
+     */
+    heartbeat?: true | Duration;
+    /**
+     * Called once if the auto-heartbeat learns the lease is no longer yours
+     * (expired and possibly granted onward). The loop has already stopped;
+     * abandon the work or re-claim. Any write attempted under the old lease is
+     * independently rejected by its `readAt` guard.
+     */
+    onHeartbeatLost?: (error: AbloClaimedError) => void;
+    /**
+     * Called after every successful beat (manual or auto) with the server's
+     * answer — chiefly `queueDepth`, the number of participants waiting in
+     * line behind this lease. A worker that can checkpoint may read pressure
+     * here and release early when others wait.
+     */
+    onHeartbeat?(beat: ClaimHeartbeat): void;
 }
 /** Options for `claim({ id, ... })`. */
 export interface ClaimParams<T = Record<string, unknown>> extends ClaimTargetOptions<T> {
@@ -236,7 +252,7 @@ export interface ClaimReorderParams<T = Record<string, unknown>> extends ClaimLo
     readonly order: readonly Claim[];
 }
 /**
- * A claim handle: the held entity data plus an explicit release hook, so
+ * A claim handle: the held entity data plus an explicit release hook.
  *
  * ```ts
  * const claim = await ablo.weatherReports.claim({
@@ -257,9 +273,9 @@ export interface ClaimReorderParams<T = Record<string, unknown>> extends ClaimLo
  *
  * `data` is a snapshot taken after the lease is held. Write through the flat
  * `ablo.<model>.update({ id, data, claim })` verb — the handle carries the
- * lease id and snapshot watermark for attribution + stale protection.
+ * lease id and snapshot watermark for attribution and stale-write protection.
  */
-export type { Claim, HeldClaim };
+export type { Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim };
 export type ClaimOptions<T = Record<string, unknown>> = ClaimTargetOptions<T>;
 /**
  * The coordination surface for a model, exposed as a callable namespace.
@@ -284,15 +300,15 @@ export type ClaimOptions<T = Record<string, unknown>> = ClaimTargetOptions<T>;
  * controls for UI and operators.
  */
 /**
- * Coordination reads + scheduler controls on a claim namespace, in their
- * REACTIVE (synchronous) form — `state`/`queue`/`reorder` resolve against the
- * local pool with no round-trip, which is what lets `useAblo((ablo) =>
- * ablo.x.claim.state({ id }))` read coordination state inside a React render.
+ * The coordination reads and scheduler controls on a claim namespace, in their
+ * reactive (synchronous) form: `state`, `queue`, and `reorder` resolve against
+ * the local pool with no round-trip, which is what lets a reactive selector read
+ * coordination state inside a React render.
  *
- * This is the single source of truth for the claim read surface: the stateless
- * HTTP client exposes the *awaited* projection of EXACTLY these methods
- * (`HttpClaimApi` in `Ablo.ts`, derived via {@link AwaitedClaimMethod}), so the
- * two transports can never drift — edit a signature here and HTTP follows.
+ * This is the single source of truth for the claim read surface. The stateless
+ * HTTP client exposes the awaited projection of exactly these methods (derived
+ * via {@link AwaitedClaimMethod}), so the two transports cannot drift — change a
+ * signature here and the HTTP surface follows.
  */
 export interface ClaimReadApi<T = Record<string, unknown>> {
     /**
@@ -323,10 +339,10 @@ export interface ClaimReadApi<T = Record<string, unknown>> {
 export type AwaitedClaimMethod<F> = F extends (...args: infer A) => infer R ? R extends Promise<unknown> ? (...args: A) => R : (...args: A) => Promise<R> : F;
 export interface ClaimApi<T> extends ClaimReadApi<T> {
     /**
-     * Take a claim and get an explicit held-work handle back. Returns a
-     * {@link HeldClaim} — `data`, `release`, `revoke`, and the async disposer are
-     * guaranteed present (this door always re-reads the row under the lease), so
-     * callers use `handle.data` directly and `await using` works without a guard.
+     * Takes a claim and returns an explicit held-work handle — a {@link HeldClaim}.
+     * `data`, `release`, `revoke`, and the async disposer are always present (this
+     * call re-reads the row under the lease), so callers can use `handle.data`
+     * directly and `await using` works without a guard.
      */
     (params: ClaimParams<T>): Promise<HeldClaim<T>>;
 }
@@ -358,42 +374,37 @@ export interface WatchOptions {
 }
 export interface ModelOperations<T, CreateInput> {
     /**
-     * Read a single entity by id from the **server** — async. Resolves through
-     * the 3-tier lookup (local pool → IndexedDB → network `POST /sync/query`)
-     * and lands the row in the local graph. Resolves to `undefined` when no
-     * such row exists.
+     * Reads a single entity by id from the server; asynchronous. Resolves through
+     * a three-tier lookup — local pool, then IndexedDB, then a network
+     * `POST /sync/query` — and lands the row in the local graph. Resolves to
+     * `undefined` when no such row exists.
      *
-     * This is the default "get me this entity" read and the one hosted /
-     * stateless callers want, since their local graph starts empty. For a
-     * synchronous read of an already-warm graph (a React selector) use
-     * `get(id)`.
-     *
-     * Mirrors `stripe.customers.retrieve({ id })` — network-backed.
+     * This is the default "get me this entity" read, and the one a stateless
+     * client wants, since its local graph starts empty. For a synchronous read of
+     * an already-warm graph (such as a React selector) use `get(id)`.
      */
     retrieve(params: ModelRetrieveParams): Promise<T | undefined>;
     /**
-     * List entities matching a filter from the **server** — async. Same 3-tier
-     * lookup + graph hydration as `retrieve`; single-flight deduped. Returns the
-     * matched rows.
-     *
-     * Mirrors `stripe.customers.list({...})` — network-backed. For a synchronous
-     * read of the local graph use `getAll(...)`.
+     * Lists entities matching a filter from the server; asynchronous. Uses the
+     * same three-tier lookup and graph hydration as `retrieve`, deduplicated so
+     * concurrent identical calls share one request. Returns the matched rows. For
+     * a synchronous read of the local graph use `getAll(...)`.
      */
     list(options?: ServerReadOptions<T>): Promise<T[]>;
     /**
-     * Synchronous snapshot of a single entity from the **local graph** — no
-     * network. Returns `undefined` when the row isn't resident (cold hosted
-     * client, or a `lazy` model not yet loaded). Pairs with reactive selectors:
-     * `useAblo((ablo) => ablo.<model>.get(id))`.
+     * Synchronous snapshot of a single entity from the local graph; no network.
+     * Returns `undefined` when the row is not resident (a client whose graph is
+     * still empty, or a `lazy` model not yet loaded). Pairs with reactive
+     * selectors: `useAblo((ablo) => ablo.<model>.get(id))`.
      */
     get(id: string): T | undefined;
     /**
-     * Synchronous snapshot of a filtered collection from the **local graph** —
-     * no network round-trip. Empty until `retrieve`/`list`/bootstrap has warmed
+     * Synchronous snapshot of a filtered collection from the local graph; no
+     * network round-trip. Empty until `retrieve`, `list`, or bootstrap has warmed
      * the graph.
      */
     getAll(options?: LocalReadOptions<T>): T[];
-    /** Count entities in the **local graph** (synchronous, no network). */
+    /** Count entities in the local graph; synchronous, no network. */
     getCount(options?: LocalCountOptions<T>): number;
     /**
      * Create a new entity — **optimistic, offline-first**. Resolves once
@@ -404,14 +415,14 @@ export interface ModelOperations<T, CreateInput> {
     /** Update an entity by id — optimistic, offline-first (see `create`). */
     update(params: ModelUpdateParams<T>): Promise<T>;
     /**
-     * Update under contention with a function of the latest state —
-     * `update(id, current => next)`, the `setState(prev => next)` of the data
-     * layer. The SDK reads the freshest row, runs your updater, writes it as a
-     * compare-and-swap, and re-reads + re-runs on any concurrent write. Nothing
-     * about claims, identity, or conflict codes surfaces: the write either lands
-     * or throws {@link AbloContentionError} once its reconcile budget is spent.
-     * Return `null`/`undefined` from the updater to skip the write. Resolves to
-     * the reconciled row (or `undefined` when the updater opted out).
+     * Updates under contention with a function of the latest state —
+     * `update(id, current => next)`. The client reads the freshest row, runs your
+     * updater, writes the result as a compare-and-swap, and re-reads and re-runs
+     * on any concurrent write. Nothing about claims, identity, or conflict codes
+     * surfaces: the write either lands or throws {@link AbloContentionError} once
+     * its reconcile budget is spent. Return `null` or `undefined` from the updater
+     * to skip the write. Resolves to the reconciled row, or `undefined` when the
+     * updater opted out.
      */
     update(id: string, updater: ModelUpdater<T>, options?: ContentionOptions): Promise<T | undefined>;
     /** Delete an entity by id — optimistic, offline-first (see `create`). */
@@ -445,13 +456,12 @@ export interface ModelOperations<T, CreateInput> {
      */
     claim: ClaimApi<T>;
     /**
-     * Subscribe this client to the sync group(s) for one or more rows of this
-     * model and get a live participant handle back — presence (`.peers`), the
+     * Subscribes this client to the sync group(s) for one or more rows of this
+     * model and returns a live participant handle — presence (`.peers`), the
      * scoped claim stream (`.claims`), and `.leave()` / `await using` disposal.
      *
-     * The model-scoped relocation of the former `ablo.participants.join({
-     * scope: { <model>: ids } })`. WebSocket only — presence needs a socket, so
-     * this is absent on HTTP clients and throws on any non-ws construction.
+     * WebSocket only: presence needs a live socket, so this is absent on HTTP
+     * clients and throws on any non-WebSocket construction.
      *
      * ```ts
      * await using participant = await ablo.slides.watch(slideIds, { ttl: '5m' });
@@ -459,7 +469,7 @@ export interface ModelOperations<T, CreateInput> {
      * ```
      */
     watch(ids: string | readonly string[], options?: WatchOptions): Promise<JoinedParticipant>;
-    /** Listen for changes (callback called on every change). */
+    /** Subscribe to changes; the callback runs on every change. */
     onChange(callback: (entities: T[]) => void, options?: LocalReadOptions<T>): () => void;
 }
-export declare function createModelProxy<T, C>(schemaKey: string, registeredModelName: string, objectPool: ObjectPool, syncClient: SyncClient, registry: ModelRegistry, hydration: HydrationCoordinator, collaboration?: ModelCollaboration<T>): ModelOperations<T, C>;
+export declare function createModelProxy<T, C>(schemaKey: string, registeredModelName: string, objectPool: InstanceCache, syncClient: SyncClient, registry: ModelRegistry, hydration: OnDemandLoader, collaboration?: ModelCollaboration<T>): ModelOperations<T, C>;