@abloatai/ablo 0.25.0 → 0.27.0

package/dist/client/functionalUpdate.d.ts

@@ -1,30 +1,30 @@
 /**
  * The functional update — `ablo.<model>.update(id, current => next)`.
  *
- * This is the "just works under contention" surface. The developer expresses
- * ONLY their intent — "given the latest row, here is the next state" — and the
- * SDK owns everything else: read the fresh row + its watermark, run the updater,
- * write it as a compare-and-swap against that watermark, and on any concurrent
- * write re-read → recompute → retry. No claim, no identity, no transport
- * awareness, and no `stale_context` / `claim_*` error codes ever reach the
+ * This is the surface that just works under contention. You express only your
+ * intent — given the latest row, here is the next state — and the client does
+ * the rest: it reads the fresh row and its watermark, runs your updater, writes
+ * the result as a compare-and-swap against that watermark, and on any concurrent
+ * write it re-reads, recomputes, and retries. No claim, no identity, no transport
+ * awareness, and no `stale_context` or `claim_*` error codes ever reach the
  * caller. The write either lands or, at the extreme, throws a single
- * {@link AbloContentionError} after the reconcile budget is spent.
+ * {@link AbloContentionError} once the reconcile budget is spent.
  *
- * Correctness comes from the `readAt` watermark + `onStale: 'reject'`
- * (optimistic concurrency / compare-and-swap), NOT from participant identity —
- * which is why it is immune to the shared-credential silent-clobber footgun and
- * behaves identically on both transports. The HTTP and WebSocket clients inject
- * the same two thunks ({@link ReconcileTransport}); the loop below is shared, so
- * the guarantee can never drift between them — only the mechanism differs.
+ * Correctness comes from the `readAt` watermark plus `onStale: 'reject'`
+ * (optimistic concurrency, or compare-and-swap), not from participant identity.
+ * That is why it is immune to the shared-credential silent-overwrite hazard and
+ * behaves identically on both transports: the HTTP and WebSocket clients inject
+ * the same two functions ({@link ReconcileTransport}) into the shared loop below,
+ * so the guarantee cannot drift between them — only the mechanism differs.
  *
  * The mental model is React's `setState(prev => next)`: pass a function of the
- * current state, the runtime owns reconciliation.
+ * current state and the runtime owns reconciliation.
  */
 import { AbloContentionError } from '../errors.js';
 /**
  * The functional form of an update: given the freshly-read row, return the
- * fields to write. Return `null` / `undefined` to make NO write — a no-op the
- * caller decided on after seeing the latest state (e.g. "already done").
+ * fields to write. Return `null` or `undefined` to make no write — a no-op the
+ * caller chose after seeing the latest state (for example, "already done").
  */
 export type ModelUpdater<T> = (current: T) => Partial<T> | null | undefined | Promise<Partial<T> | null | undefined>;
 /** Tuning for the functional update's internal reconcile loop. */
