@abloatai/ablo 0.8.0 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## 0.9.1
+
+### Patch Changes
+
+- 90b656c: `drizzleDataSource` now takes `(db, schema)` and derives snake_case columns from your schema, so it composes with `ablo migrate` with no parallel Drizzle table. Update calls from `drizzleDataSource(db, tables)` → `drizzleDataSource(db, schema)`. Also adds the `snakeToCamel` export and provisions the adapter's `ablo_outbox` / `ablo_idempotency` tables via `ablo migrate`.
+
+## 0.9.0
+
+A single options object for every model verb, and a disposable `claim` handle.
+
+### Breaking Changes
+
+- **One options object per verb.** `create`, `update`, `delete`, and the async
+  server `retrieve` each take a single options object instead of positional
+  arguments, so the id, the data, and every modifier live as named siblings:
+  `create({ data, id? })`, `update({ id, data, ...options })`,
+  `delete({ id, ...options })`, `retrieve({ id, ...options })`. Reactive local
+  reads stay on `get(id)` (synchronous) —
+  `useAblo((ablo) => ablo.tasks.get(id))`.
+
+  ```diff
+  - await ablo.tasks.update(id, { status: 'done' }, { wait: 'confirmed' })
+  + await ablo.tasks.update({ id, data: { status: 'done' }, wait: 'confirmed' })
+
+  - await ablo.tasks.retrieve(id)
+  + await ablo.tasks.retrieve({ id })
+
+  - useAblo((ablo) => ablo.tasks.retrieve(id)) ?? serverTask
+  + useAblo((ablo) => ablo.tasks.get(id)) ?? serverTask
+  ```
+
+- **`claim` returns a disposable handle** instead of taking a callback. The
+  handle exposes the fresh row on `.data` and is released on scope exit
+  (`await using`) or explicitly via `.release()`. `claim.state`, `claim.queue`,
+  `claim.release`, and `claim.reorder` also take the options object.
+
+  ```diff
+  - await ablo.tasks.claim(id, async (task) => {
+  -   await ablo.tasks.update(task.id, { status: 'in_review' })
+  - })
+  + await using claim = await ablo.tasks.claim({ id })
+  + const task = claim.data
+  + await ablo.tasks.update({ id: task.id, data: { status: 'in_review' } })
+  ```
+
 ## 0.8.0
 
 A callable `claim` coordination namespace and bring-your-own-database support
@@ -325,7 +370,7 @@ The SDK covers exactly three integration shapes. Each has a canonical example in
 ### Env / config
 
 - `ABLO_API_KEY` — required for server-side use.
-- `ABLO_BASE_URL` — optional override for staging / local-dev (defaults to `https://mesh.ablo.finance`). Not a customer-facing self-hosting path.
+- `baseURL` — optional override for private deployments / local-dev (defaults to `wss://api.abloatai.com`).
 - `organizationId` — **no longer required** in `createMesh`. The API key or session binds the caller to one org; the capability mint response echoes it back.
 - `createMeshFromEnv` — removed. `new Ablo({ schema })` auto-reads env.
 

package/README.md

