@abloatai/ablo 0.11.1 → 0.12.0

package/dist/react/index.d.ts

@@ -2,11 +2,14 @@
  * @abloatai/ablo/react — React bindings (v0.3.0)
  *
  * Umbrella provider:
- *   <AbloProvider schema={...} userId={...} orgId={...} fallback={<Skeleton/>}>
- *     — owns sync engine + multiplayer lifecycle; the `fallback` prop
+ *   const ablo = Ablo({ schema, apiKey })   // build once — module scope or useMemo
+ *   <AbloProvider client={ablo} fallback={<Skeleton/>}>
+ *     — `client` is the only required prop (construct it yourself; the provider
+ *     is the thin reactive binding, like `<Elements stripe={...}>`). `userId`
+ *     is optional + informational. Owns sync engine + multiplayer lifecycle;
+ *     the `fallback` prop
  *     gates children on first bootstrap. Pass `fallback="passthrough"`
  *     to disable the gate.
- *   <SyncGroupProvider id="matter:...">         — per-entity scope
  *   <ClientSideSuspense fallback={<Skeleton/>}> — NESTED gate inside an
  *     already-ready provider. Use only when you need a separate gate
  *     for a heavy subtree (e.g. a canvas) while app chrome renders
@@ -28,9 +31,7 @@
  *
  * Multiplayer (always available — `<AbloProvider>` always constructs a client):
  *   useAblo((ablo) => ablo.<model>.claim.state(...)) — reactive coordination reads
- *   useParticipant({ scope }) — join multiplayer for a scope, get peers/claims
- *   usePresence()             — typed presence view
- *   useClaim(name)           — typed claim dispatcher
+ *   useWatch({ scope }) — join multiplayer for a scope, get peers/claims
  *
  * ── Breaking changes from v0.2.x ───────────────────────────────────
  * Removed: <SyncProvider>, SyncContext, useSyncContext — folded into
@@ -44,8 +45,7 @@
  *   migration notes in CHANGELOG.md.
  */
 export type { DefaultSyncShape, ResolveSchema, ResolvePresence, ResolveClaims, ResolveUserMeta, ResolveModelKey, } from '../types/global.js';
-export { AbloProvider, useParticipant, usePeers, useSync, useSyncStore, type AbloProviderProps, type ParticipantScope, type ParticipantStatus, type UseParticipantOptions, type UseParticipantReturn, type MeshParticipantStatus, } from './AbloProvider.js';
-export { SyncGroupProvider, useSyncGroup, type SyncGroupProviderProps, } from './SyncGroupProvider.js';
+export { AbloProvider, useWatch, usePeers, useSync, useSyncStore, type AbloProviderProps, type ParticipantScope, type ParticipantStatus, type UseWatchOptions, type UseWatchReturn, type MeshParticipantStatus, } from './AbloProvider.js';
 export { ClientSideSuspense, type ClientSideSuspenseProps, } from './ClientSideSuspense.js';
 export { DefaultFallback } from './DefaultFallback.js';
 export type { SyncStoreContract } from './context.js';
@@ -59,6 +59,4 @@ export type { ReaderActions, ReaderFindOptions } from '../mutators/readerActions
 export { useMutators, type MutatorInvokers, type InvokerFor, type UseMutatorsOptions, } from './useMutators.js';
 export { useUndoScope, type UseUndoScopeResult } from './useUndoScope.js';
 export { useAblo, type UseAbloHydratedModelResult, type UseAbloModelOptions, type UseAbloModelResult, } from './useAblo.js';
-export { usePresence } from './usePresence.js';
-export { useClaim } from './useClaim.js';
 export { ModelScope } from '../types/index.js';

package/dist/react/index.js

@@ -2,11 +2,14 @@
  * @abloatai/ablo/react — React bindings (v0.3.0)
  *
  * Umbrella provider:
- *   <AbloProvider schema={...} userId={...} orgId={...} fallback={<Skeleton/>}>
- *     — owns sync engine + multiplayer lifecycle; the `fallback` prop
+ *   const ablo = Ablo({ schema, apiKey })   // build once — module scope or useMemo
+ *   <AbloProvider client={ablo} fallback={<Skeleton/>}>
+ *     — `client` is the only required prop (construct it yourself; the provider
+ *     is the thin reactive binding, like `<Elements stripe={...}>`). `userId`
+ *     is optional + informational. Owns sync engine + multiplayer lifecycle;
+ *     the `fallback` prop
  *     gates children on first bootstrap. Pass `fallback="passthrough"`
  *     to disable the gate.