@@ -41,30 +41,32 @@ export interface ContentionOptions {
 /** Reconcile rounds before a hot row is declared permanently contended. */
 export declare const DEFAULT_CONTENTION_RETRIES = 16;
 /**
- * Does this thrown error mean "another writer moved the row — re-read and
- * retry" rather than a genuine failure to surface? These are the optimistic-
- * concurrency signals the functional update reconciles against:
- *   - `stale_context` — our `readAt` watermark was overtaken by a concurrent write
- *   - `claim_lost`    — a holder preempted us (e.g. a human under `humansOverwrite`)
+ * Reports whether a thrown error means "another writer moved the row — re-read
+ * and retry" rather than a genuine failure to surface. These are the
+ * optimistic-concurrency signals the functional update reconciles against:
+ *   - `stale_context` — the `readAt` watermark was overtaken by a concurrent write
+ *   - `claim_lost`    — a holder preempted the write (for example a human under `humansOverwrite`)
  *   - `claim_queued`  — a holder is actively editing the row right now
  */
 export declare function isReconcilableConflict(err: unknown): boolean;
 /**
- * Transport-specific read/write the shared loop drives. Each client injects its
- * own pair — that's the ONLY thing that differs between HTTP and WebSocket.
+ * The transport-specific read and write that the shared loop drives. Each client
+ * injects its own pair — the one thing that differs between the HTTP and
+ * WebSocket transports.
  */
 export interface ReconcileTransport<T, R> {
     readonly model: string;
     readonly id: string;
-    /** Read the latest row + its watermark from the authoritative store. */
+    /** Read the latest row and its watermark from the authoritative store. */
     readFresh: () => Promise<{
         readonly data: T | null | undefined;
         readonly stamp: number;
     }>;
     /**
-     * Write the computed patch as a compare-and-swap against `readAt`. MUST throw
-     * a reconcilable conflict (`stale_context` / `claim_*`) when the watermark was
-     * overtaken — that rejection is what drives the next reconcile round.
+     * Write the computed patch as a compare-and-swap against `readAt`. It must
+     * throw a reconcilable conflict (`stale_context` or `claim_*`) when the
+     * watermark was overtaken — that rejection is what drives the next reconcile
+     * round.
      */
     writeNext: (patch: Partial<T>, readAt: number) => Promise<R>;
 }

package/dist/client/functionalUpdate.js

@@ -1,34 +1,34 @@
 /**
  * The functional update — `ablo.<model>.update(id, current => next)`.
  *
- * This is the "just works under contention" surface. The developer expresses
- * ONLY their intent — "given the latest row, here is the next state" — and the
- * SDK owns everything else: read the fresh row + its watermark, run the updater,
- * write it as a compare-and-swap against that watermark, and on any concurrent
- * write re-read → recompute → retry. No claim, no identity, no transport
- * awareness, and no `stale_context` / `claim_*` error codes ever reach the
+ * This is the surface that just works under contention. You express only your
+ * intent — given the latest row, here is the next state — and the client does
+ * the rest: it reads the fresh row and its watermark, runs your updater, writes
+ * the result as a compare-and-swap against that watermark, and on any concurrent
+ * write it re-reads, recomputes, and retries. No claim, no identity, no transport
+ * awareness, and no `stale_context` or `claim_*` error codes ever reach the
  * caller. The write either lands or, at the extreme, throws a single
- * {@link AbloContentionError} after the reconcile budget is spent.
+ * {@link AbloContentionError} once the reconcile budget is spent.
  *
- * Correctness comes from the `readAt` watermark + `onStale: 'reject'`
- * (optimistic concurrency / compare-and-swap), NOT from participant identity —
- * which is why it is immune to the shared-credential silent-clobber footgun and
- * behaves identically on both transports. The HTTP and WebSocket clients inject
- * the same two thunks ({@link ReconcileTransport}); the loop below is shared, so
- * the guarantee can never drift between them — only the mechanism differs.
+ * Correctness comes from the `readAt` watermark plus `onStale: 'reject'`
+ * (optimistic concurrency, or compare-and-swap), not from participant identity.
+ * That is why it is immune to the shared-credential silent-overwrite hazard and
+ * behaves identically on both transports: the HTTP and WebSocket clients inject
+ * the same two functions ({@link ReconcileTransport}) into the shared loop below,
+ * so the guarantee cannot drift between them — only the mechanism differs.
  *
  * The mental model is React's `setState(prev => next)`: pass a function of the
- * current state, the runtime owns reconciliation.
+ * current state and the runtime owns reconciliation.
  */
 import { AbloError, AbloNotFoundError, AbloStaleContextError, AbloClaimedError, AbloContentionError, } from '../errors.js';
 /** Reconcile rounds before a hot row is declared permanently contended. */
 export const DEFAULT_CONTENTION_RETRIES = 16;
 /**
- * Does this thrown error mean "another writer moved the row — re-read and
- * retry" rather than a genuine failure to surface? These are the optimistic-
- * concurrency signals the functional update reconciles against:
- *   - `stale_context` — our `readAt` watermark was overtaken by a concurrent write
- *   - `claim_lost`    — a holder preempted us (e.g. a human under `humansOverwrite`)
+ * Reports whether a thrown error means "another writer moved the row — re-read
+ * and retry" rather than a genuine failure to surface. These are the
+ * optimistic-concurrency signals the functional update reconciles against:
+ *   - `stale_context` — the `readAt` watermark was overtaken by a concurrent write
+ *   - `claim_lost`    — a holder preempted the write (for example a human under `humansOverwrite`)
  *   - `claim_queued`  — a holder is actively editing the row right now
  */
 export function isReconcilableConflict(err) {
@@ -82,6 +82,6 @@ export async function reconcileFunctionalUpdate(updater, options, transport) {
         cause: lastConflict,
     });
 }
