npm - @abloatai/ablo - Versions diffs - 0.6.0 → 0.8.0 - Mend

@abloatai/ablo 0.6.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (121) hide show

package/CHANGELOG.md +77 -0
package/README.md +95 -57
package/dist/BaseSyncedStore.d.ts +1 -1
package/dist/BaseSyncedStore.js +8 -4
package/dist/SyncEngineContext.d.ts +2 -1
package/dist/SyncEngineContext.js +5 -3
package/dist/agent/session.js +3 -2
package/dist/auth/index.js +39 -11
package/dist/client/Ablo.d.ts +112 -3
package/dist/client/Ablo.js +144 -10
package/dist/client/ApiClient.d.ts +32 -0
package/dist/client/ApiClient.js +76 -44
package/dist/client/auth.d.ts +11 -1
package/dist/client/auth.js +21 -2
package/dist/client/createModelProxy.d.ts +120 -53
package/dist/client/createModelProxy.js +66 -31
package/dist/client/identity.js +14 -0
package/dist/client/registerDataSource.d.ts +19 -0
package/dist/client/registerDataSource.js +57 -0
package/dist/client/validateAbloOptions.d.ts +2 -1
package/dist/client/validateAbloOptions.js +8 -7
package/dist/coordination/index.d.ts +6 -0
package/dist/coordination/index.js +6 -0
package/dist/coordination/schema.d.ts +329 -0
package/dist/coordination/schema.js +209 -0
package/dist/core/QueryView.d.ts +4 -1
package/dist/core/QueryView.js +1 -1
package/dist/core/query-utils.d.ts +7 -10
package/dist/core/query-utils.js +2 -3
package/dist/errorCodes.d.ts +286 -0
package/dist/errorCodes.js +284 -0
package/dist/errors.d.ts +103 -7
package/dist/errors.js +192 -41
package/dist/index.d.ts +11 -6
package/dist/index.js +10 -6
package/dist/keys/index.d.ts +61 -0
package/dist/keys/index.js +151 -0
package/dist/policy/index.d.ts +1 -1
package/dist/policy/index.js +1 -1
package/dist/policy/types.d.ts +31 -0
package/dist/policy/types.js +15 -0
package/dist/query/client.js +19 -8
package/dist/react/AbloProvider.d.ts +37 -0
package/dist/react/AbloProvider.js +107 -4
package/dist/react/ClientSideSuspense.d.ts +1 -1
package/dist/react/DefaultFallback.d.ts +1 -1
package/dist/react/SyncGroupProvider.d.ts +1 -1
package/dist/react/index.d.ts +3 -2
package/dist/react/index.js +3 -2
package/dist/react/useAblo.d.ts +4 -4
package/dist/react/useAblo.js +10 -5
package/dist/react/useReactive.js +16 -3
package/dist/schema/ddl.d.ts +62 -0
package/dist/schema/ddl.js +317 -0
package/dist/schema/diff.d.ts +6 -0
package/dist/schema/diff.js +21 -3
package/dist/schema/field.d.ts +16 -19
package/dist/schema/field.js +30 -17
package/dist/schema/index.d.ts +7 -4
package/dist/schema/index.js +9 -3
package/dist/schema/model.d.ts +87 -25
package/dist/schema/model.js +33 -3
package/dist/schema/relation.d.ts +17 -0
package/dist/schema/roles.d.ts +148 -0
package/dist/schema/roles.js +149 -0
package/dist/schema/schema.d.ts +2 -112
package/dist/schema/schema.js +50 -62
package/dist/schema/select.d.ts +25 -0
package/dist/schema/select.js +55 -0
package/dist/schema/serialize.d.ts +16 -12
package/dist/schema/serialize.js +16 -12
package/dist/schema/sugar.d.ts +20 -3
package/dist/schema/sugar.js +5 -1
package/dist/schema/tenancy.d.ts +66 -0
package/dist/schema/tenancy.js +58 -0
package/dist/sync/BootstrapHelper.js +46 -27
package/dist/sync/ConnectionManager.d.ts +3 -1
package/dist/sync/ConnectionManager.js +37 -1
package/dist/sync/HydrationCoordinator.d.ts +2 -0
package/dist/sync/HydrationCoordinator.js +26 -19
package/dist/sync/NetworkProbe.d.ts +8 -0
package/dist/sync/NetworkProbe.js +24 -2
package/dist/sync/SyncWebSocket.d.ts +1 -1
package/dist/sync/SyncWebSocket.js +43 -53
package/dist/sync/createIntentStream.d.ts +2 -1
package/dist/sync/createIntentStream.js +46 -1
package/dist/sync/participants.js +10 -16
package/dist/transactions/TransactionQueue.js +13 -1
package/dist/types/streams.d.ts +53 -33
package/docs/api-keys.md +47 -3
package/docs/api.md +103 -57
package/docs/audit.md +16 -9
package/docs/cli.md +222 -0
package/docs/client-behavior.md +35 -21
package/docs/coordination.md +74 -36
package/docs/data-sources.md +23 -21
package/docs/examples/agent-human.md +72 -28
package/docs/examples/ai-sdk-tool.md +14 -11
package/docs/examples/existing-python-backend.md +30 -19
package/docs/examples/nextjs.md +21 -8
package/docs/examples/scoped-agent.md +93 -0
package/docs/examples/server-agent.md +27 -5
package/docs/guarantees.md +29 -17
package/docs/identity.md +198 -121
package/docs/index.md +35 -18
package/docs/integration-guide.md +79 -83
package/docs/interaction-model.md +40 -25
package/docs/mcp/claude-code.md +9 -17
package/docs/mcp/cursor.md +6 -24
package/docs/mcp/windsurf.md +6 -19
package/docs/mcp.md +103 -26
package/docs/quickstart.md +31 -39
package/docs/react.md +18 -14
package/docs/roadmap.md +15 -3
package/docs/schema-contract.md +109 -0
package/examples/README.md +8 -4
package/examples/data-source/README.md +6 -2
package/examples/data-source/run.ts +4 -3
package/examples/quickstart.ts +1 -1
package/llms.txt +27 -16
package/package.json +13 -1

