@abloatai/ablo 0.25.0 → 0.27.0

package/dist/errors.js

@@ -1,18 +1,14 @@
 /**
- * Typed error hierarchy for `@abloatai/ablo`.
- *
- * Inlined directly so the publishable dist is self-contained. The public
- * package should never reference an unpublished internal package from emitted
- * JS; strict bundlers surface that immediately.
- *
- * ### Two patterns for consumers
+ * The typed error hierarchy for this package. Every error the SDK throws is an
+ * {@link AbloError} or one of its subclasses, so a consumer can catch broadly or
+ * narrowly. There are two equivalent ways to tell errors apart:
  *
  * ```ts
- * // Stripe-style instanceof
+ * // By class, with instanceof
  * if (err instanceof AbloRateLimitError) backoff(err.retryAfterSeconds);
  *
- * // Discriminator-string (for cross-boundary cases where the class
- * // identity gets lost, e.g. across a web worker postMessage)
+ * // By discriminator string, for cases where class identity is lost —
+ * // for example after an error crosses a web worker boundary
  * if (err.type === 'AbloRateLimitError') { ... }
  * ```
  *
@@ -23,37 +19,41 @@ import { errorCodeSpec, classifyRecovery } from './errorCodes.js';
 import { wireClaimSummarySchema, descriptionFromMeta, } from './coordination/schema.js';
 export { ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, classifyRecovery, recoveryClassSchema, RECOVERY_CLASSES, } from './errorCodes.js';
 // ── AbloError hierarchy — the typed error surface ────────────────────
-/** Common shape for all errors thrown by this SDK. */
+/**
+ * The base class for every error this SDK throws. It carries the fields common
+ * to all of them — a {@link type} discriminator, an optional stable {@link code},
+ * and optional HTTP and diagnostic metadata — and defines the shared JSON and
+ * string serialization. Every other error class extends it.
+ */
 export class AbloError extends Error {
-    /** Discriminator string — matches the class name. Lets consumers
-     *  switch on `e.type` without `instanceof` checks across package
-     *  boundaries (matches Stripe's `err.type` pattern). */
+    /** A discriminator string equal to the class name. Switch on `error.type` to
+     *  distinguish error kinds when `instanceof` is unreliable, such as after an
+     *  error has crossed a serialization boundary. */
     type = 'AbloError';
-    /** Stable short identifier for logs + metrics, drawn from the closed
-     *  {@link ErrorCode} registry — e.g. `'apikey_invalid'`,
-     *  `'capability_scope_denied'`. Stored as a plain `string` (not
-     *  `ErrorCode`) so an older SDK still surfaces a newer server's code it
-     *  doesn't recognise yet; producers are constrained at the constructor
-     *  param instead. */
+    /** A stable, machine-readable identifier for the error, drawn from the
+     *  {@link ErrorCode} registry — for example `'apikey_invalid'` or
+     *  `'capability_scope_denied'` — suitable for logs, metrics, and `switch`
+     *  handling. It is typed as a plain `string` rather than {@link ErrorCode} so
+     *  this client can still surface a code from a newer server that it does not
+     *  yet recognize; code producers are constrained at the constructor instead. */
     code;
-    /** HTTP status code when the error originated from an HTTP response. */
+    /** HTTP status code, when the error originated from an HTTP response. */
     httpStatus;
-    /** Correlation id for ops — present when the server sent one on
-     *  `x-request-id`. Include in support tickets. */
+    /** A correlation id for tracing a request through the server, present when the
+     *  server returned one on the `x-request-id` header. Include it in support
+     *  requests. */
     requestId;
-    /** Which input caused the error — a model/field path like
-     *  `'dataroomMember.grants.subject'`. Mirrors Stripe's `error.param`;
-     *  lets tooling point at the exact offending declaration. */
+    /** The specific input that caused the error, as a model or field path such as
+     *  `'dataroomMember.grants.subject'`, so tooling can point at the exact
+     *  offending value. */
     param;
-    /** Link to the docs for this `code`. Mirrors Stripe's `error.doc_url`.
-     *  Defaults from `code` via {@link docUrlForCode} when omitted. */
+    /** A link to the documentation for this error's {@link code}. When not set
+     *  explicitly, it is derived from the code by {@link docUrlForCode}. */
     docUrl;
-    /** Domain-specific structured payload merged into the wire envelope —
-     *  e.g. a schema push's `{ warnings, unexecutable }`, a stale write's
-     *  conflicting rows. Mirrors how Stripe attaches type-specific fields
-     *  (`decline_code`, `payment_intent`) alongside the standard ones, so a
-     *  structured error keeps its detail through `toJSON` instead of being
-     *  flattened to a bare message. */
+    /** Extra structured data specific to this error, merged into the serialized
+     *  envelope — for example a schema push's `{ warnings, unexecutable }`, or the
+     *  conflicting rows of a stale write. This detail is preserved through
+     *  {@link toJSON} rather than flattened into the message. */
     details;
     constructor(message, options) {
         super(message);
@@ -76,9 +76,10 @@ export class AbloError extends Error {
         }
     }
     /**
-     * Serialize to Stripe's error-object shape: `{ type, code, param, message,
-     * doc_url, request_id }`. One JSON shape across HTTP bodies, WS frames, and
-     * logs — so consumers parse Ablo errors the way they already parse Stripe's.
+     * Serializes the error to its wire shape: `{ type, code, param, message,
+     * doc_url, request_id }`, with any {@link details} merged in. This is the same
+     * JSON shape the SDK uses across HTTP bodies, WebSocket frames, and logs, so a
+     * consumer parses every Ablo error the same way.
      */
     toJSON() {
         return {
@@ -92,12 +93,13 @@ export class AbloError extends Error {
         };
     }
     /**
-     * A single, leak-proof line for logs and `String(err)` / template
-     * interpolation: `AbloValidationError [code]: message (see docs) [request_id: …]`.
+     * Formats the error as a single line for logs and string interpolation:
+     * `AbloValidationError [code]: message (see docs) [request_id: …]`.
      *
-     * Deliberately does NOT dump `details`, `cause`, or the stack — the thing that
-     * makes `console.error(richError)` an unreadable wall of text. The structured
-     * payload stays available via {@link toJSON}; this is the human one-liner.
+     * It intentionally omits {@link details}, the cause, and the stack, which are
+     * what turn a logged rich error into an unreadable wall of text. The full
+     * structured payload remains available through {@link toJSON}; this is the
+     * concise human-readable form.
      */
     toString() {
         const code = this.code ? ` [${this.code}]` : '';
@@ -107,9 +109,9 @@ export class AbloError extends Error {
     }
 }
 /**
- * Map a stable error `code` to its docs URL — the one place the convention
- * lives, so every error carrying a code gets a `doc_url` for free (Stripe
- * ships a link on every error).
+ * Builds the documentation URL for a stable error {@link ErrorCode}. This is the
+ * single place the URL convention lives, so every error that carries a code gets
+ * a `doc_url` automatically.
  */
 export function docUrlForCode(code) {
     return `https://docs.abloatai.com/errors#${code}`;
@@ -147,11 +149,11 @@ export class AbloValidationError extends AbloError {
     type = 'AbloValidationError';
 }
 /**
- * 404 — an UPDATE/DELETE addressed a row that doesn't exist (or is outside the
- * caller's org). The engine reports such targets on `CommitReceipt.missingIds`;
- * the typed resource wrappers raise this instead of returning a success receipt
- * for a write that quietly matched zero rows. Carries the offending ids so a
- * caller can see exactly which targets were absent.
+ * An update or delete addressed a row that does not exist, or lies outside the
+ * caller's organization (HTTP 404). Such targets are reported on
+ * {@link CommitReceipt.missingIds}, and the typed resource methods raise this
+ * error rather than returning a successful receipt for a write that quietly
+ * matched zero rows. The absent ids are carried on {@link missingIds}.
  */
 export class AbloNotFoundError extends AbloError {
     type = 'AbloNotFoundError';
@@ -172,15 +174,13 @@ export class AbloServerError extends AbloError {
     type = 'AbloServerError';
 }
 /**
- * 409 — a write carried `readAt: N` but the target entity has received
- * deltas since `N`. The caller's reasoning snapshot is stale; the safe
- * response is to re-read (or re-capture a watermark) and regenerate.
+ * A write carried a `readAt` watermark, but the target row has changed since
+ * that point (HTTP 409). The snapshot the caller reasoned from is stale, so the
+ * safe response is to re-read the row and regenerate the write.
  *
- * Carries `conflicts` so callers can inspect which specific (model, id)
- * pairs moved during the generation window — useful for metrics
- * ("72% of stale rejects were on slide titles") and for selective
- * regeneration (only re-think the slides that changed, not the whole
- * deck).
+ * {@link conflicts} lists the specific model-and-id pairs that changed during
+ * the window between the read and the write, which lets a caller regenerate only
+ * the rows that actually moved rather than everything.
  */
 export class AbloStaleContextError extends AbloError {
     type = 'AbloStaleContextError';
@@ -197,16 +197,15 @@ export class AbloStaleContextError extends AbloError {
     }
 }
 /**
- * The functional `update(id, current => next)` form exhausted its reconcile
- * budget — the row stayed continuously contended (a hot row under sustained
- * concurrent writes), so no attempt could land a compare-and-swap.
+ * The functional `update(id, current => next)` form gave up after exhausting its
+ * reconcile budget, because the row stayed continuously contended under
+ * sustained concurrent writes and no attempt could land its compare-and-swap.
  *
- * This is the ONLY coordination concept the functional update ever surfaces, and
- * only at the extreme: the SDK has already read-fresh → recomputed → retried on
- * every stale/claim conflict on the caller's behalf. Catch it to back off and
- * retry later, raise the `retries` budget, or move that row to the WebSocket
- * transport (which parks writers in a fair FIFO queue instead of racing). The
- * last underlying conflict that drove the final retry is on `.cause`.
+ * The SDK reaches this only at the extreme: it has already re-read, recomputed,
+ * and retried on every intervening conflict on the caller's behalf. Catch it to
+ * back off and retry later, raise the `retries` budget, or move the row to the
+ * WebSocket transport, which queues writers fairly instead of racing them. The
+ * last underlying conflict is available on `cause`.
  */
 export class AbloContentionError extends AbloError {
     type = 'AbloContentionError';
@@ -290,18 +289,17 @@ export class AbloClaimedError extends AbloError {
     }
 }
 /**
- * The `/`-joined human label for a claim target — `model/id/field`, dropping
- * absent parts, falling back to `'target'`. The one place this join lived in
- * three copies (client `Ablo`, HTTP `ApiClient`, `awaitClaimGrant`).
+ * Builds a human-readable label for a claim target by joining its `model`, `id`,
+ * and `field` with `/`, omitting any absent parts and falling back to `'target'`
+ * when none are present.
  */
 export function claimTargetLabel(target) {
     return [target.model, target.id, target.field].filter(Boolean).join('/') || 'target';
 }
 /**
- * Build the {@link AbloClaimedError} for a contended `ablo.<model>` write — the
- * single factory shared by the realtime client (`Ablo`) and the HTTP client
- * (`ApiClient`), which carried byte-identical copies. The first claim is the
- * holder whose metadata shapes the message.
+ * Builds the {@link AbloClaimedError} for a write that was rejected because the
+ * row is claimed. The first entry in `claims` is treated as the current holder,
+ * and its metadata shapes the error message.
  */
 export function claimedError(target, claims, code) {
     const label = claimTargetLabel(target);
@@ -314,18 +312,17 @@ export function claimedError(target, claims, code) {
     }), { code, claims });
 }
 /**
- * A scoped credential was denied — either the key is unknown / revoked /
- * expired (`capability_invalid`), or the connection's resolved scope
- * doesn't cover the attempted action (`capability_scope_denied`). With
- * opaque restricted (`rk_`) API keys this is a server-side check against
- * the key's `syncGroups` / `operations`, not a signed-caveat verification.
- *
- * Extends `AbloPermissionError` so existing `instanceof CapabilityError`
- * checks keep working AND broader `instanceof AbloPermissionError`
- * matches for consumers who don't care about the scope specifics.
+ * A scoped credential was denied, either because the key is unknown, revoked, or
+ * expired (`capability_invalid`), or because the connection's scope does not
+ * cover the attempted action (`capability_scope_denied`). For restricted (`rk_`)
+ * API keys this is a server-side check against the key's granted sync groups and
+ * operations.
  *
- * `requiredCapability` (when present) describes the scope a key must
- * carry for the request to succeed on retry.
+ * It extends {@link AbloPermissionError}, so it is caught both by code that
+ * specifically checks for `CapabilityError` and by code that only distinguishes
+ * the broader permission category. When present, {@link requiredCapability}
+ * describes the scope a key would need to carry for the request to succeed on
+ * retry.
  */
 export class CapabilityError extends AbloPermissionError {
     requiredCapability;
@@ -339,15 +336,12 @@ export class CapabilityError extends AbloPermissionError {
 }
 // ── Legacy session error (now part of the typed hierarchy) ───────────
 /**
- * SyncSessionError — Thrown when authentication/session is invalid or expired.
- * Signals that the user should be redirected to sign in
- * rather than showing a generic retry option.
+ * Thrown when the login session itself is invalid or expired, signaling that the
+ * user should be sent to sign in again rather than offered a generic retry.
  *
- * Extends `AbloAuthenticationError` so existing
- * `SyncSessionError.isSessionError(...)` duck-type callers keep
- * working, AND downstream code that only catches the typed hierarchy
- * (`instanceof AbloAuthenticationError` / `e.type === 'AbloAuthenticationError'`)
- * now sees session failures too.
+ * It extends {@link AbloAuthenticationError}, so it is caught both by code using
+ * the {@link SyncSessionError.isSessionError} check and by code that catches the
+ * authentication category in general.
  */
 export class SyncSessionError extends AbloAuthenticationError {
     isSessionError = true;
@@ -361,44 +355,59 @@ export class SyncSessionError extends AbloAuthenticationError {
         }
     }
     /**
-     * Check if an error is a session error (duck-type check)
+     * Returns true when a value is a {@link SyncSessionError}, or any error-like
+     * object that reports itself as a session error through an `isSessionError`
+     * flag.
      */
     static isSessionError(error) {
         if (error instanceof SyncSessionError) {
             return true;
         }
         if (error && typeof error === 'object' && 'isSessionError' in error) {
-            return error.isSessionError === true;
+            return error.isSessionError;
         }
         return false;
     }
     /**
-     * Check if an HTTP response status indicates a session error
+     * Determines whether an HTTP response means the login session has expired and
+     * the user should sign in again. When the body carries a structured Ablo error
+     * code, the decision is made from that code's recovery class; otherwise a bare
+     * 401 is treated as an expiry and a 403 is not.
      */
     static isSessionErrorResponse(status, body) {
-        // "Should this response sign the user out?" — TRUE only for a genuine
-        // expiry of the LONG-LIVED login (`recovery: 'session_expiry'`). Decided
-        // via the closed recovery taxonomy rather than a hardcoded code list, so
-        // the access-vs-session split lives in one place (errorCodes.ts). This is
-        // behaviourally identical to the old `session_expired || jwt_expired` list.
+        // Sign the user out only for a genuine expiry of the long-lived login
+        // (`recovery: 'session_expiry'`). The decision runs through the recovery
+        // classification rather than a hardcoded list, so the access-versus-session
+        // split lives in one place.
         //
-        // Deliberately NOT true for `access_credential_expiry` (`apikey_expired` —
-        // the Stripe-style ephemeral key): an expired `ek_`/`rk_` is re-mintable
-        // from the still-valid login and must NOT log the user out — the connection
-        // layer silently re-mints instead. Likewise NOT true for `auth_blocked` /
-        // `permission` failures (api_key_required, jwt_issuer_untrusted, 403s):
-        // re-auth re-mints the same rejected credential and loops ("flash then
-        // bounce to /signin").
+        // It deliberately does not fire for `access_credential_expiry`
+        // (`apikey_expired`): an expired short-lived key is re-mintable from the
+        // still-valid login and must not sign the user out — the connection layer
+        // re-mints it instead. It also does not fire for `auth_blocked` or
+        // `permission` failures, where re-authenticating would present the same
+        // rejected credential and loop.
         const code = extractWireCode(body);
         if (code) {
             return classifyRecovery(code) === 'session_expiry';
         }
-        // No structured code (bare body, non-Ablo proxy response): a 401 is taken as
-        // expiry — the historical default that drives re-auth — while a 403 is a
-        // permission failure, not a session error.
+        // With no structured code (a bare body or a non-Ablo proxy response), treat
+        // a 401 as an expiry that drives re-authentication, and a 403 as a
+        // permission failure rather than a session error.
         return status === 401;
     }
 }
+/**
+ * The WebSocket-close counterpart to {@link SyncSessionError.isSessionErrorResponse}:
+ * returns true for close reasons that mean the short-lived access credential
+ * (`ek_` or `rk_`) has expired. The server closes such sockets with code 4001
+ * and reason `'credential_expired'`. Because the credential is re-mintable from
+ * the still-valid login, the connection layer re-mints it and reconnects rather
+ * than signing the user out or clearing local data. Every other session close
+ * reason, such as a revoked key or a genuinely lost login, stays terminal.
+ */
+export function isAccessCredentialExpiryCloseReason(reason) {
+    return reason === 'credential_expired' || classifyRecovery(reason) === 'access_credential_expiry';
+}
 // ── HTTP → class mapping ──────────────────────────────────────────────
 const OptionalWireStringSchema = z.preprocess((value) => (typeof value === 'string' ? value : undefined), z.string().optional());
 const RequiredCapabilityWireSchema = z
@@ -432,8 +441,8 @@ const ErrorFieldSchema = z
     .catch(undefined);
 const ErrorBodyShapeSchema = z
     .object({
-    /** Legacy: `error` was a flat code string on older endpoints. Newer
-     *  endpoints (CommitReceipt) carry `error` as a nested object. */
+    /** The `error` field may be a flat code string, as some endpoints return,
+     *  or a nested error object, as a {@link CommitReceipt} carries. */
     error: ErrorFieldSchema,
     code: OptionalWireStringSchema,
     reason: OptionalWireStringSchema,
@@ -452,16 +461,16 @@ function parseErrorBodyShape(body) {
     return parsed.success ? parsed.data : {};
 }
 /**
- * Coerce ANY thrown value into an {@link AbloError} — the last-line guarantee
- * that an SDK consumer never catches an untagged error. An already-typed
- * AbloError passes through untouched (so `code`/`httpStatus`/subclass survive);
- * a bare `Error` keeps its message and is preserved as `cause` (carrying any
- * `.code` someone attached); a non-Error is stringified.
+ * Coerces any thrown value into an {@link AbloError}, so a consumer never catches
+ * an untyped error from the SDK. An error that is already an {@link AbloError}
+ * passes through unchanged, preserving its subclass, `code`, and `httpStatus`; a
+ * plain `Error` keeps its message and is retained as the `cause` (carrying any
+ * `code` attached to it); anything else is stringified.
  *
- * This is the client mirror of the server's `normalizeError` — applied at the
- * SDK's public async boundaries so `instanceof AbloError` / `e.type` always
- * hold for whatever a consumer catches, regardless of which internal layer
- * (transport, IndexedDB, bootstrap, a third-party throw) produced it.
+ * The SDK applies this at its public async boundaries so that `instanceof
+ * AbloError` and `error.type` hold for whatever a consumer catches, no matter
+ * which internal layer — transport, local storage, bootstrap, or a third-party
+ * throw — produced the original error.
  */
 export function toAbloError(err) {
     if (err instanceof AbloError)
@@ -474,16 +483,15 @@ export function toAbloError(err) {
     return new AbloError(String(err), { cause: err });
 }
 /**
- * Build the appropriate typed {@link AbloError} from a wire error — the
- * single code→class mapping shared by every transport that can reject a
- * request (HTTP responses via {@link translateHttpError}, WebSocket
- * `mutation_result`/`claim_ack` frames, agent-job receipts).
+ * Builds the appropriate typed {@link AbloError} from a wire error. This is the
+ * single code-to-class mapping shared by every transport that can reject a
+ * request — HTTP responses through {@link translateHttpError}, WebSocket result
+ * frames, and agent-job receipts.
  *
- * Code-first, then status-driven. A known {@link ErrorCode} carries its own
- * canonical `httpStatus` in the registry, so frame transports that don't have
- * an HTTP status (the WebSocket commit path) still produce the right subclass
- * — instead of a hand-rolled `new Error(message)` that drops out of the typed
- * hierarchy and loses `code`/`httpStatus`/retryability.
+ * It decides by code first, then by status. Because a known {@link ErrorCode}
+ * carries its canonical HTTP status in the registry, a transport that has no
+ * status of its own (such as the WebSocket commit path) still produces the right
+ * subclass, with its `code`, status, and retryability intact.
  */
 export function errorFromWire(message, opts = {}) {
     const { code, requestId, requiredCapability, claims } = opts;
@@ -503,9 +511,13 @@ export function errorFromWire(message, opts = {}) {
         return new CapabilityError(code, message, requiredCapability);
     }
     // Claim enforcement (rides 409): the target entity is held by another
-    // participant. Discriminate on code BEFORE the generic 409→idempotency
-    // mapping so a claim rejection surfaces as AbloClaimedError.
-    if (code === 'claim_conflict' || code === 'claim_conflict' || code === 'entity_claimed') {
+    // participant, or a lease this participant held is gone (`claim_lost` —
+    // the answer a heartbeat gets after its lease lapsed). Discriminate on
+    // code BEFORE the generic 409→idempotency mapping so claim outcomes
+    // surface as AbloClaimedError on every transport.
+    if (code === 'claim_conflict' ||
+        code === 'entity_claimed' ||
+        code === 'claim_lost') {
         return new AbloClaimedError(message, { ...baseOpts, claims });
     }
     // A write whose `readAt` watermark went stale — callers re-read and retry.
@@ -528,13 +540,11 @@ export function errorFromWire(message, opts = {}) {
     return new AbloError(message, baseOpts);
 }
 /**
- * Translate an HTTP response into the appropriate typed error.
- *
- * Single source of truth for status-code → class mapping — every SDK
- * fetch path that sees a non-2xx response should route through here
- * so the customer-visible error is always the right subclass. Delegates
- * the actual class selection to {@link errorFromWire} (shared with the
- * frame transports) after extracting code/message from the HTTP body.
+ * Translates an HTTP response into the appropriate typed {@link AbloError}. This
+ * is the single mapping every request path routes a non-2xx response through, so
+ * the error a consumer sees is always the right subclass. After extracting the
+ * code and message from the response body, it delegates the class selection to
+ * {@link errorFromWire}, the same logic the frame transports use.
  */
 export function translateHttpError(status, body, requestId) {
     const parsed = parseErrorBodyShape(body);
@@ -565,12 +575,12 @@ export function translateHttpError(status, body, requestId) {
     });
 }
 /**
- * Whether an HTTP error body carries a code {@link translateHttpError} can read
- * — a top-level `code`, a nested `error.code`, or a string `error`. Callers that
- * own a meaningful fallback code (e.g. `turn_open_failed`) use this to decide
- * between routing through `translateHttpError` (structured envelope present) and
- * throwing their own typed error with the fallback (bare/non-Ablo body), instead
- * of emitting a code-less error.
+ * Reports whether an HTTP error body carries a code that {@link translateHttpError}
+ * can read — a top-level `code`, a nested `error.code`, or a string `error`. A
+ * caller that has a meaningful fallback code uses this to choose between routing
+ * a structured body through {@link translateHttpError} and throwing its own typed
+ * error with the fallback when the body is bare, rather than producing an error
+ * with no code.
  */
 export function hasWireCode(body) {
     const parsed = parseErrorBodyShape(body);
@@ -583,10 +593,10 @@ export function hasWireCode(body) {
         typeof parsed.error.code === 'string');
 }
 /**
- * Extract the canonical error `code` from a raw HTTP error body STRING — the
- * top-level `code` or a nested `error.code`. Returns undefined for non-JSON or
- * code-less bodies. Used by session-error detection to tell a genuine expiry
- * (`session_expired`/`jwt_expired`) apart from other auth failures.
+ * Extracts the canonical error `code` from a raw HTTP error body string — the
+ * top-level `code` or a nested `error.code` — returning `undefined` for a
+ * non-JSON or code-less body. Session-error detection uses it to tell a genuine
+ * session expiry apart from other authentication failures.
  */
 export function extractWireCode(body) {
     if (!body)

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @abloatai/ablo — The Collaboration Layer for AI and Humans
+ * @abloatai/ablo — the collaboration layer for AI agents and people.
  *
  * ```ts
  * import Ablo from '@abloatai/ablo';
@@ -14,38 +14,41 @@
  * type Entry = Ablo.Peer;
  * ```
  *
- * `Ablo({ schema, apiKey })` gives typed model clients. `Ablo({ apiKey })`
- * gives the HTTP model/commit client for agents, MCP routes, and custom
- * runtimes.
+ * `Ablo({ schema, apiKey })` returns typed model clients. `Ablo({ apiKey })`
+ * returns the stateless HTTP model and commit client, which suits agents, MCP
+ * route handlers, and custom runtimes.
  *
- * Stripe / Anthropic / OpenAI all do this: one import, model clients
- * reached via dot-access on the engine, types via namespace dots.
+ * The whole package reaches you through one name: `Ablo` is at once a factory
+ * function, a type, and a namespace. You call model clients with dot access on
+ * the instance (`ablo.reports.retrieve(...)`) and reach every supporting type
+ * through the namespace (`Ablo.Peer`, `Ablo.Claim`).
  *
- * Public subpaths:
+ * Related surfaces live on their own import subpaths:
  *   @abloatai/ablo/schema   — defineSchema, model, z (Zod)
  *   @abloatai/ablo/react    — <AbloProvider>, useQuery, useMutate
- *   @abloatai/ablo/testing  — test harnesses + mocks
+ *   @abloatai/ablo/testing  — test harnesses and fixtures
  *
- * Reads split by where the data comes from. `ablo.<model>.retrieve({ id })` and
- * `.list({ where })` are the async **server** reads (pool → IDB → network via
- * the `HydrationCoordinator`, single-flight deduped); they're the default and
- * what hosted/stateless callers want, since their local graph starts empty.
- * `ablo.<model>.get(id)` / `.getAll(...)` / `.getCount(...)` are synchronous
- * **local-graph** snapshots with no network round-trip — for reactive React
- * selectors (`useAblo((ablo) => ablo.<model>.get(id))`) once the graph is warm.
+ * Reads come in two flavors, distinguished by where the data is fetched from.
+ * `ablo.<model>.retrieve({ id })` and `.list({ where })` are asynchronous reads
+ * that consult the local cache first and fall back to the network, de-duplicating
+ * concurrent requests for the same row. They are the default, and the right
+ * choice for stateless callers whose local graph starts empty.
+ * `ablo.<model>.get(id)`, `.getAll(...)`, and `.getCount(...)` are synchronous
+ * snapshots of the already-loaded local graph with no network round-trip — use
+ * them in reactive React selectors (`useAblo((ablo) => ablo.<model>.get(id))`)
+ * once the graph is warm.
  *
- * ── What to import (read this first) ────────────────────────────────
- * Default path — this is all most apps and agents ever need:
- *   • `Ablo` (default export) + `AbloOptions` + the `Model*Params` bags
- *   • the `Ablo*Error` classes, to discriminate failures in catch blocks
- * That's it. If you're reaching past those, you're in advanced territory.
+ * What to import, in short:
+ *   • `Ablo` (the default export), `AbloOptions`, and the `Model*Params` option
+ *     bags cover what most applications and agents ever need.
+ *   • the `Ablo*Error` classes let you discriminate failures in catch blocks.
  *
- * Advanced — opt-in, most apps never import these (each is tagged
- * "Advanced —" at its export below, with the one situation it's for):
- *   • `dataSource` / `abloSource`  — only if your own DB stays canonical
- *   • `defaultPolicy`              — only to customize conflict resolution
- *   • `defineMutators` / `createTransaction` — only for custom mutators
- * If you don't recognize one, you don't need it — the default path covers you.
+ * A handful of exports are for advanced use and are marked "Advanced" at their
+ * declaration below, each with the one situation it is for:
+ *   • `dataSource` / `abloSource`  — when your own database stays canonical.
+ *   • `defaultPolicy`              — when you customize conflict resolution.
+ *   • `defineMutators` / `createTransaction` — when you write custom mutators.
+ * If you don't recognize one of these, you don't need it.
  */
 export { Ablo } from './client/Ablo.js';
 export type { MutationExecutor } from './interfaces/index.js';
@@ -54,7 +57,7 @@ export { DEFAULT_CONTENTION_RETRIES } from './client/functionalUpdate.js';
 export type { HttpClaimApi, InternalAbloOptions } from './client/Ablo.js';
 export { type AbloHttpClientOptions, type AbloHttpClient, type HttpModelClient, } from './client/httpClient.js';
 export { ABLO_DEFAULT_BASE_URL, ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_URL, normalizeAbloHostedBaseUrl, } from './client/auth.js';
-export type { AbloOptions, LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, Claim, HeldClaim, ModelOperations, } from './client/Ablo.js';
+export type { AbloOptions, LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, ModelOperations, } from './client/Ablo.js';
 export type { AbloPersistence } from './client/persistence.js';
 import { Ablo } from './client/Ablo.js';
 export default Ablo;