@abloatai/ablo 0.26.0 → 0.28.0

package/dist/client/options.d.ts

@@ -1,43 +1,33 @@
 /**
- * Option types for the `Ablo({...})` factory — the public `AbloOptions` bag
- * and the full internal construction surface (`InternalAbloOptions`).
- *
- * Extracted from `Ablo.ts` so the option types can be referenced without
- * pulling in the factory's runtime graph. This module is type-only — ZERO
- * runtime imports — so importing it can never create a cycle. `Ablo.ts`
- * re-exports everything here, so existing import paths keep resolving.
+ * The option types for the {@link Ablo} client: the public {@link AbloOptions}
+ * bag callers pass, and the fuller {@link InternalAbloOptions} construction
+ * surface. This module holds only types and has no runtime imports.
  */
 import type { Schema, SchemaRecord } from '../schema/schema.js';
 import type { SyncEngineConfig, SyncLogger, MutationExecutor, SyncObservabilityProvider, SyncAnalytics, SessionErrorDetector, OnlineStatusProvider } from '../interfaces/index.js';
 import type { AbloPersistence } from './persistence.js';
+import type { CommitOutboxStore } from '../transactions/commitOutboxStore.js';
+import type { CommitOutboxScope } from '../transactions/commitEnvelope.js';
 /**
- * Async function that resolves an apiKey at request time. Use for
- * credential rotation — rotate from a vault, refresh from session
- * storage, or pull from a Better Auth session. Mirrors Anthropic's
- * `ApiKeySetter` exactly so any rotation pattern that works with
- * `@anthropic-ai/sdk` works here.
- *
- * Re-exported from `./auth` so existing import paths (`@abloatai/ablo`)
- * keep resolving; the canonical definition lives there alongside the
- * resolvers that consume it.
+ * An async function that resolves an apiKey at request time. Use it for credential
+ * rotation — read from a vault, refresh from session storage, or pull from an
+ * existing auth session. The canonical definition lives in `./auth`; it is
+ * re-exported here for convenience.
  */
 export type { ApiKeySetter } from './auth.js';
 import type { ApiKeySetter } from './auth.js';
 /**
- * Options for `Ablo({...})`.
+ * Options for the {@link Ablo} client.
  *
- * The only required field is `schema`. The default path is one line:
+ * The only required field is `schema`. Because `apiKey` defaults to the
+ * `ABLO_API_KEY` environment variable, most server setups need nothing more:
  *
  * ```ts
  * const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
  * ```
  *
- * `apiKey` itself defaults to `process.env.ABLO_API_KEY`, so in most
- * server setups `Ablo({ schema })` is enough. Every other field is
- * optional tuning (timeouts, retries, custom fetch, persistence) —
- * if you're not sure whether you need one, you don't. Reach for them
- * the way you'd reach for the equivalent option on the Stripe / OpenAI
- * / Anthropic clients: rarely, and deliberately.
+ * Every other field is optional tuning — timeouts, retries, a custom fetch,
+ * persistence. If you are unsure whether you need one, you do not.
  *
  * @see https://docs.abloatai.com — full option reference
  */