-// Re-exported so call sites import the loop + its terminal error from one place;
-// the class itself lives with the rest of the hierarchy in `errors.ts`.
+// Re-exported so call sites import the loop and its terminal error from one
+// place; the class itself lives with the rest of the error hierarchy.
 export { AbloContentionError };

package/dist/client/hostedEndpoints.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The hosted Ablo Cloud endpoint constants, with no dependencies of their own.
+ *
+ * This is the single place the hosted API host is declared. URL resolution, the
+ * CLI's default URL, the data-source connector's base, the generated OpenAPI
+ * server entry, and the network probe's default all import from here, so
+ * changing the API domain is a one-line edit.
+ *
+ * These constants are kept dependency-free deliberately: several low-level
+ * modules consume them, and routing those modules through the auth layer would
+ * pull the error registry and credential policy into otherwise-clean paths and
+ * risk an import cycle.
+ */
+/** The hosted API domain (no scheme). */
+export declare const ABLO_HOSTED_API_DOMAIN = "api.abloatai.com";
+/** The hosted HTTP origin — `https://` + {@link ABLO_HOSTED_API_DOMAIN}. */
+export declare const ABLO_HOSTED_HTTP_BASE_URL = "https://api.abloatai.com";
+/** Default `baseURL` when the caller passes none. Same value as
+ *  {@link ABLO_HOSTED_HTTP_BASE_URL}; kept as a distinct name because it is
+ *  the documented client-options default. */
+export declare const ABLO_DEFAULT_BASE_URL = "https://api.abloatai.com";

package/dist/client/hostedEndpoints.js

@@ -0,0 +1,21 @@
+/**
+ * The hosted Ablo Cloud endpoint constants, with no dependencies of their own.
+ *
+ * This is the single place the hosted API host is declared. URL resolution, the
+ * CLI's default URL, the data-source connector's base, the generated OpenAPI
+ * server entry, and the network probe's default all import from here, so
+ * changing the API domain is a one-line edit.
+ *
+ * These constants are kept dependency-free deliberately: several low-level
+ * modules consume them, and routing those modules through the auth layer would
+ * pull the error registry and credential policy into otherwise-clean paths and
+ * risk an import cycle.
+ */
+/** The hosted API domain (no scheme). */
+export const ABLO_HOSTED_API_DOMAIN = 'api.abloatai.com';
+/** The hosted HTTP origin — `https://` + {@link ABLO_HOSTED_API_DOMAIN}. */
+export const ABLO_HOSTED_HTTP_BASE_URL = `https://${ABLO_HOSTED_API_DOMAIN}`;
+/** Default `baseURL` when the caller passes none. Same value as
+ *  {@link ABLO_HOSTED_HTTP_BASE_URL}; kept as a distinct name because it is
+ *  the documented client-options default. */
+export const ABLO_DEFAULT_BASE_URL = ABLO_HOSTED_HTTP_BASE_URL;

package/dist/client/httpClient.d.ts