@@ -84,17 +84,19 @@ const ablo = Ablo({
 await ablo.ready();
 
 const created = await ablo.weatherReports.create({
-  location: 'Stockholm',
-  status: 'pending',
+  data: {
+    location: 'Stockholm',
+    status: 'pending',
+  },
 });
 
 // An agent claims the row, does its slow work, then writes back. While the
 // claim is held nobody else can overwrite it; anyone else who tries waits in
 // line and re-reads the result. This is the whole point of Ablo.
-await ablo.weatherReports.claim(created.id, async (report) => {
-  const forecast = await fetchForecast(report.location); // slow: API or LLM call
-  await ablo.weatherReports.update(report.id, { status: 'ready', forecast });
-});
+await using claim = await ablo.weatherReports.claim({ id: created.id });
+const report = claim.data;
+const forecast = await fetchForecast(report.location); // slow: API or LLM call
+await ablo.weatherReports.update({ id: report.id, data: { status: 'ready', forecast } });
 
 const ready = ablo.weatherReports.get(created.id);
 console.log({ id: ready.id, status: ready.status });
@@ -145,7 +147,7 @@ matter day to day:
 | `idempotencyKey` | `string` | Auto-generated per call. Override only when you own the retry boundary (e.g. a job id) so a re-run dedupes server-side. |
 
 ```ts
-await ablo.weatherReports.update(id, { status: 'ready' }, { wait: 'confirmed' });
+await ablo.weatherReports.update({ id, data: { status: 'ready' }, wait: 'confirmed' });
 ```
 
 To guard a write against a row that changed under you, pass `readAt` + `onStale`
@@ -157,30 +159,32 @@ An agent reads a row, thinks for 30s, writes back — and clobbers whatever chan
 meanwhile, or worse, acts on stale state. `claim` holds the row across that gap:
 
 ```ts
-await ablo.weatherReports.claim('report_stockholm', async (report) => {
-  const forecast = await weatherAgent.getWeather(report.location);
-  await ablo.weatherReports.update(report.id, { forecast, status: 'ready' });
-});
+await using claim = await ablo.weatherReports.claim({ id: 'report_stockholm' });
+const report = claim.data;
+const forecast = await weatherAgent.getWeather(report.location);
+await ablo.weatherReports.update({ id: report.id, data: { forecast, status: 'ready' } });
 ```
 
 If someone else holds the row, `claim()` waits in a fair queue, then re-reads —
 so `report` is the current row, never a stale snapshot. Reads stay open by
-default; only acting on the row serializes. The claim releases when the callback
-returns or throws.
+default; only acting on the row serializes. The claim releases when the `await
+using` scope exits.
 
 See who's mid-edit before you act — decide to wait, or skip:
 
 ```ts
-ablo.weatherReports.claim.state('report_stockholm');
-ablo.weatherReports.claim.queue('report_stockholm');
+ablo.weatherReports.claim.state({ id: 'report_stockholm' });
+ablo.weatherReports.claim.queue({ id: 'report_stockholm' });
 
-await ablo.weatherReports.claim(id, async (report) => {
+{
+  await using claim = await ablo.weatherReports.claim({ id, wait: false });
   /* do the held work */
-}, { wait: false });
+}
 
-await ablo.weatherReports.claim(id, async (report) => {
+{
+  await using claim = await ablo.weatherReports.claim({ id, maxQueueDepth: 2 });
   /* do the held work */
-}, { maxQueueDepth: 2 });
+}
 ```
 
 `claim.state` returns the holder (or `null`); `claim.queue` returns the line waiting
@@ -194,14 +198,15 @@ Even an unclaimed write can't land on stale reasoning — the commit is guarded:
 
 ```ts
 try {
-  await ablo.weatherReports.update(id, { status: 'ready' }, { readAt, onStale: 'reject' });
+  await ablo.weatherReports.update({ id, data: { status: 'ready' }, readAt, onStale: 'reject' });
 } catch (e) {
   if (e instanceof AbloStaleContextError) { /* row moved under you — re-read, retry */ }
 }
 ```
 
-> Prefer the callback form for ordinary held work. Manual scoped claims are
-> available for wider lifetimes, but callback claims are the docs default.
+> Use `await using` for ordinary held work — the claim releases when the scope
+> exits. Call `claim.release({ id })` only to give a manually held claim back
+> early.
 
 See [Coordination](./docs/coordination.md) for the full `claim` / `claim.state` /
 `claim.queue` / `claim.release` reference.
@@ -231,7 +236,7 @@ function Report({ id }: { id: string }) {
   if (!report) return null;
 
   return (
-    <button onClick={() => ablo?.weatherReports.update(id, { status: 'ready' })}>
+    <button onClick={() => ablo?.weatherReports.update({ id, data: { status: 'ready' } })}>
       {report.status}
     </button>
   );
@@ -285,7 +290,7 @@ each other's changes in real time — that's the default, not a feature you turn
 
 - `ablo.<model>.create/update/delete` fan out confirmed deltas to subscribers.
 - `useAblo(...)` gives React clients the live row, kept current automatically.
-- `ablo.<model>.claim(id)` / `claim.state(id)` / `queue(id)` let humans and agents coordinate (and observe) active work on a row — and the line waiting behind it — before a write lands.
+- `ablo.<model>.claim({ id })` / `claim.state({ id })` / `claim.queue({ id })` let humans and agents coordinate (and observe) active work on a row — and the line waiting behind it — before a write lands.
 
 Always write through Ablo — either the SDK model methods
 (`ablo.<model>.create/update/delete`) or the HTTP write endpoint below. If you
@@ -314,7 +319,7 @@ curl https://api.abloatai.com/v1/commits \
 ## Connect Your Database
 
 Every schema model has a backing store. By default, Ablo stores rows for the
-models you declare, so `ablo.weatherReports.create(...)` and `ablo.weatherReports.update(...)`
+models you declare, so `ablo.weatherReports.create({ data })` and `ablo.weatherReports.update({ id, data })`
 write to Ablo-managed state.
 
 If your existing database stays the source of truth, connect it as a Data
@@ -332,7 +337,7 @@ See [Connect Your Database](./docs/data-sources.md) for the integration shape.
 | --- | --- | --- | --- |
 | `schema` | `Schema` | — (required) | Typed model proxies (`ablo.<model>.*`) |
 | `apiKey` | `string \| ApiKeySetter \| null` | `process.env.ABLO_API_KEY` | Server key — a string, or an async function for rotation |
-| `baseURL` | `string` | `wss://mesh.ablo.finance` | Point at a self-hosted or staging mesh |
+| `baseURL` | `string` | `wss://api.abloatai.com` | Point at a self-hosted or private API |
 
 Keep `apiKey` in trusted server runtimes. In the browser, `<AbloProvider>`
 authenticates with the signed-in user's session; the raw-key path is gated
@@ -348,7 +353,7 @@ survives worker / `postMessage` boundaries, where `instanceof` does not:
 
 ```ts
 try {
-  await ablo.weatherReports.update(id, { status: 'ready' }, { readAt, onStale: 'reject' });
+  await ablo.weatherReports.update({ id, data: { status: 'ready' }, readAt, onStale: 'reject' });
 } catch (e) {
   if (e instanceof AbloStaleContextError) { /* row moved under you — re-read, retry */ }
   if ((e as AbloError).type === 'AbloClaimedError') { /* another participant holds it */ }
@@ -379,7 +384,7 @@ contract; there are no retry or timeout knobs to tune.
 
 ## Production Reference
 
-- [Identity & Sync Groups](./docs/identity.md) — bring your own auth; tell Ablo who's connecting and how org / team / user map to sync-group scope.
+- [Identity & Sync Groups](./docs/identity.md) — use your own authentication; tell Ablo who's connecting and how org / team / user map to sync-group scope.
 - [Schema Contract](./docs/schema-contract.md) — one schema becomes typed model clients, React reads, agent writes, Data Source shape, and schema push.
 - [Guarantees](./docs/guarantees.md) — confirmed writes, stale-write protection, claim coordination, and agent lifecycle.
 - [Integration Guide](./docs/integration-guide.md) — pick the backing mode and integrate React, Data Source, multiplayer, and agents.

package/dist/BaseSyncedStore.d.ts

@@ -22,6 +22,8 @@ import { Model } from './Model.js';
 import { ModelScope } from './ObjectPool.js';
 import type { Schema } from './schema/schema.js';
 import { type ReaderActions } from './mutators/readerActions.js';
+import type { LocalMutation } from './react/context.js';
+import type { AuthCredentialSource } from './auth/credentialSource.js';
 /** Constructor type for Model subclasses (accepts abstract classes) */
 export type ModelConstructor<T extends Model> = abstract new (...args: never[]) => T;
 /** Concrete constructor type for instantiation */
@@ -240,6 +242,7 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     protected readonly database: Database;
     protected readonly objectPool: ObjectPool;
     protected readonly modelRegistry: ModelRegistry;
+    protected readonly auth?: AuthCredentialSource;
     /**
      * Schema the store was constructed with. Persisted so the `query`
      * accessor namespace can build typed per-model reader actions lazily
@@ -308,6 +311,8 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
         schema?: TSchema;
         /** Sync server URL for WebSocket connection. Converted to wss:// automatically. */
         url?: string;
+        /** Shared bearer credential source for every auth-aware transport. */
+        auth?: AuthCredentialSource;
     }, config?: SyncedStoreConfig);
     /**
      * Register foreign key indexes for O(1) lookups.
@@ -355,6 +360,24 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      * return null.
      */
     protected connectionManager: import('./sync/ConnectionManager.js').ConnectionManager | null;
+    /**
+     * Re-mint hook for the short-lived access credential (the Stripe-style
+     * `ek_`/`rk_`). Wired by the React provider from its `getToken`/`authEndpoint`
+     * — the engine owns WHEN to refresh (a stale-credential probe / an external
+     * nudge), the integrator owns HOW to mint. Mirrors the `getToken` contract:
+     * resolves a token string on success, `null` when the long-lived login is
+     * gone (terminal), and THROWS on a transient/offline failure. Used by
+     * {@link performCredentialRefresh}. Absent ⇒ no silent re-mint (e.g. a static
+     * `apiKey` deployment whose credential source refreshes out-of-band).
+     */
+    private credentialRefresher;
+    /** Single-flight guard so a wake nudge + an in-flight request + a probe don't
+     *  all mint at once (the classic "token thrash → random logout" bug). */
+    private inFlightCredentialRefresh;
+    /** Teardown for the proactive credential lifecycle (refresh timer + wake/
+     *  online/focus listeners) installed by {@link startCredentialLifecycle};
+     *  cleared on {@link disconnect}. Null when no resolver is wired. */
+    private credentialLifecycleTeardown;
     /**
      * Listeners registered via `subscribeSessionError()`. Fired when the
      * WebSocket closes with a session-invalid code (1008/4001/4003) or a
@@ -393,6 +416,15 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      * lookup contract; resolves immediately if nothing is in flight.
      */
     waitForConfirmation(modelName: string, modelId: string): Promise<void>;
+    /**
+     * Observe the LOCAL mutation stream for undo recording (see
+     * {@link import('./react/context.js').LocalMutation}). Taps the
+     * TransactionQueue's `transaction:created` event — fired once per local
+     * create/update/delete/archive with `previousData` already captured.
+     * Remote/collaborator deltas apply via `applyDeltaBatchToPool` and never
+     * emit here, so undo is naturally local-only (you can't undo a teammate).
+     */
+    subscribeLocalMutations(handler: (mutation: LocalMutation) => void): () => void;
     /**
      * Execute a bootstrap function with timeout protection and automatic retry.
      * Prevents the common issue where bootstrap hangs on startup.
@@ -404,6 +436,57 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     protected resetBootstrapState(): void;
     /** Perform reconnect: bootstrap + WS reconnect. Returns outcome for state machine. */
     performReconnect(): Promise<'success' | 'session_error' | 'network_error'>;
+    /**
+     * Register the access-credential re-mint hook. Called by the React provider
+     * with a thunk that mints a fresh `ek_`/`rk_` (typically its `getToken`).
+     * See {@link credentialRefresher}.
+     */
+    setCredentialRefresher(refresher: (() => Promise<string | null>) | null): void;
+    /**
+     * Re-mint the short-lived access credential and push it into the credential
+     * source, reporting a tri-state outcome the {@link ConnectionManager} maps to
+     * its FSM. The contract mirrors `getToken` (and PowerSync's `fetchCredentials`
+     * / Liveblocks' `authEndpoint`, but made explicit instead of overloading
+     * return/throw):
+     *   - token string  → `'refreshed'`     (fresh key in place; re-probe & reconnect)
+     *   - `null`        → `'session_error'` (login itself is gone → terminal, sign out)
+     *   - throw         → `'network_error'` (couldn't reach the mint endpoint → transient)
+     *
+     * SINGLE-FLIGHT: concurrent callers (a wake nudge, an in-flight request, the
+     * probe) share one in-flight promise so we never double-mint — the canonical
+     * fix for the "every 401 mints a token → thrash → spurious logout" anti-pattern.
+     *
+     * No refresher wired ⇒ `'refreshed'` (a no-op re-probe): a static-`apiKey`
+     * deployment has no session to re-mint from; its credential source refreshes
+     * out-of-band, so we just re-probe with whatever it currently holds.
+     */
+    performCredentialRefresh(): Promise<'refreshed' | 'session_error' | 'network_error'>;
+    /**
+     * Nudge the connection FSM to re-probe with the current credential. Idempotent
+     * and safe in any state (ignored while `connected`). Call after pushing a
+     * freshly-minted token via `setAuthToken`, or on an OS-wake signal, so a
+     * connection parked in `offline` / `backoff` / `auth_blocked` picks the new
+     * credential up immediately instead of waiting for the 30s watchdog.
+     */
+    nudgeReconnect(): void;
+    /**
+     * Install the access-credential lifecycle the CLIENT owns (this used to live
+     * in the React provider — wrong layer). Two parts:
+     *   1. REACTIVE — register `getToken` as the re-mint hook the FSM calls when a
+     *      probe finds the key stale (`credential_stale`) or on a nudge.
+     *   2. PROACTIVE — keep the short-lived key fresh ahead of trouble: a refresh
+     *      timer inside the TTL, plus re-mint on OS wake / network-online / tab
+     *      focus. Browser-only triggers are env-gated, so Node/agent hosts get
+     *      only the timer (a no-op there — agents use a static `apiKey`, no
+     *      resolver, so this is never called for them).
+     *
+     * Config-driven and invisible, like Supabase's `autoRefreshToken` — consumers
+     * never call a refresh method. Idempotent (a second call replaces the first);
+     * torn down on {@link disconnect}.
+     */
+    startCredentialLifecycle(getToken: () => Promise<string | null>): void;
+    /** Tear down the proactive credential lifecycle (idempotent). */
+    private stopCredentialLifecycle;
     /**
      * Handle an actionType 'G' delta.
      *

package/dist/BaseSyncedStore.js

@@ -124,6 +124,7 @@ export class BaseSyncedStore {
     database;
     objectPool;
     modelRegistry;
+    auth;
     /**
      * Schema the store was constructed with. Persisted so the `query`
      * accessor namespace can build typed per-model reader actions lazily
@@ -199,6 +200,7 @@ export class BaseSyncedStore {
         this.database = dependencies.database;
         this.objectPool = dependencies.objectPool;
         this.modelRegistry = dependencies.modelRegistry;
+        this.auth = dependencies.auth;
         this.schema = dependencies.schema;
         this._syncServerUrl = dependencies.url;
         // Set this store as the global Model store
@@ -351,6 +353,24 @@ export class BaseSyncedStore {
      * return null.
      */
     connectionManager = null;
+    /**
+     * Re-mint hook for the short-lived access credential (the Stripe-style
+     * `ek_`/`rk_`). Wired by the React provider from its `getToken`/`authEndpoint`
+     * — the engine owns WHEN to refresh (a stale-credential probe / an external
+     * nudge), the integrator owns HOW to mint. Mirrors the `getToken` contract:
+     * resolves a token string on success, `null` when the long-lived login is
+     * gone (terminal), and THROWS on a transient/offline failure. Used by
+     * {@link performCredentialRefresh}. Absent ⇒ no silent re-mint (e.g. a static
+     * `apiKey` deployment whose credential source refreshes out-of-band).
+     */
+    credentialRefresher = null;
+    /** Single-flight guard so a wake nudge + an in-flight request + a probe don't
+     *  all mint at once (the classic "token thrash → random logout" bug). */
+    inFlightCredentialRefresh = null;
+    /** Teardown for the proactive credential lifecycle (refresh timer + wake/
+     *  online/focus listeners) installed by {@link startCredentialLifecycle};
+     *  cleared on {@link disconnect}. Null when no resolver is wired. */
+    credentialLifecycleTeardown = null;
     /**
      * Listeners registered via `subscribeSessionError()`. Fired when the
      * WebSocket closes with a session-invalid code (1008/4001/4003) or a
@@ -392,6 +412,28 @@ export class BaseSyncedStore {
     waitForConfirmation(modelName, modelId) {
         return this.syncClient.waitForConfirmation(modelName, modelId);
     }
+    /**
+     * Observe the LOCAL mutation stream for undo recording (see
+     * {@link import('./react/context.js').LocalMutation}). Taps the
+     * TransactionQueue's `transaction:created` event — fired once per local
+     * create/update/delete/archive with `previousData` already captured.
+     * Remote/collaborator deltas apply via `applyDeltaBatchToPool` and never
+     * emit here, so undo is naturally local-only (you can't undo a teammate).
+     */
+    subscribeLocalMutations(handler) {
+        return this.syncClient.subscribe('transaction:created', (data) => {
+            const tx = data;
+            if (!tx || !tx.type || !tx.modelName || !tx.modelId)
+                return;
+            handler({
+                type: tx.type,
+                modelName: tx.modelName,
+                modelId: tx.modelId,
+                data: tx.data ?? null,
+                previousData: tx.previousData ?? null,
+            });
+        });
+    }
     // ── Bootstrap + Retry ────────────────────────────────────────────────────
     /**
      * Execute a bootstrap function with timeout protection and automatic retry.
@@ -531,6 +573,147 @@ export class BaseSyncedStore {
             return 'network_error';
         }
     }
+    /**
+     * Register the access-credential re-mint hook. Called by the React provider
+     * with a thunk that mints a fresh `ek_`/`rk_` (typically its `getToken`).
+     * See {@link credentialRefresher}.
+     */
+    setCredentialRefresher(refresher) {
+        this.credentialRefresher = refresher;
+    }
+    /**
+     * Re-mint the short-lived access credential and push it into the credential
+     * source, reporting a tri-state outcome the {@link ConnectionManager} maps to
+     * its FSM. The contract mirrors `getToken` (and PowerSync's `fetchCredentials`
+     * / Liveblocks' `authEndpoint`, but made explicit instead of overloading
+     * return/throw):
+     *   - token string  → `'refreshed'`     (fresh key in place; re-probe & reconnect)
+     *   - `null`        → `'session_error'` (login itself is gone → terminal, sign out)
+     *   - throw         → `'network_error'` (couldn't reach the mint endpoint → transient)
+     *
+     * SINGLE-FLIGHT: concurrent callers (a wake nudge, an in-flight request, the
+     * probe) share one in-flight promise so we never double-mint — the canonical
+     * fix for the "every 401 mints a token → thrash → spurious logout" anti-pattern.
+     *
+     * No refresher wired ⇒ `'refreshed'` (a no-op re-probe): a static-`apiKey`
+     * deployment has no session to re-mint from; its credential source refreshes
+     * out-of-band, so we just re-probe with whatever it currently holds.
+     */
+    async performCredentialRefresh() {
+        const refresher = this.credentialRefresher;
+        if (!refresher)
+            return 'refreshed';
+        if (this.inFlightCredentialRefresh)
+            return this.inFlightCredentialRefresh;
+        const run = (async () => {
+            try {
+                const token = await refresher();
+                if (!token) {
+                    // null = the long-lived login is gone (mint endpoint answered 401/403).
+                    // Terminal — the FSM routes this to sign-out.
+                    return 'session_error';
+                }
+                this.auth?.setAuthToken(token);
+                return 'refreshed';
+            }
+            catch (error) {
+                // A throw = transient (offline / mint endpoint unreachable / 5xx). The
+                // login may be perfectly valid; never sign out for this — back off and
+                // retry. Mirrors the `getToken` throw-vs-null contract end-to-end.
+                getContext().logger.warn('[BaseSyncedStore] Access-credential re-mint failed (transient)', {
+                    error: error?.message,
+                });
+                return 'network_error';
+            }
+        })();
+        this.inFlightCredentialRefresh = run;
+        try {
+            return await run;
+        }
+        finally {
+            this.inFlightCredentialRefresh = null;
+        }
+    }
+    /**
+     * Nudge the connection FSM to re-probe with the current credential. Idempotent
+     * and safe in any state (ignored while `connected`). Call after pushing a
+     * freshly-minted token via `setAuthToken`, or on an OS-wake signal, so a
+     * connection parked in `offline` / `backoff` / `auth_blocked` picks the new
+     * credential up immediately instead of waiting for the 30s watchdog.
+     */
+    nudgeReconnect() {
+        this.connectionManager?.send({ type: 'CREDENTIAL_REFRESHED' });
+    }
+    /**
+     * Install the access-credential lifecycle the CLIENT owns (this used to live
+     * in the React provider — wrong layer). Two parts:
+     *   1. REACTIVE — register `getToken` as the re-mint hook the FSM calls when a
+     *      probe finds the key stale (`credential_stale`) or on a nudge.
+     *   2. PROACTIVE — keep the short-lived key fresh ahead of trouble: a refresh
+     *      timer inside the TTL, plus re-mint on OS wake / network-online / tab
+     *      focus. Browser-only triggers are env-gated, so Node/agent hosts get
+     *      only the timer (a no-op there — agents use a static `apiKey`, no
+     *      resolver, so this is never called for them).
+     *
+     * Config-driven and invisible, like Supabase's `autoRefreshToken` — consumers
+     * never call a refresh method. Idempotent (a second call replaces the first);
+     * torn down on {@link disconnect}.
+     */
+    startCredentialLifecycle(getToken) {
+        this.stopCredentialLifecycle();
+        this.setCredentialRefresher(getToken);
+        // A transient failure is swallowed: the engine keeps its current token and
+        // the next trigger — or the reactive `credential_stale` path — retries. We
+        // never tear down or sign out on a failed proactive roll.
+        const refresh = async () => {
+            try {
+                const token = await getToken();
+                if (token) {
+                    // Push into the shared credential source (read lazily by bootstrap
+                    // HTTP, probes, and the WS reconnect URL), then nudge a parked
+                    // connection to re-probe with the fresh key. Same two steps the
+                    // engine's `setAuthToken` wrapper performs.
+                    this.auth?.setAuthToken(token);
+                    this.nudgeReconnect();
+                }
+            }
+            catch {
+                // transient (offline / mint hiccup) — a later trigger retries.
+            }
+        };
+        // Comfortably inside the 15m `ek_` TTL; a missed (background-throttled) tick
+        // is recovered by the next, or by the reactive probe.
+        const REFRESH_INTERVAL_MS = 10 * 60 * 1000;
+        const timer = setInterval(() => void refresh(), REFRESH_INTERVAL_MS);
+        const teardowns = [() => clearInterval(timer)];
+        if (typeof window !== 'undefined') {
+            const onTrigger = () => void refresh();
+            window.addEventListener('online', onTrigger);
+            // OS-wake: the desktop shell bridges Electron `powerMonitor` 'resume' to
+            // this DOM event (visibilitychange does NOT fire on wake-from-sleep, so a
+            // nap longer than the TTL would otherwise leave a dead key untouched).
+            window.addEventListener('ablo:wake', onTrigger);
+            teardowns.push(() => window.removeEventListener('online', onTrigger));
+            teardowns.push(() => window.removeEventListener('ablo:wake', onTrigger));
+        }
+        if (typeof document !== 'undefined') {
+            const onVisible = () => {
+                if (document.visibilityState === 'visible')
+                    void refresh();
+            };
+            document.addEventListener('visibilitychange', onVisible);
+            teardowns.push(() => document.removeEventListener('visibilitychange', onVisible));
+        }
+        this.credentialLifecycleTeardown = () => {
+            for (const t of teardowns)
+                t();
+        };
+    }
+    /** Tear down the proactive credential lifecycle (idempotent). */
+    stopCredentialLifecycle() {
+        this.credentialLifecycleTeardown?.();
+        this.credentialLifecycleTeardown = null;
+    }
     // ── Sync Group Management ────────────────────────────────────────────────
     /**
      * Handle an actionType 'G' delta.
@@ -970,10 +1153,14 @@ export class BaseSyncedStore {
     createConnectionManager(kind) {
         if (kind === 'agent')
             return null;
-        return new ConnectionManager({ baseUrl: this._syncServerUrl });
+        return new ConnectionManager({
+            baseUrl: this._syncServerUrl,
+            getAuthToken: () => this.auth?.getAuthToken() ?? this.syncWebSocket?.getAuthToken() ?? null,
+        });
     }
     /** Disconnect and clean up all resources */
     async disconnect() {
+        this.stopCredentialLifecycle();
         if (this.batchTimer) {
             clearTimeout(this.batchTimer);
             this.batchTimer = null;
@@ -1099,6 +1286,7 @@ export class BaseSyncedStore {
             versions: this.versionVector,
             kind: context.kind,
             capabilityToken: context.capabilityToken,
+            getAuthToken: this.auth?.getAuthToken,
             capabilities: {
                 partialBootstrap: true,
                 compressedDeltas: true,
@@ -1217,6 +1405,7 @@ export class BaseSyncedStore {
             };
             manager.start({
                 onReconnect: () => this.performReconnect(),
+                onRefreshCredential: () => this.performCredentialRefresh(),
                 onSessionExpired: () => {
                     const err = new SyncSessionError('Session expired');
                     for (const listener of this.sessionErrorListeners) {
@@ -1253,10 +1442,13 @@ export class BaseSyncedStore {
                             }
                             break;
                         case 'probing_network':
+                        case 'refreshing_credential':
                         case 'reconnecting':
                         case 'backoff':
                             // Active recovery — the UI should reflect that the FSM
-                            // is doing work, not that we've given up.
+                            // is doing work, not that we've given up. (Re-minting a stale
+                            // access key is just another recovery step, surfaced the same
+                            // way; the user never sees a credential-level distinction.)
                             if (this.syncStatus.state !== 'reconnecting') {
                                 this.updateSyncStatus({ state: 'reconnecting' });
                             }

package/dist/Model.d.ts

@@ -212,10 +212,52 @@ export declare abstract class Model {
      * Prepare unarchive operation
      */
     prepareUnarchive(): ModelChanges;
+    /**
+     * Safely assign each field of `data` onto this instance, skipping `id`,
+     * unknown keys, MobX computed accessors, and getter-only (read-only)
+     * properties, and coercing date fields. Shared by `updateFromData`
+     * (hydration) and `applyChanges` (local user update).
+     *
+     * Change tracking is EXPLICIT, not magic: for every field actually
+     * written, `onWrite(key, oldValue, newValue)` is invoked with the value
+     * captured immediately before assignment. `applyChanges` passes a hook
+     * that records the change in `modifiedProperties`; `updateFromData`
+     * passes none (hydration must not generate outbound mutations). This
+     * is the single source of mutation tracking now that the `mobx-setup`
+     * `observe()` bridge has been removed (one write path: the SDK proxy).
+     */
+    private assignFieldsFromData;
     /**
      * Update from raw data (hydration)
+     *
+     * Used for inbound server deltas and pool upserts. Change tracking is
+     * deliberately suppressed: hydration writes must NOT land in
+     * `modifiedProperties`, otherwise applying a server delta would queue a
+     * brand-new outbound mutation and the record would echo forever. For a
+     * LOCAL user edit, use `applyChanges` instead.
+     *
+     * Suppression is belt-and-suspenders: we pass no `onWrite` hook AND
+     * clear/restore `modifiedProperties` around the assignment, so any
+     * remaining `mobx-setup` `observe()` side-channel writes are discarded
+     * too. (The clear/restore is a harmless no-op once that bridge is gone.)
      */
     updateFromData(data: ModelData): void;
+    /**
+     * Apply a LOCAL user-initiated update from a data object — the write
+     * path for `proxy.update({ id, data })`, which is the ONE AND ONLY way
+     * application code mutates synced fields.
+     *
+     * Unlike `updateFromData` (hydration, untracked), this records every
+     * written field in `modifiedProperties` via `propertyChanged`, so
+     * `getChanges()` / the transaction queue send the edited fields to the
+     * server and the undo system gets a correct pre-write baseline.
+     * Recording is EXPLICIT here (via the `onWrite` hook) — it does not rely
+     * on any MobX `observe()` side-channel.
+     *
+     * `_originalData` is intentionally NOT reset here: it stays as the
+     * last-persisted baseline until `clearChanges()` runs on sync-ack.
+     */
+    applyChanges(data: ModelData): void;
     /**
      * Serialize to JSON
      * This method should not trigger MobX reactions since it's used for serialization