package/dist/keys/index.js ADDED Viewed

@@ -0,0 +1,151 @@
+/**
+ * Canonical Ablo API-key format — the single source of truth for how keys
+ * are minted, hashed, and validated. Both the sync-server (`apiKeyStore`)
+ * and the web control-plane (`generate-key.ts`) consume THIS module, so the
+ * format can no longer drift between the two mint sites (it used to live as
+ * a hand-copied twin kept in sync by a comment).
+ *
+ * Node-only — uses `node:crypto`. Exposed via the `@abloatai/ablo/keys`
+ * subpath and NEVER re-exported from the browser-facing `.` entry, so the
+ * client bundle never pulls in `node:crypto`.
+ *
+ * Format (GitHub-style): `<sk|rk|ek>_<live|test>_<30 base62 body><6-char
+ * base62 CRC32 checksum>`. The identifiable prefix + CRC32 checksum let
+ * secret scanners detect leaks and let us reject typo'd/forged keys OFFLINE
+ * (no DB round-trip). Legacy keys (a ~43-char base64url body, no checksum)
+ * still validate by hash — they parse here as `checksummed: false`.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { z } from 'zod';
+// ── Vocabulary ──────────────────────────────────────────────────────────
+// The three-key Stripe model:
+//   secret (sk_)      — backend / server-to-server / agents. Full authority. Never in a browser.
+//   restricted (rk_)  — scoped SERVER key (agent session tokens / capabilities).
+//   ephemeral (ek_)   — short-lived, backend-minted, USER-scoped BROWSER session credential
+//                       (Stripe ephemeral keys). Carries participantKind:'user' + baked syncGroups.
+// (There is no publishable `pk_` — the minted session token, not a project
+//  identifier, is what the browser holds; it already names the org.)
+export const API_KEY_KINDS = ['secret', 'restricted', 'ephemeral'];
+export const API_KEY_ENVS = ['live', 'test'];
+const PREFIX_BY_KIND = {
+    secret: 'sk',
+    restricted: 'rk',
+    ephemeral: 'ek',
+};
+const KIND_BY_PREFIX = {
+    sk: 'secret',
+    rk: 'restricted',
+    ek: 'ephemeral',
+};
+const BASE62 = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+/** Random base62 chars before the checksum. */
+const KEY_BODY_LEN = 30;
+/** base62(CRC32): 62^6 (~5.7e10) > 2^32, so a CRC32 always fits in 6 chars. */
+const CHECKSUM_LEN = 6;
+/** A new checksummed body is exactly this long and pure base62. */
+const CHECKSUMMED_BODY_LEN = KEY_BODY_LEN + CHECKSUM_LEN;
+/** `<sk|rk|ek>_<live|test>_<body>`; body charset covers base62 AND legacy base64url. */
+const KEY_RE = /^(sk|rk|ek)_(live|test)_([0-9A-Za-z\-_]+)$/;
+const BASE62_RE = /^[0-9A-Za-z]+$/;
+// ── Checksum (standard CRC-32, GitHub-compatible) ───────────────────────
+const CRC32_TABLE = (() => {
+    const t = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        t[n] = c >>> 0;
+    }
+    return t;
+})();
+function crc32(s) {
+    let c = 0xffffffff;
+    for (let i = 0; i < s.length; i++) {
+        c = (CRC32_TABLE[(c ^ s.charCodeAt(i)) & 0xff] ^ (c >>> 8)) >>> 0;
+    }
+    return (c ^ 0xffffffff) >>> 0;
+}
+/** 6-char base62 encoding of the CRC32 of `payload`. */
+function checksum6(payload) {
+    let n = crc32(payload);
+    let out = '';
+    for (let i = 0; i < CHECKSUM_LEN; i++) {
+        out = BASE62[n % 62] + out;
+        n = Math.floor(n / 62);
+    }
+    return out;
+}
+/** `len` cryptographically-random base62 chars (rejection-sampled, no bias). */
+function randomBase62(len) {
+    let out = '';
+    while (out.length < len) {
+        for (const b of randomBytes(len * 2)) {
+            if (b < 248) {
+                out += BASE62[b % 62];
+                if (out.length === len)
+                    break;
+            }
+        }
+    }
+    return out;
+}
+function bodyIsChecksummed(body) {
+    return body.length === CHECKSUMMED_BODY_LEN && BASE62_RE.test(body);
+}
+/**
+ * Canonical schema for an Ablo API key. `parse`/`safeParse` returns a typed
+ * {@link ParsedApiKey}; a new checksummed-format key with a BAD checksum is
+ * rejected (the offline-reject), while a legacy key parses as
+ * `checksummed: false` and passes (the server still hash-validates it).
+ */
+export const apiKeySchema = z.string().transform((raw, ctx) => {
+    const m = KEY_RE.exec(raw);
+    if (!m) {
+        ctx.addIssue({ code: 'custom', message: 'not a valid Ablo API key format' });
+        return z.NEVER;
+    }
+    const [, prefix, env, body] = m;
+    const checksummed = bodyIsChecksummed(body);
+    if (checksummed && checksum6(raw.slice(0, -CHECKSUM_LEN)) !== body.slice(KEY_BODY_LEN)) {
+        ctx.addIssue({ code: 'custom', message: 'API key checksum mismatch' });
+        return z.NEVER;
+    }
+    return { raw, kind: KIND_BY_PREFIX[prefix], env: env, body, checksummed };
+});
+// ── Derived validators (thin wrappers over the same spec) ───────────────
+/** Parse + fully validate (incl. checksum). Returns null when invalid. */
+export function parseApiKey(raw) {
+    const r = apiKeySchema.safeParse(raw);
+    return r.success ? r.data : null;
+}
+/** True when the key uses the new checksummed format (regardless of validity). */
+export function isChecksummedKey(raw) {
+    const m = KEY_RE.exec(raw);
+    return m !== null && bodyIsChecksummed(m[3]);
+}
+/** Verify the embedded checksum. Meaningful only for checksummed-format keys. */
+export function keyChecksumMatches(raw) {
+    const m = KEY_RE.exec(raw);
+    if (!m || !bodyIsChecksummed(m[3]))
+        return false;
+    return checksum6(raw.slice(0, -CHECKSUM_LEN)) === m[3].slice(KEY_BODY_LEN);
+}
+// ── Mint + hash (node:crypto) ───────────────────────────────────────────
+/**
+ * Mint a key: `<prefix>_<env>_<body><checksum>`. Returns the plaintext (shown
+ * once), its SHA-256 hash (persisted), and the 12-char display prefix.
+ */
+export function generateApiKey(env = 'live', kind = 'secret') {
+    const body = randomBase62(KEY_BODY_LEN);
+    const payload = `${PREFIX_BY_KIND[kind]}_${env}_${body}`;
+    const plaintext = `${payload}${checksum6(payload)}`;
+    return { plaintext, hash: hashApiKey(plaintext), prefix: plaintext.slice(0, 12) };
+}
+/**
+ * Stable SHA-256 hex of a plaintext key. A fast hash is CORRECT here (not
+ * bcrypt) — API keys are high-entropy random, so there's no dictionary to
+ * defend against. Used at both write (mint) and lookup.
+ */
+export function hashApiKey(plaintext) {
+    return createHash('sha256').update(plaintext).digest('hex');
+}

