@abloatai/humans 0.64.0 → 0.64.2

package/dist/react/useAblo.d.ts

@@ -1,66 +1,20 @@
-import type { AbloClient as Ablo, AbloReads } from '../client.js';
+import type { AbloReads } from '../client.js';
 import type { ModelClaim } from '@abloatai/transaction/coordination';
 import { type ModelOperations } from '../local/client/createModelOperations.js';
 import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
-import type { ResolveSchema } from '@abloatai/transaction/types/global';
-/**
- * The app's resolved schema-record type. It reads your `Register` module
- * augmentation when you declare one and falls back to the loose
- * {@link SchemaRecord} otherwise, so `useAblo()` returns a fully typed client
- * without you passing `<(typeof schema)['models']>` at every call site.
- */
-type DefaultModels = ResolveSchema extends {
-    models: infer M;
-} ? M extends SchemaRecord ? M : SchemaRecord : SchemaRecord;
+import type { ResolveModels as DefaultModels } from '@abloatai/transaction/types/global';
 export type ModelClientSelector<R extends SchemaRecord, T, C> = (ablo: AbloReads<R>) => ModelOperations<T, C>;
 export type AbloSelector<R extends SchemaRecord, T> = (ablo: AbloReads<R>) => T;
-/**
- * Reads Ablo from inside an `<AbloProvider>` subtree. Called with no arguments
- * it returns the typed client for use in callbacks and effects; called with a
- * selector it subscribes the component to a reactive read — such as one
- * `ablo.<model>` row — and re-renders when that read changes.
- *
- * You can call it with no type arguments once you declare the `Register` module
- * augmentation (`declare module '@abloatai/ablo' { interface Register {
- * Schema: typeof schema } }`); the default type then resolves through your
- * schema's models, so call sites stay clean:
- *
- * **Prefer the binding.** `createAbloReact(schema)` captures the schema once
- * in your app's binding file and returns a `useAblo` that needs none of the
- * typing arrangements below — no type argument, no `Register` declaration
- * (see `react.md`). Passing an explicit schema type argument to THIS hook is
- * deprecated in favor of that binding; it keeps working for shared packages
- * that cannot bind a concrete schema.
- *
- * ```ts
- * // With the Register augmentation (recommended):
- * const ablo = useAblo();
- * if (!ablo) return <Loading />;
- * const doc = await ablo.records.get({ id }); // observational async server read
- *
- * // Reactive selector (a synchronous local snapshot). The selector's reads
- * // are typed as snapshot rows — data fields + computeds, no relation
- * // accessors — matching what the hook actually returns:
- * const doc = useAblo((ablo) => ablo.records.local.get(id)) ?? serverDoc;
- * const { claimed } = useAblo((ablo) => ablo.records, id);
- *
- * // Without the augmentation, pass the schema as a type argument:
- * const ablo = useAblo<(typeof schema)['models']>();
- * ```
- *
- * The client and its status are available during provider startup. Select
- * `ablo.status` to display connection state; await `ablo.ready()` before
- * operations that require an initialized client. Without a provider, the
- * no-argument form returns `null` and selectors return `undefined`.
- */
-export declare function useAblo<R extends SchemaRecord = DefaultModels>(): Ablo<R> | null;
+/** Select a reactive snapshot or read a row with its current claims. */
 export declare function useAblo<R extends SchemaRecord = DefaultModels, T = unknown>(select: AbloSelector<R, T>): T | undefined;
 export declare function useAblo<T, C>(modelClient: ModelOperations<T, C>, id: string, options?: useAblo.Options<T>): useAblo.Result<T>;
 export declare function useAblo<R extends SchemaRecord = DefaultModels, T = Record<string, unknown>, C = unknown>(select: ModelClientSelector<R, T, C>, id: string, options?: useAblo.Options<T>): useAblo.Result<T>;