- *   <SyncGroupProvider id="matter:...">         — per-entity scope
  *   <ClientSideSuspense fallback={<Skeleton/>}> — NESTED gate inside an
  *     already-ready provider. Use only when you need a separate gate
  *     for a heavy subtree (e.g. a canvas) while app chrome renders
@@ -28,9 +31,7 @@
  *
  * Multiplayer (always available — `<AbloProvider>` always constructs a client):
  *   useAblo((ablo) => ablo.<model>.claim.state(...)) — reactive coordination reads
- *   useParticipant({ scope }) — join multiplayer for a scope, get peers/claims
- *   usePresence()             — typed presence view
- *   useClaim(name)           — typed claim dispatcher
+ *   useWatch({ scope }) — join multiplayer for a scope, get peers/claims
  *
  * ── Breaking changes from v0.2.x ───────────────────────────────────
  * Removed: <SyncProvider>, SyncContext, useSyncContext — folded into
@@ -44,8 +45,7 @@
  *   migration notes in CHANGELOG.md.
  */
 // ── Umbrella provider + lifecycle hooks ────────────────────────────
-export { AbloProvider, useParticipant, usePeers, useSync, useSyncStore, } from './AbloProvider.js';
-export { SyncGroupProvider, useSyncGroup, } from './SyncGroupProvider.js';
+export { AbloProvider, useWatch, usePeers, useSync, useSyncStore, } from './AbloProvider.js';
 export { ClientSideSuspense, } from './ClientSideSuspense.js';
 export { DefaultFallback } from './DefaultFallback.js';
 // ── Status + errors + identity ─────────────────────────────────────
@@ -63,8 +63,5 @@ export { useReactive } from './useReactive.js';
 export { useMutators, } from './useMutators.js';
 export { useUndoScope } from './useUndoScope.js';
 export { useAblo, } from './useAblo.js';
-// ── Presence + claim (typed via Register module augmentation) ─────
-export { usePresence } from './usePresence.js';
-export { useClaim } from './useClaim.js';
 // ── ModelScope re-export ───────────────────────────────────────────
 export { ModelScope } from '../types/index.js';

package/dist/react/useMutators.js

