@abloatai/ablo 0.26.0 → 0.28.0

package/dist/client/Ablo.js

@@ -1,8 +1,8 @@
 /**
- * Ablo — The one-liner consumer API.
- *
- * Hides all internal wiring (ObjectPool, Database, SyncClient, WebSocket,
- * bootstrap, offline queue, DI adapters) behind a single function call.
+ * `Ablo` — the one-call entry point to the sync engine client. It hides the
+ * internal wiring — the object pool, local database, sync client, WebSocket,
+ * bootstrap, and offline queue — behind a single function that returns a typed
+ * client with one property per model in your schema.
  *
  * Usage:
  *   import { Ablo } from '@abloatai/ablo';
@@ -18,13 +18,14 @@
  *   });
  *   await sync.reports.delete({ id: reportId });
  */
+import { durableCommitOperationSchema, } from '../transactions/commitEnvelope.js';
 import { AbloAuthenticationError, AbloConnectionError, AbloValidationError, AbloNotFoundError, translateHttpError, toAbloError, claimedError } from '../errors.js';
 import { descriptionFromMeta } from '../coordination/schema.js';
 import { initSyncEngine } from '../context.js';
 import { noopObservability, browserOnlineStatus, defaultSessionErrorDetector, noopAnalytics, } from '../SyncEngineContext.js';
 import { alwaysOnline } from '../adapters/alwaysOnline.js';
 import { validateAbloOptions } from './validateAbloOptions.js';
-import { ObjectPool } from '../ObjectPool.js';
+import { InstanceCache } from '../InstanceCache.js';
 import {} from '../auth/index.js';
 import { mintSession } from './sessionMint.js';
 import { createAuthCredentialSource } from '../auth/credentialSource.js';