package/dist/policy/index.d.ts CHANGED Viewed

@@ -16,4 +16,4 @@
  * ```
  */
 export type { Conflict, ConflictDecision, ConflictKind, ConflictOperation, ConflictPolicy, StaleContextConflict, IntentHeldConflict, } from './types.js';
-export { defaultPolicy } from './types.js';
+export { defaultPolicy, capabilityPreemptPolicy } from './types.js';

package/dist/policy/index.js CHANGED Viewed

@@ -15,4 +15,4 @@
  * };
  * ```
  */
-export { defaultPolicy } from './types.js';
+export { defaultPolicy, capabilityPreemptPolicy } from './types.js';

package/dist/policy/types.d.ts CHANGED Viewed

@@ -48,6 +48,14 @@ export interface IntentHeldConflict extends ConflictBase {
     readonly entityId: string;
     /** Holder's intent expiry (ms since epoch). */
     readonly expiresAt: number;
+    /**
+     * The committer's granted capability operations (the key's allowlist). A
+     * policy is a pure function of the conflict value, so it can only authorize
+     * on what's carried here — this is what lets a policy express "preempt iff
+     * the committer holds `intent.preempt`" (see `capabilityPreemptPolicy`).
+     * Empty for a human session with no allowlist.
+     */
+    readonly committerOperations: readonly string[];
 }
 /**
  * The discriminated union the policy receives. Switch on `.kind` to
@@ -61,6 +69,20 @@ export type ConflictDecision = {
 } | {
     readonly action: 'allow';
     readonly note?: string;
+}
+/**
+ * Evict the current holder and grant the target to the committer. Only
+ * meaningful for an `intent_held` conflict at claim time (`intent_begin`):
+ * the holder receives an `intent_lost` (reason `'preempted'`) and the
+ * preemptor takes the lease, jumping ahead of any FIFO waiters. This is the
+ * authorization seam for preemption — a policy returns `preempt` only for a
+ * committer it deems higher-priority (e.g. a supervisor over its sub-agents,
+ * or an identity holding a preempt capability). At commit time there is no
+ * holder to evict, so a `preempt` decision there is treated as `allow`.
+ */
+ | {
+    readonly action: 'preempt';
+    readonly reason?: string;
 };
 /**
  * Pluggable decision function. Sync or async.
@@ -81,4 +103,13 @@ export type ConflictPolicy = (conflict: Conflict) => ConflictDecision | Promise<
  * intent-conflicting write through.
  */
 export declare const defaultPolicy: ConflictPolicy;
