@abloatai/humans 0.63.1 → 0.64.1

package/dist/Ablo.d.ts

@@ -86,6 +86,11 @@ import type * as _Global from '@abloatai/transaction/types/global';
  *      into one of the public subpaths.
  */
 export declare namespace Ablo {
+    /** Payload delivered by the core client's onMutationFailure subscription. */
+    type MutationFailure = Parameters<Parameters<AbloClient<SchemaRecord>['onMutationFailure']>[0]>[0];
+    /** Current client lifecycle, also selected through React's useAblo. */
+    type Store = import('./local/storeContract.js').SyncStoreContract;
+    type Status = import('./local/client/status.js').ClientStatus;
     type Options<S extends SchemaRecord = SchemaRecord> = AbloOptions<S>;
     /**
      * The read view of the client that `useAblo` selectors receive: model reads
@@ -119,6 +124,7 @@ export declare namespace Ablo {
      * different schemas.
      */
     type ResolveSchema = _Global.ResolveSchema;
+    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/dist/client.d.ts

@@ -12,9 +12,9 @@
  */
 import type { Schema, SchemaRecord, Model, InferCreate, InferRow } from '@abloatai/transaction/schema/schema';
 import type { InstanceCache } from './local/InstanceCache.js';
-import type { SyncStoreContract } from './react/context.js';
+import type { SyncStoreContract } from './local/storeContract.js';
 import type { SyncWebSocket, CoreSyncEventMap } from './local/sync/SyncWebSocket.js';
-import type { SyncStatus } from './local/BaseSyncedStore.js';
+import type { ClientStatus } from './local/client/status.js';
 import type { ModelOperations } from './local/client/createModelOperations.js';
 import type { ClaimResource, CommitResource } from '@abloatai/transaction/client/resources/httpResources';
 import type { EffectiveAuthority } from '@abloatai/transaction/auth';
@@ -25,7 +25,9 @@ export type { LocalReadOptions } from './local/client/resourceTypes.js';
 /** The typed sync engine client — one property per model in the schema */
 export type AbloClient<S extends SchemaRecord> = {
     readonly [K in keyof S & string]: ModelOperations<Model<Schema<S>, K>, InferCreate<Schema<S>, K>>;
-} & {
+} & AbloCore<S>;
+/** Core members stay intact even when the model schema is not registered. */
+interface AbloCore<S extends SchemaRecord> {
     /**
      * Wait for the sync engine to finish its initial bootstrap.
      * Resolves once entity data is loaded and the WebSocket is connected.
@@ -50,7 +52,7 @@ export type AbloClient<S extends SchemaRecord> = {
      * acknowledged everything before continuing — for example, before
      * navigating away, before triggering a server-side workflow, or in tests.
      *
-     * Resolves when `syncStatus.pendingChanges` reaches 0. If the engine is
+     * Resolves when all pending local changes are confirmed. If the engine is
      * offline, this waits until reconnect + flush completes.
      *
      * ```ts
@@ -171,32 +173,10 @@ export type AbloClient<S extends SchemaRecord> = {
      */
     waitForConfirmation(modelName: string, modelId: string): Promise<void>;
     /**
-     * Reactive sync status — a MobX observable.
-     *
-     * Single source of truth for "what's the sync engine doing?" Contains:
-     * - `state`: `'idle' | 'syncing' | 'error' | 'offline' | 'reconnecting'`
-     * - `progress`: 0-100 for bootstrap progress
-     * - `error?`: Error object when `state === 'error'`
-     * - `pendingChanges`: Number of unconfirmed mutations in the queue
-     * - `lastSyncAt?`: Timestamp of the last successful delta processing
-     * - `offlineSince?`: When the connection dropped
-     * - `isSessionError`: True when the error requires re-authentication
-     *
-     * React components using `observer()` re-render automatically when
-     * any field changes — no manual subscription or polling needed.
-     *
-     * ```tsx
-     * import { observer } from 'mobx-react-lite';
-     *
-     * const SyncIndicator = observer(() => {
-     *   if (sync.syncStatus.state === 'syncing') return <Spinner />;
-     *   if (sync.syncStatus.state === 'error') return <Error msg={sync.syncStatus.error} />;
-     *   if (sync.syncStatus.state === 'offline') return <OfflineBadge />;
-     *   return null;
-     * });
-     * ```
+     * Current connection and confirmation state. Available before ready().
+     * React reads the same value with `useAblo(ablo => ablo.status)`.
      */
-    readonly syncStatus: SyncStatus;
+    readonly status: ClientStatus;
     /**
      * Session-owned live activity projected from this client's existing
      * connection. Use `active` for every visible activity, `others` to exclude
@@ -230,7 +210,7 @@ export type AbloClient<S extends SchemaRecord> = {
     subscribe<K extends keyof CoreSyncEventMap>(event: K, handler: (...args: CoreSyncEventMap[K]) => void): () => void;
     /**
      * 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;
@@ -243,7 +223,7 @@ export type AbloClient<S extends SchemaRecord> = {
      * no window in which this is absent and nothing needs to guard for one.
      */
     readonly _ws: SyncWebSocket;
-};
+}
 /**
  * The reactive-read client a `useAblo` selector receives. The same surface as
  * {@link AbloClient}, except model reads are typed as reactive rows
@@ -253,6 +233,6 @@ export type AbloClient<S extends SchemaRecord> = {
  * compile error here instead of a silent runtime `undefined`; compose
  * relations through selectors or hooks that resolve the pool's instance.
  */
