@abloatai/ablo 0.11.1 → 0.11.2

package/dist/errors.d.ts

@@ -186,8 +186,9 @@ export declare function formatClaimedErrorMessage(args: {
  * The target entity is currently claimed by another participant and the caller
  * asked the SDK not to read/write through that claim.
  *
- * Use `ifClaimed: 'wait'` to wait for the claim to clear, or
- * `ifClaimed: 'return'` to inspect active claims yourself.
+ * Pass `ifClaimed: 'return'` to inspect active claims yourself instead of
+ * throwing; to wait for the claim to clear, take `ablo.<model>.claim({ id })`
+ * (it queues fairly) rather than blocking the read.
  */
 export declare class AbloClaimedError extends AbloError {
     readonly type: "AbloClaimedError";

package/dist/errors.js

@@ -208,8 +208,9 @@ export function formatClaimedErrorMessage(args) {
  * The target entity is currently claimed by another participant and the caller
  * asked the SDK not to read/write through that claim.
  *
- * Use `ifClaimed: 'wait'` to wait for the claim to clear, or
- * `ifClaimed: 'return'` to inspect active claims yourself.
+ * Pass `ifClaimed: 'return'` to inspect active claims yourself instead of
+ * throwing; to wait for the claim to clear, take `ablo.<model>.claim({ id })`
+ * (it queues fairly) rather than blocking the read.
  */
 export class AbloClaimedError extends AbloError {
     type = 'AbloClaimedError';

package/dist/index.d.ts

@@ -43,7 +43,6 @@
  * Advanced — opt-in, most apps never import these (each is tagged
  * "Advanced —" at its export below, with the one situation it's for):
  *   • `dataSource` / `abloSource`  — only if your own DB stays canonical
- *   • `session` / `agent`          — only for delegated agent principals
  *   • `defaultPolicy`              — only to customize conflict resolution
  *   • `defineMutators` / `createTransaction` — only for custom mutators
  * If you don't recognize one, you don't need it — the default path covers you.
@@ -51,11 +50,10 @@
 export { Ablo } from './client/Ablo.js';
 export type { MutationExecutor } from './interfaces/index.js';
 export type { HttpClaimApi, InternalAbloOptions } from './client/Ablo.js';
-export { createAbloHttpClient, type AbloHttpClientOptions, type AbloHttpClient, type HttpModelClient, } from './client/httpClient.js';
+export { type AbloHttpClientOptions, type AbloHttpClient, type HttpModelClient, } from './client/httpClient.js';
 export { ABLO_DEFAULT_BASE_URL, ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_URL, normalizeAbloHostedBaseUrl, } from './client/auth.js';
-export type { AbloOptions, ModelCountOptions, ModelListOptions, ModelListScope, ModelLoadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, ClaimHandle, ModelOperations, } from './client/Ablo.js';
+export type { AbloOptions, LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, ClaimHandle, ModelOperations, } from './client/Ablo.js';
 export type { AbloPersistence } from './client/persistence.js';
-export { session, agent } from './principal.js';
 import { Ablo } from './client/Ablo.js';
 export default Ablo;
 export { dataSource, abloSource, sourceEventForOperation, signAbloSourceRequest, verifyAbloSourceRequest, } from './source/index.js';
@@ -70,6 +68,8 @@ export { writeOptionsSchema, onStaleModeSchema, assertWriteOptions, } from './cl
 export type { WriteOptionsInput } from './client/writeOptionsSchema.js';
 export type { WriteOptions, MutationOptions } from './interfaces/index.js';
 export { IDBOpenTimeoutError, isStorageOpenTimeout } from './core/openIDBWithTimeout.js';
+export { PUBLIC_MODEL_VERBS, PUBLIC_LIST_OPTION_KEYS, PUBLIC_ABLO_OPTION_KEYS, } from './surface.js';
+export type { ModelVerb, ListOptionKey, AbloOptionKey } from './surface.js';
 export type { Register, DefaultSyncShape } from './types/global.js';
 export { defineMutators } from './mutators/defineMutators.js';
 export { createTransaction, type Transaction } from './mutators/Transaction.js';

package/dist/index.js

@@ -43,7 +43,6 @@
  * Advanced — opt-in, most apps never import these (each is tagged
  * "Advanced —" at its export below, with the one situation it's for):
  *   • `dataSource` / `abloSource`  — only if your own DB stays canonical
- *   • `session` / `agent`          — only for delegated agent principals
  *   • `defaultPolicy`              — only to customize conflict resolution
  *   • `defineMutators` / `createTransaction` — only for custom mutators
  * If you don't recognize one, you don't need it — the default path covers you.
@@ -56,17 +55,11 @@
 // `import Ablo from '@abloatai/ablo'` works; named export so
 // `import { Ablo }` also compiles.
 export { Ablo } from './client/Ablo.js';
-export { createAbloHttpClient, } from './client/httpClient.js';
 export { ABLO_DEFAULT_BASE_URL, ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_URL, normalizeAbloHostedBaseUrl, } from './client/auth.js';
 // Participant types live under `Ablo.Participant.*` —
 // `Ablo.Participant.Joined`, `Ablo.Participant.Manager`,
 // `Ablo.Participant.JoinOptions`, etc. Same dot-access shape as
 // `Ablo.Peer`, `Ablo.Claim`. No flat re-exports.
-// Advanced — most apps never import this. Principal constructors for
-// delegated agent paths (`Ablo({ kind: 'agent', as: session({...}) })`).
-// The default `Ablo({ schema, apiKey })` resolves identity from the key;
-// reach for these only when minting a delegated agent principal.
-export { session, agent } from './principal.js';
 import { Ablo } from './client/Ablo.js';
 export default Ablo;
 // Advanced — most apps never import this. Customer-owned storage adapter
@@ -100,6 +93,10 @@ export { writeOptionsSchema, onStaleModeSchema, assertWriteOptions, } from './cl
 // Storage-wedge detection — lets app shells render a recovery screen when the
 // IndexedDB backing store is stuck (see core/openIDBWithTimeout.ts).
 export { IDBOpenTimeoutError, isStorageOpenTimeout } from './core/openIDBWithTimeout.js';
+// Machine-checked surface manifest — the SDK's own description of its public
+// verb/option names, compile-time-bound to the real types (see surface.ts).
+// The MCP `get_api_surface` imports these so docs can't name a phantom verb.
+export { PUBLIC_MODEL_VERBS, PUBLIC_LIST_OPTION_KEYS, PUBLIC_ABLO_OPTION_KEYS, } from './surface.js';
 // Advanced — most apps never import this. Custom (Zero-style) mutators:
 // `ablo.<model>.create/update/delete` already covers normal writes. Reach
 // for `defineMutators` only when you need a named, multi-step mutation with

package/dist/mutators/RecordingTransaction.js

@@ -59,55 +59,27 @@ function wrapMutateForKey(modelKey, mutate, store, inverses, forwards) {
         // wider shape is exactly right.
         return model.toJSON();
     };
+    // Before-image for the undo inverse. Delegates to `Model.capturePreviousValues`
+    // — the SINGLE shared implementation (the stream path's
+    // `TransactionQueue.extractPreviousData` calls the same method). `fallbackToLive`
+    // is ON here: the manual-record path wants the live value as a last resort for
+    // a field that was neither pre-mutated nor in the original snapshot. (The
+    // stream path passes `false` so it can omit-and-drop instead — that flag is
+    // the one intentional difference between the two callers.)
     const snapshotFields = (id, fieldNames) => {
         const model = store.pool.get(id);
         if (!model)
             return null;
-        const out = {};
-        // `modifiedProperties` is populated by M1's `observe()` listener the
-        // moment the caller mutates an observable field directly. Thanks to
-        // `Model.propertyChanged`'s first-old-wins policy, `.old` holds the TRUE
-        // pre-session baseline even after many in-place mutations (e.g. a drag
-        // frame loop). That makes it the authoritative source for the undo
-        // inverse when the caller pre-mutates before invoking the mutator.
-        //
-        // Fallback chain for models/fields that weren't pre-mutated (so no
-        // `modifiedProperties` entry exists yet): `getOriginalSnapshot()`
-        // (populated on load/`markAsPersisted`/sync-ack), then the live
-        // observable. The live read is correct only when the caller didn't
-        // touch the field first.
-        const original = model.getOriginalSnapshot();
-        for (const f of fieldNames) {
-            if (f === 'id')
-                continue;
-            const mod = model.modifiedProperties.get(f);
-            if (mod) {
-                out[f] = mod.old;
-            }
-            else if (original && f in original) {
-                out[f] = original[f];
-            }
-            else {
-                out[f] = Reflect.get(model, f);
-            }
-        }
-        return out;
+        return model.capturePreviousValues(fieldNames, { fallbackToLive: true });
     };
     // After a mutator's `base.update` succeeds, drop the `modifiedProperties`
-    // entries we snapshotted from. The next mutator call should see THIS
-    // update's result as its baseline, not the pre-session old value. The
-    // transaction queue already captured its frozen copy synchronously inside
-    // `store.save` (via `captureModelChanges`/`extractPreviousData`), so this
-    // clear is safe for server rollback.
+    // entries we snapshotted from so the next mutator call sees THIS update's
+    // result as its baseline, not the pre-session old value. The transaction
+    // queue already captured its frozen copy synchronously inside `store.save`,
+    // so this clear is safe for server rollback. Shared with the stream path via
+    // `Model.consumeModifiedFields`.
     const consumeModifiedFields = (id, fieldNames) => {
-        const model = store.pool.get(id);
-        if (!model)
-            return;
-        for (const f of fieldNames) {
-            if (f === 'id')
-                continue;
-            model.modifiedProperties.delete(f);
-        }
+        store.pool.get(id)?.consumeModifiedFields(fieldNames);
     };
     return {
         // Overloaded — single row or array. The recorder dispatches the

package/dist/react/AbloProvider.d.ts

@@ -36,7 +36,7 @@ import { type SyncStoreContract } from './context.js';
  * // Build once at module scope — a new instance per render tears down the socket.
  * const ablo = Ablo({
  *   schema,
- *   getToken: () =>
+ *   apiKey: () =>
  *     fetch('/api/ablo-session', { method: 'POST' })
  *       .then((r) => r.json())
  *       .then((d) => d.token),
@@ -120,12 +120,7 @@ export type { EngineParticipant, ParticipantScope, ParticipantStatus };
  */
 export interface UseParticipantOptions {
     readonly scope?: ParticipantScope;
-    readonly label?: string;
-    readonly as?: unknown;
     readonly ttlSeconds?: number | string | null;
-    readonly agent?: unknown;
-    readonly idempotencyKey?: string | null;
-    readonly autoRefreshThresholdSeconds?: number | null;
     /** Tear down + don't re-join while true. */
     readonly paused?: boolean;
     /**

package/dist/react/AbloProvider.js

@@ -36,7 +36,7 @@ export function AbloProvider(props) {
     // REACTIVE binding over it (context + bootstrap gate + error/session
     // forwarding); it does NOT construct, configure, or own the connection. The
     // client owns auth, the credential lifecycle (first mint, refresh, and
-    // wake/online/focus re-mint — see `Ablo({ getToken })`), transport, and
+    // wake/online/focus re-mint — see `Ablo({ apiKey })`), transport, and
     // `dispose()`. The CONSUMER built the client, so the consumer owns teardown;
     // the provider never disposes it.
     const engine = client;
@@ -338,10 +338,6 @@ export function useParticipant(opts) {
             unsubClaims();
         };
     }, [participant, paused]);
-    // `opts.as`, `opts.agent`, `opts.idempotencyKey`, and
-    // `opts.autoRefreshThresholdSeconds` remain migration placeholders
-    // for future capability-mint/attenuation wiring. `scope` is already
-    // active: it opens a multiplexed claim on the engine WebSocket.
     return { participant, peers, claims, status, error };
 }
 /**

package/dist/react/context.d.ts

@@ -137,24 +137,6 @@ export interface SyncReactContext {
      * augmentation — see `src/types/global.ts`.
      */
     schema?: Schema;
-    /**
-     * Optional presence source. When set, `usePresence()` returns this
-     * value cast to the consumer's `ResolvePresence` type (declared via
-     * `interface Register { Presence: ... }`). The SDK doesn't own a
-     * presence wire format — consumers plug whatever backs their cursors,
-     * status, or activity state (a MobX store, a Zustand slice, a custom
-     * subscription). The typed-global gives it a call-site-ergonomic
-     * type without the SDK dictating the transport.
-     */
-    presence?: unknown;
-    /**
-     * Optional claim initiator. Same pattern as presence — consumers
-     * plug a function that turns an claim claim into a handle they
-     * control (WebSocket send, optimistic local update, whatever).
-     * `useClaim(name)` returns a typed invoker for the named claim
-     * from `interface Register { Claims: ... }`.
-     */
-    beginClaim?: (claimName: string, claim: unknown) => unknown;
 }
 export declare const SyncContext: import("react").Context<SyncReactContext | null>;
 /**
@@ -177,18 +159,6 @@ export interface SyncProviderProps {
      * their legacy `(schema, modelKey, …)` signatures.
      */
     schema?: Schema;
-    /**
-     * Optional presence source for `usePresence()`. See
-     * {@link SyncReactContext.presence} — the consumer plugs whatever
-     * backs their presence state; the hook returns it with
-     * `ResolvePresence` typing.
-     */
-    presence?: unknown;
-    /**
-     * Optional claim initiator for `useClaim()`. See
-     * {@link SyncReactContext.beginClaim}.
-     */
-    beginClaim?: (claimName: string, claim: unknown) => unknown;
     children?: ReactNode;
 }
 /**
@@ -206,4 +176,4 @@ export interface SyncProviderProps {
  *   );
  * }
  */
-export declare function SyncProvider({ store, organizationId, schema, presence, beginClaim, children, }: SyncProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<SyncReactContext | null>>;
+export declare function SyncProvider({ store, organizationId, schema, children, }: SyncProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<SyncReactContext | null>>;

package/dist/react/context.js

@@ -30,6 +30,6 @@ export function useSyncContext() {
  *   );
  * }
  */
-export function SyncProvider({ store, organizationId, schema, presence, beginClaim, children, }) {
-    return createElement(SyncContext.Provider, { value: { store, organizationId, schema, presence, beginClaim } }, children);
+export function SyncProvider({ store, organizationId, schema, children, }) {
+    return createElement(SyncContext.Provider, { value: { store, organizationId, schema } }, children);
 }

package/dist/react/index.d.ts

@@ -6,7 +6,6 @@
  *     — 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
@@ -29,8 +28,6 @@
  * 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
  *
  * ── Breaking changes from v0.2.x ───────────────────────────────────
  * Removed: <SyncProvider>, SyncContext, useSyncContext — folded into
@@ -45,7 +42,6 @@
  */
 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 { ClientSideSuspense, type ClientSideSuspenseProps, } from './ClientSideSuspense.js';
 export { DefaultFallback } from './DefaultFallback.js';
 export type { SyncStoreContract } from './context.js';
@@ -59,6 +55,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

@@ -6,7 +6,6 @@
  *     — 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
@@ -29,8 +28,6 @@
  * 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
  *
  * ── Breaking changes from v0.2.x ───────────────────────────────────
  * Removed: <SyncProvider>, SyncContext, useSyncContext — folded into
@@ -45,7 +42,6 @@
  */
 // ── Umbrella provider + lifecycle hooks ────────────────────────────
 export { AbloProvider, useParticipant, usePeers, useSync, useSyncStore, } from './AbloProvider.js';
-export { SyncGroupProvider, useSyncGroup, } from './SyncGroupProvider.js';
 export { ClientSideSuspense, } from './ClientSideSuspense.js';
 export { DefaultFallback } from './DefaultFallback.js';
 // ── Status + errors + identity ─────────────────────────────────────
@@ -63,8 +59,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/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/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/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';