+/**
+ * Capability-gated preemption. An `intent_held` conflict is PREEMPTED when the
+ * committer holds the `intent.preempt` operation in its capability allowlist
+ * (the holder is evicted, the committer takes the lease); everything else falls
+ * back to `defaultPolicy` (reject). Opt-in — wire it as a `conflictPolicies`
+ * global to let a privileged identity jump a held entity without a bespoke
+ * policy. The authorization is the capability, not an identity string.
+ */
+export declare const capabilityPreemptPolicy: ConflictPolicy;
 export {};

package/dist/policy/types.js CHANGED Viewed

@@ -15,3 +15,18 @@ export const defaultPolicy = (conflict) => ({
     action: 'reject',
     reason: conflict.kind === 'stale_context' ? 'stale_context' : 'intent_conflict',
 });
+/**
+ * Capability-gated preemption. An `intent_held` conflict is PREEMPTED when the
+ * committer holds the `intent.preempt` operation in its capability allowlist
+ * (the holder is evicted, the committer takes the lease); everything else falls
+ * back to `defaultPolicy` (reject). Opt-in — wire it as a `conflictPolicies`
+ * global to let a privileged identity jump a held entity without a bespoke
+ * policy. The authorization is the capability, not an identity string.
+ */
+export const capabilityPreemptPolicy = (conflict) => {
+    if (conflict.kind === 'intent_held' &&
+        conflict.committerOperations.includes('intent.preempt')) {
+        return { action: 'preempt', reason: 'capability:intent.preempt' };
+    }
+    return defaultPolicy(conflict);
+};

package/dist/query/client.js CHANGED Viewed

@@ -12,6 +12,7 @@
  * without duplicating the fetch boilerplate.
  */
 import { z } from 'zod';
+import { translateHttpError } from '../errors.js';
 // ── Response validation ─────────────────────────────────────────────────
 //
 // Each result slot is an array of rows (or an object for bundled
@@ -60,14 +61,24 @@ export async function postQuery(options, batch) {
             signal: controller.signal,
         });
         if (!response.ok) {
-            // Direct console.error is INTENTIONAL — operators alert on the
-            // `[postQuery.error]` prefix in browser console. Routing through
-            // an injected logger here would require a coordinated change to
-            // the alerting pipeline. Tracked as future work; the dual-channel
-            // alternative (logger + observability.captureException) is the
-            // production target. Never throw — fire-and-forget callers would
-            // kill Next.js router on unhandled rejection.
-            console.error(`[postQuery.error] ${response.status} ${response.statusText} for ${batch.queries.map((q) => q.model).join(',')}`);
+            // Build the typed AbloError for this HTTP failure (same code→class
+            // map the throwing paths use) so the log is tagged + carries a
+            // registry `code` (e.g. AbloAuthenticationError/session_expired on a
+            // 401) instead of a bare status. We deliberately DON'T throw —
+            // fire-and-forget callers would kill the Next.js router on an
+            // unhandled rejection — and still return empty slots, but the failure
+            // is now legible as an Ablo error. Direct console.error is
+            // INTENTIONAL: operators alert on the `[postQuery.error]` prefix.
+            let body = null;
+            try {
+                body = await response.clone().json();
+            }
+            catch {
+                // non-JSON error page — translateHttpError falls back to status text
+            }
+            const err = translateHttpError(response.status, body);
+            console.error(`[postQuery.error] ${err.type} ${err.code ?? response.status} for ` +
+                `${batch.queries.map((q) => q.model).join(',')}: ${err.message}`);
             return { results: batch.queries.map(() => []) };
         }
         const raw = await response.json();

package/dist/react/AbloProvider.d.ts CHANGED Viewed

