@abloatai/ablo 0.26.0 → 0.28.0

package/dist/client/Ablo.d.ts

@@ -1,8 +1,8 @@
 /**
- * Ablo — The one-liner consumer API.
- *
- * Hides all internal wiring (ObjectPool, Database, SyncClient, WebSocket,
- * bootstrap, offline queue, DI adapters) behind a single function call.
+ * `Ablo` — the one-call entry point to the sync engine client. It hides the
+ * internal wiring — the object pool, local database, sync client, WebSocket,
+ * bootstrap, and offline queue — behind a single function that returns a typed
+ * client with one property per model in your schema.
  *
  * Usage:
  *   import { Ablo } from '@abloatai/ablo';
@@ -18,10 +18,10 @@
  *   });
  *   await sync.reports.delete({ id: reportId });
  */
-import type { Schema, SchemaRecord, InferModel, InferCreate } from '../schema/schema.js';
+import type { Schema, SchemaRecord, InferModel, InferCreate, InferRow } from '../schema/schema.js';
 import type { ModelTarget, ModelClaim } from '../coordination/schema.js';
 export type { ModelTarget, ModelClaim };
-import { ObjectPool } from '../ObjectPool.js';
+import { InstanceCache } from '../InstanceCache.js';
 import type { SyncStoreContract } from '../react/context.js';
 import type { SyncWebSocket } from '../sync/SyncWebSocket.js';
 import { type SyncStatus } from '../BaseSyncedStore.js';
@@ -31,9 +31,21 @@ import { type AbloHttpClient, type AbloHttpClientOptions } from './httpClient.js
 import type { AbloOptions } from './options.js';
 import type { AbloSession, CommitResource, CreateAgentClientParams, CreateSessionParams, ModelClient } from './resourceTypes.js';
 export type { ApiKeySetter, AbloOptions, InternalAbloOptions } from './options.js';
-export type { LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, Claim, HeldClaim, ModelOperations, ModelOperationAction, CommitWait, ModelRead, IfClaimedPolicy, ClaimedOptions, ClaimWaitOptions, ModelReadOptions, ClaimCreateOptions, CommitOperationInput, CommitCreateOptions, CommitReceipt, CommitResource, ClaimResource, ModelMutationOptions, HttpClaimApi, ModelClient, SessionOperation, CreateUserSessionParams, CreateAgentSessionParams, CreateSessionParams, CreateAgentClientParams, AbloSession, } from './resourceTypes.js';
+export type { LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, ModelOperations, ModelOperationAction, CommitWait, ModelRead, IfClaimedPolicy, ClaimedOptions, ClaimWaitOptions, ModelReadOptions, ClaimCreateOptions, CommitOperationInput, CommitCreateOptions, CommitReceipt, CommitResource, ClaimResource, ModelMutationOptions, HttpClaimApi, ModelClient, SessionOperation, CreateUserSessionParams, CreateAgentSessionParams, CreateSessionParams, CreateAgentClientParams, AbloSession, } from './resourceTypes.js';
 export { computeFKDepthPriority } from './schemaConfig.js';
 import type { ModelOperations } from './createModelProxy.js';