@@ -49,70 +39,68 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      */
     schema: Schema<S>;
     /**
-     * API key — **the one auth field most apps set.** Three shapes, one option:
+     * The API key — the auth field most apps set. It accepts three shapes:
      *
-     *  - **A key string** (server): your secret `sk_` — defaults to
-     *    `process.env['ABLO_API_KEY']`, so you usually pass nothing. A
+     *  - **A key string** (server): your secret `sk_` key. Defaults to the
+     *    `ABLO_API_KEY` environment variable, so you usually pass nothing. A
      *    long-lived key needs no refresh; the client uses it as-is.
      *
-     *  - **An endpoint path/URL** — `apiKey: '/api/ablo-session'` (the route
-     *    `ablo init` scaffolds). The SDK owns the whole exchange: it POSTs the
-     *    endpoint (same-origin, cookies included), reads the minted short-lived
-     *    token, and keeps it fresh — a refresh timer ahead of expiry plus
-     *    re-mint on OS-wake and a reactive re-mint when the server reports the
-     *    key stale. You never call a refresh method (the Ably `authUrl` /
-     *    Liveblocks `authEndpoint` model). Detection is by prefix (`/`,
-     *    `http://`, `https://`) — key strings are `sk_`/`ek_`/`rk_`-prefixed so
-     *    the shapes can't collide. Long-lived server clients should pass the
-     *    ABSOLUTE URL: it enables pre-expiry renewal on windowless hosts too.
+     *  - **An endpoint path or URL** — for example `apiKey: '/api/ablo-session'`.
+     *    The client owns the whole exchange: it POSTs the endpoint (same-origin,
+     *    cookies included), reads the minted short-lived token, and keeps it fresh
+     *    with a refresh timer ahead of expiry, a re-mint after the machine wakes
+     *    from sleep, and a re-mint when the server reports the token stale. You
+     *    never call a refresh method yourself. The shape is detected by prefix (`/`,
+     *    `http://`, or `https://`); key strings start with `sk_`/`ek_`/`rk_`, so the
+     *    two cannot be confused. A long-lived server client should pass an absolute
+     *    URL, which also enables pre-expiry renewal on hosts that never sleep.
      *
-     *  - **An async resolver** `() => Promise<string | null>` — the escape
-     *    hatch when the exchange needs custom headers, a body, or a non-HTTP
-     *    mint (vault rotation, AWS STS, a Better Auth session). Same renewal
-     *    machinery as the endpoint form.
+     *  - **An async resolver** `() => Promise<string | null>` — the escape hatch for
+     *    when the exchange needs custom headers, a request body, or a non-HTTP mint
+     *    (vault rotation, a cloud token service, an existing auth session). It uses
+     *    the same renewal machinery as the endpoint form.
      *
-     * Endpoint/resolver contract: produce a token; produce `null` when the login
-     * itself is gone (terminal → the client signs out / fails `ready()` with
-     * `session_expired`); or THROW on a transient failure (→ back off and retry,
-     * never sign out). The endpoint form maps HTTP onto this for you: 401/403 →
-     * signed out, any other failure → transient.
+     * The endpoint and resolver forms share one contract: return a token; return
+     * `null` when the login itself is gone (terminal — the client signs out and
+     * fails `ready()` with `session_expired`); or throw on a transient failure, which
+     * backs off and retries without signing out. The endpoint form maps HTTP onto
+     * this for you: 401 and 403 mean signed out, any other failure is transient.
      */
     apiKey?: string | ApiKeySetter | null | undefined;
     /**
-     * Session-mint endpoint — **the browser auth field**, and the named twin of
-     * `apiKey`'s endpoint-string shape (Liveblocks `authEndpoint` / Ably
-     * `authUrl`). Point it at the route that mints the signed-in user's
-     * short-lived token (`ablo init` scaffolds `/api/ablo-session`):
+     * The session-mint endpoint — the browser-side auth field, and the named
+     * counterpart to the endpoint-string form of {@link AbloOptions.apiKey}. Point it
+     * at the route that mints the signed-in user's short-lived token:
      *
      * ```ts
      * const ablo = Ablo({ schema, authEndpoint: '/api/ablo-session' });
      * ```
      *
-     * The SDK owns the whole exchange — POSTs the route (same-origin, cookies
-     * included), reads `{ token }`, keeps it fresh ahead of expiry, re-mints
-     * when the server reports it stale. 401/403 from the route = signed out;
-     * any other failure is retried, never a sign-out. Also accepts an async
-     * resolver `() => Promise<string | null>` when the exchange needs custom
-     * headers or a body (same contract as the `apiKey` resolver form).
+     * The client owns the whole exchange: it POSTs the route (same-origin, cookies
+     * included), reads `{ token }`, keeps it fresh ahead of expiry, and re-mints when
+     * the server reports the token stale. A 401 or 403 from the route means signed
+     * out; any other failure is retried rather than treated as a sign-out. It also
+     * accepts an async resolver `() => Promise<string | null>` when the exchange
+     * needs custom headers or a body — the same contract as the resolver form of
+     * `apiKey`.
      *
-     * Mutually exclusive with `apiKey` — servers hold a key, browsers hold a
-     * mint route; passing both is a validation error.
+     * Mutually exclusive with `apiKey`: a server holds a key, a browser holds a mint
+     * route, and passing both is a validation error.
      */
     authEndpoint?: string | ApiKeySetter | null | undefined;
     /**
-     * @deprecated The direct connector lets Ablo dial INTO your Postgres and write to
-     * it — the operate-their-database posture we are moving off. Ablo is Stripe-shaped:
-     * it hosts only the transaction log (the ordered sync_deltas) + coordination, never
-     * your data; your rows always live in your own database. Use the signed Data Source
-     * endpoint instead — keep `DATABASE_URL` in your app, expose `dataSource(...)`, and
-     * let your server own the write while Ablo coordinates the sync stream. To keep the
-     * log in your infra too, self-host the engine. See
-     * docs/plans/stripe-shaped-storage-posture.md.
+     * @deprecated The direct connector lets Ablo dial into your Postgres and write to
+     * it directly. Prefer the signed data-source endpoint: keep your `DATABASE_URL`
+     * in your own app, expose `dataSource(...)`, and let your server own the write
+     * while Ablo coordinates the sync stream. Ablo hosts only the ordered
+     * `sync_deltas` log and coordination, never your rows. To keep the log in your own
+     * infrastructure as well, self-host the engine.
      *
-     * Still honored at runtime for back-compat. SERVER-ONLY: it carries credentials, so
-     * it is never sent from the browser — constructing a client with `databaseUrl` and
-     * `dangerouslyAllowBrowser` throws. If you use it, provide a NON-superuser,
-     * non-`BYPASSRLS` role; the connector rejects privileged roles that cannot enforce RLS.
+     * Still honored at runtime for backward compatibility. It is server-only: because
+     * it carries credentials it is never sent from the browser, and constructing a
+     * client with both `databaseUrl` and `dangerouslyAllowBrowser` throws. If you do
+     * use it, supply a role that is neither a superuser nor `BYPASSRLS`; the connector
+     * rejects privileged roles that cannot enforce row-level security.
      */
     databaseUrl?: string | null | undefined;
     /**
@@ -123,35 +111,54 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      */
     persistence?: AbloPersistence;
     /**
-     * Transport selector. `'websocket'` (default) is the live client —
-     * persistent socket, local synced pool, `onChange` subscriptions. `'http'`
-     * returns the STATELESS client for server-side actors (agents, workers,
-     * serverless): same `ablo.<model>` surface and coordination plane, but each
-     * call is one HTTP round-trip, identity rides the Bearer credential, and no
-     * socket is ever opened. With `'http'` the return type narrows to
-     * `AbloHttpClient<S>`, so stateful-only capabilities (`get`/`getAll`,
-     * `onChange`) are compile errors rather than latent runtime gaps.
+     * Durable commit-envelope storage for server-side agents and workers.
+     * The stateful browser client uses its strict IndexedDB transaction store;
+     * the stateless HTTP client has no implicit filesystem and therefore needs a
+     * workflow-, SQLite-, or filesystem-backed implementation to survive a
+     * process restart. One store may serve several actors because every record
+     * is checked against its authenticated scope before replay.
+     */
+    commitOutbox?: CommitOutboxStore;
+    /**
+     * Stable actor/server scope for an injected HTTP {@link commitOutbox}.
+     * Omit it to resolve `organizationId` and `participantId` from the authenticated
+     * `/auth/identity` endpoint. Supplying it avoids that one setup request in
+     * trusted worker environments; `namespace` distinguishes deployments or
+     * workflow lanes that share the same actor identity.
+     */
+    commitOutboxScope?: CommitOutboxScope;
+    /**
+     * Selects the transport. `'websocket'` (the default) is the live client: a
+     * persistent socket, a local synced cache, and `onChange` subscriptions. `'http'`
+     * returns the stateless client for server-side actors — agents, workers, and
+     * serverless handlers. It offers the same `ablo.<model>` surface and coordination
+     * plane, but every call is a single HTTP round-trip, identity rides the bearer
+     * credential, and no socket is opened. With `'http'` the return type narrows to
+     * {@link AbloHttpClient}, so stateful-only capabilities such as `get`, `getAll`,
+     * and `onChange` become compile errors instead of runtime gaps.
      *
-     * Note: session/credential minting (`sessions.create`) currently runs on the
-     * stateful (default) client, not the http client.
+     * Note: session minting through `sessions.create` runs on the default WebSocket
+     * client, not the HTTP client.
      *
      * @default 'websocket'
      */
     transport?: 'websocket' | 'http' | undefined;
     /**
-     * Turn Ablo's diagnostic logging on/off. `true` surfaces the `[Ablo]`
-     * coordination trace — claims requested / queued / granted / released, agent
-     * handovers, connection state — so you can SEE the human+agent coordination
-     * you built while debugging. Omitted/`false` keeps the quiet default (only
-     * warnings + errors). For a middle ground use {@link logLevel}. Env override:
-     * `ABLO_LOG_LEVEL`. Ignored if a custom logger is supplied.
+     * Turns Ablo's diagnostic logging on or off. `true` surfaces the `[Ablo]`
+     * coordination trace — claims requested, queued, granted, and released, agent
+     * handovers, and connection state — so you can watch the coordination between
+     * humans and agents while debugging. Omitting it, or `false`, keeps the quiet
+     * default of warnings and errors only. For a middle ground use {@link logLevel}.
+     * The `ABLO_LOG_LEVEL` environment variable overrides it, and a custom logger
+     * takes precedence.
      */
     debug?: boolean | undefined;
     /**
-     * Log threshold for the default `[Ablo]` logger (takes precedence over
-     * {@link debug}). `'info'` = coordination + connection events without the
-     * per-model registration firehose; `'debug'` = everything; `'warn'` (default)
-     * = warnings + errors only; `'silent'` = nothing. Env override: `ABLO_LOG_LEVEL`.
+     * The log threshold for the default `[Ablo]` logger; takes precedence over
+     * {@link debug}. `'info'` shows coordination and connection events without the
+     * per-model registration detail, `'debug'` shows everything, `'warn'` (the
+     * default) shows warnings and errors only, and `'silent'` shows nothing. The
+     * `ABLO_LOG_LEVEL` environment variable overrides it.
      */
     logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'silent' | undefined;
     /**
@@ -178,18 +185,15 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
 }
 export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
     /**
-     * API key used for authentication.
+     * The API key used for authentication.
      *
-     * Accepts a static string (`sk_live_...`) or an async function that
-     * resolves to one. Defaults to `process.env['ABLO_API_KEY']`.
+     * Accepts a static string (`sk_live_...`) or an async function that resolves to
+     * one. Defaults to the `ABLO_API_KEY` environment variable.
      *
-     * When a function is provided, it's invoked before each request so
-     * you can rotate or refresh credentials at runtime. The function
-     * must return a non-empty string; otherwise an `AbloAuthenticationError`
-     * is thrown. If the function throws, the error is wrapped with the
-     * original available as `cause`.
-     *
-     * Mirrors Anthropic / OpenAI / Stripe SDK shape exactly.
+     * When a function is provided, it is invoked before each request, so you can
+     * rotate or refresh credentials at runtime. It must return a non-empty string, or
+     * an `AbloAuthenticationError` is thrown; if it throws, the error is wrapped with
+     * the original available as `cause`.
      */
     apiKey?: string | ApiKeySetter | null | undefined;
     /**
@@ -198,12 +202,11 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      */
     authEndpoint?: string | ApiKeySetter | null | undefined;
     /**
-     * Bearer auth token. Sent as `Authorization: Bearer <token>` on
-     * every request.
+     * A bearer auth token, sent as `Authorization: Bearer <token>` on every request.
      *
-     * Use this for self-hosted deployments where your auth layer mints
-     * cap tokens directly. Hosted-cloud consumers pass `apiKey` instead;
-     * the server handles cap-mint internally.
+     * Use it for self-hosted deployments where your own auth layer mints capability
+     * tokens directly. Hosted-cloud consumers pass `apiKey` instead and let the
+     * server mint the capability token.
      */
     authToken?: string | null | undefined;
     /**
@@ -244,59 +247,62 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      */
     schema: Schema<S>;
     /**
-     * @deprecated Server derives participant kind from the apiKey's
-     * scope. Pass apiKey only; this option will be removed once the
-     * server-internal cap-mint flow lands.
+     * @deprecated The server derives the participant kind from the apiKey's scope.
+     * Pass `apiKey` only.
      */
     kind?: 'user' | 'agent' | 'system';
     /**
-     * @deprecated Server derives user identity from the apiKey's
-     * scope (or from `Ablo-Acting-User` request header for B2B2C).
-     * Removed once Phase 3 ships.
+     * @deprecated The server derives user identity from the apiKey's scope, or from
+     * the `Ablo-Acting-User` request header for multi-tenant setups. Pass `apiKey`
+     * only.
      */
     user?: {
         id: string;
         teamIds?: string[];
     };
     /**
-     * @deprecated Server derives agent identity from the apiKey's
-     * scope. Removed once Phase 3 ships.
+     * @deprecated The server derives agent identity from the apiKey's scope. Pass
+     * `apiKey` only.
      */
     agentId?: string;
     /**
-     * @deprecated Cap-mint moves server-internal in Phase 3. Pass
-     * `apiKey` only; the server handles capability issuance.
+     * @deprecated Pass `apiKey` only; the server issues the capability token.
      */
     capabilityToken?: string;
     /** Custom logger (default: console). Supplying one bypasses {@link debug}/{@link logLevel}. */
     logger?: SyncLogger;
     /**
-     * Turn Ablo's diagnostic logging on/off. `true` surfaces the `[Ablo]`
-     * coordination trace — claims acquired / queued / granted / released, agent
-     * handovers, connection state — plus internal lifecycle, so you can SEE the
-     * human+agent coordination you built. Omitted/`false` keeps the quiet default
-     * (only warnings + errors). For a middle ground use {@link logLevel}.
-     * Env override: `ABLO_LOG_LEVEL`. Ignored if a custom {@link logger} is passed.
+     * Turns Ablo's diagnostic logging on or off. `true` surfaces the `[Ablo]`
+     * coordination trace — claims acquired, queued, granted, and released, agent
+     * handovers, and connection state — along with internal lifecycle events, so you
+     * can watch the coordination between humans and agents. Omitting it, or `false`,
+     * keeps the quiet default of warnings and errors only. For a middle ground use
+     * {@link logLevel}. The `ABLO_LOG_LEVEL` environment variable overrides it, and a
+     * custom {@link logger} takes precedence.
      */
     debug?: boolean;
     /**
-     * Log threshold for the default `[Ablo]` logger (takes precedence over
-     * {@link debug}). `'info'` = coordination + connection events without the
-     * per-model registration firehose; `'debug'` = everything; `'warn'` (default)
-     * = warnings + errors only; `'silent'` = nothing. Env override: `ABLO_LOG_LEVEL`.
+     * The log threshold for the default `[Ablo]` logger; takes precedence over
+     * {@link debug}. `'info'` shows coordination and connection events without the
+     * per-model registration detail, `'debug'` shows everything, `'warn'` (the
+     * default) shows warnings and errors only, and `'silent'` shows nothing. The
+     * `ABLO_LOG_LEVEL` environment variable overrides it.
      */
     logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'silent';