@@ -1,100 +1,104 @@
 /**
- * `createAbloHttpClient` — a STATELESS, typed HTTP client for server-side actors
- * (agents, workers, serverless), modelled on `@liveblocks/node` / the Stripe
- * server SDK / Netflix Conductor workers: it talks to Ablo over plain HTTP with
- * the credential as identity, and holds **no WebSocket and no connection state**.
+ * Creates a stateless, typed HTTP client for server-side actors — agents,
+ * workers, and serverless handlers. It talks to Ablo over plain request/response
+ * HTTP, uses the bearer credential as its identity, and holds no WebSocket and no
+ * connection state.
  *
- * Why this exists (docs/plans/agent-transport-event-driven.md): the stateful
- * `Ablo({ schema })` client is for INTERACTIVE participants — it opens a
- * WebSocket and seeds its identity (userId/orgId) during the connect/bootstrap
- * step, then routes writes through a `TransactionQueue` that drops mutations
- * until that identity exists. A reactive agent has no socket, so that identity is
- * never seeded and writes drop. The proven fix (unanimous across Liveblocks,
- * Stripe, PlanetScale, Conductor, Better Auth) is NOT to de-socket the stateful
- * client — it's a separate stateless client where the credential carries identity
- * and the SERVER resolves it per request.
+ * This is the counterpart to the stateful {@link Ablo} client. The stateful
+ * client is for interactive participants: it opens a WebSocket, learns its
+ * identity (user id and organization id) during the connect-and-bootstrap step,
+ * and routes writes through a queue that waits for that identity. A server-side
+ * actor has no socket, so instead of reusing that machinery it uses this client,
+ * where the credential itself carries identity and the server resolves it on
+ * every request.
  *
- * Ablo already has that stateless surface: `Ablo({ schema: null })` returns the
- * protocol client (`createProtocolClient` → `AbloApi`), which commits via
- * `POST /v1/commits` and reads via the HTTP `ApiClient`, authenticating with the
- * Bearer token on every request. Its only ergonomic gap is that model access is
- * string-keyed (`api.model('slides')`) rather than typed (`api.slides`). This
- * wraps it in a typed proxy facade so server code gets the SAME `client.<model>`
- * surface as the browser client — typed proxies, stateless transport.
+ * Under the hood this wraps the schema-agnostic protocol client that
+ * {@link createProtocolClient} returns in a typed proxy. The protocol client
+ * commits over `POST /v1/commits` and reads over HTTP, authenticating with the
+ * bearer token each time; its model access is string-keyed (`api.model('slides')`).
+ * The proxy gives server code the same typed `client.<model>` surface the
+ * stateful client offers, over stateless transport.
  */
 import { type AbloApiClientOptions } from './ApiClient.js';