@@ -17,8 +17,9 @@ export function useMutators(schemaOrMutators, mutatorsOrOptions, maybeOptions) {
     const mutators = (isExplicit ? mutatorsOrOptions : schemaOrMutators);
     const options = (isExplicit ? maybeOptions : mutatorsOrOptions);
     if (!schema) {
-        throw new AbloValidationError('useMutators: no schema available. Pass the schema as the first arg ' +
-            'or wire SyncProvider with a `schema` prop when using the zero-arg overload.', { code: 'mutators_schema_missing' });
+        throw new AbloValidationError('useMutators: no schema available. Pass the schema as the first arg, ' +
+            'or build the <AbloProvider> above with `Ablo({ schema })` so the ' +
+            'zero-arg overload can read it from context.', { code: 'mutators_schema_missing' });
     }
     const { undoScope } = options ?? {};
     return useMemo(() => {

package/dist/react/useSyncStatus.d.ts

@@ -17,7 +17,7 @@
  *    `reason` carries the human-readable close reason when available.
  * - `disconnected` — network failure, server error, or the retry loop
  *    gave up. Show the offline / error UI.
- * - `needs-auth` — server rejected the session (1008/4001/4003). The
+ * - `needs-auth` — server rejected the auth token (1008/4001/4003). The
  *    consumer's `onSessionExpired` callback has already been invoked
  *    by `<AbloProvider>`; this variant exists for UI that wants to
  *    reflect the auth state itself.

package/dist/react/useUndoScope.js

@@ -34,8 +34,9 @@ export function useUndoScope(schemaOrName, nameOrOptions, maybeOptions) {
     const name = isExplicit ? nameOrOptions : schemaOrName;
     const options = (isExplicit ? maybeOptions : nameOrOptions);
     if (!schema) {
-        throw new AbloValidationError('useUndoScope: no schema available. Pass the schema as the first arg ' +
-            'or wire SyncProvider with a `schema` prop when using the zero-arg overload.', { code: 'undo_scope_schema_missing' });
+        throw new AbloValidationError('useUndoScope: no schema available. Pass the schema as the first arg, ' +
+            'or build the <AbloProvider> above with `Ablo({ schema })` so the ' +
+            'zero-arg overload can read it from context.', { code: 'undo_scope_schema_missing' });
     }
     const scope = useMemo(() => {
         // Store is the identity for the manager — one per SyncProvider.

package/dist/realtime/index.d.ts

@@ -5,6 +5,6 @@
  * subscriptions, presence, offline queueing, and a long-lived WebSocket.
  */
 export { Ablo, computeFKDepthPriority } from '../client/Ablo.js';
-export type { AbloOptions, InternalAbloOptions, ModelCountOptions, ModelListOptions, ModelListScope, ModelLoadOptions, ModelOperations, } from '../client/Ablo.js';
+export type { AbloOptions, InternalAbloOptions, LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelOperations, } from '../client/Ablo.js';
 import { Ablo } from '../client/Ablo.js';
 export default Ablo;

package/dist/schema/generate.js

@@ -14,8 +14,7 @@
  * unions). Relations are resolved by the runtime SDK's typed accessors and are
  * not expanded here.
  */
-/** The base columns every model carries (mirrors `baseFieldsSchema`). */
-const BASE_FIELDS = ['id', 'createdAt', 'updatedAt', 'organizationId', 'createdBy'];
+import { BASE_FIELDS } from './schema.js';
 function tsType(meta) {
     switch (meta.type) {
         case 'string':

package/dist/schema/model.d.ts

@@ -95,9 +95,16 @@ export interface ModelOptions {
      */
     tableName?: string;
     /**
-     * Whether this model's table has an organization_id column.
-     * Default: true. When false, the bootstrap query omits the
-     * `WHERE organization_id = $1` clause for this model.
+     * Whether this model's table has an `organization_id` column. Default: true.
+     * When false, the bootstrap/read query omits the `WHERE organization_id = $1`
+     * tenant filter for this model.
+     *
+     * ⚠ SECURITY — `orgScoped: false` makes the table GLOBALLY READABLE: every
+     * client of every tenant sees every row. It is ONLY correct for genuinely
+     * tenant-less tables (the `organizations` table itself, global lookups). If
+     * rows belong to a tenant through a foreign key but this table has no
+     * `organization_id` of its own, use {@link scopedVia} INSTEAD — reaching for
+     * `orgScoped: false` there silently exposes the entire table cross-tenant.
      */
     orgScoped?: boolean;
     /**

package/dist/schema/schema.d.ts

@@ -78,6 +78,15 @@ export declare const baseFieldsSchema: z.ZodObject<{
     organizationId: z.ZodOptional<z.ZodString>;
     createdBy: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+/**
+ * The base-column names every model carries automatically (the keys of
+ * {@link baseFieldsSchema}). The single source of truth — `generate.ts`
+ * imports this to avoid double-emitting a redeclared base column, and the
+ * `defineSchema` field loop uses it to reject a model that tries to redeclare
+ * one (Zod `.merge` would otherwise silently overwrite the base field with the
+ * user's, producing a `string & Date` type that breaks the build).
+ */
+export declare const BASE_FIELDS: readonly ["id", "createdAt", "updatedAt", "organizationId", "createdBy"];
 /** The base fields type — pure data columns. */
 export type BaseModelFields = z.infer<typeof baseFieldsSchema>;
 /**
@@ -138,7 +147,8 @@ export type Model<A, B = never> = [B] extends [never] ? A extends keyof Register
  * Drizzle deprecated its own `InferModel` for the same reason. Kept as an
  * alias; no behavior difference.
  */
-export type InferModel<S extends Schema, ModelName extends keyof S['models']> = S['models'][ModelName] extends ModelDef<infer Shape, infer R, infer C> ? z.infer<z.ZodObject<Shape>> & BaseModelFields & BaseModelMethods & InferComputed<C> & InferRelations<S, R> : never;
+export type InferModel<S extends Schema, ModelName extends keyof S['models']> = S['models'][ModelName] extends ModelDef<infer Shape, infer R, infer C> ? // `Omit<…, keyof BaseModelFields>` so a model that (wrongly) redeclares a
+Omit<z.infer<z.ZodObject<Shape>>, keyof BaseModelFields> & BaseModelFields & BaseModelMethods & InferComputed<C> & InferRelations<S, R> : never;
 /**
  * Infer relation accessor types from a model's relations record.
  *
@@ -184,7 +194,8 @@ export type InferComputed<C> = string extends keyof C ? unknown : {
  * // createdAt, updatedAt are NOT accepted — they're auto-generated
  * ```
  */
-export type InferCreate<S extends Schema, ModelName extends keyof S['models']> = S['models'][ModelName] extends ModelDef<infer Shape> ? z.input<z.ZodObject<Shape>> & Partial<BaseModelFields> : never;
+export type InferCreate<S extends Schema, ModelName extends keyof S['models']> = S['models'][ModelName] extends ModelDef<infer Shape> ? // Same reserved-field guard as InferModel: drop any (wrongly) redeclared
+Omit<z.input<z.ZodObject<Shape>>, keyof BaseModelFields> & Partial<BaseModelFields> : never;
 /**
  * Extract all model names from a schema.
  */

package/dist/schema/schema.js

@@ -58,6 +58,21 @@ export const baseFieldsSchema = z.object({
     organizationId: z.string().optional(),
     createdBy: z.string().optional(),
 });
+/**
+ * The base-column names every model carries automatically (the keys of
+ * {@link baseFieldsSchema}). The single source of truth — `generate.ts`
+ * imports this to avoid double-emitting a redeclared base column, and the
+ * `defineSchema` field loop uses it to reject a model that tries to redeclare
+ * one (Zod `.merge` would otherwise silently overwrite the base field with the
+ * user's, producing a `string & Date` type that breaks the build).
+ */
+export const BASE_FIELDS = [
+    'id',
+    'createdAt',
+    'updatedAt',
+    'organizationId',
+    'createdBy',
+];
 // ── Factory ───────────────────────────────────────────────────────────────
 /**
  * Define a sync engine schema.
@@ -146,6 +161,17 @@ export function defineSchema(models, options) {
         // failure immediate and unambiguous.
         for (const fieldName of Object.keys(def.shape)) {
             assertRoundTrippableCamelCase(name, fieldName);
+            // Reserved base columns are merged in below via `baseFieldsSchema.merge`,
+            // and Zod `.merge` silently OVERWRITES the base field with the user's —
+            // e.g. a model declaring `createdAt: z.string()` ends up with a field
+            // typed `string & Date`, which breaks the build. Reject the collision at
+            // definition time so the author sees an unambiguous error instead.
+            if (BASE_FIELDS.includes(fieldName)) {
+                throw new AbloValidationError(`[defineSchema] ${name}.${fieldName}: field \`${fieldName}\` collides with a ` +
+                    `reserved field that the SDK provides automatically ` +
+                    `(${BASE_FIELDS.join(', ')}). Remove it from your model — redeclaring it ` +
+                    `produces a \`string & Date\` type and breaks the build.`, { code: 'schema_reserved_field', param: `${name}.${fieldName}` });
+            }
         }
         validators[name] = baseFieldsSchema.merge(def.schema);
         // Resolve every relation's `foreignKeyColumn` once, now. The builder

package/dist/surface.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Machine-checked public API-surface manifest — the SDK owns the description of
+ * its OWN surface, bound to the real exported types at COMPILE TIME so the MCP
+ * `get_api_surface` / docs can never drift from reality.
+ *
+ * This exists because the hand-authored surface (apps/sync-web/.../api-surface.ts)
+ * once named `load` / `count` / `scope` — verbs/options that don't exist — with no
+ * coupling to the code. The fix: the name lists live HERE, next to the types, and
+ * each is proven EXACTLY equal to the keys of its source interface via
+ * `Expect<Equal<…>>`. Add or remove a verb/option without updating the matching
+ * tuple and THIS FILE FAILS TO COMPILE (the `Equal` constraint is checked eagerly
+ * at the alias declaration — both directions: no phantom name, no missing name).
+ *
+ * Consumers (the MCP `get_api_surface`) import these NAME tuples and build their
+ * prose from them, so a summary can never reference a verb that doesn't exist.
+ * NAMES are guaranteed; descriptions stay hand-written (prose can't be type-checked).
+ */
+/** Every method on `ablo.<model>` (the stateful `ModelOperations`). The single
+ *  source of truth for the model-verb names the docs/MCP may describe. */
+export declare const PUBLIC_MODEL_VERBS: readonly ["retrieve", "list", "get", "getAll", "getCount", "create", "update", "delete", "claim", "watch", "onChange"];
+/** Keys accepted by `list`/`getAll`/`onChange` options (`LocalReadOptions`).
+ *  Note `state` (lifecycle filter) — NOT `scope` (a historic doc drift). */
+export declare const PUBLIC_LIST_OPTION_KEYS: readonly ["where", "filter", "orderBy", "limit", "offset", "state"];
+/** Public keys of `AbloOptions`. `schema` is required; the rest are optional
+ *  (the locked happy path is `Ablo({ schema, apiKey, databaseUrl, transport })`). */
+export declare const PUBLIC_ABLO_OPTION_KEYS: readonly ["schema", "apiKey", "databaseUrl", "persistence", "transport", "authToken", "baseURL", "fetch", "defaultHeaders", "defaultQuery", "dangerouslyAllowBrowser"];
+export type ModelVerb = (typeof PUBLIC_MODEL_VERBS)[number];
+export type ListOptionKey = (typeof PUBLIC_LIST_OPTION_KEYS)[number];
+export type AbloOptionKey = (typeof PUBLIC_ABLO_OPTION_KEYS)[number];

package/dist/surface.js

@@ -0,0 +1,60 @@
+/**
+ * Machine-checked public API-surface manifest — the SDK owns the description of
+ * its OWN surface, bound to the real exported types at COMPILE TIME so the MCP
+ * `get_api_surface` / docs can never drift from reality.
+ *
+ * This exists because the hand-authored surface (apps/sync-web/.../api-surface.ts)
+ * once named `load` / `count` / `scope` — verbs/options that don't exist — with no
+ * coupling to the code. The fix: the name lists live HERE, next to the types, and
+ * each is proven EXACTLY equal to the keys of its source interface via
+ * `Expect<Equal<…>>`. Add or remove a verb/option without updating the matching
+ * tuple and THIS FILE FAILS TO COMPILE (the `Equal` constraint is checked eagerly
+ * at the alias declaration — both directions: no phantom name, no missing name).
+ *
+ * Consumers (the MCP `get_api_surface`) import these NAME tuples and build their
+ * prose from them, so a summary can never reference a verb that doesn't exist.
+ * NAMES are guaranteed; descriptions stay hand-written (prose can't be type-checked).
+ */
+// ── the per-`ablo.<model>` verb surface ────────────────────────────────────
+/** Every method on `ablo.<model>` (the stateful `ModelOperations`). The single
+ *  source of truth for the model-verb names the docs/MCP may describe. */
+export const PUBLIC_MODEL_VERBS = [
+    'retrieve',
+    'list',
+    'get',
+    'getAll',
+    'getCount',
+    'create',
+    'update',
+    'delete',
+    'claim',
+    'watch',
+    'onChange',
+];
+// ── the read/list query option surface ─────────────────────────────────────
+/** Keys accepted by `list`/`getAll`/`onChange` options (`LocalReadOptions`).
+ *  Note `state` (lifecycle filter) — NOT `scope` (a historic doc drift). */
+export const PUBLIC_LIST_OPTION_KEYS = [
+    'where',
+    'filter',
+    'orderBy',
+    'limit',
+    'offset',
+    'state',
+];
+// ── the `Ablo({ … })` constructor option surface ───────────────────────────
+/** Public keys of `AbloOptions`. `schema` is required; the rest are optional
+ *  (the locked happy path is `Ablo({ schema, apiKey, databaseUrl, transport })`). */
+export const PUBLIC_ABLO_OPTION_KEYS = [
+    'schema',
+    'apiKey',
+    'databaseUrl',
+    'persistence',
+    'transport',
+    'authToken',
+    'baseURL',
+    'fetch',
+    'defaultHeaders',
+    'defaultQuery',
+    'dangerouslyAllowBrowser',
+];

package/dist/sync/ConnectionManager.d.ts

@@ -20,18 +20,29 @@
  * Designed to be embedded by `BaseSyncedStore`: one instance per store,
  * started on first successful connect, disposed on teardown.
  *
- *   CONNECTED ──► OFFLINE ──► PROBING_NETWORK ──► RECONNECTING ──► CONNECTED
- *                    │              │                    │
- *                    ▼              ▼                    ▼
- *             WAITING_FOR_NETWORK  SESSION_EXPIRED    BACKOFF ──► PROBING_NETWORK
+ *   CONNECTED ──(socket drop)──► PROBING_NETWORK ──► RECONNECTING ──► CONNECTED
+ *        │                              │                  │
+ *   (network lost)                      ▼                  ▼
+ *        ▼                        SESSION_EXPIRED       BACKOFF ──► PROBING_NETWORK
+ *     OFFLINE ──(online)──► PROBING_NETWORK
+ *        │
+ *        ▼
+ *   WAITING_FOR_NETWORK
  *
- * Includes two fixes over the original app-side FSM:
+ * Includes three fixes over the original app-side FSM:
  *   1. `backoff` accepts `NETWORK_ONLINE` / `TAB_VISIBLE` — jumps to
  *      probing immediately when the network comes back, without
  *      waiting for the backoff timer to elapse.
  *   2. `scheduleBackoff` parks in `waiting_for_network` (resetting
  *      `attempt`) when `navigator.onLine === false` at max retries,
  *      instead of hard-reloading an already-offline browser.
+ *   3. A socket drop (`WS_DISCONNECTED`, typically code 1006) goes
+ *      STRAIGHT to `probing_network`, not the passive `offline` state.
+ *      1006 is browser-local and carries no connectivity signal, so on a
+ *      healthy machine no `online`/`offline` event ever fires — parking in
+ *      `offline` stranded recovery until the 30s watchdog, long enough for
+ *      queued commits to roll back. Only a genuine OS-level `NETWORK_LOST`
+ *      parks in `offline` and waits for the `online` event.
  */
 import { type ProbeResult } from './NetworkProbe.js';
 import type { AuthTokenGetter } from '../auth/credentialSource.js';

package/dist/sync/ConnectionManager.js

@@ -20,18 +20,29 @@
  * Designed to be embedded by `BaseSyncedStore`: one instance per store,
  * started on first successful connect, disposed on teardown.
  *
- *   CONNECTED ──► OFFLINE ──► PROBING_NETWORK ──► RECONNECTING ──► CONNECTED
- *                    │              │                    │
- *                    ▼              ▼                    ▼
- *             WAITING_FOR_NETWORK  SESSION_EXPIRED    BACKOFF ──► PROBING_NETWORK
+ *   CONNECTED ──(socket drop)──► PROBING_NETWORK ──► RECONNECTING ──► CONNECTED
+ *        │                              │                  │
+ *   (network lost)                      ▼                  ▼
+ *        ▼                        SESSION_EXPIRED       BACKOFF ──► PROBING_NETWORK
+ *     OFFLINE ──(online)──► PROBING_NETWORK
+ *        │
+ *        ▼
+ *   WAITING_FOR_NETWORK
  *
- * Includes two fixes over the original app-side FSM:
+ * Includes three fixes over the original app-side FSM:
  *   1. `backoff` accepts `NETWORK_ONLINE` / `TAB_VISIBLE` — jumps to
  *      probing immediately when the network comes back, without
  *      waiting for the backoff timer to elapse.
  *   2. `scheduleBackoff` parks in `waiting_for_network` (resetting
  *      `attempt`) when `navigator.onLine === false` at max retries,
  *      instead of hard-reloading an already-offline browser.
+ *   3. A socket drop (`WS_DISCONNECTED`, typically code 1006) goes
+ *      STRAIGHT to `probing_network`, not the passive `offline` state.
+ *      1006 is browser-local and carries no connectivity signal, so on a
+ *      healthy machine no `online`/`offline` event ever fires — parking in
+ *      `offline` stranded recovery until the 30s watchdog, long enough for
+ *      queued commits to roll back. Only a genuine OS-level `NETWORK_LOST`
+ *      parks in `offline` and waits for the `online` event.
  */
 import { makeAutoObservable, runInAction } from 'mobx';
 import { getContext } from '../context.js';
@@ -142,8 +153,19 @@ export class ConnectionManager {
             case 'connected':
                 switch (event.type) {
                     case 'NETWORK_LOST':
-                    case 'WS_DISCONNECTED':
+                        // The OS reported the NIC down — park passively in `offline` and
+                        // wait for the `online` event. Probing a downed adapter is wasted
+                        // work.
                         return 'offline';
+                    case 'WS_DISCONNECTED':
+                        // The socket died (typically code 1006) but the OS network is
+                        // almost certainly fine — 1006 is generated locally when the TCP
+                        // conn vanishes and carries NO connectivity signal, so the browser
+                        // fires no online/offline event. Probe IMMEDIATELY rather than
+                        // landing in the passive `offline` dead-end (which only escaped via
+                        // the 30s watchdog, long after queued commits rolled back). The
+                        // probe fast-fails if we genuinely ARE offline → waiting_for_network.
+                        return 'probing_network';
                     case 'WS_SESSION_ERROR':
                     case 'BOOTSTRAP_FAILED_SESSION':
                         return 'session_expired';
@@ -301,7 +323,7 @@ export class ConnectionManager {
         }
     }
     // ── Side effects per state ───────────────────────────────────────────
-    onEnterState(state, _event) {
+    onEnterState(state, event) {
         switch (state) {
             case 'connected':
                 this.clearBackoffTimer();
@@ -314,6 +336,19 @@ export class ConnectionManager {
                 this.callbacks?.onDisconnectWebSocket();
                 break;
             case 'probing_network':
+                // A socket drop (`WS_DISCONNECTED`) now lands here directly so recovery
+                // starts immediately. Tear the dead socket down FIRST — this is what
+                // sets SyncWebSocket's `isManualClose=true` and suppresses its own
+                // scheduleReconnect, keeping the FSM the single reconnect authority on
+                // the human path. The teardown runs synchronously inside the
+                // `disconnected` emit, before `SyncWebSocket.onclose` checks the flag,
+                // so the timing matches the previous `offline`-entry teardown. We gate
+                // on the drop event specifically: the other paths into `probing_network`
+                // (TAB_VISIBLE re-validation, handshake retry, backoff elapse) must NOT
+                // tear down a socket that may still be live.
+                if (event.type === 'WS_DISCONNECTED') {
+                    this.callbacks?.onDisconnectWebSocket();
+                }
                 this.runProbe();
                 break;
             case 'waiting_for_network':

package/dist/sync/createClaimStream.js

@@ -192,7 +192,8 @@ export function createClaimStream(config, transport = null) {
                 entityId: claim.entityId,
                 path: claim.path,
                 range: claim.range,
-                action: claim.action,
+                // Wire field stays `action` (coordination schema); source is `reason`.
+                action: claim.reason,
                 field: claim.field,
                 meta: claim.meta,
                 estimatedMs: claim.estimatedMs,
@@ -244,7 +245,7 @@ export function createClaimStream(config, transport = null) {
             range: args.range,
             field: args.field,
             meta: args.meta,
-            action: args.action,
+            reason: args.reason,
             estimatedMs,
             queue: args.queue,
         };
@@ -261,7 +262,7 @@ export function createClaimStream(config, transport = null) {
         return {
             object: 'claim',
             claimId,
-            action: args.action,
+            reason: args.reason,
             target: {
                 model: args.entityType,
                 id: args.entityId,
@@ -294,7 +295,7 @@ export function createClaimStream(config, transport = null) {
                 range: resolved.range,
                 field: resolved.field,
                 meta: withDescription(resolved.meta, opts?.description),
-                action: opts?.reason ?? 'editing',
+                reason: opts?.reason ?? 'editing',
                 ttl: opts?.ttl,
                 queue: opts?.queue,
             });

package/dist/sync/participants.js

@@ -221,7 +221,7 @@ function createJoinedParticipant(args) {
         return {
             object: 'claim',
             claimId: handle.claimId,
-            action: handle.action,
+            reason: handle.reason,
             target: handle.target,
             async release() {
                 ownHandles.delete(handle);

package/dist/transactions/TransactionQueue.d.ts

@@ -427,17 +427,6 @@ export declare class TransactionQueue extends EventEmitter {
     private extractUpdateData;
     private buildUpdateInput;
     private extractPreviousData;
-    /**
-     * Re-baseline `modifiedProperties` for the fields a freshly-staged update just
-     * committed. Called right after {@link extractPreviousData} freezes their
-     * `.old` into the transaction, so the NEXT update to the same field sees this
-     * update's result as its baseline rather than the stale pre-session `.old`
-     * preserved by `Model.propertyChanged`'s first-old-wins policy. Only consumes
-     * keys present in this update — untouched fields keep their baselines. Safe
-     * because the wire payload lives on `transaction.data` and rollback restores
-     * from `transaction.previousData`; neither re-reads `modifiedProperties`.
-     */
-    private consumeModifiedFields;
     /**
      * Public API
      */

package/dist/transactions/TransactionQueue.js

@@ -780,8 +780,8 @@ export class TransactionQueue extends EventEmitter {
         // instead of THIS update's result — corrupting the stream-recorded undo
         // inverse (the second move's "before" would point all the way back). The
         // wire payload is already frozen in `transaction.data`, so dropping the
-        // consumed entries is safe. Mirrors `RecordingTransaction.consumeModifiedFields`.
-        this.consumeModifiedFields(model, updateInput);
+        // consumed entries is safe.
+        model.consumeModifiedFields(Object.keys(updateInput));
         const modelKey = normalizeModelKey(actualModelName);
         const priorityScore = this.computePriorityScore('update', actualModelName);
         const transaction = {
@@ -1999,63 +1999,19 @@ export class TransactionQueue extends EventEmitter {
     // model ever needs to surface previous-state outside `modifiedProperties`,
     // expose a typed `getPreviousData()` accessor on Model and call that.
     extractPreviousData(model, updateInput) {
-        const prev = { id: model.id };
-        const modified = model.modifiedProperties instanceof Map ? model.modifiedProperties : null;
         // When the update's written keys are known, capture a before-image for
         // EXACTLY those keys so the recorded undo inverse can revert them and only
         // them (a full-row inverse would clobber concurrent edits to unrelated
-        // fields). Resolution order mirrors `RecordingTransaction.snapshotFields`:
-        //   1. `modifiedProperties.old` — first-old-wins pre-session baseline, set
-        //      whenever the caller mutated the field in place before committing.
-        //   2. `getOriginalSnapshot()` — the last loaded/acked row, the correct
-        //      before-image for a key written WITHOUT a prior in-place mutation
-        //      (e.g. a `precomputedChanges` write).
-        // Without (2) such a key yields an empty `previousData`, and `buildUndoOps`
-        // nulls the inverse entirely — making updates silently un-undoable where a
-        // create's `delete(id)` inverse never is. This closes that asymmetry.
-        if (updateInput) {
-            const original = model.getOriginalSnapshot();
-            for (const key of Object.keys(updateInput)) {
-                if (key === 'id')
-                    continue;
-                const mod = modified?.get(key);
-                if (mod) {
-                    prev[key] = mod.old;
-                }
-                else if (original && key in original) {
-                    prev[key] = original[key];
-                }
-            }
-            return prev;
-        }
-        if (modified && modified.size > 0) {
-            for (const [key, change] of modified) {
-                prev[key] = change.old;
-            }
-        }
-        return prev;
-    }
-    /**
-     * Re-baseline `modifiedProperties` for the fields a freshly-staged update just
-     * committed. Called right after {@link extractPreviousData} freezes their
-     * `.old` into the transaction, so the NEXT update to the same field sees this
-     * update's result as its baseline rather than the stale pre-session `.old`
-     * preserved by `Model.propertyChanged`'s first-old-wins policy. Only consumes
-     * keys present in this update — untouched fields keep their baselines. Safe
-     * because the wire payload lives on `transaction.data` and rollback restores
-     * from `transaction.previousData`; neither re-reads `modifiedProperties`.
-     */
-    consumeModifiedFields(model, updateInput) {
-        if (!(model.modifiedProperties instanceof Map) || model.modifiedProperties.size === 0) {
-            return;
-        }
-        for (const key of [...model.modifiedProperties.keys()]) {
-            if (key === 'id')
-                continue;
-            if (updateInput && !(key in updateInput))
-                continue;
-            model.modifiedProperties.delete(key);
-        }
+        // fields). `fallbackToLive: false` makes `Model.capturePreviousValues` OMIT
+        // any key it can't resolve from `modifiedProperties.old` / the original
+        // snapshot — `buildUndoOps` then drops an un-revertible inverse rather than
+        // inventing one. With no `updateInput` (full extract) fall back to every
+        // tracked field. `Model.capturePreviousValues` is the single before-image
+        // source shared with `RecordingTransaction.snapshotFields`.
+        const keys = updateInput
+            ? Object.keys(updateInput)
+            : [...(model.modifiedProperties instanceof Map ? model.modifiedProperties.keys() : [])];
+        return { id: model.id, ...model.capturePreviousValues(keys, { fallbackToLive: false }) };
     }
     /**
      * Public API

package/dist/types/global.d.ts

@@ -60,6 +60,9 @@ export interface DefaultSyncShape {
  * Empty by default — every SDK resolver falls back to {@link DefaultSyncShape}
  * when an expected key is absent. Exported from the package root so the module
  * augmentation merges into this declaration.
+ *
+ * The `Schema` augmentation key holds the type produced by `defineSchema`, so
+ * the same noun reads consistently here and in {@link ResolveSchema}.
  */
 export interface Register {
 }