-    /** ObjectPool size limit (default: 10000) */
+    /** InstanceCache size limit (default: 10000) */
     maxPoolSize?: number;
     /**
-     * Local persistence mode. Defaults to `memory` so Ablo behaves like a
-     * point solution for shared state instead of silently bolting IndexedDB
-     * durability onto every browser consumer.
+     * Local persistence mode. Defaults to `memory`, keeping the local cache in
+     * process rather than adding IndexedDB durability to every browser consumer.
      *
-     * Pass `persistence: 'indexeddb'` only when you want offline queueing
-     * and a reload-surviving local cache in a browser.
+     * Pass `persistence: 'indexeddb'` only when you want offline queueing and a
+     * reload-surviving local cache in a browser.
      */
     persistence?: AbloPersistence;
+    /** Internal mirror of {@link AbloOptions.commitOutbox}. */
+    commitOutbox?: CommitOutboxStore;
+    /** Internal mirror of {@link AbloOptions.commitOutboxScope}. */
+    commitOutboxScope?: CommitOutboxScope;
     /** @deprecated Use `persistence: 'indexeddb'` for durable browser storage. */
     offline?: boolean;
     /**
@@ -306,26 +312,23 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      */
     inMemory?: boolean;
     /**
-     * If true, initialization starts immediately in the background so
-     * `sync.reports.findMany()` works after `await sync.ready()`.
-     *
-     * If false (default), the consumer MUST call `await sync.ready()` before
-     * using the engine — any query before that returns empty results.
+     * When `true`, initialization starts immediately in the background, so reads work
+     * once `await ready()` resolves.
      *
-     * Default: false (explicit is better — prevents silent init failures).
+     * When `false` (the default), you must call `await ready()` before using the
+     * engine; any query before that returns empty results. The explicit default
+     * guards against silent initialization failures.
      */
     autoStart?: boolean;
     /**
-     * How aggressively this client should pull baseline state at
-     * startup.
+     * How much baseline state this client pulls at startup.
      *
-     *  - `'full'`: pull every delta in the configured sync groups before
-     *    `ready()` resolves. Default for `kind: 'user'`.
-     *  - `'none'`: open the WS and process live deltas only — no baseline
-     *    fetch. Reads round-trip via `model.retrieve()`; subscriptions
-     *    populate the pool lazily via covering deltas. Default for
-     *    `kind: 'agent'` because agent-worker / routine runners don't
-     *    need (or want) a local replica of the org's tenant plane.
+     *  - `'full'`: pull every delta in the configured sync groups before `ready()`
+     *    resolves. The default for user clients.
+     *  - `'none'`: open the socket and process live deltas only, with no baseline
+     *    fetch. Reads round-trip through `retrieve`, and subscriptions fill the local
+     *    cache lazily. The default for agent clients, which do not need a local
+     *    replica of the organization's data.
      */
     bootstrapMode?: 'full' | 'none';
     /**
@@ -366,13 +369,10 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      */
     configOverrides?: Partial<SyncEngineConfig>;
     /**
-     * Sync groups (entity scopes) this client subscribes to. **Provisional, not
-     * deprecated** — pick the right lane: normally the server derives these from
-     * the apiKey's scope, but passing them is still REQUIRED today in any config
-     * where the key doesn't resolve them (omitting yields a `degenerate
-     * syncGroups` warning and a zero-fan-out client). Keep passing it explicitly
-     * until the server-derived path ships in Phase 3, at which point it becomes a
-     * true no-op and is removed. Build values with `syncGroup(kind, id)` from
+     * The sync groups (entity scopes) this client subscribes to. Normally the server
+     * derives these from the apiKey's scope; pass them explicitly when the key does
+     * not resolve them, otherwise the client fans out nothing and logs a `degenerate
+     * syncGroups` warning. Build values with `syncGroup(kind, id)` from
      * `@abloatai/ablo/schema`.
      */
     syncGroups?: string[];