@@ -55,17 +56,18 @@ import { assertWriteOptions } from './writeOptionsSchema.js';
 // that read it. Re-exported there for use elsewhere in the file.
 // ── Auth normalization ─────────────────────────────────────────────────────
 /**
- * The one resolver the credential lifecycle needs: an async `() => token | null`,
- * or `null` when auth is static (a plain long-lived `apiKey` STRING with no
- * refresh — the common case).
+ * The single resolver the credential lifecycle needs: an async
+ * `() => token | null`, or `null` when auth is static — a plain long-lived
+ * `apiKey` string with no refresh, which is the common case.
  *
- * The short-lived per-user browser path passes a FUNCTION `apiKey` (an
- * `ApiKeySetter`): the SDK then drives the full credential lifecycle off it —
- * mint-before-connect, the proactive refresh timer + wake/online/focus re-mint,
- * and the reactive `credential_stale` re-mint. The resolver's contract is the
- * `ApiKeySetter` contract end-to-end: resolve a token, resolve `null` when the
- * login is gone (terminal → `session_expired` → sign out), or THROW on a
- * transient failure (→ back off, never sign out).
+ * The short-lived per-user browser path passes a function `apiKey` (an
+ * {@link ApiKeySetter}), and the SDK then drives the whole credential lifecycle
+ * from it: mint-before-connect, the proactive refresh timer with its
+ * wake/online/focus re-mint, and the reactive `credential_stale` re-mint. The
+ * resolver follows the `ApiKeySetter` contract end to end: resolve a token,
+ * resolve `null` when the login is gone (terminal — surfaces `session_expired`
+ * and signs the user out), or throw on a transient failure (backs off, without
+ * signing out).
  */
 function resolveCredentialResolver(apiKey) {
     if (typeof apiKey === 'function')
@@ -86,10 +88,10 @@ export function Ablo(options) {
     const authInput = { options, env };
     const configuredApiKey = resolveApiKey(authInput);
     const configuredAuthToken = resolveAuthToken(authInput);
-    // The client OWNS its credential lifecycle (not the React layer): this resolver
-    // drives both the reactive re-mint (FSM `credential_stale`) and the proactive
-    // refresh timer + wake/online/focus triggers. Null for the common static
-    // `apiKey` path — no refresh needed.
+    // The client owns its credential lifecycle (not the React layer): this resolver
+    // drives both the reactive re-mint (the connection's `credential_stale` state)
+    // and the proactive refresh timer with its wake/online/focus triggers. Null for
+    // the common static `apiKey` path, which needs no refresh.
     const credentialResolver = resolveCredentialResolver(configuredApiKey);
     const authCredentials = createAuthCredentialSource(
     // eslint-disable-next-line @typescript-eslint/no-deprecated -- load-bearing on the self-hosted path; server-internal cap-mint (Phase 3) not shipped
@@ -118,24 +120,19 @@ export function Ablo(options) {
         ...deriveConfigFromSchema(schema),
         ...internalOptions.configOverrides,
     };
-    // 2. Create the mutation executor + dispatcher.
+    // 2. Create the mutation executor and dispatcher.
     //
-    //    The default executor sends `{ type: 'commit', ... }` over the
-    //    engine's WebSocket. The WS doesn't exist yet at this point (it's
-    //    created later when `BaseSyncedStore` initializes), so the default
-    //    takes a lazy getter that resolves the live WS at commit time.
-    //    `storeForTransport` is captured by the closure and assigned below
-    //    once the store is built — JS closures close over bindings, not
-    //    values, so by the time the first commit fires the store is live.
+    //    The default executor sends `{ type: 'commit', ... }` over the engine's
+    //    WebSocket. The socket doesn't exist yet at this point (it's created later
+    //    when the store initializes), so the default takes a lazy getter that
+    //    resolves the live socket at commit time. `storeHolder` is captured by the
+    //    closure and assigned below once the store is built — JS closures close
+    //    over bindings, not values, so by the time the first commit fires the store
+    //    is live.
     //
-    //    Caller-supplied executors are still honored for advanced cases
-    //    (test mocks, alternative transports) but the public `<AbloProvider>`
-    //    surface will mark this option `@internal` — apps should almost
-    //    never need to override transport. See Zero's `ClientOptions`
-    //    (packages/zero-client/src/client/options.ts) and Liveblocks'
-    //    `ClientOptions` (packages/liveblocks-core/src/client.ts) for the
-    //    reference shape: URLs + auth + declarative mutators, never a
-    //    pluggable commit transport.
+    //    Caller-supplied executors are still honored for advanced cases (test
+    //    mocks, alternative transports), but apps should almost never need to
+    //    override the transport.
     // Captured-by-reference binding — assigned below after BaseSyncedStore
     // is constructed. The default executor's `getWs` closure reads it
     // lazily at commit time.
@@ -195,18 +192,16 @@ export function Ablo(options) {
     });
     // Hand the credential lifecycle to the client (refresher + proactive refresh
     // timer + wake/online/focus re-mint). Installed once here so refresh works for
-    // ANY consumer of `Ablo({ auth })` — not only those who render `<AbloProvider>`.
+    // any consumer of `Ablo({ auth })`, not only those who render `<AbloProvider>`.
     // The first mint happens in `ready()` so the first connection carries a token.
     //
-    // Long-lived server clients also get the pre-roll TIMER on windowless hosts
-    // (`proactiveInNode`): their socket must renew its `rk_`/`ek_` BEFORE the
-    // hub's keepalive reaper closes it (4001 `credential_expired`). Two signals
-    // qualify — agent/system participants (the axis `createConnectionManager`
-    // gates on; `kind` is deprecated but still what agent runtimes pass today),
-    // and an ABSOLUTE endpoint-string `apiKey` (a relative one can't fetch in
-    // Node at all, so an absolute URL is unambiguously a deliberate server
-    // client, kind or no kind). User-kind clients in Node (an SSR/RSC module
-    // eval of scaffolded browser code) stay reactive-only.
+    // Long-lived server clients also get the pre-roll timer on windowless hosts
+    // (`proactiveInNode`): their socket must renew its `rk_` or `ek_` before the
+    // server's keepalive reaper closes it (4001 `credential_expired`). Two signals
+    // qualify — an agent or system participant, and an absolute endpoint-string
+    // `apiKey` (a relative one can't be fetched in Node, so an absolute URL is
+    // unambiguously a deliberate server client). User-kind clients in Node (an
+    // SSR/RSC module evaluating scaffolded browser code) stay reactive-only.
     if (credentialResolver) {
         const rawEndpoint = internalOptions.authEndpoint ?? internalOptions.apiKey;
         const absoluteEndpoint = typeof rawEndpoint === 'string' && /^https?:\/\//i.test(rawEndpoint);
@@ -218,27 +213,25 @@ export function Ablo(options) {
             /* eslint-enable @typescript-eslint/no-deprecated */
         });
     }
-    // Put the lazy-query lane on the SAME auth-recovery backbone as the WS probe
+    // Put the lazy-query lane on the same auth-recovery path as the WebSocket probe
     // and the proactive pre-roll: a 401 on `/sync/query` re-mints via the store's
-    // single-flight lifecycle and replays once, instead of silently returning
-    // empty rows against an expired `ek_` until the next proactive tick (the
-    // "Could not load documents — apikey_expired" wedge). Late-bound because the
-    // coordinator is constructed before the store exists.
+    // single-flight lifecycle and replays once, instead of silently returning empty
+    // rows against an expired `ek_` until the next proactive tick. Late-bound
+    // because the coordinator is constructed before the store exists.
     hydration.setCredentialRecovery((recovery) => store.recoverFromAuthRejection(recovery));
     // Wire the store back into the default executor's lazy getter (see
     // `storeHolder` above). The executor was constructed before the store
     // existed; this late binding closes the loop so commits dispatch over
     // the engine's WebSocket once it opens.
     storeHolder.store = store;
-    // Bind THIS executor to THIS Ablo's TransactionQueue. Without this,
-    // the queue resolves `mutationExecutor` from the module-level
-    // `getContext()`, which `initSyncEngine()` overwrites on every Ablo
-    // construction. In multi-Ablo flows (e.g. agent-worker's worker +
-    // per-job peer) the second `initSyncEngine()` call would silently
-    // redirect the first Ablo's queue through the second Ablo's executor
-    // closure — and when the second Ablo disposes, its `storeHolder.store`
-    // becomes null, so the first Ablo's commits start throwing
-    // `ws_not_ready` forever (terminal AgentJob writes hang on retry).
+    // Bind this executor to this client's TransactionQueue. Without it, the queue
+    // resolves `mutationExecutor` from the module-level `getContext()`, which
+    // `initSyncEngine()` overwrites on every client construction. In multi-client
+    // flows (for example a worker plus a per-job peer) the second `initSyncEngine()`
+    // call would silently redirect the first client's queue through the second
+    // client's executor closure — and when the second client disposes, its
+    // `storeHolder.store` becomes null, so the first client's commits start throwing
+    // `ws_not_ready` forever.
     syncClient.getTransactionQueue().setMutationExecutor(executor);
     // Presence + claim streams — built eagerly so `engine.presence`
     // and `engine.claims` return the same reference for the engine's
@@ -317,13 +310,13 @@ export function Ablo(options) {
         }
         _readyPromise = (async () => {
             try {
-                // Mint the FIRST access credential before we connect, so the initial
-                // WebSocket upgrade + bootstrap carry a valid bearer (no tokenless first
-                // connect that has to self-heal). Only when a refreshing resolver is
-                // wired AND no static credential is already present. Contract mirrors
-                // the `apiKey` resolver: `null` ⇒ the login is gone (terminal — fail ready so the
-                // app shows sign-in); a THROW ⇒ transient (rethrown; autoStart swallows
-                // and the lifecycle's online/wake triggers retry).
+                // Mint the first access credential before we connect, so the initial
+                // WebSocket upgrade and bootstrap carry a valid bearer (no tokenless first
+                // connect that has to self-heal). Only when a refreshing resolver is wired
+                // and no static credential is already present. Follows the `apiKey`
+                // resolver contract: `null` means the login is gone (terminal — fail ready
+                // so the app shows sign-in); a throw means transient (rethrown; autoStart
+                // swallows it and the lifecycle's online/wake triggers retry).
                 if (credentialResolver && !authCredentials.getAuthToken()) {
                     const token = await credentialResolver();
                     if (!token) {
@@ -331,7 +324,7 @@ export function Ablo(options) {
                     }
                     authCredentials.setAuthToken(token);
                 }
-                // Register the caller's own database for write-back BEFORE bootstrap, so
+                // Register the caller's own database for write-back before bootstrap, so
                 // the server resolves this org's data plane to the customer's DB rather
                 // than serving an empty/wrong store. The org is derived server-side from
                 // the API key. Idempotent server-side (register-or-update). Skipped when
@@ -353,15 +346,15 @@ export function Ablo(options) {
                     url,
                     kind,
                     configuredApiKey,
-                    // Resolve identity against the LIVE token, not the construction-time
-                    // `configuredAuthToken`. Consumers using a function `apiKey` (apps/web)
-                    // never pass `authToken` at construction — the lifecycle mints the
-                    // first `ek_`/`rk_` and calls `setAuthToken()` before
-                    // `ready()`, which updates the shared credential source. Reading the frozen
-                    // `configuredAuthToken` here made `/auth/identity` fire with no Bearer
-                    // (→ `no_matching_provider` / `session_expired`) even though the JWT
-                    // was present. Mirrors every other transport by reading the shared
-                    // credential source.
+                    // Resolve identity against the live token, not the construction-time
+                    // `configuredAuthToken`. Consumers using a function `apiKey` never pass
+                    // `authToken` at construction — the lifecycle mints the first `ek_` or
+                    // `rk_` and calls `setAuthToken()` before `ready()`, which updates the
+                    // shared credential source. Reading the frozen `configuredAuthToken`
+                    // here made `/auth/identity` fire with no bearer (returning
+                    // `no_matching_provider` / `session_expired`) even though the token was
+                    // present. This reads the shared credential source, like every other
+                    // transport.
                     configuredAuthToken: authCredentials.getAuthToken() ?? configuredAuthToken,
                     bootstrapHelper,
                     auth: authCredentials,
@@ -369,11 +362,11 @@ export function Ablo(options) {
                 });
                 const { userId, accountScope, teamIds, capabilityToken, syncGroups, participantKind, } = resolved;
                 // Fail-loud guard: detect the degenerate "no real sync groups
-                // resolved" state before opening the WS. Same class of bug as
-                // the schema-drift `[commit] dropped stale field` warning —
+                // resolved" state before opening the socket. It is the same class of bug as
+                // a
                 // sensible-looking default that's functionally broken: the
                 // SDK ends up subscribing only to the server-side
-                // `['default']` fallback (bootstrap.ts:45, Hub.ts:480), no
+                // `['default']` fallback, no
                 // delta has that tag, live fan-out silently never delivers.
                 // For human users (kind:'user') this is almost certainly a
                 // misconfiguration upstream — either the caller didn't pass
@@ -385,9 +378,9 @@ export function Ablo(options) {
                 if (participantKind === 'user' &&
                     (resolvedSyncGroups.length === 0 ||
                         (resolvedSyncGroups.length === 1 && resolvedSyncGroups[0] === 'default'))) {
-                    // Actionable and NOT self-healing (no live updates until fixed):
-                    // kept at warn, consumer register — engine jargon and the internal
-                    // file pointer stripped; forensic fields ride the debug companion.
+                    // Actionable and not self-healing (no live updates until fixed):
+                    // kept at warn level for consumers; the low-level diagnostic
+                    // fields ride the debug log below.
                     logger.warn('This client was started without sync groups, so it will not receive ' +
                         'live updates. Pass `syncGroups` (for example ' +
                         '`["org:<id>", "user:<id>"]`) or check that your auth provider supplies them.');
@@ -459,15 +452,15 @@ export function Ablo(options) {
                     httpStatus: error.httpStatus,
                     error: error.message,
                 });
-                // Clear the memo so a FUTURE `ready()` re-attempts bootstrap instead of
-                // replaying this rejection forever. Bootstrap failures here are
-                // transient by nature — offline, an IndexedDB open timeout, a bootstrap
-                // fetch hiccup — and used to brick the engine until a full page reload
-                // because line ~2013 (`if (_readyPromise) return _readyPromise`) handed
-                // every later caller this same dead promise. Nulling it lets the
-                // provider's online/wake/retry triggers drive a clean re-bootstrap.
-                // (The terminal `_validationError` branch above intentionally stays
-                // cached — config can't change without recreating the engine.)
+                // Clear the memo so a future `ready()` re-attempts bootstrap instead of
+                // replaying this rejection forever. Bootstrap failures here are transient
+                // by nature — offline, an IndexedDB open timeout, a bootstrap fetch
+                // hiccup — and the early `if (_readyPromise) return _readyPromise` guard
+                // would otherwise hand every later caller this same dead promise, bricking
+                // the engine until a full page reload. Nulling it lets the provider's
+                // online/wake/retry triggers drive a clean re-bootstrap. (The terminal
+                // `_validationError` branch above intentionally stays cached — config
+                // can't change without recreating the engine.)
                 _readyPromise = null;
                 throw error;
             }
@@ -531,7 +524,7 @@ export function Ablo(options) {
         }
         const type = op.action.toUpperCase();
         const id = op.id ?? op.target?.id ?? '';
-        return {
+        return durableCommitOperationSchema.parse({
             type,
             model: model.toLowerCase(),
             id,
@@ -539,7 +532,7 @@ export function Ablo(options) {
             transactionId: op.transactionId ?? undefined,
             readAt: op.readAt ?? defaults.readAt ?? undefined,
             onStale: op.onStale ?? defaults.onStale ?? undefined,
-        };
+        });
     }
     function normalizeCommitOperations(commitOptions) {
         if (commitOptions.operation && commitOptions.operations) {
@@ -574,27 +567,6 @@ export function Ablo(options) {
             },
         };
     }
-    function modelClaimFromQueued(claim) {
-        return {
-            id: claim.id,
-            actor: claim.heldBy ?? "",
-            participantKind: claim.participantKind ?? "user",
-            reason: claim.reason,
-            ...(claim.description ? { description: claim.description } : {}),
-            field: claim.target.field,
-            status: 'queued',
-            position: claim.position,
-            expiresAt: claim.expiresAt ?? 0,
-            target: {
-                model: claim.target.type,
-                id: claim.target.id,
-                path: claim.target.path,
-                range: claim.target.range,
-                field: claim.target.field,
-                meta: claim.target.meta,
-            },
-        };
-    }
     function targetMatchesModel(target, claim) {
         if (target.model &&
             claim.target.type.toLowerCase() !== target.model.toLowerCase()) {
@@ -611,14 +583,6 @@ export function Ablo(options) {
             .filter((claim) => (target ? targetMatchesModel(target, claim) : true))
             .map(modelClaimFromActive);
     }
-    function listModelClaimQueue(target) {
-        if (!target?.model || !target.id)
-            return [];
-        return publicClaims
-            .queueFor({ type: target.model, id: target.id })
-            .filter((claim) => (target.field ? claim.target.field === target.field : true))
-            .map(modelClaimFromQueued);
-    }
     function waitForModelUnclaimed(target, options) {
         if (listModelClaims(target).length === 0)
             return Promise.resolve();
@@ -690,6 +654,10 @@ export function Ablo(options) {
             waited,
             release,
             revoke: claim.revoke,
+            // The lease-control members are forwarded explicitly — this wrapper
+            // rebuilds the handle field by field, so anything not named here is
+            // silently dropped from the public claim.
+            heartbeat: claim.heartbeat,
             [Symbol.asyncDispose]: release,
         };
     }
@@ -752,7 +720,7 @@ export function Ablo(options) {
             createSnapshot: (modelKey, id) => createSnapshot({
                 pool: objectPool,
                 transport: store.getSyncWebSocket(),
-                // `position.readFloor` is THE value claims/snapshots stamp as
+                // `position.readFloor` is the value claims and snapshots stamp as
                 // `readAt` (max of the pool-applied cursor and the acked
                 // watermark for our own writes — see sync/syncPosition.ts).
                 // Stamping a bare stream cursor made a claim taken right after
@@ -798,19 +766,18 @@ export function Ablo(options) {
             selfParticipantKind: kind,
             // Read-interest / write-intent enrolment for the typed surface.
             // `enterScope`/`pinScope` resolve the `{ [schemaKey]: id }` scope
-            // through the SAME resolver the claim path uses, landing this client in
+            // through the same resolver the claim path uses, landing this client in
             // the entity-scoped group the holder's claim presence fans out on.
-            // Return the store promise so the claim write path can AWAIT pinScope
-            // BEFORE acquiring the lease (closing the subscribe-vs-broadcast race);
+            // Returns the store promise so the claim write path can await pinScope
+            // before acquiring the lease (closing the subscribe-vs-broadcast race);
             // read-interest callers (`retrieve`/`claim.state`) still `void` it and
-            // stay fire-and-forget. SOFT either way — the store swallows reconcile
-            // errors so read interest never makes a read reject or stall.
+            // stay fire-and-forget. It's soft either way — the store swallows
+            // reconcile errors so read interest never makes a read reject or stall.
             enterScope: (scope) => store.enterScope(scope),
             pinScope: (scope) => store.pinScope(scope),
-            // `ablo.<model>.watch(ids, { ttl })` → a scoped participant join on
-            // this model's sync group(s). The model-scoped relocation of the old
-            // `ablo.participants.join({ scope: { <model>: ids } })`. WebSocket
-            // only — `join` throws AbloConnectionError if the socket isn't ready.
+            // `ablo.<model>.watch(ids, { ttl })` performs a scoped participant join
+            // on this model's sync group(s). WebSocket only — `join` throws
+            // `AbloConnectionError` if the socket isn't ready.
             createWatch: (modelKey, ids, options) => participantManager.join({
                 scope: { [modelKey]: ids },
                 ...(options?.ttl !== undefined ? { ttlSeconds: options.ttl } : {}),
@@ -851,7 +818,7 @@ export function Ablo(options) {
             // SyncClient we already hold from createInternalComponents —
             // no need to leak an accessor through BaseSyncedStore.
             const queue = syncClient.getTransactionQueue();
-            queue.enqueueCommit(clientTxId, operations, {
+            await queue.enqueueCommit(clientTxId, operations, {
                 ...(commitOptions.reads ? { reads: [...commitOptions.reads] } : {}),
             });
             if (wait === 'queued') {
@@ -960,7 +927,7 @@ export function Ablo(options) {
                 const id = params.id ?? createModelId();
                 await applyClaimedPolicy({ model: name, id }, params);
                 // Confirm, then return the authoritative row (with framework defaults;
-                // the EXISTING row on an idempotent re-create) — mirrors the WS client.
+                // the existing row on an idempotent re-create) — mirrors the WebSocket client.
                 await commits.create({
                     claimRef: params.claimRef,
                     idempotencyKey: params.idempotencyKey,
@@ -1005,13 +972,13 @@ export function Ablo(options) {
         };
     }
     /**
-     * The CONTROL-PLANE credential: always the original configured secret key.
+     * The control-plane credential: always the original configured secret key.
      * Never reads `authCredentials` — that holds the exchanged sync credential
      * (a wide-scope `rk_` on the hosted path), which control-plane routes
      * rightly refuse (e.g. the user-session mint is sk_-gated). Counterpart to
      * `getAuthToken()`, which resolves the sync-plane token.
      *
-     * The sk_-only rule is enforced server-side; the credential KIND taxonomy
+     * The secret-key-only rule is enforced on the server; the credential-kind taxonomy
      * (secret/restricted/ephemeral/publishable) lives in `auth/credentialPolicy`.
      */
     async function controlPlaneApiKey() {
@@ -1019,7 +986,7 @@ export function Ablo(options) {
     }
     /**
      * Resolve the control-plane context a session/agent mint needs (sk_ +
-     * bootstrap base URL + the schema-key→typename map the Hub gates on).
+     * bootstrap base URL + the schema-key→typename map the server gates on).
      * Shared by `sessions.create` and `agents.create` so the two mint doors
      * can never drift on how a token is minted. Throws if no `sk_` is present —
      * minting is a backend-only operation.
@@ -1036,7 +1003,7 @@ export function Ablo(options) {
                 bootstrapBaseUrl: internalOptions.bootstrapBaseUrl,
             }),
             ...(internalOptions.fetch ? { fetch: internalOptions.fetch } : {}),
-            // Map every `can` schema-key to the wire typename the Hub gates on, so a
+            // Map every `can` schema-key to the wire typename the server gates on, so a
             // typename override (`documents` → `Document`) doesn't mint a capability
             // the server then denies. See `MintSessionContext`.
             modelTypenames: Object.fromEntries(Object.entries(schema.models).map(([key, def]) => [
@@ -1064,9 +1031,9 @@ export function Ablo(options) {
             // The live short-lived bearer (set via `setAuthToken` / `apiKey`-resolver refresh)
             // is the canonical credential; fall back to a configured API key.
             //
-            // This is the SYNC-PLANE token (bootstrap, WS, query HTTP). Control-plane
+            // This is the sync-plane token (bootstrap, WebSocket, query HTTP). Control-plane
             // calls (sessions.create, datasource registration) never use it — they
-            // present the ORIGINAL secret key via `controlPlaneApiKey()` below. The
+            // present the original secret key via `controlPlaneApiKey()` below. The
             // split matters: after the startup exchange this resolver returns the
             // derived wide-scope `rk_`, a credential the control-plane routes
             // correctly refuse (an agent token must never mint humans).
@@ -1078,9 +1045,8 @@ export function Ablo(options) {
         setCredentialRefresher(refresher) {
             store.setCredentialRefresher(refresher);
         },
-        // The org this client resolved to — null until `ready()` completes.
-        // Integrators previously had no programmatic way to learn it (the Pulse
-        // agent regex-scraped `ablo status` output); now it's a property.
+        // The org this client resolved to — null until `ready()` completes. Exposed
+        // as a property so integrators can read it programmatically.
         get organizationId() {
             return _resolvedOrganizationId;
         },
@@ -1088,33 +1054,33 @@ export function Ablo(options) {
             store.nudgeReconnect();
         },
         sessions: {
-            // Stripe `ephemeralKeys.create` shape: a BACKEND (holding `sk_`) mints a
-            // short-lived scoped token for one end user OR one agent.
+            // A backend (holding `sk_`) mints a short-lived scoped token for one end
+            // user or one agent.
             //
-            // CONTROL-PLANE CREDENTIAL RULE: both arms authenticate with the
-            // ORIGINAL secret key (`controlPlaneApiKey()`), never the wide-scope
-            // `rk_` the startup exchange installed as the sync credential. A derived
-            // agent credential silently replacing the secret key on control-plane
-            // calls is how humans get minted as agents — attribution is the product.
+            // Both arms authenticate with the original secret key
+            // (`controlPlaneApiKey()`), never the wide-scope `rk_` the startup exchange
+            // installed as the sync credential. A derived agent credential silently
+            // replacing the secret key on control-plane calls is how humans would get
+            // minted as agents — and correct attribution is the point.
             async create(params) {
-                // Both mint doors (`{ user }` → /auth/ephemeral-keys → `ek_`,
+                // Both mint paths (`{ user }` → /auth/ephemeral-keys → `ek_`,
                 // `{ agent, can }` → /auth/capability → scoped `rk_`) resolve their
                 // control-plane context through the shared `buildMintContext`, so this
-                // client, `agents.create`, and the stateless HTTP client can never drift
-                // on how a token is minted.
+                // client, `agents.create`, and the stateless HTTP client can't drift on
+                // how a token is minted.
                 return mintSession(params, await buildMintContext('sessions.create'));
             },
         },
-        // Mint a scoped agent IDENTITY and hand back a connected client bound to it
-        // — `sessions.create({ agent })` + `Ablo({ apiKey })` fused into one call,
-        // for agents that run in THIS (sk_-holding) process. Omitting `id` yields a
-        // fresh uuid per call, so concurrent agents are distinct participants that
-        // queue behind each other (even when they share a `name`). Humans don't get
-        // a server-built client — ship them a token via `sessions.create({ user })`.
+        // Mint a scoped agent identity and hand back a connected client bound to it —
+        // `sessions.create({ agent })` plus `Ablo({ apiKey })` fused into one call,
+        // for agents that run in this (secret-key-holding) process. Omitting `id`
+        // yields a fresh uuid per call, so concurrent agents are distinct participants
+        // that queue behind each other (even when they share a `name`). Humans don't
+        // get a server-built client — ship them a token via `sessions.create({ user })`.
         agents: {
             async create(params) {
                 // Distinct participant by default: omit `id` → a fresh uuid, so even two
-                // agents that share a `name` are INDEPENDENT participants and queue
+                // agents that share a `name` are independent participants and queue
                 // behind one another. `name` is display only (→ userMeta.name); it never
                 // derives the id. Pass an explicit `id` only to re-attach an agent to
                 // its own held claims.
@@ -1128,7 +1094,7 @@ export function Ablo(options) {
                     ...(userMeta ? { userMeta } : {}),
                 };
                 // Re-mint the `rk_` on every resolver call so a long-lived agent client
-                // never hits token expiry; the `sk_` stays in THIS process — the child
+                // never hits token expiry; the `sk_` stays in this process — the child
                 // only ever sees its own short-lived `rk_`.
                 const mintToken = async () => (await mintSession(sessionParams, await buildMintContext('agents.create')))
                     .token;
@@ -1175,7 +1141,7 @@ export function Ablo(options) {
          * the session (WebSocket close code 1008/4001/4003 or a session_error
          * frame). Multiple subscribers supported; returns an unsubscribe
          * function. Consumers typically use this to trigger auth-failed UI
-         * flows (e.g., redirect to sign-in). Does NOT automatically purge the
+         * flows (e.g., redirect to sign-in). Does not automatically purge the
          * IndexedDB — call `engine.purge()` from the listener if you need
          * that behavior (the SDK's `<AbloProvider>` does this by default).
          */
@@ -1202,7 +1168,7 @@ export function Ablo(options) {
         // the pool). Prefixed with _ to signal "internal but stable."
         /** The BaseSyncedStore — implements SyncStoreContract for SyncContext.Provider. */
         get _store() { return store; },
-        /** The ObjectPool — for demand loaders that need pool.createFromData(). */
+        /** The InstanceCache — for demand loaders that need pool.createFromData(). */
         get _pool() { return objectPool; },
         /** The SyncWebSocket — for collaboration events (slide selection, cursors). */
         get _ws() { return store.getSyncWebSocket() ?? null; },