@abloatai/ablo 0.26.0 → 0.27.0

package/dist/client/auth.js

@@ -1,15 +1,15 @@
 /**
- * Auth + URL resolution for `Ablo()`.
+ * Authentication and URL resolution for the `Ablo()` client.
  *
- * Mirrors the small, focused helpers Anthropic ships in `client.ts`
- * (`apiKeyAuth`, `bearerAuth`, `validateHeaders`). Each function does
- * one thing — resolve a value with the right precedence, or fail
- * with an actionable message — so the constructor reads as a
- * sequence of named decisions rather than a stream of `??`-chains.
+ * Each function here makes one decision: it resolves a configuration value with
+ * the right precedence, or fails with an actionable message. Together they let
+ * the client constructor read as a sequence of named steps rather than a chain
+ * of fallbacks.
  *
- * Customer-facing env surface is intentionally small: `ABLO_API_KEY`
- * is the only environment fallback. Other routing/auth overrides are
- * explicit options so generated apps do not accrete hidden env knobs.
+ * The environment surface is deliberately small: `ABLO_API_KEY` is the only
+ * value read from the environment. Every other routing or authentication
+ * override is an explicit option, so an app never picks up hidden behavior from
+ * a stray environment variable.
  */
 import { AbloAuthenticationError, AbloValidationError } from '../errors.js';
 import { classifyCredentialKind } from '../auth/credentialPolicy.js';