-/** @internal Resolve the nearest provider's client through one schema rebind. */
-export declare function useAbloClient<R extends SchemaRecord>(): Ablo<R> | null;
 /** Type annotations belong to the operation; most callers rely on inference. */
 export declare namespace useAblo {
+    interface Bound<S extends SchemaRecord> {
+        <T>(select: AbloSelector<S, T>): T | undefined;
+        <T, C>(model: ModelOperations<T, C> | ModelClientSelector<S, T, C>, id: string, options?: Options<T>): Result<T>;
+    }
     interface Options<T> {
         /**
          * An initial row, usually from a server component or a route loader. The hook
@@ -78,4 +32,3 @@ export declare namespace useAblo {
         readonly claimed: boolean;
     }
 }
-export {};

package/dist/react/useAblo.js

@@ -1,24 +1,10 @@
 'use client';
-import { useCallback, useContext, useEffect, useMemo } from 'react';
-import { AbloInternalContext } from './internalContext.js';
+import { useCallback, useEffect, useMemo } from 'react';
+import { useAbloClient } from './useAbloClient.js';
 import { getModelClientMeta, } from '../local/client/createModelOperations.js';
 import { useReactive } from './useReactive.js';
 const EMPTY_CLAIMS = Object.freeze([]);
-/**
- * Restore the caller's schema generics on the context-held engine. React
- * context erases generics (see `AbloInternalContextValue.engine`), so this is
- * the one deliberate rebind point: the runtime value is the fully typed
- * client, and `R` is the compile-time view the calling hook declared.
- */
-function rebindEngine(engine) {
-    return engine;
-}
-/**
- * The reactive-read view of a client — the identical runtime object, with
- * model reads typed as snapshot rows, because everything a selector returns
- * is converted through `snapshotValue` before the hook hands it back. Same
- * generic in and out, so this compiles with no schema rebinding.
- */
+// Selector results are detached snapshots with no model methods or relations.
 function reactiveReads(engine) {
     return engine;
 }
@@ -50,12 +36,11 @@ export function useAblo(modelOrSelect, id, options) {
     // These dependencies define when the seed belongs to a different row.
     // eslint-disable-next-line react-hooks/exhaustive-deps
     const seed = useMemo(() => ({ received: false }), [engine, modelClient, id]);
-    const reading = modelOrSelect !== undefined;
     const subscribe = useCallback((notify) => {
-        if (!engine || !reading)
+        if (!engine)
             return () => undefined;
         return engine.claims.onChange(notify);
-    }, [engine, reading]);
+    }, [engine]);
     const value = useReactive(() => {
         if (isSelectorOnly && typeof modelOrSelect === 'function') {
             return engine ? modelOrSelect(reactiveReads(engine)) : undefined;
@@ -76,12 +61,5 @@ export function useAblo(modelOrSelect, id, options) {
         if (id !== undefined && modelClient?.local.get(id) !== undefined)
             seed.received = true;
     }, [seed, modelClient, id, value]);
-    if (isSelectorOnly || modelOrSelect)
-        return value;
-    return engine;
-}
-/** @internal Resolve the nearest provider's client through one schema rebind. */
-export function useAbloClient() {
-    const ctx = useContext(AbloInternalContext);
-    return ctx?.engine ? rebindEngine(ctx.engine) : null;
+    return value;
 }

package/dist/react/useAbloClient.d.ts

@@ -0,0 +1,5 @@
+import type { AbloClient } from '../client.js';
+import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
+import type { ResolveModels } from '@abloatai/transaction/types/global';
+/** Writable client for event handlers. Available before ready(); null without a provider. */
+export declare function useAbloClient<S extends SchemaRecord = ResolveModels>(): AbloClient<S> | null;

package/dist/react/useAbloClient.js

@@ -0,0 +1,9 @@
+'use client';
+import { useContext } from 'react';
+import { AbloInternalContext } from './internalContext.js';
+/** Writable client for event handlers. Available before ready(); null without a provider. */
+export function useAbloClient() {
+    const client = useContext(AbloInternalContext)?.engine;
+    // React context erases the schema; the application binding restores it.
+    return client ? client : null;
+}

package/dist/react/useMutationFailure.d.ts

@@ -0,0 +1,6 @@
+import type { AbloClient } from '../client.js';
+import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
+/** Subscribe for this component's lifetime using the latest committed listener.
+ * Replacing the provider client moves the subscription; unmount removes it.
+ */
+export declare function useMutationFailure(listener: Parameters<AbloClient<SchemaRecord>['onMutationFailure']>[0]): void;

package/dist/react/useMutationFailure.js

@@ -0,0 +1,11 @@
+'use client';
+import { useEffect, useEffectEvent } from 'react';
+import { useAbloClient } from './useAbloClient.js';
+/** Subscribe for this component's lifetime using the latest committed listener.
+ * Replacing the provider client moves the subscription; unmount removes it.
+ */
+export function useMutationFailure(listener) {
+    const client = useAbloClient();
+    const onFailure = useEffectEvent(listener);
+    useEffect(() => client?.onMutationFailure(onFailure), [client]);
+}

package/dist/react/useMutators.d.ts

@@ -1,7 +1,7 @@
 import type { Schema } from '@abloatai/transaction/schema/schema';
 import type { MutatorDefs } from '../local/mutators/defineMutators.js';
 import type { UndoScope } from '../local/mutators/UndoManager.js';
-import type { ResolveSchema } from '@abloatai/transaction/types/global';
+import type { ResolveSchema, RequireRegisteredSchema } from '@abloatai/transaction/types/global';
 /**
  * Turns a mutator tree built with `defineMutators` into callable invokers. The
  * returned object mirrors that tree one-to-one, but each leaf becomes an
@@ -37,9 +37,9 @@ export type InvokerFor<F> = F extends (options: infer O) => Promise<infer R> ? O
 /** Mutator invokers (explicit schema arg). */
 export declare function useMutators<S extends Schema, M extends MutatorDefs<S>>(schema: S, mutators: M, options?: useMutators.Options<S>): useMutators.Result<M>;
 /** Mutator invokers via the `Register` module augmentation. Schema comes
- * from the `SyncProvider`'s context; the mutator tree is typed against
+ * from the `AbloProvider` store context; the mutator tree is typed against
  * `ResolveSchema` at the call site. */
-export declare function useMutators<M extends ResolveSchema extends Schema ? MutatorDefs<ResolveSchema> : MutatorDefs<Schema>>(mutators: M, options?: useMutators.Options<ResolveSchema extends Schema ? ResolveSchema : Schema>): useMutators.Result<M>;
+export declare function useMutators<M extends ResolveSchema extends Schema ? MutatorDefs<ResolveSchema> : MutatorDefs<Schema>>(mutators: RequireRegisteredSchema<M>, options?: useMutators.Options<ResolveSchema extends Schema ? ResolveSchema : Schema>): useMutators.Result<M>;
 /** Optional annotations for custom mutation bindings. */
 export declare namespace useMutators {
     type Result<M> = {

package/dist/react/useMutators.js

@@ -2,11 +2,11 @@
 import { useMemo } from 'react';
 import { createTransaction } from '../local/mutators/Transaction.js';
 import { createRecordingMutation } from '../local/mutators/RecordingMutation.js';
-import { useSyncContext } from './context.js';
+import { useAbloStoreContext } from './context.js';
 import { AbloValidationError } from '@abloatai/transaction/errors';
 import { getContext } from '../local/context.js';
 export function useMutators(schemaOrMutators, mutatorsOrOptions, maybeOptions) {
-    const { store, organizationId, schema: ctxSchema } = useSyncContext();
+    const { store, organizationId, schema: ctxSchema } = useAbloStoreContext();
     // Disambiguate: explicit-schema path has the schema object in first slot;
     // the global-resolved path has the mutator tree there. A schema object
     // has a `.models` property; a mutator tree doesn't.
@@ -19,7 +19,7 @@ export function useMutators(schemaOrMutators, mutatorsOrOptions, maybeOptions) {
     if (!schema) {
         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' });
+            'schema-free overload can read it from context.', { code: 'mutators_schema_missing' });
     }
     const { undoScope } = options ?? {};
     return useMemo(() => {

package/dist/react/usePresence.d.ts

@@ -2,18 +2,18 @@ import type { PresenceSession } from '@abloatai/transaction/presence';
 import { type ModelOperations } from '../local/client/createModelOperations.js';
 import type { AbloClient as Ablo } from '../client.js';
 import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
-import type { ResolveSchema } from '@abloatai/transaction/types/global';
-type DefaultModels = ResolveSchema extends {
-    models: infer M;
-} ? M extends SchemaRecord ? M : SchemaRecord : SchemaRecord;
+import type { ResolveModels as DefaultModels } from '@abloatai/transaction/types/global';
 export type PresenceModelSelector<R extends SchemaRecord, T, C> = (ablo: Ablo<R>) => ModelOperations<T, C>;
 /**
  * Declare that this component is reading one row and return every live session
  * reading or otherwise acting on that row. Ablo owns the lease, refresh,
  * reconnect, and cleanup mechanics for the component's lifetime.
  */
-export declare function usePresence<T, C>(modelClient: ModelOperations<T, C>, recordId: string): readonly PresenceSession[];
-export declare function usePresence<R extends SchemaRecord = DefaultModels, T = Record<string, unknown>, C = unknown>(select: PresenceModelSelector<R, T, C>, recordId: string): readonly PresenceSession[];
-/** @internal Shared by the global hook and schema-bound React factory. */
-export declare function usePresenceImpl<R extends SchemaRecord, T, C>(engine: Ablo<R> | null, modelOrSelect: ModelOperations<T, C> | PresenceModelSelector<R, T, C>, recordId: string): readonly PresenceSession[];
-export {};
+export declare function usePresence<T, C>(modelClient: ModelOperations<T, C>, recordId: string, options?: usePresence.Options): readonly PresenceSession[];
+export declare function usePresence<R extends SchemaRecord = DefaultModels, T = Record<string, unknown>, C = unknown>(select: PresenceModelSelector<R, T, C>, recordId: string, options?: usePresence.Options): readonly PresenceSession[];
+export declare namespace usePresence {
+    interface Bound<S extends SchemaRecord> {
+        <T, C>(model: ModelOperations<T, C> | PresenceModelSelector<S, T, C>, recordId: string, options?: Options): readonly PresenceSession[];
+    }
+    type Options = import('@abloatai/transaction/presence').PresenceQueryOptions;
+}

package/dist/react/usePresence.js

@@ -2,14 +2,10 @@
 import { useCallback, useEffect } from 'react';
 import { AbloValidationError } from '@abloatai/transaction/errors';
 import { getModelClientMeta, } from '../local/client/createModelOperations.js';
-import { useAbloClient } from './useAblo.js';
+import { useAbloClient } from './useAbloClient.js';
 import { useReactive } from './useReactive.js';
-export function usePresence(modelOrSelect, recordId) {
+export function usePresence(modelOrSelect, recordId, options) {
     const engine = useAbloClient();
-    return usePresenceImpl(engine, modelOrSelect, recordId);
-}
-/** @internal Shared by the global hook and schema-bound React factory. */
-export function usePresenceImpl(engine, modelOrSelect, recordId) {
     if (recordId.length === 0) {
         throw new AbloValidationError('usePresence requires a non-empty record id.', { code: 'invalid_request', param: 'recordId' });
     }
@@ -23,7 +19,7 @@ export function usePresenceImpl(engine, modelOrSelect, recordId) {
         throw new AbloValidationError('usePresence requires a model from the reactive Ablo client.', { code: 'invalid_request', param: 'modelClient' });
     }
     const subscribe = useCallback((notify) => presence?.subscribe(notify) ?? (() => undefined), [presence]);
-    const sessions = useReactive(() => presence?.get(recordId) ?? [], { subscribe });
+    const sessions = useReactive(() => presence?.get(recordId, options) ?? [], { subscribe });
     useEffect(() => presence?.read(recordId), [presence, recordId]);
     return sessions;
 }

package/dist/react/useUndoScope.d.ts

@@ -1,10 +1,10 @@
 import type { Schema } from '@abloatai/transaction/schema/schema';
 import { type UndoScope, type UndoScopeOptions } from '../local/mutators/UndoManager.js';
-import type { ResolveSchema } from '@abloatai/transaction/types/global';
+import type { ResolveSchema, RequireRegisteredSchema } from '@abloatai/transaction/types/global';
 /** Per-surface undo/redo (explicit schema arg). */
 export declare function useUndoScope<S extends Schema>(schema: S, name: string, options?: UndoScopeOptions): useUndoScope.Result<S>;
 /** Per-surface undo/redo via the `Register` module augmentation. */
-export declare function useUndoScope(name: string, options?: UndoScopeOptions): useUndoScope.Result<ResolveSchema extends Schema ? ResolveSchema : Schema>;
+export declare function useUndoScope(name: RequireRegisteredSchema<string>, options?: UndoScopeOptions): useUndoScope.Result<ResolveSchema extends Schema ? ResolveSchema : Schema>;
 /** The state returned by an undo scope; inferred for ordinary hook calls. */
 export declare namespace useUndoScope {
     interface Result<S extends Schema> {

package/dist/react/useUndoScope.js

@@ -1,7 +1,7 @@
 'use client';
 import { useEffect, useMemo, useState } from 'react';
 import { UndoManager, } from '../local/mutators/UndoManager.js';
-import { useSyncContext } from './context.js';
+import { useAbloStoreContext } from './context.js';
 import { AbloValidationError } from '@abloatai/transaction/errors';
 /**
  * Provides per-surface undo and redo for mutator invocations. Each named scope
@@ -21,7 +21,7 @@ import { AbloValidationError } from '@abloatai/transaction/errors';
  * useHotkey('mod+z', () => { if (canUndo) void undo(); });
  */
 // Module-level weak registry: `SyncStoreContract` → `UndoManager`.
-// A single app wiring through one SyncProvider shares one manager across
+// A single AbloProvider shares one manager across
 // every useUndoScope call, so scopes with the same name are identity-equal.
 // The hook implementation already operates on the runtime-wide `Schema` type;
 // its overloads restore the caller's precise schema type at the public boundary,
@@ -37,7 +37,7 @@ function getManager(key, factory) {
     return m;
 }
 export function useUndoScope(schemaOrName, nameOrOptions, maybeOptions) {
-    const { store, organizationId, schema: ctxSchema } = useSyncContext();
+    const { store, organizationId, schema: ctxSchema } = useAbloStoreContext();
     const isExplicit = typeof schemaOrName !== 'string';
     const schema = isExplicit ? (schemaOrName) : ctxSchema;
     const name = isExplicit ? nameOrOptions : schemaOrName;
@@ -48,7 +48,7 @@ export function useUndoScope(schemaOrName, nameOrOptions, maybeOptions) {
             '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.
+        // Store is the identity for the manager — one per AbloProvider.
         const manager = getManager(store, () => new UndoManager(schema, store, organizationId));
         return manager.getScope(name, options);
         // eslint-disable-next-line react-hooks/exhaustive-deps

package/dist/react.d.ts

@@ -2,6 +2,8 @@
 export { AbloProvider } from './react/AbloProvider.js';
 export { createAbloReact } from './react/createAbloReact.js';
 export { useAblo } from './react/useAblo.js';
+export { useAbloClient } from './react/useAbloClient.js';
+export { useMutationFailure } from './react/useMutationFailure.js';
 export { usePresence } from './react/usePresence.js';
 export { useMutators } from './react/useMutators.js';
 export { useUndoScope } from './react/useUndoScope.js';

package/dist/react.js

@@ -2,6 +2,8 @@
 export { AbloProvider } from './react/AbloProvider.js';
 export { createAbloReact } from './react/createAbloReact.js';
 export { useAblo } from './react/useAblo.js';
+export { useAbloClient } from './react/useAbloClient.js';
+export { useMutationFailure } from './react/useMutationFailure.js';
 export { usePresence } from './react/usePresence.js';
 export { useMutators } from './react/useMutators.js';
 export { useUndoScope } from './react/useUndoScope.js';

package/dist/reactRuntime.d.ts

@@ -1,4 +1,4 @@
 export { AbloInternalContext, type AbloInternalContextValue, } from './react/internalContext.js';
-export { useSyncContext, type SyncReactContext, } from './react/context.js';
+export { useAbloStoreContext, type AbloStoreContextValue, } from './react/context.js';
 export type { SyncStoreContract } from './local/storeContract.js';
 export type { QueuedMutation } from './local/transactions/mutations/MutationQueue.js';

package/dist/reactRuntime.js

@@ -1,2 +1,2 @@
 export { AbloInternalContext, } from './react/internalContext.js';
-export { useSyncContext, } from './react/context.js';
+export { useAbloStoreContext, } from './react/context.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/humans",
-  "version": "0.64.0",
+  "version": "0.64.2",
   "description": "The optional human-facing local-state package for Ablo: presence, live queries, and React bindings.",
   "license": "Apache-2.0",
   "type": "module",
@@ -85,7 +85,7 @@
     "directory": "packages/humans"
   },
   "dependencies": {
-    "@abloatai/transaction": "^0.64.0",
+    "@abloatai/transaction": "0.64.2",
     "mobx": "^6.13.7",
     "uuid": "^11.1.0",
     "zod": "^4.4.3"

package/src/Ablo.ts

@@ -267,6 +267,7 @@ export namespace Ablo {
   /** Payload delivered by the core client's onMutationFailure subscription. */
   export type MutationFailure = Parameters<Parameters<AbloClient<SchemaRecord>['onMutationFailure']>[0]>[0];
   /** Current client lifecycle, also selected through React's useAblo. */
+  export type Store = import('./local/storeContract.js').SyncStoreContract;
   export type Status = import('./local/client/status.js').ClientStatus;
 
   // ── Factory options ────────────────────────────────────────────────
@@ -320,6 +321,7 @@ export namespace Ablo {
    * different schemas.
    */
   export type ResolveSchema = _Global.ResolveSchema;
+  export type ResolveClaimMeta = _Global.ResolveClaimMeta;
   /**
    * `ResolveSchema` guaranteed to satisfy the `Schema` bound. `ResolveSchema`
    * falls back to a loose `{ models }` shape when nothing is registered, which

package/src/client.ts

@@ -256,7 +256,7 @@ interface AbloCore<S extends SchemaRecord> {
 
   /**
    * The internal store. It implements {@link SyncStoreContract} — pass it to
-   * `SyncContext.Provider` so the SDK's `useModel` / `useModels` / `useMutations`
+   * `AbloStoreContext.Provider` so the SDK's React data hooks
    * hooks can reach it.
    */
   readonly _store: SyncStoreContract;

package/src/index.ts

@@ -39,3 +39,5 @@ export {
 export type {
   CommitLatencySample,
 } from './local/transactions/mutations/commitLatency.js';
+
+export { getAbloStore } from './local/storeAccess.js';

package/src/local/BaseSyncedStore.ts

@@ -379,18 +379,15 @@ export class BaseSyncedStore<
     this.syncWebSocket.sendCollaborationEvent(messageType, payload);
   }
 
-  // ── Area-of-interest (dynamic read subscription) ─────────────────
+  // ── Group interest and loading ──────────────────────────────────
   //
-  // `enterScope`/`leaveScope` move the connection's read interest as the
-  // user navigates (open or close a record); `pinScope`/`unpinScope`
-  // express prominence (an active claim keeps a group subscribed). All four
-  // resolve the scope to sync-group strings through the same resolver the
-  // claim path uses (`resolveParticipantSyncGroups`), so read interest and
-  // write claims always agree on the string for a given entity. Before the
-  // connection opens they record interest without a wire send, and they
-  // never reject when the transport is offline (see
-  // {@link SubscriptionManager.reconcile}); the on-connect `resync` pushes
-  // whatever interest accumulated.
+  // Authority comes from the server-issued session. Enter/leave track what
+  // this connection wants to receive; pin/unpin keep an active scope subscribed.
+  // All resolve selectors through scopeToGroups. Hydration separately loads
+  // a scoped baseline into the local pool. Leaving interest does not revoke
+  // authority or selectively evict cached records.
+  // Offline interest is recorded locally and reconciled when the connection
+  // opens; recording interest is not confirmation of a server subscription.
 
   private scopeToGroups(scope: GroupScope): string[] {
     return resolveScopeGroups(scope, this.schema);
@@ -399,10 +396,11 @@ export class BaseSyncedStore<
   /**
    * Bring a scope into view and subscribe to its sync groups. With
    * `{ hydrate: true }`, also backfill the groups' current state into the pool
-   * once the subscription is active. The order matters: subscribing first
-   * guarantees no live delta is missed in the gap before the snapshot lands.
-   * Hydration is best-effort — a failed backfill never rejects `enterScope`,
-   * and the live delta stream keeps flowing regardless.
+   * after subscription reconciliation. Offline reconciliation may only record
+   * interest locally; it is not proof that the server is delivering changes.
+   * Hydration is best-effort: failure leaves the groups unmarked for retry and
+   * does not reject `enterScope`. Snapshot application uses version guards so
+   * older baseline rows cannot overwrite newer deltas already in the pool.
    */
   enterScope(scope: GroupScope, opts?: { hydrate?: boolean }): Promise<void> {
     const groups = this.scopeToGroups(scope);

package/src/local/client/createModelOperations.ts

@@ -143,7 +143,7 @@ import type {
   HttpModelClient,
 } from '@abloatai/transaction/transport/http';
 import type { ParticipantKind } from '@abloatai/transaction/types/participant';
-import type { PresenceSession } from '@abloatai/transaction/presence';
+import type { PresenceSession, PresenceQueryOptions } from '@abloatai/transaction/presence';
 import type {
   CollaborationEventContext,
   ModelEventEnvelope,
@@ -165,7 +165,7 @@ export interface ModelClientMeta {
   readonly key: string;
   readonly typename: string;
   readonly presence?: {
-    get(recordId: string): readonly PresenceSession[];
+    get(recordId: string, options?: PresenceQueryOptions): readonly PresenceSession[];
     subscribe(listener: () => void): () => void;
     read(recordId: string): () => void;
   };
@@ -192,7 +192,7 @@ type EntityHalf = Pick<ModelTarget, 'model' | 'id'>;
 // while reading as though they differed.
 export interface ModelCollaboration {
   /** Session projections already held by this client's one presence store. */
-  presence(model: string, recordId?: string): readonly PresenceSession[];
+  presence(model: string, recordId?: string, options?: PresenceQueryOptions): readonly PresenceSession[];
   /** Subscribe once to the connection-owned presence projection. */
   onPresenceChange(listener: () => void): () => void;
   /** Start one session-owned read activity and return its cleanup. */
@@ -1784,7 +1784,7 @@ export function createModelOperations<T, C>(
     ...(collaboration
       ? {
           presence: {
-            get: (recordId: string) => collaboration.presence(registeredModelName, recordId),
+            get: (recordId, options) => collaboration.presence(registeredModelName, recordId, options),
             subscribe: (listener: () => void) => collaboration.onPresenceChange(listener),
             read: (recordId: string) => {
               const scope = { [schemaKey]: recordId };

package/src/local/client/reactiveEngine.ts

@@ -576,7 +576,7 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
       modelRegistry,
       hydration,
       {
-        presence: (model, recordId) => presenceStream.forModel(model, recordId),
+        presence: (model, recordId, options) => presenceStream.forModel(model, recordId, options),
         onPresenceChange: (listener) => presenceStream.onChange(listener),
         startReadPresence: (target) => presenceStream.startRead(target),
         modelEventTarget: (recordId) => {
@@ -857,11 +857,11 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
 
     // ── Internal accessors for framework integration ─────────────────
     // These expose internal components for consumers that need direct
-    // access (e.g., SyncEngineProvider wiring SyncContext, collaboration
+    // access (e.g., AbloProvider wiring its store context, collaboration
     // events accessing the WebSocket handle, demand loaders accessing
     // the pool). Prefixed with _ to signal "internal but stable."
 
-    /** The BaseSyncedStore — implements SyncStoreContract for SyncContext.Provider. */
+    /** The BaseSyncedStore — implements SyncStoreContract for AbloStoreContext.Provider. */
     get _store() { return store; },
 
     /** The InstanceCache — for demand loaders that need pool.createFromData(). */

package/src/local/mutators/defineMutators.ts

@@ -1,76 +1,28 @@
-/**
- * Declares a tree of named custom mutators grouped by model key. Each mutator is
- * a plain async function that receives `{ tx, args }` and composes any number of
- * `tx.mutations.*` and `tx.read.*` calls to carry out a named operation, such as
- * `sections.createWithBlocks`.
- *
- * The function is purely a place for types to anchor and returns its input
- * unchanged; the runtime that dispatches a mutator lives elsewhere — the
- * transaction object it receives and the React hook that invokes it. Because
- * `defineMutators(schema, { ... })` returns the exact object you wrote,
- * `typeof mutators` carries every mutator's precise `args` and result types
- * through to wherever they are invoked.
- */
-
+/** Define typed named operations. Pass the schema explicitly across package boundaries. */
 import type { Schema } from '@abloatai/transaction/schema/schema';
 import type { Transaction } from './Transaction.js';
-import type { ResolveSchema } from '@abloatai/transaction/types/global';
+import type { ResolveSchema, RequireRegisteredSchema } from '@abloatai/transaction/types/global';
 
-/**
- * `ResolveSchema` narrowed to satisfy the `Schema` bound — mirrors
- * {@link Ablo.RegisteredSchema}. When nothing is registered, `ResolveSchema`
- * is a loose `{ models }` shape that doesn't extend `Schema`, so we fall back
- * to `Schema` to keep the mutator tree typed rather than collapsing.
- */
 type RegisteredSchema = ResolveSchema extends Schema ? ResolveSchema : Schema;
 
-/**
- * The signature of a single custom mutator. The engine supplies `tx`; you control
- * `args`, in whatever shape you like, and the resolved return value. `TArgs` and
- * `TResult` are bounded by `unknown` rather than `any`, so a mixed tree of
- * mutators can be typed together without falling back to `any`.
- */
 export type MutatorFn<S extends Schema, TArgs, TResult = void> = (
   options: { tx: Transaction<S>; args: TArgs },
 ) => Promise<TResult>;
 
-/**
- * The shape {@link defineMutators} accepts: an optional record per model key
- * whose values are named mutator functions. The `unknown` bounds keep the public
- * boundary type-safe without `any`; when you write your mutators inline,
- * TypeScript still infers the concrete `args` and result of each function, so the
- * `unknown` here is only a ceiling, not what you end up working with.
- */
 export type MutatorDefs<S extends Schema> = {
   [K in keyof S['models']]?: Record<string, MutatorFn<S, never, unknown>>;
 };
 
-/**
- * Returns the mutators object unchanged while constraining its shape against the
- * schema. The `S` generic pins the model keys, and the `M` generic is inferred as
- * a `const`, so each mutator's literal signature survives. There is no runtime
- * work here; the function exists purely as a place for type inference to anchor.
- */
 export function defineMutators<
   S extends Schema,
   const M extends MutatorDefs<S>,
 >(_schema: S, mutators: M): M;
-/**
- * Register-anchored overload: omit the schema value and the tree is typed
- * against `ResolveSchema` (this app's registered schema). Shared product code
- * used across apps that bind different schemas should use this form — it moves
- * with each app's `Register` instead of pinning one concrete schema, so the
- * mutator tree stays assignable at every consumer (which reads the same
- * `Register`). See docs/plans/per-product-schema-projections.md.
- */
 export function defineMutators<const M extends MutatorDefs<RegisteredSchema>>(
-  mutators: M,
+  mutators: RequireRegisteredSchema<M>,
 ): M;
 export function defineMutators(
   schemaOrMutators: Schema | MutatorDefs<Schema>,
   maybeMutators?: MutatorDefs<Schema>,
 ): MutatorDefs<Schema> {
-  // The schema argument is a type anchor only — never read at runtime. With one
-  // argument the mutator tree is in the first slot; with two it's in the second.
   return (maybeMutators ?? schemaOrMutators) as MutatorDefs<Schema>;
 }

package/src/local/storeAccess.ts

@@ -0,0 +1,10 @@
+import type { AbloClient } from '../client.js';
+import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
+import type { SyncStoreContract } from './storeContract.js';
+
+/** Access the supported local store contract for custom framework adapters,
+ * demand loading, scope management and custom undo infrastructure.
+ */
+export function getAbloStore<S extends SchemaRecord>(client: AbloClient<S>): SyncStoreContract {
+  return client._store;
+}