-import type { CommitReceipt, CommitResource, HttpClaimApi, ModelRead, ModelReadOptions, CreateSessionParams, AbloSession } from './Ablo.js';
+import type { CommitReceipt, CommitResource, HttpClaimApi, ModelRead, ModelReadOptions, CreateSessionParams, AbloSession } from './resourceTypes.js';
 import type { ModelCreateParams, ModelDeleteParams, ServerReadOptions, ModelRetrieveParams, ModelUpdateParams } from './createModelProxy.js';
 import type { Schema, SchemaRecord, InferModel, InferCreate } from '../schema/schema.js';
 import type { ModelUpdater, ContentionOptions } from './functionalUpdate.js';
 export interface AbloHttpClientOptions<S extends SchemaRecord> extends Omit<AbloApiClientOptions, 'schema'> {
-    /** The schema — used for TYPING only (typed model proxies); never sent or used at runtime. */
+    /** The schema. Used only to type the model proxies; it is never sent over the wire or read at runtime. */
     readonly schema: Schema<S>;
 }
 /**
- * The per-model HTTP surface — exactly what a stateless client can do over
- * request/response: reads (`retrieve`/`list`), writes (`create`/`update`/`delete`),
- * and the durable-lease claim plane (`claim` — acquire/hold/release). It does NOT
- * include `get`/`getAll`/`getCount` (local synced-pool reads) or `onChange` (live
- * subscription); those need the stateful plane and are absent BY TYPE here.
+ * The per-model surface of the stateless HTTP client — everything reachable over
+ * request/response: reads (`retrieve` and `list`), writes (`create`, `update`,
+ * and `delete`), and the durable-lease {@link HttpClaimApi | claim} plane for
+ * coordinated writes. It deliberately omits the stateful client's local-cache
+ * reads (`get`, `getAll`, `getCount`) and live subscriptions (`onChange`), which
+ * need a persistent socket; those are absent from the type, so reaching for one
+ * is a compile error rather than a runtime gap.
  *
- * Read-shape asymmetry (by design, not a gap): `retrieve(...)` returns a
- * `ModelRead<T>` envelope `{ data, stamp, claims }` — the stateless client has no
- * local graph, so the watermark/claims the stateful client reads from its pool
- * must ride inline on the read (an agent needs the `stamp` to do a stale-guarded
- * write; there is no `snapshot()` to fetch it from). `list(...)` returns a bare `T[]`.
+ * The read shapes differ on purpose. `retrieve` returns a {@link ModelRead}
+ * envelope of `{ data, stamp, claims }`, because a stateless client keeps no local
+ * copy of the data: the watermark (`stamp`) and any active claims must travel
+ * inline on the read so a caller can follow it with a stale-guarded write. `list`
+ * returns a plain array.
  */
 export interface HttpModelClient<T, C = T> {
     retrieve(params: ModelRetrieveParams & ModelReadOptions): Promise<ModelRead<T>>;
     list(options?: ServerReadOptions<T>): Promise<T[]>;
     /**
-     * Create a row and return it — the confirmed, authoritative server row (with
-     * framework defaults), mirroring the WebSocket client's `create`. A re-create
-     * of an existing caller-supplied id is idempotent and returns the EXISTING row.
+     * Creates a row and returns the confirmed server row, including any
+     * framework-applied defaults. Matches the stateful client's `create`. Passing an
+     * id that already exists is idempotent: the existing row is returned unchanged.
      */
     create(params: ModelCreateParams<T, C>): Promise<T>;
     update(params: ModelUpdateParams<C>): Promise<CommitReceipt>;
     /**
-     * Functional update under contention — `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. No claim, no identity, no conflict codes: the write
-     * lands or throws `AbloContentionError`. Return `null`/`undefined` to skip.
+     * Updates a row with a function of its latest value — `update(id, current =>
+     * next)`, the data-layer equivalent of a `setState(prev => next)` reducer. The
+     * client reads the freshest row, runs your updater, and writes the result as a
+     * compare-and-swap against the row's watermark; if another write landed first it
+     * re-reads and re-runs. No claim or conflict handling is needed: the write either
+     * lands or throws `AbloContentionError` once its retry budget is spent. Return
+     * `null` or `undefined` from the updater to skip the write.
      */
     update(id: string, updater: ModelUpdater<T>, options?: ContentionOptions): Promise<CommitReceipt | undefined>;
     delete(params: ModelDeleteParams<T>): Promise<CommitReceipt>;
     claim: HttpClaimApi<T>;
 }
 /**
- * The honest type of the stateless HTTP client: typed model proxies (the
- * request/response subset) + `commits` + `dispose`. Reaching for a
- * stateful-only capability (`get`/`getAll`/`getCount`, `onChange`,
- * `claim.state`/`queue`/`reorder`) is a COMPILE error here, not a latent runtime
- * `undefined` — the type matches what the transport can actually do.
+ * The type of the stateless HTTP client: a typed {@link HttpModelClient} per
+ * schema model, plus `commits`, `dispose`, and the session-mint surface. It
+ * exposes only what request/response transport can do, so reaching for a
+ * stateful-only capability — `get`, `getAll`, `getCount`, `onChange`, or the
+ * synchronous `claim.state`/`queue`/`reorder` reads — is a compile error rather
+ * than a value that is `undefined` at runtime.
  */
 export type AbloHttpClient<S extends SchemaRecord> = {
     readonly [K in keyof S & string]: HttpModelClient<InferModel<Schema<S>, K>, InferCreate<Schema<S>, K>>;
 } & {
-    /** Register `databaseUrl` when configured. Also runs lazily before the first request. */
+    /** Runs one-time setup, such as registering a configured `databaseUrl` data source, before the client is used. It also runs lazily ahead of the first request, so calling it yourself is optional. */
     ready(): Promise<void>;
     readonly commits: CommitResource;
     dispose(): Promise<void>;
-    /** Resolve the bearer credential this client authenticates with (see `AbloApi.getAuthToken`). */
+    /** Resolves the bearer credential this client authenticates with, or `null` if none is set. */
     getAuthToken(): Promise<string | null>;
     /**
-     * Mint a short-lived scoped session (Stripe ephemeral-key shape). Minting is a
-     * stateless control-plane call, so — unlike `get`/`getAll`/`onChange` — it IS
-     * available on the HTTP client. `{ user }` → `ek_`, `{ agent, can }` → `rk_`.
+     * Mints a short-lived, scoped session token. Minting is itself a stateless
+     * request, so it is available here even though the local-cache reads are not.
+     * Pass `{ user }` to mint an end-user key (`ek_`) or `{ agent, can }` to mint a
+     * scoped agent key (`rk_`). See {@link CreateSessionParams}.
      */
     readonly sessions: {
         create(params: CreateSessionParams<S>): Promise<AbloSession>;
     };
-    /** String-keyed model accessor (for dynamic model names). */
+    /** Looks up a model client by name, for when the model name is only known at runtime. */
     model<T = Record<string, unknown>>(name: string): HttpModelClient<T>;
 };
 /**
- * Stateless, typed HTTP client. Each `client.<model>` resolves to the protocol
- * client's `model(name)`; `commits`, `dispose`, etc. pass through. No socket is
- * ever opened; identity is the Bearer credential.
+ * Builds the stateless, typed HTTP client. Each `client.<model>` resolves to the
+ * protocol client's model accessor, while `commits`, `dispose`, and the other
+ * protocol members pass through unchanged. No socket is ever opened; the bearer
+ * credential is the identity.
  */
 export declare function createAbloHttpClient<S extends SchemaRecord>(options: AbloHttpClientOptions<S>): AbloHttpClient<S>;