@@ -25,13 +25,12 @@ export function readProcessEnv() {
     return maybeGlobal.process?.env ?? {};
 }
 export function resolveApiKey(input) {
-    // `authEndpoint` — the NAMED session-mint field (Liveblocks `authEndpoint` /
-    // Ably `authUrl`): a route string the SDK exchanges for a short-lived token,
-    // or an async resolver for custom exchanges. Resolved HERE — the one
-    // resolution point all three factory branches (WS, `transport: 'http'`,
-    // protocol client) share — into an `ApiKeySetter`, so every downstream
-    // consumer sees the familiar resolver and the credential lifecycle drives
-    // renewal off it.
+    // `authEndpoint` is the option that names a session-mint route: a URL the
+    // client exchanges for a short-lived token, or an async resolver for custom
+    // exchanges. It is resolved into an `ApiKeySetter` here — the single point
+    // shared by every client variant (WebSocket, HTTP, and protocol clients) — so
+    // every downstream consumer sees the same resolver and the credential
+    // lifecycle drives renewal off it.
     const endpoint = input.options.authEndpoint;
     const configured = input.options.apiKey;
     if (endpoint != null) {
@@ -48,10 +47,10 @@ export function resolveApiKey(input) {
         }
         return createEndpointCredentialResolver(endpoint);
     }
-    // `apiKey` also accepts the endpoint-string shape directly (same detection —
-    // key strings are `sk_`/`ek_`/`rk_`-prefixed so the shapes can't collide).
-    // Deliberately only the EXPLICIT option: an `ABLO_API_KEY` env value is
-    // always a literal key, never endpoint-detected.
+    // `apiKey` also accepts the endpoint-string form directly, detected the same
+    // way — key strings are prefixed (`sk_`/`ek_`/`rk_`), so the two shapes never
+    // collide. Only the explicit option is treated this way: an `ABLO_API_KEY`
+    // environment value is always a literal key, never an endpoint.
     if (typeof configured === 'string' && isCredentialEndpoint(configured)) {
         return createEndpointCredentialResolver(configured);
     }
@@ -63,7 +62,7 @@ export function resolveAuthToken(input) {
 function keyPrefix(key) {
     return `${key.slice(0, 12)}…`;
 }
-/** Infer sandbox/production from Ablo key prefixes without importing CLI code. */
+/** Infer the sandbox or production mode from an Ablo key's prefix. */
 export function modeFromApiKey(key) {
     if (/^(sk|rk)_test_/.test(key))
         return 'sandbox';
@@ -225,39 +224,38 @@ export function describeCliKeyMismatch(configured, cli) {
     return null;
 }
 /**
- * Resolve the direct-URL connector's Postgres connection string.
+ * Resolves the Postgres connection string for the direct-connection option, or
+ * `null` when none was given.
  *
- * `databaseUrl` is an EXPLICIT, opt-in option: Ablo registers a dedicated
- * tenant database only when the caller passes it to `Ablo(...)`. It is NOT
- * read from `process.env.DATABASE_URL` — per this module's invariant
- * (`ABLO_API_KEY` is the only environment fallback), an app's `DATABASE_URL`
- * (commonly set for Prisma/Drizzle/docker) must never silently flip the client
- * into connection-string mode. The default Data Source path keeps `DATABASE_URL`
- * in the app and exposes `dataSource(...)`; that path leaves this null.
- * `warnIfDatabaseUrlEnvIgnored` nudges callers who set the env but omitted the option.
+ * `databaseUrl` is opt-in: the client registers a dedicated database only when
+ * the caller passes it explicitly. It is never read from
+ * `process.env.DATABASE_URL`, because this module treats `ABLO_API_KEY` as the
+ * one environment fallback — an app's `DATABASE_URL`, commonly set for other
+ * tools, must not silently switch the client into connection-string mode. The
+ * default path leaves `DATABASE_URL` untouched and reads through `dataSource(...)`
+ * instead, so this returns `null`. {@link warnIfDatabaseUrlEnvIgnored} nudges a
+ * caller who set the environment variable but omitted the option.
  */
 export function resolveDatabaseUrl(input) {
     return input.options.databaseUrl ?? null;
 }
 /**
- * One-time migration nudge for the dropped `DATABASE_URL` env fallback.
+ * Warns once when `DATABASE_URL` is set in the environment but `databaseUrl` was
+ * not passed as an option.
  *
- * Earlier versions silently adopted `process.env.DATABASE_URL` when `databaseUrl`
- * was not passed, registering a direct connector behind the caller's back — which
- * surprised any app that keeps `DATABASE_URL` for another tool (Prisma, Drizzle,
- * docker-compose) and, on localhost, tried to register a database Ablo's cloud
- * cannot reach. The env value is now ignored; this points the developer at the
- * explicit option instead of flipping their mode for them. Warns once per process
- * so it never spams, and falls back to `console.warn` when no logger is supplied
- * (the `transport: 'api'` client has none).
+ * The client does not adopt `process.env.DATABASE_URL` on its own, because that
+ * value is commonly set for other tools and switching the client into
+ * connection-string mode behind the caller's back is surprising — and on
+ * localhost it would try to register a database the hosted service cannot reach.
+ * This warning points the developer at the explicit option instead. It fires at
+ * most once per process and falls back to `console.warn` when no logger is
+ * supplied.
  *
- * Suppressed entirely on the hosted/token path: if an `apiKey` resolves (option
- * or `ABLO_API_KEY` env), the caller has chosen the hosted capability-token /
- * Data Source transport, which is mutually exclusive with direct `databaseUrl`
- * mode. A `DATABASE_URL` sitting in that environment is unrelated infra (Prisma,
- * Drizzle, the sync-server) — never an omitted option — so nudging would be a
- * false positive. This is the first-party hosted app's exact shape, where the
- * stray nudge otherwise reaches end-user desktop logs.
+ * The warning is skipped entirely when an `apiKey` resolves (from the option or
+ * `ABLO_API_KEY`): that caller has chosen the hosted, token-based transport,
+ * which is separate from the direct `databaseUrl` connection. A `DATABASE_URL`
+ * present in that environment belongs to unrelated infrastructure, not an omitted
+ * option, so warning would be a false positive.
  */
 let warnedDatabaseUrlEnvIgnored = false;
 export function warnIfDatabaseUrlEnvIgnored(input, warn) {
@@ -282,19 +280,18 @@ export function warnIfDatabaseUrlEnvIgnored(input, warn) {
         console.warn('[Ablo]', message);
 }
 /**
- * One-time deprecation nudge for the `databaseUrl` direct connector.
+ * Warns once when the deprecated `databaseUrl` option is used.
  *
- * `databaseUrl` registers the `dedicated` storage mode — Ablo opens a pool INTO
- * the caller's Postgres and writes into it directly. That is 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. The supported path is the signed Data
- * Source endpoint (`dataSource(...)`), where your app owns the write and your
- * credentials never leave it. See docs/plans/stripe-shaped-storage-posture.md.
+ * Passing `databaseUrl` opens a connection pool directly into your Postgres and
+ * writes to it. That option is deprecated. Ablo is designed to host only the
+ * ordered transaction log (the `sync_deltas` table) and coordination state,
+ * never your rows — your data stays in your own database. The supported path is
+ * a signed data-source endpoint (`dataSource(...)`), where your app owns the
+ * write and your database credentials never leave it.
  *
- * Still honored at runtime so existing integrations keep working; this only warns
- * once per process (so it never spams) and falls back to `console.warn` when no
- * logger is supplied (the `transport: 'http'`/`'api'` client has none).
+ * The option still works at runtime so existing integrations keep running. This
+ * warning fires at most once per process and falls back to `console.warn` when
+ * no logger is supplied.
  */
 let warnedDatabaseUrlDeprecated = false;
 export function warnIfDatabaseUrlDeprecated(input, warn) {
@@ -335,8 +332,8 @@ export async function warnIfCliKeyMismatch(input, warn) {
     else if (typeof console !== 'undefined')
         console.warn('[Ablo]', mismatch.message);
 }
-// Declared in the dependency-free `hostedEndpoints.ts` leaf (single source of
-// the hosted domain); re-exported here so existing import paths keep working.
+// Declared in `./hostedEndpoints`, the single source of the hosted domain, and
+// re-exported here so existing import paths keep working.
 export { ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_URL, ABLO_DEFAULT_BASE_URL } from './hostedEndpoints.js';
 const LEGACY_HOSTED_API_HOSTS = new Set([
     'mesh.ablo.finance',
@@ -345,29 +342,29 @@ const LEGACY_HOSTED_API_HOSTS = new Set([
     'sync-staging.ablo.finance',
 ]);
 /**
- * Normalize old hosted aliases to the public API domain. Self-hosted/custom
- * URLs pass through unchanged; only first-party legacy hosts are rewritten.
+ * Normalizes older hosted host names to the current public API domain.
+ * Self-hosted or custom URLs pass through unchanged; only the retired
+ * first-party host names are rewritten.
  */
 export function normalizeAbloHostedBaseUrl(rawUrl) {
     const trimmed = rawUrl.trim();
     if (!trimmed)
         return trimmed;
-    // A scheme-less value (e.g. `api-staging.abloatai.com`) is a RELATIVE URL:
-    // `new URL()` throws on it, and downstream `fetch` then resolves it against
-    // the current page — producing `https://<app-host>/<route>/api-staging…/api/
-    // auth/identity`, a 404 from the app's own origin. Prepend a scheme so the
-    // base is absolute. `https` mirrors `ABLO_HOSTED_HTTP_BASE_URL`; the socket
-    // layer derives `wss` from it. An existing scheme (ws/wss/http/https) is
-    // preserved untouched.
+    // A scheme-less value (e.g. `api-staging.abloatai.com`) is treated as a
+    // relative URL: `new URL()` throws on it, and a later `fetch` would resolve it
+    // against the current page — producing a 404 from the app's own origin.
+    // Prepending a scheme makes the base absolute. `https` matches
+    // {@link ABLO_HOSTED_HTTP_BASE_URL}; the socket layer derives `wss` from it.
+    // An existing scheme (ws, wss, http, or https) is preserved untouched.
     const schemed = /^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`;
     try {
         const url = new URL(schemed);
-        // Canonicalize the scheme to the HTTP family — the WHATWG WebSocket
-        // model: accept all four schemes (`http`/`https`/`ws`/`wss`), normalize
-        // ONCE at the entry point, and let each layer derive its own protocol
-        // (the socket layer maps http→ws / https→wss; fetch uses it as-is).
-        // Before this, a `ws://` baseURL reached HTTP consumers un-normalized
-        // and the client wedged at startup instead of connecting.
+        // Canonicalize the scheme to the HTTP family: accept all four schemes
+        // (http, https, ws, wss), normalize at this single entry point, and let
+        // each layer derive its own protocol (the socket layer maps http to ws and
+        // https to wss; fetch uses the URL as-is). Without this, a `ws://` base URL
+        // reaches HTTP consumers un-normalized and the client fails at startup
+        // instead of connecting.
         if (url.protocol === 'ws:')
             url.protocol = 'http:';
         if (url.protocol === 'wss:')
@@ -388,11 +385,12 @@ export function resolveBaseURL(input) {
     return normalizeAbloHostedBaseUrl(input.options.baseURL ?? ABLO_DEFAULT_BASE_URL);
 }
 /**
- * Browser guard — apiKey is server-side-only by default. Same check
- * Anthropic, OpenAI, and Stripe ship: shipping `sk_live_...` to a
- * browser exposes it in every visitor's network tab. Consumers opt
- * in explicitly when the browser holds a minted session token
- * (`ek_`/`rk_`) or routes through a server proxy.
+ * Guards against using a secret `apiKey` in a browser. A secret key is
+ * server-side only by default: shipping an `sk_live_...` key to a browser would
+ * expose it in every visitor's network tab. Callers opt in explicitly when the
+ * browser instead holds a minted session token (`ek_`/`rk_`) or routes through a
+ * server proxy. Throws {@link AbloAuthenticationError} when a secret key is
+ * detected in a browser without opt-in.
  */
 export function assertBrowserSafety(input) {
     const inBrowser = typeof window !== 'undefined';
@@ -407,9 +405,9 @@ export function assertBrowserSafety(input) {
             '`dangerouslyAllowBrowser` option to `true`, e.g.,\n\n' +
             '    Ablo({ schema, apiKey, dangerouslyAllowBrowser: true });\n', { code: 'browser_apikey_blocked' });
     }
-    // `databaseUrl` carries DB credentials and is NEVER browser-safe, so
-    // `dangerouslyAllowBrowser` does not override it. Register your database from
-    // a server-side runtime.
+    // `databaseUrl` carries database credentials and is never browser-safe, so
+    // `dangerouslyAllowBrowser` does not override this check. Register your
+    // database from a server-side runtime.
     if (inBrowser && typeof input.databaseUrl === 'string' && input.databaseUrl.length > 0) {
         throw new AbloAuthenticationError('Ablo `databaseUrl` cannot be used in a browser-like environment — it ' +
             'carries your database credentials. Initialize the client with ' +
@@ -417,12 +415,10 @@ export function assertBrowserSafety(input) {
     }
 }
 /**
- * Resolve an `ApiKeySetter` callable to its current string value.
- * Used at request time so a rotating credential picks up rotations
- * between requests. Returns `null` when no key was configured.
- *
- * Mirrors Anthropic's pattern of supporting both a static string and
- * a callable for credential rotation.
+ * Resolves an {@link ApiKeySetter} callable to its current string value, or
+ * returns a plain string key as-is. Called at request time so a rotating
+ * credential picks up new values between requests. Returns `null` when no key
+ * was configured.
  */
 export async function resolveApiKeyValue(apiKey) {
     if (apiKey == null)
@@ -432,44 +428,39 @@ export async function resolveApiKeyValue(apiKey) {
     return apiKey;
 }
 /**
- * Translate a sync-engine WebSocket URL to the matching HTTP API
- * base URL, defaulting to `${url}/api` when the caller hasn't
- * overridden `bootstrapBaseUrl`. Used by `BootstrapHelper`,
- * `HydrationCoordinator`, the apiKey-exchange flow, and the
- * self-derived identity flow — same derivation in all four spots,
- * so it lives here as a single source of truth.
+ * Translates a WebSocket URL into the matching HTTP API base URL, defaulting to
+ * `${url}/api` when the caller has not overridden `bootstrapBaseUrl`. The
+ * bootstrap helper, the hydration coordinator, the credential-exchange flow, and
+ * the identity flow all derive their base URL through this one function, so the
+ * derivation stays consistent across them.
  *
- * Note: when both `wss://` and `https://` are valid, `replace(/^ws/, 'http')`
- * preserves the protocol family (ws → http, wss → https).
+ * When both `wss://` and `https://` are valid, the ws-to-http rewrite preserves
+ * the protocol family: ws becomes http and wss becomes https.
  */
 export function resolveBootstrapBaseUrl(input) {
     if (input.bootstrapBaseUrl) {
-        // Coerce ws/wss → http/https on the override path too. This base URL is
-        // used for HTTP fetches (identity resolve, apiKey exchange, bootstrap) and
-        // the browser `fetch` rejects ws/wss schemes outright ("URL scheme \"wss\"
-        // is not supported"). apps/web derives this override as `${baseUrl}/api`
-        // where `baseUrl` may carry a WebSocket scheme, so the override can
-        // legitimately arrive as `wss://…` — normalize it here rather than
-        // faceplanting at fetch time. The derive branch below already does this;
-        // the override branch silently skipped it.
+        // Coerce ws/wss to http/https on the override path as well. This base URL is
+        // used for HTTP fetches (identity resolution, credential exchange, and
+        // bootstrap), and the browser `fetch` rejects ws and wss schemes outright.
+        // The override can legitimately arrive with a WebSocket scheme when a caller
+        // derives it as `${baseUrl}/api` from a WebSocket base URL, so normalize it
+        // here rather than failing at fetch time.
         return ensureApiSuffix(normalizeAbloHostedBaseUrl(input.bootstrapBaseUrl).replace(/^ws/, 'http'));
     }
     const url = normalizeAbloHostedBaseUrl(input.url);
     return ensureApiSuffix(url.replace(/^ws/, 'http'));
 }
 /**
- * Guarantee the HTTP base ends in the `/api` route segment the sync-server
- * mounts every endpoint under (`apps/sync-server/src/index.ts` — `app.route('/api', …)`).
+ * Ensures the HTTP base ends in the `/api` route segment that every endpoint is
+ * mounted under.
  *
- * The derive branch always appended `/api`; the override branch did NOT,
- * trusting the caller (apps/web passes `${baseUrl}/api`). But a hosted
- * customer setting a custom `baseURL`/`bootstrapBaseUrl` (their own subdomain,
- * staging, etc.) without the suffix sent every credential exchange to
- * `…/auth/capability` instead of `…/api/auth/capability` → a 404 surfaced as
- * `exchange_failed`. Since the SDK hardcodes routes relative to this base and
- * there is no valid Ablo deployment that serves them off the root, normalizing
- * to a single trailing `/api` here is always correct — and idempotent for
- * callers who already include it.
+ * A hosted deployment that sets a custom `baseURL` or `bootstrapBaseUrl` (a
+ * custom subdomain, a staging host, and so on) without the `/api` suffix would
+ * send every credential exchange to `…/auth/capability` instead of
+ * `…/api/auth/capability`, producing a 404 that surfaces as `exchange_failed`.
+ * Since the client builds routes relative to this base and no valid deployment
+ * serves them from the root, appending a single trailing `/api` here is always
+ * correct, and it is idempotent for callers who already include it.
  */
 function ensureApiSuffix(httpBase) {
     const trimmed = httpBase.replace(/\/+$/, '');
@@ -482,8 +473,8 @@ function ensureApiSuffix(httpBase) {
         return u.toString().replace(/\/+$/, '');
     }
     catch {
-        // Should be unreachable post-`normalizeAbloHostedBaseUrl` (which yields an
-        // absolute URL), but fall back to a string check rather than throwing.
+        // Should be unreachable after `normalizeAbloHostedBaseUrl`, which yields an
+        // absolute URL, but fall back to a string check rather than throwing.
         return trimmed.endsWith("/api") ? trimmed : `${trimmed}/api`;
     }
 }

package/dist/client/claimHeartbeatLoop.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The auto-heartbeat loop behind `claim({ id, heartbeat: true })` — one
+ * implementation shared by both transports (the WebSocket claim stream and the
+ * HTTP `ApiClient`), so the cadence and failure semantics cannot drift.
+ *
+ * A beat is the "still working" signal that keeps a lease alive for the
+ * duration of real work. The loop's failure handling follows the lease-system
+ * convention (SQS visibility heartbeats, Kubernetes leases): a beat that fails
+ * for a transient reason — the network blipped, the server was briefly
+ * unavailable — is simply retried on the next tick, because the lease has
+ * runway to spare by construction (the default cadence is a third of the TTL,
+ * so two consecutive beats can fail before the lease is even at risk). Only a
+ * definitive answer from the server — the lease lapsed and may have been
+ * granted to the next in line ({@link AbloClaimedError}) — stops the loop and
+ * surfaces the loss, because for a caller with no push channel the failed beat
+ * IS the loss notification.
+ */
+import { AbloClaimedError } from '../errors.js';
+import type { ClaimHeartbeat, ClaimHeartbeatOptions, Duration } from '../types/streams.js';
+/**
+ * Normalize the public `heartbeat(options?)` argument — a bare Duration is
+ * shorthand for `{ ttl }`. Shared by both transports' handle assembly so the
+ * shorthand cannot drift.
+ */
+export declare function resolveHeartbeatOptions(input: Duration | ClaimHeartbeatOptions | undefined): ClaimHeartbeatOptions;
+/**
+ * The beat cadence for a lease of `ttlMs`: an explicit duration when the
+ * caller set one, otherwise a third of the TTL (floored at 1s) — the
+ * DynamoDB-lock-client rule, leaving two missed beats of runway before the
+ * lease is at risk while keeping crash recovery within one beat window.
+ */
+export declare function heartbeatCadenceMs(ttlMs: number, heartbeat: true | Duration): number;
+export interface ClaimHeartbeatLoopOptions {
+    /** Send one beat; resolves while the lease is still ours. */
+    beat(): Promise<ClaimHeartbeat>;
+    /** Cadence between beats. Callers default this to a third of the TTL. */
+    intervalMs: number;
+    /**
+     * Called once when a beat comes back with a definitive loss — the lease
+     * expired or was taken. The loop has already stopped by the time this runs.
+     */
+    onLost?(error: AbloClaimedError): void;
+}
+/**
+ * Start beating. Returns a stop function; callers stop the loop when the
+ * claim is released (all held-claim assembly sites tie this to `release`).
+ * Beats never overlap: a tick that fires while the previous beat is still
+ * in flight is skipped rather than stacked.
+ */
+export declare function startClaimHeartbeatLoop(options: ClaimHeartbeatLoopOptions): () => void;

package/dist/client/claimHeartbeatLoop.js

@@ -0,0 +1,88 @@
+/**
+ * The auto-heartbeat loop behind `claim({ id, heartbeat: true })` — one
+ * implementation shared by both transports (the WebSocket claim stream and the
+ * HTTP `ApiClient`), so the cadence and failure semantics cannot drift.
+ *
+ * A beat is the "still working" signal that keeps a lease alive for the
+ * duration of real work. The loop's failure handling follows the lease-system
+ * convention (SQS visibility heartbeats, Kubernetes leases): a beat that fails
+ * for a transient reason — the network blipped, the server was briefly
+ * unavailable — is simply retried on the next tick, because the lease has
+ * runway to spare by construction (the default cadence is a third of the TTL,
+ * so two consecutive beats can fail before the lease is even at risk). Only a
+ * definitive answer from the server — the lease lapsed and may have been
+ * granted to the next in line ({@link AbloClaimedError}) — stops the loop and
+ * surfaces the loss, because for a caller with no push channel the failed beat
+ * IS the loss notification.
+ */
+import { AbloClaimedError } from '../errors.js';
+import { toMs } from '../utils/duration.js';
+/**
+ * Normalize the public `heartbeat(options?)` argument — a bare Duration is
+ * shorthand for `{ ttl }`. Shared by both transports' handle assembly so the
+ * shorthand cannot drift.
+ */
+export function resolveHeartbeatOptions(input) {
+    if (input === undefined)
+        return {};
+    if (typeof input === 'string' || typeof input === 'number') {
+        return { ttl: input };
+    }
+    return input;
+}
+/**
+ * The beat cadence for a lease of `ttlMs`: an explicit duration when the
+ * caller set one, otherwise a third of the TTL (floored at 1s) — the
+ * DynamoDB-lock-client rule, leaving two missed beats of runway before the
+ * lease is at risk while keeping crash recovery within one beat window.
+ */
+export function heartbeatCadenceMs(ttlMs, heartbeat) {
+    if (heartbeat !== true)
+        return toMs(heartbeat);
+    return Math.max(Math.floor(ttlMs / 3), 1_000);
+}
+/**
+ * Start beating. Returns a stop function; callers stop the loop when the
+ * claim is released (all held-claim assembly sites tie this to `release`).
+ * Beats never overlap: a tick that fires while the previous beat is still
+ * in flight is skipped rather than stacked.
+ */
+export function startClaimHeartbeatLoop(options) {
+    let stopped = false;
+    let inFlight = false;
+    const stop = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        clearInterval(timer);
+    };
+    const timer = setInterval(() => {
+        if (stopped || inFlight)
+            return;
+        inFlight = true;
+        options
+            .beat()
+            .catch((error) => {
+            if (stopped)
+                return;
+            if (error instanceof AbloClaimedError) {
+                stop();
+                options.onLost?.(error);
+                return;
+            }
+            // Transient (connection, brief server unavailability): the next tick
+            // is the retry — the ttl/3 cadence leaves runway for missed beats.
+        })
+            .finally(() => {
+            inFlight = false;
+        });
+    }, options.intervalMs);
+    // The loop must never be what keeps a Node process alive — the held work
+    // is. A worker that finishes without releasing exits anyway, and the lease
+    // lapses on schedule. No-op in browsers (where setInterval returns a number
+    // without `unref`), which is why the call is optional even though the Node
+    // timer type always has it.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    timer.unref?.();
+    return stop;
+}

package/dist/client/consoleLogger.d.ts

@@ -1,9 +1,8 @@
 /**
- * The default `[Ablo]` console logger + its level resolution.
+ * The default `[Ablo]` console logger and its level resolution.
  *
- * Extracted from `Ablo.ts`; exported so other entry points that build a
- * default logger (e.g. the agent runtime) can reuse the same gating instead
- * of hand-rolling a console shim.
+ * These helpers are exported so any entry point that needs a default logger can
+ * reuse the same level gating rather than hand-rolling a console wrapper.
  */
 import type { SyncLogger } from '../interfaces/index.js';
 /**
@@ -30,7 +29,7 @@ export declare function resolveLogLevel(opts?: {
     logLevel?: LogLevel;
 }): LogLevel;
 /**
- * Build the default logger, gated at `level` and prefixed `[Ablo]` so a creator
- * with a console full of other tools' logs can see at a glance what's ours.
+ * Builds the default logger, gated at `level` and prefixed `[Ablo]` so its lines
+ * stand out in a console full of other tools' output.
  */
 export declare function createConsoleLogger(level: LogLevel): SyncLogger;

package/dist/client/consoleLogger.js

@@ -1,9 +1,8 @@
 /**
- * The default `[Ablo]` console logger + its level resolution.
+ * The default `[Ablo]` console logger and its level resolution.
  *
- * Extracted from `Ablo.ts`; exported so other entry points that build a
- * default logger (e.g. the agent runtime) can reuse the same gating instead
- * of hand-rolling a console shim.
+ * These helpers are exported so any entry point that needs a default logger can
+ * reuse the same level gating rather than hand-rolling a console wrapper.
  */
 const LOG_LEVEL_RANK = { debug: 10, info: 20, warn: 30, error: 40, silent: 99 };
 /**
@@ -26,8 +25,8 @@ export function resolveLogLevel(opts) {
     return 'warn';
 }
 /**
- * Build the default logger, gated at `level` and prefixed `[Ablo]` so a creator
- * with a console full of other tools' logs can see at a glance what's ours.
+ * Builds the default logger, gated at `level` and prefixed `[Ablo]` so its lines
+ * stand out in a console full of other tools' output.
  */
 export function createConsoleLogger(level) {
     const threshold = LOG_LEVEL_RANK[level];

package/dist/client/createInternalComponents.d.ts

@@ -1,28 +1,25 @@
 /**
- * Internal component construction for `Ablo()`.
+ * Builds the internal component graph the client runs on.
  *
- * Builds the full sync-engine component graph from options + schema:
- * `ModelRegistry`, `ObjectPool`, `BootstrapHelper`, `Database`,
- * `SyncClient`, `HydrationCoordinator`. Each component depends on
- * the previous one, so the construction order matters; isolating it
- * here means `Ablo.ts` doesn't need to know the dependency order.
- *
- * Mirrors the pattern Anthropic uses: their client constructor wires
- * endpoint modules. Ours wires the sync-engine components instead.
+ * From the caller's options and schema this wires together the model registry,
+ * object pool, bootstrap helper, database, sync client, and hydration
+ * coordinator. Each component depends on the one before it, so construction
+ * order matters; keeping it here means the client constructor does not have to
+ * know that order.
  */
 import { Database } from '../Database.js';
 import { ModelRegistry } from '../ModelRegistry.js';
-import { ObjectPool } from '../ObjectPool.js';
+import { InstanceCache } from '../InstanceCache.js';
 import { SyncClient } from '../SyncClient.js';
-import { HydrationCoordinator } from '../sync/HydrationCoordinator.js';
-import { BootstrapHelper } from '../sync/BootstrapHelper.js';
+import { OnDemandLoader } from '../sync/OnDemandLoader.js';
+import { BootstrapFetcher } from '../sync/BootstrapFetcher.js';
 import type { AuthCredentialSource } from '../auth/credentialSource.js';
 import type { Schema, SchemaRecord } from '../schema/schema.js';
 import { type AbloPersistence } from './persistence.js';
 export interface InternalComponentsInput<S extends SchemaRecord> {
     readonly schema: Schema<S>;
-    /** WebSocket URL — used to derive bootstrap HTTP base when the
-     * caller didn't override `bootstrapBaseUrl`. */
+    /** The WebSocket URL. Used to derive the bootstrap HTTP base URL when the
+     * caller has not overridden `bootstrapBaseUrl`. */
     readonly url: string;
     readonly options: {
         readonly maxPoolSize?: number;
@@ -36,10 +33,10 @@ export interface InternalComponentsInput<S extends SchemaRecord> {
 }
 export interface InternalComponents {
     readonly modelRegistry: ModelRegistry;
-    readonly objectPool: ObjectPool;
-    readonly bootstrapHelper: BootstrapHelper;
+    readonly objectPool: InstanceCache;
+    readonly bootstrapHelper: BootstrapFetcher;
     readonly database: Database;
     readonly syncClient: SyncClient;
-    readonly hydration: HydrationCoordinator;
+    readonly hydration: OnDemandLoader;
 }
 export declare function createInternalComponents<S extends SchemaRecord>(input: InternalComponentsInput<S>): InternalComponents;