@@ -380,7 +380,7 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      * Override the bootstrap endpoint base URL. Use this when your sync
      * server's HTTP API lives on a different host than the WebSocket URL.
      *
-     * Must include the `/api` prefix — `BootstrapHelper` appends
+     * Must include the `/api` prefix — `BootstrapFetcher` appends
      * `/sync/bootstrap` directly. Example:
      * `'http://api.example.com/api'` → `http://api.example.com/api/sync/bootstrap`.
      *
@@ -388,9 +388,9 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      */
     bootstrapBaseUrl?: string;
     /**
-     * Ablo-owned account scope. Required for Branch 3 identity resolution
-     * in `identity.ts` — without it the SDK falls through to the
-     * `/api/identity` HTTP-derived path (Branch 2).
+     * The account scope. Supply it together with a user or agent id to resolve
+     * identity locally without a server round-trip; without it, the client resolves
+     * identity from the token through the identity endpoint instead.
      */
     organizationId?: string;
 }

package/dist/client/options.js

@@ -1,10 +1,6 @@
 /**
- * Option types for the `Ablo({...})` factory — the public `AbloOptions` bag
- * and the full internal construction surface (`InternalAbloOptions`).
- *
- * Extracted from `Ablo.ts` so the option types can be referenced without
- * pulling in the factory's runtime graph. This module is type-only — ZERO
- * runtime imports — so importing it can never create a cycle. `Ablo.ts`
- * re-exports everything here, so existing import paths keep resolving.
+ * The option types for the {@link Ablo} client: the public {@link AbloOptions}
+ * bag callers pass, and the fuller {@link InternalAbloOptions} construction
+ * surface. This module holds only types and has no runtime imports.
  */
 export {};