package/dist/client/httpClient.js

@@ -1,34 +1,31 @@
 /**
- * `createAbloHttpClient` — a STATELESS, typed HTTP client for server-side actors
- * (agents, workers, serverless), modelled on `@liveblocks/node` / the Stripe
- * server SDK / Netflix Conductor workers: it talks to Ablo over plain HTTP with
- * the credential as identity, and holds **no WebSocket and no connection state**.
+ * Creates a stateless, typed HTTP client for server-side actors — agents,
+ * workers, and serverless handlers. It talks to Ablo over plain request/response
+ * HTTP, uses the bearer credential as its identity, and holds no WebSocket and no
+ * connection state.
  *
- * Why this exists (docs/plans/agent-transport-event-driven.md): the stateful
- * `Ablo({ schema })` client is for INTERACTIVE participants — it opens a
- * WebSocket and seeds its identity (userId/orgId) during the connect/bootstrap
- * step, then routes writes through a `TransactionQueue` that drops mutations
- * until that identity exists. A reactive agent has no socket, so that identity is
- * never seeded and writes drop. The proven fix (unanimous across Liveblocks,
- * Stripe, PlanetScale, Conductor, Better Auth) is NOT to de-socket the stateful
- * client — it's a separate stateless client where the credential carries identity
- * and the SERVER resolves it per request.
+ * This is the counterpart to the stateful {@link Ablo} client. The stateful
+ * client is for interactive participants: it opens a WebSocket, learns its
+ * identity (user id and organization id) during the connect-and-bootstrap step,
+ * and routes writes through a queue that waits for that identity. A server-side
+ * actor has no socket, so instead of reusing that machinery it uses this client,
+ * where the credential itself carries identity and the server resolves it on
+ * every request.
  *
- * Ablo already has that stateless surface: `Ablo({ schema: null })` returns the
- * protocol client (`createProtocolClient` → `AbloApi`), which commits via
- * `POST /v1/commits` and reads via the HTTP `ApiClient`, authenticating with the
- * Bearer token on every request. Its only ergonomic gap is that model access is
- * string-keyed (`api.model('slides')`) rather than typed (`api.slides`). This
- * wraps it in a typed proxy facade so server code gets the SAME `client.<model>`
- * surface as the browser client — typed proxies, stateless transport.
+ * Under the hood this wraps the schema-agnostic protocol client that
+ * {@link createProtocolClient} returns in a typed proxy. The protocol client
+ * commits over `POST /v1/commits` and reads over HTTP, authenticating with the
+ * bearer token each time; its model access is string-keyed (`api.model('slides')`).
+ * The proxy gives server code the same typed `client.<model>` surface the
+ * stateful client offers, over stateless transport.
  */
 import { createProtocolClient, } from './ApiClient.js';
 /**
- * Members of the underlying `AbloApi` that pass straight through the facade.
- * Deliberately EXCLUDES the resource names that collide with common schema model
- * names — `tasks`, `claims`, `capabilities`, `agent` — so `client.tasks` resolves
- * to the schema model `tasks`, not the protocol `TaskResource`. Only lifecycle +
- * the genuinely-protocol methods an agent uses pass through.
+ * Names on the underlying protocol client that pass straight through the proxy.
+ * This set intentionally leaves out names that collide with common schema models —
+ * `tasks`, `claims`, `capabilities`, `agent` — so that `client.tasks` resolves to
+ * the schema model named `tasks` rather than a protocol resource. Only lifecycle
+ * methods and the genuinely protocol-level members belong here.
  */
 const PROTOCOL_MEMBERS = new Set([
     'ready',
@@ -41,9 +38,10 @@ const PROTOCOL_MEMBERS = new Set([
     'sessions',
 ]);
 /**
- * Stateless, typed HTTP client. Each `client.<model>` resolves to the protocol
- * client's `model(name)`; `commits`, `dispose`, etc. pass through. No socket is
- * ever opened; identity is the Bearer credential.
+ * Builds the stateless, typed HTTP client. Each `client.<model>` resolves to the
+ * protocol client's model accessor, while `commits`, `dispose`, and the other
+ * protocol members pass through unchanged. No socket is ever opened; the bearer
+ * credential is the identity.
  */
 export function createAbloHttpClient(options) {
     // The schema is type-level only; the protocol client is schema-agnostic.
@@ -62,8 +60,8 @@ export function createAbloHttpClient(options) {
             return api.model(prop);
         },
     });
-    // One boundary cast — and now an HONEST one: `AbloHttpClient<S>` declares only
-    // what `api.model()` + the passed-through protocol members actually implement,
-    // so there is no method on this type that fails at runtime.
+    // A single boundary cast. `AbloHttpClient<S>` declares only what the model
+    // accessor and the passed-through protocol members actually implement, so no
+    // method on this type is missing at runtime.
     return facade;
 }