@@ -72,6 +72,31 @@ export interface AbloProviderProps<R extends SchemaRecord = SchemaRecord> {
      * same-origin session cookies.
      */
     apiKey?: string;
+    /**
+     * Static bearer auth token, sent as `Authorization: Bearer <token>` on the
+     * WebSocket upgrade + HTTP. For a token that must be refreshed (e.g. a
+     * short-lived JWT), prefer {@link getToken}.
+     */
+    authToken?: string | null;
+    /**
+     * Async resolver for a short-lived bearer token. Called once before the
+     * engine connects (so the first connection carries a fresh token) and then on
+     * a refresh interval ahead of expiry — each result is pushed via
+     * `engine.setAuthToken` without tearing down the connection. Wire this to
+     * a resolver that mints a short-lived session token (`ek_`/`rk_`) — e.g.
+     * `getSyncCapabilityToken` — or your own. Takes precedence over
+     * {@link authEndpoint}.
+     */
+    getToken?: () => Promise<string | null>;
+    /**
+     * Liveblocks/Stripe-style auth endpoint: a URL on YOUR backend that returns
+     * `{ token }` — the `ek_` ephemeral key your server minted for the logged-in
+     * user with `ablo.sessions.create({ user: { id } })`. The provider POSTs to it
+     * (with cookies) to fetch + refresh the bearer, so the browser carries no
+     * secret. Shorthand for a {@link getToken} that does the fetch; ignored when
+     * `getToken` is set.
+     */
+    authEndpoint?: string;
     /** Optional Zero-style custom mutators. */
     mutators?: MutatorDefs<Schema<R>>;
     /** Options forwarded to the internal `useMutators` call (e.g., `undoScope`). */
@@ -114,7 +139,19 @@ export interface AbloProviderProps<R extends SchemaRecord = SchemaRecord> {
     sessionErrorDetector?: SessionErrorDetector;
     onlineStatus?: OnlineStatusProvider;
     configOverrides?: SyncEngineConfig;
+    /**
+     * Raw sync-group strings for the initial connection. Prefer {@link scope} —
+     * the model form (`{ decks: deckId }`) that the engine resolves through the
+     * schema's `scope`, so you never hand-write a `deck:<id>` string. Both merge.
+     */
     syncGroups?: string[];
+    /**
+     * Model-form connection scope: `{ decks: deckId, documents: documentId }` or
+     * entity refs. Resolved through the schema's per-model `scope` into group
+     * strings (so typename `SlideDeck` → `deck:<id>`), unioned with {@link syncGroups}.
+     * Memoize the object if it's derived, to avoid rotating the engine each render.
+     */
+    scope?: ParticipantScope;
     bootstrapBaseUrl?: string;
     maxPoolSize?: number;
     /**

package/dist/react/AbloProvider.js CHANGED Viewed

@@ -5,7 +5,7 @@ import { Ablo } from '../client/Ablo.js';
 import { createParticipantClaimId, parseParticipantTtlSeconds, resolveParticipantSyncGroups, } from '../sync/participants.js';
 import { SyncContext } from './context.js';
 import { AbloInternalContext } from './internalContext.js';
-import { AbloValidationError } from '../errors.js';
+import { AbloValidationError, AbloAuthenticationError } from '../errors.js';
 import { useSyncStatus } from './useSyncStatus.js';
 import { DefaultFallback } from './DefaultFallback.js';
 // ── Implementation ───────────────────────────────────────────────────
@@ -32,7 +32,7 @@ function createErrorEmitter() {
     };
 }
 export function AbloProvider(props) {
-    const { schema, url = 'wss://mesh.ablo.finance', userId, teamIds, apiKey, preventUnsavedChanges, onSessionExpired, onError, observability, logger, mutationExecutor, mutationDispatcher, sessionErrorDetector, onlineStatus, configOverrides, syncGroups, bootstrapBaseUrl, maxPoolSize, persistence, bootstrapMode, fallback = _jsx(DefaultFallback, {}), children, } = props;
+    const { schema, url = 'wss://mesh.ablo.finance', userId, teamIds, apiKey, authToken, getToken, authEndpoint, preventUnsavedChanges, onSessionExpired, onError, observability, logger, mutationExecutor, mutationDispatcher, sessionErrorDetector, onlineStatus, configOverrides, syncGroups, scope, bootstrapBaseUrl, maxPoolSize, persistence, bootstrapMode, fallback = _jsx(DefaultFallback, {}), children, } = props;
     // Account scope is no longer accepted from props. The engine learns
     // it from auth (capability token) at bootstrap and we read it back
     // out of `_store.orgId` once `engine.ready()` resolves.
@@ -54,6 +54,25 @@ export function AbloProvider(props) {
     useEffect(() => {
         return errorEmitter.subscribe((err) => onErrorRef.current?.(err));
     }, [errorEmitter]);
+    // Stash the token resolver in a ref so a new function identity each render
+    // does not re-key (tear down) the engine. Read at fire time in the connect +
+    // refresh paths below — same `useEventCallback` idiom as `onError`. `getToken`
+    // wins; otherwise `authEndpoint` is fetched for `{ token }`.
+    const tokenFromEndpoint = authEndpoint
+        ? async () => {
+            const res = await fetch(authEndpoint, {
+                method: 'POST',
+                credentials: 'include',
+                headers: { 'Content-Type': 'application/json' },
+            });
+            if (!res.ok)
+                return null;
+            const body = (await res.json());
+            return body.token ?? null;
+        }
+        : undefined;
+    const getTokenRef = useRef(getToken ?? tokenFromEndpoint);
+    getTokenRef.current = getToken ?? tokenFromEndpoint;
     // ── Engine lifecycle keyed on (userId, url) ─────────────────────
     //
     // The engine rotates when either of these change. For everything
@@ -79,6 +98,7 @@ export function AbloProvider(props) {
             schema,
             ...(userId ? { user: { id: userId, teamIds } } : {}),
             apiKey,
+            ...(authToken ? { authToken } : {}),
             logger,
             observability,
             sessionErrorDetector,
@@ -86,7 +106,11 @@ export function AbloProvider(props) {
             mutationExecutor,
             mutationDispatcher,
             configOverrides,
-            syncGroups,
+            // Union raw strings with model-form `scope` resolved through the schema,
+            // so `scope={{ decks: id }}` becomes `deck:<id>` via the model's `scope`.
+            syncGroups: scope
+                ? [...(syncGroups ?? []), ...resolveParticipantSyncGroups(scope, schema)]
+                : syncGroups,
             bootstrapBaseUrl,
             maxPoolSize,
             persistence,
@@ -117,6 +141,52 @@ export function AbloProvider(props) {
         // saves once `useAblo` exists.
         (async () => {
             try {
+                // Resolve a fresh bearer token BEFORE `ready()` (which connects —
+                // the engine is built with `autoStart: false`), so the first WS
+                // upgrade + bootstrap carry it. No race: nothing has connected yet.
+                const fetchToken = getTokenRef.current;
+                if (fetchToken) {
+                    const token = await fetchToken();
+                    if (isStale || abort.signal.aborted)
+                        return;
+                    if (token) {
+                        engine.setAuthToken(token);
+                    }
+                    else {
+                        // A configured `getToken` that resolves to falsy means "no active
+                        // session" — the session-token resolver (e.g. `getSyncCapabilityToken`)
+                        // returns null when logged out, the session hasn't hydrated, or the
+                        // mint endpoint rejects. Its contract is "the provider then surfaces
+                        // the usual unauthenticated path rather than connecting with a bad token."
+                        //
+                        // We MUST short-circuit here rather than fall through to
+                        // `engine.ready()`. On apps/web's identity path (org + user.id are
+                        // both supplied) `resolveParticipantIdentity` takes the
+                        // trust-the-caller Branch 3, which does NOT validate the (absent)
+                        // token — so init would proceed into `store.initialize()` and open
+                        // IndexedDB *before* any auth-bearing bootstrap/WS call. If storage
+                        // is at all wedged the no-session condition then surfaces only as an
+                        // opaque `IndexedDB "ablo_databases" open did not resolve within
+                        // 10000ms` stall, never the real auth error. Surface `session_expired`
+                        // explicitly and let the app redirect to sign-in.
+                        //
+                        // Unlike the server-detected `onSessionError` handler above, we do
+                        // NOT purge: nothing connected or wrote this mount, so any cached
+                        // IndexedDB belongs to a prior session and is reconciled by the next
+                        // valid bootstrap — purging here would drop a still-valid offline
+                        // queue on a merely transient null token.
+                        const authErr = new AbloAuthenticationError('No session token available — getToken() resolved to null. The ' +
+                            'session is missing or expired; sign in again.', { code: 'session_expired' });
+                        errorEmitter.emit(authErr);
+                        try {
+                            await onSessionExpired?.();
+                        }
+                        catch (hookErr) {
+                            errorEmitter.emit(hookErr);
+                        }
+                        return;
+                    }
+                }
                 await engine.ready();
                 if (isStale || abort.signal.aborted)
                     return;
@@ -142,6 +212,35 @@ export function AbloProvider(props) {
         // `mutationExecutor` identity change would destroy the WebSocket.
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [engineKey]);
+    // ── Bearer-token refresh ─────────────────────────────────────────
+    //
+    // Short-lived tokens (the sync-server JWT defaults to 15m) must be rolled
+    // before they expire or the next reconnect/HTTP call fails auth. Re-resolve
+    // ahead of expiry and push via `engine.setAuthToken`, which swaps the token
+    // on the live WebSocket + bootstrap header without tearing down the engine.
+    // Only runs when a `getToken` resolver is wired (cookie deployments skip it).
+    useEffect(() => {
+        const engine = engineState.engine;
+        if (!engine || !getTokenRef.current)
+            return;
+        // Comfortably inside the 15m JWT lifetime; a missed tick is recovered by
+        // the next one well before expiry.
+        const REFRESH_INTERVAL_MS = 10 * 60 * 1000;
+        const id = setInterval(() => {
+            void (async () => {
+                try {
+                    const token = await getTokenRef.current?.();
+                    if (token)
+                        engine.setAuthToken(token);
+                }
+                catch {
+                    // Transient (offline / session check). The next tick retries; the
+                    // engine keeps using the still-valid current token until then.
+                }
+            })();
+        }, REFRESH_INTERVAL_MS);
+        return () => clearInterval(id);
+    }, [engineState.engine]);
     // ── beforeunload + preventUnsavedChanges ─────────────────────────
     useEffect(() => {
         if (typeof window === 'undefined')
@@ -251,7 +350,11 @@ export function useParticipant(opts) {
     const ctx = useContext(AbloInternalContext);
     const engine = ctx?.engine ?? null;
     const { paused = false } = opts;
-    const scopeKey = JSON.stringify(resolveParticipantSyncGroups(opts.scope).sort());
+    // Resolve the model-form scope ({ decks: id } / refs) THROUGH the schema, so a
+    // model's declared `scope` kind is honored (typename `SlideDeck` → `deck:<id>`,
+    // not the `type:id` string fallback). Schema appears once the engine is ready;
+    // until then refs resolve by convention, then re-resolve when it arrives.
+    const scopeKey = JSON.stringify(resolveParticipantSyncGroups(opts.scope, engine?.schema).sort());
     const scopedSyncGroups = useMemo(() => JSON.parse(scopeKey), [scopeKey]);
     const [claimError, setClaimError] = useState(null);
     const [claimConnected, setClaimConnected] = useState(false);

package/dist/react/ClientSideSuspense.d.ts CHANGED Viewed

@@ -33,4 +33,4 @@ export interface ClientSideSuspenseProps {
     /** What to render once the subtree is cleared to render. */
     children: ReactNode;
 }
-export declare function ClientSideSuspense({ fallback, children }: ClientSideSuspenseProps): import("react/jsx-runtime").JSX.Element;
+export declare function ClientSideSuspense({ fallback, children }: ClientSideSuspenseProps): import("react").JSX.Element;

package/dist/react/DefaultFallback.d.ts CHANGED Viewed

@@ -21,4 +21,4 @@
  * pass `fallback={null}`. Consumers who want to skip the gate entirely
  * pass `fallback="passthrough"`.
  */
-export declare function DefaultFallback(): import("react/jsx-runtime").JSX.Element;
+export declare function DefaultFallback(): import("react").JSX.Element;

package/dist/react/SyncGroupProvider.d.ts CHANGED Viewed

@@ -4,7 +4,7 @@ export interface SyncGroupProviderProps {
     id: string;
     children: ReactNode;
 }
-export declare function SyncGroupProvider({ id, children }: SyncGroupProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function SyncGroupProvider({ id, children }: SyncGroupProviderProps): import("react").JSX.Element;
 /**
  * Returns the ID of the nearest `<SyncGroupProvider>`. Throws if
  * called outside one — sync-group awareness is mandatory by design,

package/dist/react/index.d.ts CHANGED Viewed

@@ -13,9 +13,10 @@
  *     immediately. The provider-level `fallback` is the default path.
  *
  * Data hooks:
- *   useAblo((ablo) => ablo.tasks.retrieve(id)) — primary React read API
+ *   useAblo((ablo) => ablo.tasks.get(id))     — primary React read API (sync local snapshot)
  *   useAblo()                                  — typed client for callbacks/effects
- *                                                (reads: ablo.<model>.retrieve/list;
+ *                                                (sync local reads: ablo.<model>.get/getAll;
+ *                                                 async server reads: ablo.<model>.retrieve/list;
  *                                                 writes: ablo.<model>.create/update/delete)
  *   useMutators(defs, opts?)                   — Zero-style custom mutators
  *   useUndoScope(name)                         — per-surface undo/redo

package/dist/react/index.js CHANGED Viewed

@@ -13,9 +13,10 @@
  *     immediately. The provider-level `fallback` is the default path.
  *
  * Data hooks:
- *   useAblo((ablo) => ablo.tasks.retrieve(id)) — primary React read API
+ *   useAblo((ablo) => ablo.tasks.get(id))     — primary React read API (sync local snapshot)
  *   useAblo()                                  — typed client for callbacks/effects
- *                                                (reads: ablo.<model>.retrieve/list;
+ *                                                (sync local reads: ablo.<model>.get/getAll;
+ *                                                 async server reads: ablo.<model>.retrieve/list;
  *                                                 writes: ablo.<model>.create/update/delete)
  *   useMutators(defs, opts?)                   — Zero-style custom mutators
  *   useUndoScope(name)                         — per-surface undo/redo

package/dist/react/useAblo.d.ts CHANGED Viewed

@@ -45,11 +45,11 @@ export type UseAbloHydratedModelResult<T> = Omit<UseAbloModelResult<T>, 'data'>
  * // With Register augmentation (recommended):
  * const ablo = useAblo();
  * if (!ablo) return <Loading />;
- * const docs = await ablo.documents.load({ where: { id } });
+ * const doc = await ablo.documents.retrieve(id); // async server read
  *
- * // Reactive selector:
- * const doc = useAblo((ablo) => ablo.documents.retrieve(id)) ?? serverDoc;
- * const active = useAblo((ablo) => ablo.documents.claimState(id));
+ * // Reactive selector (sync local-graph snapshot):
+ * const doc = useAblo((ablo) => ablo.documents.get(id)) ?? serverDoc;
+ * const active = useAblo((ablo) => ablo.documents.claim.state(id));
  *
  * // Without augmentation, pass the schema generic:
  * const ablo = useAblo<(typeof schema)['models']>();

package/dist/react/useAblo.js CHANGED Viewed

@@ -9,7 +9,7 @@ function readModelResult(engine, modelClient, id, initial) {
     if (!modelClient || id === undefined) {
         return { data: initial, claims: EMPTY_CLAIMS, claimed: false };
     }
-    const data = snapshotValue(modelClient.retrieve(id) ?? initial);
+    const data = snapshotValue(modelClient.get(id) ?? initial);
     const meta = getModelClientMeta(modelClient);
     const claims = meta && engine
         ? engine.intents.list({ model: meta.key, id })
@@ -29,7 +29,6 @@ export function useAblo(modelOrSelect, id, options) {
     const ctx = useContext(AbloInternalContext);
     const engine = ctx?.engine ?? null;
     const initial = options?.initial;
-    const hasSelection = modelOrSelect !== undefined;
     const isSelectorOnly = typeof modelOrSelect === 'function' && id === undefined;
     const modelClient = typeof modelOrSelect === 'function' && id !== undefined
         ? engine
@@ -38,14 +37,20 @@ export function useAblo(modelOrSelect, id, options) {
         : typeof modelOrSelect === 'function'
             ? undefined
             : modelOrSelect;
+    // Claims live on a non-MobX event emitter (engine.intents), so the useReactive
+    // reactions below cannot track them — we bridge changes through a setState bump.
+    // ONLY the model-row form (`id !== undefined`) actually reads claims, so gate the
+    // subscription on `id`. The selector-only form (`useAblo((a) => a.x.get/getAll)`)
+    // never reads claims; subscribing it to the workspace-global intent stream would
+    // re-render + double-compute it on every intent/presence delta anywhere (a real
+    // storm during AI editing / live collaboration) for a value that can't change.
     const [claimVersion, setClaimVersion] = useState(0);
     useEffect(() => {
-        if (!engine || !hasSelection)
+        if (!engine || id === undefined)
             return;
         return engine.intents.onChange(() => setClaimVersion((version) => version + 1));
-    }, [engine, hasSelection]);
+    }, [engine, id]);
     const selected = useReactive(() => {
-        void claimVersion;
         if (!engine || !isSelectorOnly || typeof modelOrSelect !== 'function') {
             return undefined;
         }

package/dist/react/useReactive.js CHANGED Viewed

@@ -66,16 +66,29 @@ export function useReactive(compute, equals = defaultEquals) {
     const subscribeVersionRef = useRef(0);
     if (snapshotRef.current === null) {
         snapshotRef.current = { value: compute() };
-        computeRef.current = compute;
     }
     else if (computeRef.current !== compute) {
+        // `compute` is a fresh inline arrow at virtually every call site, so this
+        // branch runs on essentially every render. Reconcile the snapshot against
+        // the latest closure, but only force a re-subscription when the value
+        // ACTUALLY changed. For the dominant case (same observable source, new
+        // arrow identity, unchanged value) this avoids tearing down + recreating
+        // the MobX reaction — and its double-compute — on every render. A genuine
+        // source swap (a memoized compute closing over a new observable source)
+        // changes the value, which both updates the snapshot and bumps
+        // `subscribeVersion` so the reaction below re-subscribes and re-tracks the
+        // new source's observables.
         const next = compute();
         if (!equals(snapshotRef.current.value, next)) {
             snapshotRef.current = { value: next };
+            subscribeVersionRef.current++;
         }
-        computeRef.current = compute;
-        subscribeVersionRef.current++;
     }
+    // Point the long-lived reaction at the latest closure every render. The
+    // reaction expression reads `computeRef.current` at fire time, so it always
+    // runs the newest compute (and re-tracks its observables) even when we did
+    // not re-subscribe above.
+    computeRef.current = compute;
     const subscribeVersion = subscribeVersionRef.current;
     const subscribe = useCallback((onChange) => {
         return reaction(() => computeRef.current(), (next) => {