-export type AbloReads<S extends SchemaRecord> = Omit<AbloClient<S>, keyof S & string> & {
+export type AbloReads<S extends SchemaRecord> = AbloCore<S> & {
     readonly [K in keyof S & string]: ModelOperations<InferRow<Schema<S>, K>, InferCreate<Schema<S>, K>>;
 };

package/dist/index.d.ts

@@ -9,3 +9,4 @@ export { createTransaction, type Transaction, type ReaderFindOptions, } from './
 export { ClaimLog, formatClaim, formatConflict, type ClaimLogEntry, } from './local/coordination/ClaimLog.js';
 export { isStorageOpenTimeout, } from './local/stores/openIDBWithTimeout.js';
 export type { CommitLatencySample, } from './local/transactions/mutations/commitLatency.js';
+export { getAbloStore } from './local/storeAccess.js';

package/dist/index.js

@@ -4,3 +4,4 @@ export { defineMutators, } from './local/mutators/defineMutators.js';
 export { createTransaction, } from './local/mutators/Transaction.js';
 export { ClaimLog, formatClaim, formatConflict, } from './local/coordination/ClaimLog.js';
 export { isStorageOpenTimeout, } from './local/stores/openIDBWithTimeout.js';
+export { getAbloStore } from './local/storeAccess.js';

package/dist/local/client/createModelOperations.d.ts

@@ -22,14 +22,14 @@ export type { Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, HeldLease
 import type { ClaimApi, ClaimAttemptEvent, LocalCountOptions, LocalReadOptions } from '@abloatai/transaction/client/resources/modelOperations';
 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, ModelEventInput, ModelEventTarget } from '@abloatai/transaction/collaboration';
 import { type ReadSetContext } from '@abloatai/transaction/internal/read-set';
 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;
     };
@@ -42,7 +42,7 @@ export declare function getModelClientMeta(modelClient: unknown): ModelClientMet
 type EntityHalf = Pick<ModelTarget, 'model' | 'id'>;
 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. */

package/dist/local/client/createModelOperations.js