package/dist/client/identity.d.ts

@@ -1,26 +1,21 @@
 /**
- * Participant identity + scope resolution for `Ablo()`.
+ * Resolves a participant's identity and scope when an {@link Ablo} client is
+ * constructed, following whichever of three authentication paths the caller's
+ * options select:
  *
- * Three branches, mirroring the three auth paths the SDK supports:
+ *   1. **Hosted cloud** — the caller passed an `apiKey`. The client exchanges it
+ *      for a capability token and scope, then starts a scheduler that re-mints the
+ *      token before it expires, so the rotation is invisible to the caller.
+ *   2. **Self-derived** — the caller passed a bearer or capability token but not
+ *      an identity. The client asks the identity endpoint to recover the
+ *      participant id and scope from the token.
+ *   3. **Explicit** — a self-hosted caller passed the organization id and a user
+ *      or agent id directly. No server round-trip; the client trusts the caller.
  *
- *   1. **Hosted-cloud** — caller passed `apiKey`. SDK exchanges it
- *      server-side for a capability token + scope blob, then sets
- *      up a refresh scheduler that re-mints transparently before
- *      expiry.
- *   2. **Self-derived** — caller passed an authToken / capability
- *      token but the SDK doesn't yet know the identity. Calls
- *      `resolveIdentity` against the bootstrap endpoint to recover
- *      `participantId` + scope from the token.
- *   3. **Legacy explicit** — self-hosted callers that pass
- *      `organizationId` + `user.id` (or `agentId`) directly. No
- *      server round-trip; SDK trusts the caller.
- *
- * Extracted from `Ablo.ts` so each branch is testable in isolation
- * and the constructor body reads as a single named call rather than
- * a 100+-line if/elif/else with three different side-effect chains.
+ * Each branch is a separate function below, so it can be read and tested on its own.
  */
 import { type RefreshScheduler } from '../auth/index.js';
-import type { BootstrapHelper } from '../sync/BootstrapHelper.js';
+import type { BootstrapFetcher } from '../sync/BootstrapFetcher.js';
 import type { SyncLogger } from '../interfaces/index.js';
 import type { AuthCredentialSource } from '../auth/credentialSource.js';
 import type { ApiKeySetter } from './auth.js';
@@ -42,7 +37,7 @@ export interface IdentityResolveInput {
     readonly kind: 'user' | 'agent' | 'system';
     readonly configuredApiKey: string | ApiKeySetter | null;
     readonly configuredAuthToken: string | null;
-    readonly bootstrapHelper: BootstrapHelper;
+    readonly bootstrapHelper: BootstrapFetcher;
     readonly auth: AuthCredentialSource;
     readonly logger: SyncLogger;
 }
@@ -53,7 +48,7 @@ export interface ResolvedIdentity {
     readonly capabilityToken: string | undefined;
     readonly syncGroups: readonly string[] | undefined;
     readonly participantKind: 'user' | 'agent' | 'system';
-    /** Non-null on the hosted-cloud path; caller stores it for shutdown. */
+    /** Set only on the hosted-cloud path; the caller keeps it to stop refreshes on shutdown. */
     readonly refreshScheduler: RefreshScheduler | null;
 }
 export declare function resolveParticipantIdentity(input: IdentityResolveInput): Promise<ResolvedIdentity>;