@abloatai/ablo 0.25.0 → 0.27.0

package/dist/auth/credentialSource.js

@@ -1,24 +1,16 @@
 /**
- * Single mutable source for the SDK's active bearer credential.
+ * The single mutable holder for the active bearer credential every transport
+ * uses.
  *
- * Every transport should read from this object at request/connect time:
- * bootstrap HTTP, lazy query HTTP, identity/probe HTTP, and WebSocket URL
- * auth. Token refresh writes here once; consumers observe the new value
- * through their getter without being manually patched one by one.
+ * Each transport reads the current token from this object at request or connect
+ * time — the HTTP request paths and the WebSocket URL authorizer alike. When the
+ * token is refreshed, it is written here once, and every reader observes the new
+ * value through its getter rather than being updated one by one.
  */
-/**
- * WebSocket subprotocols used to carry the bearer credential OUT of the URL.
- *
- * Browsers cannot set an `Authorization` header on a WebSocket, so the SDK
- * offers the token as a `Sec-WebSocket-Protocol` value — `ablo.bearer.<token>` —
- * alongside the real `ablo.sync.v1` protocol the server selects. This keeps the
- * credential out of the query string, which ALB access logs, proxies, and
- * browser history capture. The server reads the token from the subprotocol and
- * echoes back ONLY `ablo.sync.v1`, never the token-bearing value. Shared with
- * the sync-server so client and server can never drift on the wire format.
- */
-export const WS_BEARER_SUBPROTOCOL_PREFIX = 'ablo.bearer.';
-export const WS_SYNC_SUBPROTOCOL = 'ablo.sync.v1';
+// The WebSocket bearer-subprotocol constants are defined in `../wire/protocol.js`
+// as part of the wire contract shared between client and server. They are
+// re-exported here so this module stays a stable import site for them.
+export { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL } from '../wire/protocol.js';
 export function createAuthCredentialSource(initialToken) {
     let authToken = normalizeToken(initialToken);
     return {

package/dist/auth/index.d.ts

@@ -1,15 +1,12 @@
 /**
- * Internal apiKey → capability exchange.
+ * Exchanges an API key for a capability token and the scope it grants.
  *
- * Called by the `Ablo({...})` factory's `ready()` flow when the
- * consumer passed `apiKey` without an explicit `capabilityToken` /
- * `organizationId` / `user.id`. SDK calls `/auth/capability` once,
- * server returns the scope + userMeta blobs (Phases 1A + 1B),
- * SDK populates internal state from the response.
- *
- * Consumer never sees this happen. Same shape as Stripe / Anthropic
- * SDKs hide their internal auth-handshake — the apiKey is the only
- * credential the consumer touches.
+ * The `Ablo({...})` factory calls this during startup when you provide an
+ * `apiKey` but no explicit capability token, organization, or user identity. It
+ * sends one `POST /auth/capability` request; the server responds with the
+ * granted scope and any user metadata, which the client uses to populate its
+ * session state. The API key is the only credential you handle directly — this
+ * exchange happens automatically behind it.
  */
 import { type CapabilityExchangeResponse, type EphemeralKeyResponse, type IdentityResolveResponse } from './schemas.js';
 export type { CapabilityExchangeResponse, EphemeralKeyResponse, IdentityResolveResponse, } from './schemas.js';
@@ -28,24 +25,27 @@ export interface ExchangeApiKeyRequest {
 }
 export declare function exchangeApiKey(options: ExchangeApiKeyRequest): Promise<CapabilityExchangeResponse>;
 export interface MintUserSessionRequest {
-    /** The ORIGINAL secret (`sk_`) key — control-plane calls always present it,
-     *  never the exchanged sync credential. */
+    /** Your secret API key (an `sk_` key). Minting a session is a server-side
+     *  operation, so it always presents the secret key, never a token derived
+     *  from it. */
     readonly apiKey: string;
     readonly baseUrl: string;
-    /** The end user's external IdP id — becomes the session's `participantId`. */
+    /** The end user's identifier in your identity provider. It becomes the
+     *  session's `participantId`. */
     readonly userId: string;
-    /** Target org for a cross-org (platform) mint — the Stripe-Connect
-     *  `Stripe-Account` analogue. Requires the `sk_` to carry
-     *  `ephemeral:mint-any-org`; omit to mint into the key's own org. */
+    /** The organization to mint the session into, for a platform that manages many
+     *  organizations. Requires the secret key to carry the `ephemeral:mint-any-org`
+     *  capability. Omit to mint into the key's own organization. */
     readonly organizationId?: string;
-    /** SHARED SCHEMA — point this session's SCHEMA at the project that owns it,
-     *  while its DATA stays scoped to `organizationId`. Use this for org-per-customer
-     *  isolation: keep one schema project, and every customer's session resolves its
-     *  schema from it instead of re-pushing the schema into each customer's org.
-     *  Requires the `sk_` to carry `ephemeral:mint-any-org`. Omit for the default
-     *  (the session resolves its schema from its own org). */
+    /** Points this session's schema at a shared project while its data stays scoped
+     *  to `organizationId`. Use this when each customer has its own organization but
+     *  they all share one schema: keep a single schema project, and every customer's
+     *  session resolves its schema from it instead of pushing the schema into each
+     *  organization separately. Requires the secret key to carry the
+     *  `ephemeral:mint-any-org` capability. Omit to resolve the schema from the
+     *  session's own organization. */
     readonly schemaProject?: {
-        /** The org that owns the schema project. */
+        /** The organization that owns the shared schema project. */
         readonly organizationId: string;
         /** The project the schema was pushed under. */
         readonly projectId: string;
@@ -57,13 +57,13 @@ export interface MintUserSessionRequest {
     readonly timeoutMs?: number;
 }
 /**
- * Mint an END-USER session key (`ek_`) via `POST /auth/ephemeral-keys` — the
- * sk_-gated user-session door. This is deliberately a DIFFERENT endpoint from
- * `/auth/capability`: that route can never mint humans (its
- * `invalid_participant_kind` gate is what fired in the 2026-06-11 Pulse
- * cascade, when `sessions.create({ user })` was funneled through the agent
- * door). The server trusts the `ek_` because a secret key minted it; the
- * browser presents it as its bearer.
+ * Mints an end-user session key (an `ek_` key) by calling
+ * `POST /auth/ephemeral-keys`, using your secret key as authorization. Your
+ * backend calls this to issue a session that a browser can present as its bearer
+ * credential; the server trusts the resulting key because a secret key minted it.
+ *
+ * This is a distinct endpoint from `/auth/capability`, which exchanges keys for
+ * agents and systems and cannot mint sessions for human users.
  */
 export declare function mintUserSessionKey(options: MintUserSessionRequest): Promise<EphemeralKeyResponse>;
 export interface ResolveIdentityRequest {
@@ -73,46 +73,47 @@ export interface ResolveIdentityRequest {
     readonly timeoutMs?: number;
 }
 /**
- * Resolve the caller's Ablo identity from the authenticated request
- * context. Used by browser/session/capability flows where the SDK should
- * not require a public `userId` prop just to open local storage.
+ * Resolves the caller's identity from an authenticated request by calling
+ * `GET /auth/identity`. This lets browser and session flows learn who the
+ * current user is without requiring the application to pass a user id up front —
+ * for example, to key local storage.
  */
 export declare function resolveIdentity(options: ResolveIdentityRequest): Promise<IdentityResolveResponse>;
 /**
- * Capability-token refresh scheduler.
+ * Keeps a capability token fresh so a long-lived client never disconnects when
+ * its token expires.
  *
- * Long-lived `@abloatai/ablo` clients hold a server-issued capability
- * token whose TTL (1h default) is shorter than typical browser sessions.
- * Without proactive refresh, the WebSocket would either be force-closed
- * by the server at expiry (code 1008) or fail its next reconnect with
- * 401. Either way the user sees a mid-session disconnect.
+ * A capability token has a shorter lifetime — one hour by default — than a
+ * typical browser session. Without a refresh, the WebSocket is force-closed at
+ * expiry (close code 1008) or the next reconnect fails with a 401, and either way
+ * the user sees a mid-session disconnect. The scheduler prevents that by
+ * re-minting the token ahead of time.
  *
- * This scheduler keeps the token fresh transparently. Three triggers,
- * one refresh path:
+ * Three triggers share one refresh path:
  *
- *   1. Proactive  — `setTimeout` for `(expiresAtMs - bufferMs - now)`.
- *   2. Visibility — on `document.visibilitychange→visible`, if the
- *                   token is within the buffer window, refresh now.
- *                   Defends against dormant-tab `setTimeout` throttling.
- *   3. Reactive   — caller invokes `.refreshNow()` on observed auth
- *                   failure (WS close 1008/4001 etc).
+ *   1. Proactive  — a timer set for `expiresAtMs - bufferMs - now`.
+ *   2. Visibility — when a hidden tab becomes visible and the token is already
+ *                   within the buffer window, refresh immediately. This covers a
+ *                   background tab whose timers were throttled while it was idle.
+ *   3. Reactive   — the caller invokes {@link RefreshScheduler.refreshNow} after
+ *                   observing an auth failure, such as a WebSocket close 1008 or
+ *                   4001.
  *
- * All three resolve through the same `inFlight` promise so concurrent
- * triggers don't double-mint. On any successful refresh the new
- * `expiresAtMs` is captured and trigger 1 is rescheduled.
+ * All three await the same in-flight promise, so concurrent triggers mint the
+ * token only once. Each successful refresh records the new expiry and reschedules
+ * the proactive timer.
  *
- * Buffer policy: `max(60s, ttl/10)` — for a 1h TTL that's 360s, which
- * matches the AWS SDK / MSAL.js de-facto 5-minute standard while
- * scaling sensibly for shorter TTLs.
+ * The refresh margin is `max(60s, ttl/10)` — six minutes for a one-hour token,
+ * and it scales down for shorter lifetimes.
  */
 export interface RefreshSchedulerOptions {
     /** Initial absolute expiry, ms since epoch (server-supplied). */
     readonly initialExpiresAtMs: number;
     /**
-     * Performs the actual exchange. Returns the new expiry. Errors
-     * propagate to `onError`; the scheduler stays alive and retries on
-     * next trigger (no exponential backoff in v1 — most failures here are
-     * the user's apiKey being revoked, in which case retrying is futile).
+     * Performs the token exchange and returns the new expiry. Errors propagate to
+     * `onError`; the scheduler stays alive and retries on its next trigger. It does
+     * not back off between retries, since the common failure here is a revoked API
+     * key, for which retrying would not help.
      */
     readonly refresh: () => Promise<{
         expiresAtMs: number;
@@ -133,7 +134,7 @@ export interface RefreshSchedulerOptions {
      * If true, install a `visibilitychange` listener on `document` that
      * triggers a refresh when the tab becomes visible and the token is
      * within the buffer window. No-op if `document` is undefined (Node).
-     * Default: true in browser-ish environments.
+     * Default: true in browser environments.
      */
     readonly attachVisibilityListener?: boolean;
     /** Time source. Override in tests; defaults to `Date.now`. */

package/dist/auth/index.js

@@ -1,15 +1,12 @@
 /**
- * Internal apiKey → capability exchange.
+ * Exchanges an API key for a capability token and the scope it grants.
  *
- * Called by the `Ablo({...})` factory's `ready()` flow when the
- * consumer passed `apiKey` without an explicit `capabilityToken` /
- * `organizationId` / `user.id`. SDK calls `/auth/capability` once,
- * server returns the scope + userMeta blobs (Phases 1A + 1B),
- * SDK populates internal state from the response.
- *
- * Consumer never sees this happen. Same shape as Stripe / Anthropic
- * SDKs hide their internal auth-handshake — the apiKey is the only
- * credential the consumer touches.
+ * The `Ablo({...})` factory calls this during startup when you provide an
+ * `apiKey` but no explicit capability token, organization, or user identity. It
+ * sends one `POST /auth/capability` request; the server responds with the
+ * granted scope and any user metadata, which the client uses to populate its
+ * session state. The API key is the only credential you handle directly — this
+ * exchange happens automatically behind it.
  */
 import { parseCapabilityExchangeResponse, parseEphemeralKeyResponse, parseIdentityResolveResponse, } from './schemas.js';
 import { AbloAuthenticationError, hasWireCode, translateHttpError } from '../errors.js';
@@ -26,7 +23,7 @@ export async function exchangeApiKey(options) {
     const url = `${options.baseUrl.replace(/\/+$/, '')}/auth/capability`;
     const timeoutMs = options.timeoutMs ?? 10_000;
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const timer = setTimeout(() => { controller.abort(); }, timeoutMs);
     let response;
     try {
         response = await fetcher(url, {
@@ -62,12 +59,10 @@ export async function exchangeApiKey(options) {
         catch {
             // ignore — server returned non-JSON error
         }
-        // Route through the canonical wire-error translator so the server's
-        // envelope (`code` + `message` + `doc_url`) propagates verbatim and maps to
-        // the right AbloError subclass — instead of the legacy `error`/`reason`
-        // shape this used to read (which the server no longer emits, collapsing
-        // every failure to a generic code with an empty message). Fall back to
-        // `exchange_failed` only when the body carried no recognizable code.
+        // Route the error through the wire-error translator so the server's envelope
+        // (`code`, `message`, `doc_url`) is preserved and mapped to the matching
+        // AbloError subclass. Fall back to `exchange_failed` only when the body
+        // carried no recognizable error code.
         const requestId = response.headers.get('x-request-id') ?? undefined;
         throw hasWireCode(body)
             ? translateHttpError(response.status, body, requestId)
@@ -76,13 +71,13 @@ export async function exchangeApiKey(options) {
     return parseCapabilityExchangeResponse(await response.json());
 }
 /**
- * Mint an END-USER session key (`ek_`) via `POST /auth/ephemeral-keys` — the
- * sk_-gated user-session door. This is deliberately a DIFFERENT endpoint from
- * `/auth/capability`: that route can never mint humans (its
- * `invalid_participant_kind` gate is what fired in the 2026-06-11 Pulse
- * cascade, when `sessions.create({ user })` was funneled through the agent
- * door). The server trusts the `ek_` because a secret key minted it; the
- * browser presents it as its bearer.
+ * Mints an end-user session key (an `ek_` key) by calling
+ * `POST /auth/ephemeral-keys`, using your secret key as authorization. Your
+ * backend calls this to issue a session that a browser can present as its bearer
+ * credential; the server trusts the resulting key because a secret key minted it.
+ *
+ * This is a distinct endpoint from `/auth/capability`, which exchanges keys for
+ * agents and systems and cannot mint sessions for human users.
  */
 export async function mintUserSessionKey(options) {
     if (!options.apiKey) {
@@ -96,7 +91,7 @@ export async function mintUserSessionKey(options) {
     const url = `${options.baseUrl.replace(/\/+$/, '')}/auth/ephemeral-keys`;
     const timeoutMs = options.timeoutMs ?? 10_000;
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const timer = setTimeout(() => { controller.abort(); }, timeoutMs);
     let response;
     try {
         response = await fetcher(url, {
@@ -108,8 +103,8 @@ export async function mintUserSessionKey(options) {
             body: JSON.stringify({
                 user: { id: options.userId },
                 ...(options.organizationId ? { organizationId: options.organizationId } : {}),
-                // Flattened to the existing wire keys — the public param is project-centric,
-                // the transport contract is unchanged (no coordinated server deploy needed).
+                // The public option is project-centric; map it to the flat wire keys the
+                // endpoint expects.
                 ...(options.schemaProject
                     ? {
                         schemaProjectId: options.schemaProject.projectId,
@@ -145,9 +140,10 @@ export async function mintUserSessionKey(options) {
     return parseEphemeralKeyResponse(await response.json());
 }
 /**
- * Resolve the caller's Ablo identity from the authenticated request
- * context. Used by browser/session/capability flows where the SDK should
- * not require a public `userId` prop just to open local storage.
+ * Resolves the caller's identity from an authenticated request by calling
+ * `GET /auth/identity`. This lets browser and session flows learn who the
+ * current user is without requiring the application to pass a user id up front —
+ * for example, to key local storage.
  */
 export async function resolveIdentity(options) {
     if (!options.baseUrl) {
@@ -159,7 +155,7 @@ export async function resolveIdentity(options) {
     const url = `${options.baseUrl.replace(/\/+$/, '')}/auth/identity`;
     const timeoutMs = options.timeoutMs ?? 10_000;
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const timer = setTimeout(() => { controller.abort(); }, timeoutMs);
     let response;
     try {
         const headers = { Accept: 'application/json' };
@@ -186,12 +182,10 @@ export async function resolveIdentity(options) {
         catch {
             // ignore non-JSON auth errors
         }
-        // Canonical envelope translation (see `exchangeApiKey` above). This is what
-        // surfaces the sync-server's precise auth diagnosis — e.g.
-        // `jwt_issuer_untrusted` with its full message — to the SDK consumer,
-        // instead of collapsing every 401 to `identity_resolve_failed` with an
-        // empty reason because the old parser looked for `error`/`reason` keys the
-        // server doesn't emit.
+        // Translate the error envelope the same way `exchangeApiKey` does, so the
+        // server's precise auth diagnosis (for example `jwt_issuer_untrusted` with
+        // its full message) reaches the caller instead of collapsing every 401 to a
+        // generic `identity_resolve_failed`.
         const requestId = response.headers.get('x-request-id') ?? undefined;
         throw hasWireCode(body)
             ? translateHttpError(response.status, body, requestId)
@@ -209,9 +203,9 @@ export function createRefreshScheduler(options) {
     let timer = null;
     let inFlight = null;
     let disposed = false;
-    // Default visibility attach: only when running in a browser-like env.
-    // The Node-side agent worker never has `document`, so the default
-    // does the right thing without explicit opt-out.
+    // Attach the visibility listener only in a browser-like environment. A
+    // non-browser runtime has no `document`, so the default behaves correctly
+    // without an explicit opt-out.
     const wantsVisibility = options.attachVisibilityListener ?? true;
     const hasDocument = typeof document !== 'undefined';
     const visibilityActive = wantsVisibility && hasDocument;

package/dist/auth/schemas.d.ts

@@ -32,10 +32,11 @@ export declare const IdentityResolveResponseSchema: z.ZodObject<{
 }, z.core.$loose>;
 export type IdentityResolveResponse = z.infer<typeof IdentityResolveResponseSchema>;
 /**
- * Response of `POST /auth/ephemeral-keys` — the sk_-gated END-USER session
- * mint (`ek_`). Flat shape (no `scope` block): the server stores the scope on
- * the key row and re-derives it at every verify; the client only needs the
- * token + identity facts to hand to the browser.
+ * The response shape of `POST /auth/ephemeral-keys`, the endpoint that mints an
+ * end-user session key (an `ek_` key). The shape is flat, with no nested scope
+ * block: the server records the scope on the key itself and re-derives it on
+ * every request, so the client only needs the token and identity fields to hand
+ * to the browser.
  */
 export declare const EphemeralKeyResponseSchema: z.ZodObject<{
     object: z.ZodOptional<z.ZodLiteral<"ephemeral_key">>;

package/dist/auth/schemas.js

@@ -30,10 +30,11 @@ export const IdentityResolveResponseSchema = z
 })
     .passthrough();
 /**
- * Response of `POST /auth/ephemeral-keys` — the sk_-gated END-USER session
- * mint (`ek_`). Flat shape (no `scope` block): the server stores the scope on
- * the key row and re-derives it at every verify; the client only needs the
- * token + identity facts to hand to the browser.
+ * The response shape of `POST /auth/ephemeral-keys`, the endpoint that mints an
+ * end-user session key (an `ek_` key). The shape is flat, with no nested scope
+ * block: the server records the scope on the key itself and re-derives it on
+ * every request, so the client only needs the token and identity fields to hand
+ * to the browser.
  */
 export const EphemeralKeyResponseSchema = z
     .object({

package/dist/batching/index.d.ts

@@ -1,24 +1,21 @@
 /**
- * `@abloatai/ablo/batching` — a dependency-free batch-coalescing primitive.
+ * A small, dependency-free primitive that coalesces work into batches.
  *
- * Accumulate items issued close together (the canonical case: a synchronous
- * burst, e.g. `Promise.all([ a(), b(), c() ])` in one event-loop tick) and
- * dispatch them as ONE atomic batch instead of one call each. This is the
- * scheduling essence of Ablo's `TransactionQueue` (and Linear's sync engine) —
- * microtask same-tick staging, size/cost/delay flush triggers, and in-flight
- * backpressure — distilled to a pure state machine with NO dependency on
- * models, MobX, IndexedDB, or the wire. Consumers inject the actual dispatch.
+ * It accumulates items enqueued close together — the common case being a
+ * synchronous burst such as `Promise.all([ a(), b(), c() ])` within one
+ * event-loop tick — and dispatches them as a single batch rather than one call
+ * each. It is a pure state machine: it stages items on the microtask queue,
+ * flushes on size, cost, or time triggers, and applies in-flight backpressure,
+ * with no dependency on any data model, storage layer, or network. You supply
+ * the dispatch function through {@link BatchSchedulerHooks}.
  *
  * Guarantees:
- *   - a batch is ONE `dispatchBatch(items)` call → **atomic** (all-or-nothing).
- *   - on dispatch failure, **every** enqueued promise in that batch rejects
- *     with the same error.
- *   - items dispatch in enqueue order (optionally reordered by `compare` just
- *     before a batch is cut); batches run FIFO under a `maxInFlight` cap.
- *
- * The slides-sdk wraps this to coalesce `commits.create` calls; the stateful
- * `TransactionQueue` MAY adopt it later (it would supply `compare` for FK
- * ordering and keep its merge/confirm/retry logic in its own hooks).
+ *   - each batch is a single `dispatchBatch(items)` call, applied atomically.
+ *   - if a dispatch fails, every enqueued promise in that batch rejects with
+ *     the same error.
+ *   - items dispatch in enqueue order, optionally reordered by `compare` just
+ *     before a batch is cut; batches run first-in, first-out under a
+ *     `maxInFlight` cap.
  */
 export interface BatchSchedulerOptions<T> {
     /** Master switch. When false, every `enqueue` dispatches solo immediately. Default true. */
@@ -38,16 +35,17 @@ export interface BatchSchedulerHooks<T, R> {
     /** The single dispatch for one batch. One call → atomic at this layer. */
     dispatchBatch(items: T[]): Promise<R>;
     /**
-     * Optional ordering applied to the staged items immediately before a batch
-     * is cut (e.g. FK-priority). Omit for FIFO. Does not affect which items share
-     * a batch — only their order within the dispatched array.
+     * Optional ordering applied to the staged items just before a batch is cut —
+     * for example, to send parent rows ahead of the rows that reference them. Omit
+     * for first-in, first-out order. This changes only the order of items within
+     * the dispatched array, not which items share a batch.
      */
     compare?(a: T, b: T): number;
 }
 export interface BatchScheduler<T, R> {
     /** Stage one item; resolves with its batch's dispatch result, or rejects with the batch error. */
     enqueue(item: T): Promise<R>;
-    /** Stage an item that must dispatch in its OWN batch (e.g. it carries an explicit idempotency key). */
+    /** Stage an item that must dispatch in a batch of its own — for example, one carrying an explicit idempotency key. */
     enqueueSolo(item: T): Promise<R>;
     /** Force-flush the pending batch and resolve once everything in flight has settled. */
     flush(): Promise<void>;

package/dist/batching/index.js

@@ -1,24 +1,21 @@
 /**
- * `@abloatai/ablo/batching` — a dependency-free batch-coalescing primitive.
+ * A small, dependency-free primitive that coalesces work into batches.
  *
- * Accumulate items issued close together (the canonical case: a synchronous
- * burst, e.g. `Promise.all([ a(), b(), c() ])` in one event-loop tick) and
- * dispatch them as ONE atomic batch instead of one call each. This is the
- * scheduling essence of Ablo's `TransactionQueue` (and Linear's sync engine) —
- * microtask same-tick staging, size/cost/delay flush triggers, and in-flight
- * backpressure — distilled to a pure state machine with NO dependency on
- * models, MobX, IndexedDB, or the wire. Consumers inject the actual dispatch.
+ * It accumulates items enqueued close together — the common case being a
+ * synchronous burst such as `Promise.all([ a(), b(), c() ])` within one
+ * event-loop tick — and dispatches them as a single batch rather than one call
+ * each. It is a pure state machine: it stages items on the microtask queue,
+ * flushes on size, cost, or time triggers, and applies in-flight backpressure,
+ * with no dependency on any data model, storage layer, or network. You supply
+ * the dispatch function through {@link BatchSchedulerHooks}.
  *
  * Guarantees:
- *   - a batch is ONE `dispatchBatch(items)` call → **atomic** (all-or-nothing).
- *   - on dispatch failure, **every** enqueued promise in that batch rejects
- *     with the same error.
- *   - items dispatch in enqueue order (optionally reordered by `compare` just
- *     before a batch is cut); batches run FIFO under a `maxInFlight` cap.
- *
- * The slides-sdk wraps this to coalesce `commits.create` calls; the stateful
- * `TransactionQueue` MAY adopt it later (it would supply `compare` for FK
- * ordering and keep its merge/confirm/retry logic in its own hooks).
+ *   - each batch is a single `dispatchBatch(items)` call, applied atomically.
+ *   - if a dispatch fails, every enqueued promise in that batch rejects with
+ *     the same error.
+ *   - items dispatch in enqueue order, optionally reordered by `compare` just
+ *     before a batch is cut; batches run first-in, first-out under a
+ *     `maxInFlight` cap.
  */
 export function createBatchScheduler(hooks, options) {
     const enabled = options?.enabled ?? true;