@@ -1091,7 +1091,7 @@ hydration, collaboration, readSetContext) {
         ...(collaboration
             ? {
                 presence: {
-                    get: (recordId) => collaboration.presence(registeredModelName, recordId),
+                    get: (recordId, options) => collaboration.presence(registeredModelName, recordId, options),
                     subscribe: (listener) => collaboration.onPresenceChange(listener),
                     read: (recordId) => {
                         const scope = { [schemaKey]: recordId };

package/dist/local/client/reactiveEngine.js

@@ -15,6 +15,7 @@ import { omittedModelError } from '@abloatai/transaction/schema/select';
 import { durableCommitOperationSchema, } from '@abloatai/transaction/commit';
 import { AbloConnectionError, AbloValidationError, claimedError } from '@abloatai/transaction/errors';
 import { batchFence, claimIdFor, fenceTokenFor, modelTarget, streamTarget, subTarget, } from '@abloatai/transaction/coordination';
+import { readStatus } from './status.js';
 import { validateAbloOptions } from './validateAbloOptions.js';
 import { startStoreLifecycle } from './storeLifecycle.js';
 import { createClaimStream } from '../sync/createClaimStream.js';
@@ -394,7 +395,7 @@ export function buildReactiveEngine(inputs) {
     for (const [schemaKey, modelDef] of Object.entries(schema.models)) {
         const registeredModelName = modelDef.typename ?? schemaKey;
         modelProxies[schemaKey] = createModelOperations(schemaKey, registeredModelName, objectPool, syncClient, 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) => {
@@ -605,11 +606,9 @@ export function buildReactiveEngine(inputs) {
         waitForConfirmation(modelName, modelId) {
             return store.waitForConfirmation(modelName, modelId);
         },
-        // Expose the store's MobX observable directly — single source of truth.
-        // React components using observer() will re-render automatically on
-        // any state change (syncing, error, offline, pendingChanges, progress).
-        get syncStatus() {
-            return store.syncStatus;
+        // One core lifecycle projection; React selects the same observable reads.
+        get status() {
+            return readStatus(store);
         },
         // The humans capability owns the connection-backed presence projection.
         // Keep it on the base client as well as in the plugin surface so the
@@ -618,10 +617,10 @@ export function buildReactiveEngine(inputs) {
         schema,
         // ── 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(). */
         get _pool() { return objectPool; },

package/dist/{react/useSyncStatus.d.ts → local/client/status.d.ts}

@@ -1,4 +1,6 @@
-export type SyncStatusSnapshot = {
+import type { SyncStoreContract } from '../storeContract.js';
+/** The client lifecycle, shared by every framework binding. */
+export type ClientStatus = {
     readonly name: 'initial';
 } | {
     readonly name: 'connecting';
@@ -15,5 +17,4 @@ export type SyncStatusSnapshot = {
 } | {
     readonly name: 'needs-auth';
 };
-/** Reactively exposes the local store's connection and confirmation status. */
-export declare function useSyncStatus(): SyncStatusSnapshot;
+export declare function readStatus(store: SyncStoreContract): ClientStatus;

package/dist/local/client/status.js

@@ -0,0 +1,14 @@
+export function readStatus(store) {
+    const { state, progress, pendingChanges, isSessionError, error } = store.syncStatus;
+    if (isSessionError)
+        return { name: 'needs-auth' };
+    if (state === 'reconnecting')
+        return { name: 'reconnecting', reason: error?.message };
+    if (state === 'offline')
+        return { name: 'disconnected', reason: 'offline' };
+    if (state === 'error')
+        return { name: 'disconnected', reason: error?.message };
+    if (store.isReady)
+        return { name: 'connected', hasUnsyncedChanges: pendingChanges > 0 };
+    return { name: 'connecting', progress };
+}

package/dist/local/client/storeLifecycle.js

@@ -183,7 +183,7 @@ export function startStoreLifecycle(deps) {
                 //
                 // The store.initialize() generator updates store.syncStatus as it
                 // progresses (syncing → idle on success, error on failure), so the
-                // consumer's `sync.syncStatus` observable reflects real-time state.
+                // consumer's `ablo.status` projection reflects real-time state.
                 // Resolve bootstrap mode: explicit option wins; otherwise
                 // agents default to 'none' (transactional participant — see
                 // option doc) and everyone else defaults to 'full'.
@@ -260,7 +260,7 @@ export function startStoreLifecycle(deps) {
     if (!validationError && internalOptions.autoStart) {
         void ready().catch(() => {
             // Error is captured in store.syncStatus; consumers should check
-            // `sync.syncStatus.state === 'error'` to detect failures.
+            // `ablo.status.name === 'disconnected'` to detect failures.
         });
     }
     return {

package/dist/local/mutators/defineMutators.d.ts

@@ -1,60 +1,15 @@
-/**
- * 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';
-/**
- * `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.
- */
+import type { ResolveSchema, RequireRegisteredSchema } from '@abloatai/transaction/types/global';
 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 declare 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 declare function defineMutators<const M extends MutatorDefs<RegisteredSchema>>(mutators: M): M;
+export declare function defineMutators<const M extends MutatorDefs<RegisteredSchema>>(mutators: RequireRegisteredSchema<M>): M;
 export {};

package/dist/local/mutators/defineMutators.js

@@ -1,18 +1,3 @@
-/**
- * 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.
- */
 export function defineMutators(schemaOrMutators, maybeMutators) {
-    // 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);
 }

package/dist/local/storeAccess.d.ts

@@ -0,0 +1,7 @@
+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 declare function getAbloStore<S extends SchemaRecord>(client: AbloClient<S>): SyncStoreContract;

package/dist/local/storeAccess.js

@@ -0,0 +1,6 @@
+/** Access the supported local store contract for custom framework adapters,
+ * demand loading, scope management and custom undo infrastructure.
+ */
+export function getAbloStore(client) {
+    return client._store;
+}

package/dist/local/storeContract.d.ts

@@ -17,8 +17,7 @@ import type { GroupScope } from './sync/scopeGroups.js';
 /**
  * A snapshot of the client's synchronization state, shaped for binding to UI.
  * {@link SyncStoreContract.syncStatus} exposes a reactive instance of this, and
- * the `useSyncStatus()` hook reads its fields to render connection and progress
- * indicators.
+ * the client projects it into `ablo.status` for connection indicators.
  */
 export interface SyncStatus {
     state: 'idle' | 'syncing' | 'error' | 'offline' | 'reconnecting';
@@ -112,7 +111,7 @@ export interface SyncStoreContract {
      * are backed by observable computeds, so reading them inside a reactive
      * context — an observer component or a reaction — re-runs that context when
      * the state changes. Code that prefers not to work with the reactivity system
-     * directly can read the same values through the `useSyncStatus()` hook.
+     * directly can read the same values through `useAblo(ablo => ablo.status)`.
      */
     readonly isReady: boolean;
     readonly isSyncing: boolean;
@@ -136,7 +135,7 @@ export interface SyncStoreContract {
     pinScope?(scope: GroupScope): Promise<void>;
     unpinScope?(scope: GroupScope): Promise<void>;
     /**
-     * The full reactive {@link SyncStatus} record. The `useSyncStatus()` hook
+     * The full reactive {@link SyncStatus} record. The client status projection
      * reads its fields — `state`, `progress`, `pendingChanges`, `isSessionError`,
      * and `error` — to present the current sync state. It is part of the contract
      * so hooks and test doubles can read or set it directly.

package/dist/presence/index.d.ts

@@ -1,10 +1,10 @@
-import { type PresenceProjection, type PresenceProjectionEvents, type PresenceView } from '@abloatai/transaction/presence';
+import { type PresenceProjection, type PresenceProjectionEvents, type PresenceView, type PresenceQueryOptions } from '@abloatai/transaction/presence';
 import type { PresenceTarget } from '@abloatai/transaction/presence';
 import { type ReadActivityTransport } from './readActivity.js';
 type PresenceTransport = PresenceProjectionEvents & ReadActivityTransport;
 /** Reactive-client presence backed by the client's existing live connection. */
 export interface ReactivePresence extends PresenceView {
-    forModel(model: string, recordId?: string): ReturnType<PresenceProjection['forModel']>;
+    forModel(model: string, recordId?: string, options?: PresenceQueryOptions): ReturnType<PresenceProjection['forModel']>;
     onChange(listener: () => void): () => void;
 }
 /** Lifecycle hooks kept inside the humans composition boundary. */

package/dist/presence/index.js

@@ -1,3 +1,4 @@
+import { observable, runInAction } from 'mobx';
 import { createPresenceProjection, } from '@abloatai/transaction/presence';
 import { startReadActivity, } from './readActivity.js';
 const clientPresence = new WeakMap();
@@ -14,10 +15,12 @@ export function presenceOfClient(client) {
 export function createPresence(transport = null) {
     let projection = null;
     let attachedTransport = null;
+    const version = observable.box(0);
     const listeners = new Set();
     const reads = new Set();
     let unsubscribe = null;
     const notify = () => {
+        runInAction(() => { version.set(version.get() + 1); });
         for (const listener of listeners)
             listener();
     };
@@ -32,8 +35,8 @@ export function createPresence(transport = null) {
     if (transport !== null)
         attach(transport);
     return {
-        get active() { return projection?.active ?? []; },
-        get others() { return projection?.others ?? []; },
+        get active() { version.get(); return projection?.active ?? []; },
+        get others() { version.get(); return projection?.others ?? []; },
         onChange(listener) {
             listeners.add(listener);
             return () => { listeners.delete(listener); };
@@ -49,8 +52,9 @@ export function createPresence(transport = null) {
                 lifetime.stop();
             };
         },
-        forModel(model, recordId) {
-            return projection?.forModel(model, recordId) ?? [];
+        forModel(model, recordId, options) {
+            version.get();
+            return projection?.forModel(model, recordId, options) ?? [];
         },
         dispose() {
             for (const read of reads)