package/dist/client/registerDataSource.d.ts

@@ -1,19 +1,19 @@
 export interface RegisterDataSourceInput {
-    /** HTTP API base, e.g. `https://api.abloatai.com/api` (from resolveBootstrapBaseUrl). */
+    /** The HTTP API base, for example `https://api.abloatai.com/api`. */
     readonly baseUrl: string;
-    /** Secret key (`sk_…`) used to authenticate + derive the org. */
+    /** The secret key (`sk_…`) used to authenticate the call and derive the organization. */
     readonly apiKey: string | null;
-    /** Postgres connection string for the direct connector. */
+    /** The Postgres connection string to register. */
     readonly databaseUrl: string;
-    /** Optional Postgres schema (defaults server-side to `public`). */
+    /** An optional Postgres schema; the server defaults to `public`. */
     readonly schema?: string;
-    /** Custom fetch (tests/proxies/odd runtimes). */
+    /** A custom fetch implementation for tests, proxies, or unusual runtimes. */
     readonly fetchImpl?: typeof fetch;
 }
 /**
- * POST the connection string to the self-serve datasource route. Resolves on
- * success (the org's data plane now points at this DB); throws an `AbloError`
- * with `datasource_registration_failed` otherwise so `ready()` surfaces it
- * instead of silently bootstrapping against the wrong store.
+ * Posts the connection string to the data-source registration route. Resolves once
+ * the organization's data plane points at this database; otherwise throws an
+ * {@link AbloError} with code `datasource_registration_failed`, so `ready()`
+ * surfaces the failure instead of quietly bootstrapping against the wrong store.
  */
 export declare function registerDataSource(input: RegisterDataSourceInput): Promise<void>;