+/**
+ * The reactive-read client a `useAblo` selector receives. The same surface as
+ * {@link Ablo}, except model reads are typed as reactive rows
+ * ({@link InferRow}: data fields + computeds, no relation accessors, no model
+ * methods) — the shape a reactive read actually delivers after
+ * `toReactiveSnapshot()`. Reading `row.layers` off a reactive read is a
+ * compile error here instead of a silent runtime `undefined`; compose
+ * relations through selectors or hooks that resolve the pool's instance.
+ */
+export type AbloReads<S extends SchemaRecord> = Omit<Ablo<S>, keyof S & string> & {
+    readonly [K in keyof S & string]: ModelOperations<InferRow<Schema<S>, K>, InferCreate<Schema<S>, K>>;
+};
 /** The typed sync engine client — one property per model in the schema */
 export type Ablo<S extends SchemaRecord> = {
     readonly [K in keyof S & string]: ModelOperations<InferModel<Schema<S>, K>, InferCreate<Schema<S>, K>>;
@@ -78,31 +90,32 @@ export type Ablo<S extends SchemaRecord> = {
     /** Disconnect and clean up */
     dispose(): Promise<void>;
     /**
-     * Replace the bearer auth token used for the WebSocket upgrade and HTTP
-     * requests, WITHOUT tearing down the engine. Use to push a refreshed
-     * short-lived access key (the Stripe-style `ek_`/`rk_`) before it expires —
-     * the client's `apiKey`-resolver refresh loop calls this. Reuses the same
-     * rotation path as the internal capability-token refresh; safe to call before
-     * `ready()`. Also nudges a parked connection to re-probe with the new token.
+     * Replace the bearer token used for the WebSocket upgrade and HTTP requests,
+     * without tearing down the engine. Use it to push a refreshed short-lived
+     * access key (an `ek_` or `rk_`) before it expires — the client's `apiKey`
+     * resolver refresh loop calls this for you. It reuses the same rotation path as
+     * the internal capability-token refresh and is safe to call before `ready()`.
+     * It also nudges a parked connection to re-probe with the new token.
      */
     setAuthToken(token: string): void;
     /**
      * Resolve the active bearer credential this engine authenticates with — the
-     * live `ek_`/`rk_` the WebSocket and HTTP transports currently carry (kept
-     * fresh by the `apiKey`-resolver refresh loop), falling back to a configured
+     * live `ek_` or `rk_` the WebSocket and HTTP transports currently carry (kept
+     * fresh by the `apiKey` resolver refresh loop), falling back to a configured
      * API key. Returns `null` when no credential is set yet. Use it to authenticate
-     * a side-band request to the same server with the very token this client
-     * already holds — no extra mint round-trip.
+     * a side-band request to the same server with the token this client already
+     * holds, avoiding an extra mint round-trip.
      */
     getAuthToken(): Promise<string | null>;
     /**
-     * Register a re-mint hook for the short-lived access key. The connection
-     * layer calls it WHEN it finds the key stale (a `credential_stale` probe) or
-     * on an external nudge; the hook mints a fresh `ek_`/`rk_` from the still-valid
-     * login. Mirrors the `apiKey`-resolver contract: resolve a token, resolve
-     * `null` when the login itself is gone (→ sign out), or THROW on a transient
-     * failure (→ back off, never sign out). The client wires this automatically
-     * from a function `apiKey`. Safe to call before `ready()`.
+     * Register a re-mint hook for the short-lived access key. The connection layer
+     * calls it when it finds the key stale (a `credential_stale` probe) or on an
+     * external nudge; the hook mints a fresh `ek_` or `rk_` from the still-valid
+     * login. It follows the same contract as the `apiKey` resolver: resolve a
+     * token, resolve `null` when the login itself is gone (which signs the user
+     * out), or throw on a transient failure (which backs off without signing out).
+     * The client wires this automatically from a function `apiKey`. Safe to call
+     * before `ready()`.
      */
     setCredentialRefresher(refresher: (() => Promise<string | null>) | null): void;
     /**
@@ -114,21 +127,19 @@ export type Ablo<S extends SchemaRecord> = {
      */
     nudgeReconnect(): void;
     /**
-     * Mint a short-lived, scoped **session token** for one end user — the
-     * Stripe `ephemeralKeys.create` / Supabase session shape. Call this on YOUR
-     * BACKEND (where the `sk_` secret key lives), then hand the returned
-     * `token` to that user's browser (typically via a token route the browser's
-     * `apiKey` resolver fetches). The browser presents it as the bearer; the sync-server verifies
-     * it via `apiKeyProvider`.
+     * Mint a short-lived, scoped session token for one end user. Call this on your
+     * backend, where the `sk_` secret key lives, then hand the returned `token` to
+     * that user's browser — typically through a token route the browser's `apiKey`
+     * resolver fetches. The browser presents the token as its bearer, and the
+     * server verifies it. The browser must never see the `sk_` key, only the
+     * per-user session token.
      *
-     * The browser must NEVER see the `sk_` key — only the per-user session token.
-     *
-     * Pass `{ user: { id } }` for a full-authority end-user session (mints `ek_`,
-     * `participantKind: 'user'` attribution, stored as `actor_kind` on the delta
-     * row), or `{ agent: { id }, can: { tasks:
-     * ['update'] } }` for a scoped agent session (mints `rk_`); `can` is typed
-     * against your schema's model names. Always authenticates with the original
-     * `sk_` — never the client's exchanged sync credential.
+     * Pass `{ user: { id } }` for a full-authority end-user session, which mints an
+     * `ek_` and attributes writes to a user (recorded as `actor_kind` on the delta
+     * row). Pass `{ agent: { id }, can: { tasks: ['update'] } }` for a scoped agent
+     * session, which mints an `rk_`; `can` is typed against your schema's model
+     * names. This always authenticates with the original `sk_`, never the client's
+     * exchanged sync credential.
      */
     sessions: {
         create(params: CreateSessionParams<S>): Promise<AbloSession>;
@@ -149,15 +160,16 @@ export type Ablo<S extends SchemaRecord> = {
      * await agent.dispose(); // when the agent is done
      * ```
      *
-     * Server-side only (requires the `sk_` secret key, like `sessions.create`);
-     * throws `AbloAuthenticationError` in the browser. The returned client holds
-     * its own auto-refreshing `rk_`, so a long run never hits token expiry, and
-     * the `sk_` never leaves this process. Each call is a DISTINCT participant by
-     * default (omit `id` → fresh uuid), so even two agents sharing a `name` queue
-     * behind one another on a contended row — `name` is display only and never
-     * collapses identity. Humans don't get a server-built client — ship them a
-     * token via `sessions.create({ user })`. Need the raw token for revocation,
-     * or a stable re-attachable id? Use `sessions.create({ agent })` / pass `id`.
+     * Server-side only: it requires the `sk_` secret key (like `sessions.create`)
+     * and throws `AbloAuthenticationError` in the browser. The returned client
+     * holds its own auto-refreshing `rk_`, so a long run never hits token expiry,
+     * and the `sk_` never leaves this process. Each call is a distinct participant
+     * by default (omit `id` for a fresh uuid), so even two agents sharing a `name`
+     * queue behind one another on a contended row — `name` is display only and
+     * never collapses identity. Humans don't get a server-built client; ship them a
+     * token via `sessions.create({ user })`. If you need the raw token for
+     * revocation, or a stable re-attachable id, use `sessions.create({ agent })`
+     * or pass `id`.
      */
     agents: {
         create(params: CreateAgentClientParams<S>): Promise<Ablo<S>>;
@@ -245,14 +257,14 @@ export type Ablo<S extends SchemaRecord> = {
     /** The underlying schema */
     readonly schema: Schema<S>;
     /**
-     * Real-time presence livestream — who else is connected on this
-     * engine's sync groups, what they're doing, and a write surface for
-     * announcing this user's own activity. Rides the engine's existing
-     * WebSocket; opening a participant for presence does NOT open a
-     * second socket. See `PresenceStream` in `types/streams.ts`.
+     * A real-time presence livestream — who else is connected on this engine's
+     * sync groups, what they're doing, and a write surface for announcing this
+     * user's own activity. It rides the engine's existing WebSocket; opening a
+     * participant for presence does not open a second socket. See
+     * {@link PresenceStream}.
      *
-     * Stable reference for the engine's lifetime — the underlying
-     * connection is rotated on `dispose()` but this object is the same.
+     * The reference is stable for the engine's lifetime — the underlying connection
+     * is rotated on `dispose()`, but this object stays the same.
      */
     readonly presence: PresenceStream;
     /**
@@ -270,7 +282,7 @@ export type Ablo<S extends SchemaRecord> = {
      * Capture a context-staleness watermark over a set of entities.
      * Returns a flat snapshot with `stamp` (thread into writes as
      * `readAt`), `signal` (aborts on any captured-entity delta), and
-     * `onChange` (callback form). Reads from the engine's ObjectPool;
+     * `onChange` (callback form). Reads from the engine's InstanceCache;
      * subscription is on the engine's existing transport.
      *
      * Use before an LLM call to prevent the model from completing
@@ -282,13 +294,13 @@ export type Ablo<S extends SchemaRecord> = {
      */
     snapshot<ModelName extends keyof S & string>(entities: Readonly<Record<ModelName, string | readonly string[]>>): Snapshot<Schema<S>, ModelName>;
     /**
-     * The internal BaseSyncedStore. Implements SyncStoreContract — pass to
-     * SyncContext.Provider so the SDK's useModel/useModels/useMutations hooks
-     * can access it. Also satisfies useSyncStore() consumers during migration.
+     * The internal store. It implements {@link SyncStoreContract} — pass it to
+     * `SyncContext.Provider` so the SDK's `useModel` / `useModels` / `useMutations`
+     * hooks can reach it.
      */
     readonly _store: SyncStoreContract;
-    /** The ObjectPool — for demand loaders and direct pool operations. */
-    readonly _pool: ObjectPool;
+    /** The InstanceCache — for demand loaders and direct pool operations. */
+    readonly _pool: InstanceCache;
     /**
      * The SyncWebSocket handle — for collaboration events (slide selection,
      * cursor broadcast). Null until the engine connects.
@@ -334,25 +346,28 @@ import type * as _Tx from '../mutators/Transaction.js';
 import type * as _Undo from '../mutators/UndoManager.js';
 import type * as _SchemaTypes from '../schema/schema.js';
 /**
- * Canonical type namespace.
- *
- * Locked rules — apply uniformly to every future addition:
+ * The canonical type namespace.
  *
- *   1. Flat by default.    `Ablo.X`. Fewest dots wins.
- *   2. Sub-namespace ONLY when (a) 4+ types share a single conceptual
- *      prefix, AND (b) names read better with the prefix (`Conflict.Kind`
- *      over `ConflictKind`). If the cluster is heterogeneous (streams +
- *      data + handles), keep flat.
- *   3. Only types a consumer would write `: Ablo.X` for. Inferred-only
- *      types stay un-exported.
- *   4. Wire shapes never on `Ablo.*`. Engine vocabulary only.
- *   5. Advanced / framework-integration types stay internal unless they
- *      graduate into one of the public subpaths.
+ * Rules applied uniformly to every addition:
  *
- * Anything not on this list stays internal.
+ *   1. Flat by default. `Ablo.X`. Fewest dots wins.
+ *   2. Sub-namespace only when (a) four or more types share a single conceptual
+ *      prefix and (b) the names read better with it (`Conflict.Kind` over
+ *      `ConflictKind`). If the cluster is heterogeneous (streams, data, handles),
+ *      keep it flat.
+ *   3. Only types a consumer would write `: Ablo.X` for. Inferred-only types stay
+ *      unexported.
+ *   4. Wire shapes never appear on `Ablo.*` — engine vocabulary only.
+ *   5. Advanced or framework-integration types stay internal unless they graduate
+ *      into one of the public subpaths.
  */
 export declare namespace Ablo {
     type Options<S extends SchemaRecord = SchemaRecord> = AbloOptions<S>;
+    /**
+     * The read view of the client that `useAblo` selectors receive: model reads
+     * typed as reactive rows (data fields + computeds, no relation accessors).
+     */
+    type Reads<S extends SchemaRecord = SchemaRecord> = AbloReads<S>;
     type Api = AbloApi;
     type ApiClaims = AbloApiClaims;
     type Capability = import('./ApiClient.js').Capability;
@@ -375,6 +390,8 @@ export declare namespace Ablo {
     type Claim = _Streams.Claim;
     type ClaimRejection = _Streams.ClaimRejection;
     type ClaimLost = _Streams.ClaimLost;
+    type ClaimHeartbeat = _Streams.ClaimHeartbeat;
+    type ClaimHeartbeatOptions = _Streams.ClaimHeartbeatOptions;
     type Snapshot<TSchema extends _SchemaTypes.Schema = _SchemaTypes.Schema, K extends keyof TSchema['models'] = keyof TSchema['models']> = _Streams.Snapshot<TSchema, K>;
     namespace Auth {
         type Actor = _Streams.ParticipantRef;
@@ -390,6 +407,12 @@ export declare namespace Ablo {
     namespace Schema {
         type InferModel<S extends _SchemaTypes.Schema, K extends keyof S['models']> = _SchemaTypes.InferModel<S, K>;
         type InferCreate<S extends _SchemaTypes.Schema, K extends keyof S['models']> = _SchemaTypes.InferCreate<S, K>;
+        /**
+         * The reactive-row companion to {@link InferModel}: data fields + computed
+         * getters, no relation accessors, no model methods — the shape `useAblo`
+         * reads return.
+         */
+        type InferRow<S extends _SchemaTypes.Schema, K extends keyof S['models']> = _SchemaTypes.InferRow<S, K>;
         type InferModelNames<S extends _SchemaTypes.Schema> = _SchemaTypes.InferModelNames<S>;
     }
     type Conflict = _Policy.Conflict;