package/dist/client/registerDataSource.js

@@ -1,25 +1,24 @@
 /**
- * Self-serve direct-kind datasource registration.
+ * Registers a direct database connection as an organization's data source.
  *
- * When a client is constructed with `databaseUrl`, the SDK registers that
- * connection string BEFORE bootstrap so the server resolves the org's data plane
- * to that direct connection.
+ * When a client is constructed with `databaseUrl`, the SDK calls this before
+ * bootstrap so the server points the organization's data plane at that connection.
  *
- * Targets the unified `POST /v1/datasources` resource; on a 404 (an older
- * server without the unified route) it falls back to the legacy
- * `POST /v1/datasource` alias so an SDK upgrade never strands registration.
+ * It posts to `POST /v1/datasources`, falling back to the older
+ * `POST /v1/datasource` route on a 404 so registration still works against an
+ * earlier server.
  *
- * The org is derived server-side from the API key — the caller never sends an
- * organization id. The connection string is sent once over TLS and is never
- * echoed back (the server stores it as a secret and returns only a safe
- * `datasource` projection: host, database, schema).
+ * The organization is derived on the server from the API key; the caller never
+ * sends an organization id. The connection string is sent once over TLS and is
+ * never echoed back — the server stores it as a secret and returns only a safe
+ * projection of the data source (host, database, schema).
  */
 import { AbloError } from '../errors.js';
 /**
- * POST the connection string to the self-serve datasource route. Resolves on
- * success (the org's data plane now points at this DB); throws an `AbloError`
- * with `datasource_registration_failed` otherwise so `ready()` surfaces it
- * instead of silently bootstrapping against the wrong store.
+ * Posts the connection string to the data-source registration route. Resolves once
+ * the organization's data plane points at this database; otherwise throws an
+ * {@link AbloError} with code `datasource_registration_failed`, so `ready()`
+ * surfaces the failure instead of quietly bootstrapping against the wrong store.
  */
 export async function registerDataSource(input) {
     if (!input.apiKey) {
@@ -51,7 +50,7 @@ export async function registerDataSource(input) {
     };
     let response = await post(`${base}/v1/datasources`);
     if (response.status === 404) {
-        // Older server without the unified resource — use the legacy alias.
+        // The newer route is absent on an older server; use the earlier one.
         response = await post(`${base}/v1/datasource`);
     }
     if (!response.ok) {