@abloatai/humans 0.60.0 → 0.62.0

package/dist/local/transactions/mutations/replayValidation.d.ts

@@ -27,8 +27,8 @@ import type { RuntimeContext } from '../../RuntimeContext.js';
 export declare const persistedTransactionSchema: z.ZodObject<{
     id: z.ZodString;
     type: z.ZodEnum<{
-        update: "update";
         create: "create";
+        update: "update";
         delete: "delete";
         archive: "archive";
         unarchive: "unarchive";
@@ -95,8 +95,8 @@ export declare function deserializePersistedTransaction(row: unknown, runtime?:
 export declare const persistedMutationSchema: z.ZodObject<{
     mutationId: z.ZodOptional<z.ZodString>;
     type: z.ZodEnum<{
-        update: "update";
         create: "create";
+        update: "update";
         delete: "delete";
         archive: "archive";
     }>;
@@ -138,8 +138,8 @@ export declare const legacyPendingMutationRecordSchema: z.ZodObject<{
     type: z.ZodLiteral<"pending_mutation">;
     mutation: z.ZodObject<{
         type: z.ZodEnum<{
-            update: "update";
             create: "create";
+            update: "update";
             delete: "delete";
             archive: "archive";
         }>;
@@ -180,8 +180,8 @@ export declare const pendingMutationRecordSchema: z.ZodObject<{
     type: z.ZodLiteral<"pending_mutation">;
     mutation: z.ZodObject<{
         type: z.ZodEnum<{
-            update: "update";
             create: "create";
+            update: "update";
             delete: "delete";
             archive: "archive";
         }>;

package/dist/presence/index.d.ts

@@ -0,0 +1,15 @@
+import { type PresenceProjection, type PresenceProjectionEvents, type PresenceView } from '@abloatai/transaction/presence';
+/** Reactive-client presence backed by the client's existing live connection. */
+export interface ReactivePresence extends PresenceView {
+    forModel(model: string, recordId?: string): ReturnType<PresenceProjection['forModel']>;
+    onChange(listener: () => void): () => void;
+}
+/** Lifecycle hooks kept inside the humans composition boundary. */
+export interface AttachablePresence extends ReactivePresence {
+    attach(transport: PresenceProjectionEvents): void;
+    dispose(): void;
+}
+/** Framework bridge that does not consume a string key on the model namespace. */
+export declare function attachPresenceToClient(client: object, presence: ReactivePresence): void;
+export declare function presenceOfClient(client: object): ReactivePresence;
+export declare function createPresence(transport?: PresenceProjectionEvents | null): AttachablePresence;

package/dist/presence/index.js

@@ -0,0 +1,49 @@
+import { createPresenceProjection, } from '@abloatai/transaction/presence';
+const clientPresence = new WeakMap();
+/** Framework bridge that does not consume a string key on the model namespace. */
+export function attachPresenceToClient(client, presence) {
+    clientPresence.set(client, presence);
+}
+export function presenceOfClient(client) {
+    const presence = clientPresence.get(client);
+    if (presence === undefined)
+        throw new Error('presence is not attached to this client');
+    return presence;
+}
+export function createPresence(transport = null) {
+    let projection = null;
+    const listeners = new Set();
+    let unsubscribe = null;
+    const notify = () => {
+        for (const listener of listeners)
+            listener();
+    };
+    const attach = (events) => {
+        if (projection !== null)
+            return;
+        projection = createPresenceProjection(events);
+        unsubscribe = projection.subscribe(notify);
+        notify();
+    };
+    if (transport !== null)
+        attach(transport);
+    return {
+        get active() { return projection?.active ?? []; },
+        get others() { return projection?.others ?? []; },
+        onChange(listener) {
+            listeners.add(listener);
+            return () => { listeners.delete(listener); };
+        },
+        attach,
+        forModel(model, recordId) {
+            return projection?.forModel(model, recordId) ?? [];
+        },
+        dispose() {
+            unsubscribe?.();
+            unsubscribe = null;
+            projection?.dispose();
+            projection = null;
+            listeners.clear();
+        },
+    };
+}

package/dist/react/AbloProvider.d.ts

@@ -1,7 +1,7 @@
 import { type ReactNode } from 'react';
 import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
 import type { AbloClient as Ablo } from '../client.js';
-import type { Peer } from '@abloatai/transaction/types/streams';
+import type { PresenceSession } from '@abloatai/transaction/presence';
 import type { GroupScope } from '../local/sync/scopeGroups.js';
 import { type SyncStoreContract } from './context.js';
 /**
@@ -109,7 +109,7 @@ export interface AbloProviderProps<R extends SchemaRecord = SchemaRecord> {
 export declare function AbloProvider<R extends SchemaRecord = SchemaRecord>(props: AbloProviderProps<R>): React.ReactElement;
 export type { GroupScope };
 /**
- * Read-only presence: the OTHER participants currently visible to this
+ * Read-only presence: the other sessions currently visible to this
  * connection, bridged to React. This is a pure reader of the engine's
  * already-flowing presence stream; it does not mutate connection groups.
  *
@@ -127,7 +127,7 @@ export type { GroupScope };
  * const alone = !peers.some((p) => p.participantKind === 'user');
  * ```
  */
-export declare function usePeers(scope?: GroupScope): readonly Peer[];
+export declare function usePeers(scope?: GroupScope): readonly PresenceSession[];
 /**
  * Returns the raw `SyncEngine` proxy. Typically you want the typed
  * hooks (`useQuery`, `useOne`, `useMutate`) — this is for rare cases

package/dist/react/AbloProvider.js

@@ -7,6 +7,7 @@ import { AbloInternalContext } from './internalContext.js';
 import { AbloValidationError } from '@abloatai/transaction/errors';
 import { useSyncStatus } from './useSyncStatus.js';
 import { DefaultFallback } from './DefaultFallback.js';
+import { presenceOfClient } from '../presence/index.js';
 // ── Implementation ───────────────────────────────────────────────────
 /**
  * Lightweight event emitter for provider-level errors. Lives on the
@@ -201,7 +202,7 @@ function BootstrapGate({ fallback, children, }) {
 }
 const EMPTY_PRESENCE = Object.freeze([]);
 /**
- * Read-only presence: the OTHER participants currently visible to this
+ * Read-only presence: the other sessions currently visible to this
  * connection, bridged to React. This is a pure reader of the engine's
  * already-flowing presence stream; it does not mutate connection groups.
  *
@@ -232,10 +233,10 @@ export function usePeers(scope) {
             setPeers(EMPTY_PRESENCE);
             return;
         }
-        const presence = engine.presence;
+        const presence = presenceOfClient(engine);
         const compute = () => groups.length === 0
             ? presence.others
-            : presence.others.filter((p) => p.syncGroups.some((g) => groups.includes(g)));
+            : presence.others.filter((session) => session.activities.some(({ target }) => target.id !== undefined && groups.includes(`${target.model.toLowerCase()}:${target.id}`)));
         // Plain useState + onChange — presence changes on connect/disconnect/activity
         // only (never on cursor traffic, a separate channel), so this fires
         // rarely; a frame of stale presence is harmless.

package/dist/react/useErrorListener.js

@@ -10,5 +10,5 @@ export function useErrorListener(listener) {
     }
     const listenerRef = useRef(listener);
     listenerRef.current = listener;
-    useEffect(() => context.subscribeError((error) => listenerRef.current(error)), [context]);
+    useEffect(() => context.subscribeError((error) => { listenerRef.current(error); }), [context]);
 }

package/dist/react/useMutationFailureListener.js

@@ -14,6 +14,6 @@ export function useMutationFailureListener(listener) {
         const engine = context.engine;
         if (!engine)
             return;
-        return engine.onMutationFailure((payload) => listenerRef.current(payload));
+        return engine.onMutationFailure((payload) => { listenerRef.current(payload); });
     }, [context, context.engine]);
 }

package/dist/surface.d.ts

@@ -19,7 +19,7 @@
  * tuple, so it is the one list of model-verb names a generated summary can
  * describe.
  */
-export declare const PUBLIC_MODEL_VERBS: readonly ["get", "read", "list", "listAll", "local", "create", "update", "delete", "claim", "onChange"];
+export declare const PUBLIC_MODEL_VERBS: readonly ["get", "read", "list", "listAll", "local", "presence", "create", "update", "delete", "claim", "onChange"];
 /**
  * The option keys accepted by `local.list` and `onChange`, matching the
  * keys of {@link LocalReadOptions}. Note that the lifecycle filter is named

package/dist/surface.js

@@ -26,6 +26,7 @@ export const PUBLIC_MODEL_VERBS = [
     'list',
     'listAll',
     'local',
+    'presence',
     'create',
     'update',
     'delete',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/humans",
-  "version": "0.60.0",
+  "version": "0.62.0",
   "description": "The optional human-facing local-state package for Ablo: presence, live queries, and React bindings.",
   "license": "Apache-2.0",
   "type": "module",
@@ -68,7 +68,7 @@
     "test:property": "jest --testPathPatterns=__tests__/property",
     "test:migrated-integration": "jest --testPathPatterns=__tests__/integration",
     "test:e2e": "E2E_TEST=true jest --config jest.e2e.config.ts",
-    "lint:eslint": "eslint . --cache",
+    "lint:eslint": "eslint . --cache --suppressions-location eslint-suppressions.json",
     "check:boundary": "node scripts/check-boundary.mjs",
     "test:integration": "npm run build && node scripts/check-package-integration.mjs",
     "lint:pkg": "publint"
@@ -84,7 +84,7 @@
     "directory": "packages/humans"
   },
   "dependencies": {
-    "@abloatai/transaction": "^0.60.0",
+    "@abloatai/transaction": "^0.62.0",
     "mobx": "^6.13.7",
     "uuid": "^11.1.0",
     "zod": "^4.4.3"
@@ -114,7 +114,6 @@
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "ts-jest": "^29.4.5",
-    "ts-node": "^10.9.2",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
     "ws": "^8.18.3"
   }

package/src/Ablo.ts

@@ -99,7 +99,7 @@ export type Ablo<S extends SchemaRecord> = AbloClient<S>;
  * const ablo = Ablo({ schema, session: { endpoint: '/api/ablo-session' } });
  * ```
  *
- * Server-side agents, workers, and services use `@abloatai/transaction`.
+ * Server-side agents, workers, and services use `@abloatai/ablo`.
  */
 export function Ablo<
   const S extends SchemaRecord,
@@ -117,7 +117,15 @@ export function Ablo<const S extends SchemaRecord>(
   //    resolver, the base URL, the logger, and this participant's identity —
   //    and fails on a misconfiguration before anything is constructed.
   const prelude = resolveClientPrelude(options);
-  const { internalOptions, authCredentials, logger, url, participantId, kind } = prelude;
+  const {
+    internalOptions,
+    authCredentials,
+    presenceSession,
+    logger,
+    url,
+    participantId,
+    kind,
+  } = prelude;
 
   // 2. The connection, built here in the composition root — before the plugin
   //    list resolves, so `PluginContext.transport` carries the instance a
@@ -134,6 +142,7 @@ export function Ablo<const S extends SchemaRecord>(
         baseUrl: url,
         kind,
         getAuthToken: authCredentials.getAuthToken,
+        presenceSession,
         collaborationEvents: [...(internalOptions.collaborationEvents ?? [])],
         syncGroups: [...(internalOptions.syncGroups ?? [])],
         deferConnect: true,
@@ -223,7 +232,7 @@ export function Ablo<const S extends SchemaRecord>(
 //
 // One default import, with types hung underneath via namespace dots:
 // `import { Ablo } from "@abloatai/humans"` gets the factory, its return type, and
-// every type a typical consumer references (`Ablo.Peer`,
+// every type a typical consumer references (`Ablo.PresenceSession`,
 // and so on) — all purely type-level, with zero runtime cost.
 //
 // The types still live in their canonical homes (`types/streams`, `principal`,
@@ -272,10 +281,10 @@ export namespace Ablo {
   export type Duration = _Streams.Duration;
 
   // ── Real-time multiplayer (flat — heterogeneous cluster) ──────────
-  export type PresenceStream = _Streams.PresenceStream;
+  export type Presence = import('./presence/index.js').ReactivePresence;
+  export type PresenceSession = import('@abloatai/transaction/presence').PresenceSession;
+  export type PresenceActivity = import('@abloatai/transaction/presence').PresenceActivity;
   export type ClaimStream = _Streams.ClaimStream;
-  export type Peer = _Streams.Peer;
-  export type Activity = _Streams.Activity;
   export type Claim = _Streams.Claim;
   export type ClaimRejection = _Streams.ClaimRejection;
   export type ClaimLost = _Streams.ClaimLost;

package/src/client.ts

@@ -18,7 +18,6 @@ import type {
   InferCreate,
   InferRow,
 } from '@abloatai/transaction/schema/schema';
-import type { PresenceStream } from '@abloatai/transaction/types/streams';
 import type { InstanceCache } from './local/InstanceCache.js';
 import type { SyncStoreContract } from './react/context.js';
 import type { SyncWebSocket, CoreSyncEventMap } from './local/sync/SyncWebSocket.js';
@@ -31,6 +30,7 @@ import type {
 import type { EffectiveAuthority } from '@abloatai/transaction/auth';
 import type { ReadDependency } from '@abloatai/transaction/coordination';
 import type { CapturedRow } from '@abloatai/transaction/transport/http';
+import type { ReactivePresence } from './presence/index.js';
 export type { LocalReadOptions } from './local/client/resourceTypes.js';
 
 /** The typed sync engine client — one property per model in the schema */
@@ -232,20 +232,15 @@ export type AbloClient<S extends SchemaRecord> = {
    */
   readonly syncStatus: SyncStatus;
 
-  /** The underlying schema */
-  readonly schema: Schema<S>;
-
   /**
-   * A real-time presence livestream — who else is connected on this engine's
-   * sync groups, what they're doing, and a write surface for announcing this
-   * user's own activity. It rides the engine's existing WebSocket; opening a
-   * participant for presence does not open a second socket. See
-   * {@link PresenceStream}.
-   *
-   * The reference is stable for the engine's lifetime — the underlying connection
-   * is rotated on `dispose()`, but this object stays the same.
+   * Session-owned live activity projected from this client's existing
+   * connection. Use `active` for every visible activity, `others` to exclude
+   * this session, and `forModel(model, id?)` for a model-native view.
    */
-  readonly presence: PresenceStream;
+  readonly presence: ReactivePresence;
+
+  /** The underlying schema */
+  readonly schema: Schema<S>;
 
   /**
    * @internal The supported coordination API is `ablo.<model>.claim`. This

package/src/humans.ts

@@ -7,7 +7,7 @@
  */
 import type { AbloPlugin, PluginContext, AppliedChange } from './plugin.js';
 import { AbloValidationError } from '@abloatai/transaction/errors';
-import { createPresenceStream, type AttachablePresenceStream } from './presenceStream.js';
+import { createPresence, type AttachablePresence } from './presence/index.js';
 import {
   buildStoreCluster,
   kStoreCluster,
@@ -16,7 +16,7 @@ import {
 } from './local/client/storeCluster.js';
 
 export interface HumansSurface {
-  readonly presence: AttachablePresenceStream;
+  readonly presence: AttachablePresence;
   readonly [kStoreCluster]?: StoreCluster;
 }
 
@@ -45,14 +45,7 @@ export function humans() {
         applyChanges = (changes) => { cluster.store.applyChangesToPool(changes); };
       }
       return {
-        presence: createPresenceStream(
-          {
-            participantId: context.participant?.id ?? '',
-            syncGroups: [...(context.syncGroups ?? [])],
-            isAgent: context.participant?.kind === 'agent',
-          },
-          context.transport ?? null,
-        ),
+        presence: createPresence(context.transport ?? null),
         ...(cluster ? { [kStoreCluster]: cluster } : {}),
       };
     },

package/src/local/BaseSyncedStore.ts

@@ -35,7 +35,6 @@ import {
   type GroupRemovedPayload,
   type BootstrapHint,
   type BootstrapDataEvent,
-  type PresenceUpdate,
   type EventMap,
   type DefaultCollaborationEvents,
   type SyncWebSocketEventMap,
@@ -238,7 +237,6 @@ export type {
   GroupRemovedPayload,
   BootstrapHint,
   BootstrapDataEvent,
-  PresenceUpdate,
 };
 
 // deriveSyncPlanFromSchema derives a sync plan from a schema and is
@@ -1500,7 +1498,6 @@ export class BaseSyncedStore<
       applyDeltaFrame: (deltas) => { this.applyDeltaFrame(deltas); },
       handleBootstrapRequired: (hint) => { this.handleBootstrapRequired(hint); },
       handleBootstrapData: (data) => { this.handleBootstrapData(data); },
-      handlePresenceUpdate: (data) => { this.handlePresenceUpdate(data); },
       performCredentialRefresh: () => this.performCredentialRefresh(),
       handleTerminalSessionError: (error) => { this.terminalSessionLifecycle.start(error); },
       nudgeReconnect: () => { this.nudgeReconnect(); },
@@ -1759,9 +1756,9 @@ export class BaseSyncedStore<
     const isCreate = !this.objectPool.get(model.id);
     if (isCreate) {
       model.updatedAt = new Date();
-      this.syncClient.add(model);
+      await this.syncClient.add(model);
     } else {
-      this.syncClient.update(model);
+      await this.syncClient.update(model);
     }
   }
 
@@ -1779,21 +1776,21 @@ export class BaseSyncedStore<
     const model = rowAsModel(entity);
     this.pendingDeletes.add(model.id);
     // SyncClient.delete handles: pool remove, transaction queue
-    this.syncClient.delete(model);
+    await this.syncClient.delete(model);
   }
 
   /** Archive a model. Accepts schema-inferred entity shapes (see `save`). */
   async archive<T extends { id: string; archivedAt?: Date | null }>(entity: T): Promise<void> {
     const model = rowAsModel(entity);
     model.archivedAt = new Date();
-    this.syncClient.archive(model);
+    await this.syncClient.archive(model);
   }
 
   /** Unarchive a model. Accepts schema-inferred entity shapes (see `save`). */
   async unarchive<T extends { id: string; archivedAt?: Date | null }>(entity: T): Promise<void> {
     const model = rowAsModel(entity);
     model.archivedAt = null;
-    this.syncClient.update(model);
+    await this.syncClient.update(model);
   }
 
 
@@ -1935,9 +1932,6 @@ export class BaseSyncedStore<
     this.updateSyncStatus({ state: 'syncing' });
   }
 
-  /** Handle presence_update event. Override in subclass. */
-  protected handlePresenceUpdate(_data: PresenceUpdate): void {}
-
   // ── Pending changes tracking ─────────────────────────────────────────────
 
   protected incrementPendingChanges(): void {

package/src/local/Model.ts

@@ -416,7 +416,7 @@ export abstract class Model {
     const original = this.getOriginalSnapshot();
     for (const key of keys) {
       if (key === 'id') continue;
-      const mod = modified?.get(key);
+      const mod = modified.get(key);
       if (mod) {
         out[key] = mod.old;
       } else if (original && key in original) {
@@ -463,25 +463,23 @@ export abstract class Model {
     const modelName = this.getModelName();
     const properties = getActiveRegistry().getProperties(modelName);
 
-    if (properties) {
-      const json = this.toJSON();
-      for (const [propName, metadata] of properties) {
-        // Check required fields
-        if (!metadata.nullable && !metadata.optional) {
-          const value = json[propName];
-          if (value == null || value === '') {
-            errors.push(`${propName} is required`);
-          }
+    const json = this.toJSON();
+    for (const [propName, metadata] of properties) {
+      // Check required fields
+      if (!metadata.nullable && !metadata.optional) {
+        const value = json[propName];
+        if (value == null || value === '') {
+          errors.push(`${propName} is required`);
         }
+      }
 
-        // Run custom validation rules
-        const rules = this.validationRules[propName];
-        if (rules) {
-          const value = json[propName];
-          for (const rule of rules) {
-            const error = rule(value);
-            if (error) errors.push(error);
-          }
+      // Run custom validation rules
+      const rules = this.validationRules[propName];
+      if (rules) {
+        const value = json[propName];
+        for (const rule of rules) {
+          const error = rule(value);
+          if (error) errors.push(error);
         }
       }
     }
@@ -816,18 +814,16 @@ export abstract class Model {
       result.archivedAt = this.archivedAt?.toISOString() ?? null;
     }
 
-    if (properties) {
-      const self = this as Record<string, unknown>;
-      for (const [propName, metadata] of properties) {
-        // Skip certain types
-        if (metadata.type === 'ephemeralProperty') continue;
-        if (metadata.type === 'referenceModel') continue;
-        if (metadata.type === 'referenceCollection') continue;
-
-        const value = self[propName];
-        if (value !== undefined) {
-          result[propName] = value;
-        }
+    const self = this as Record<string, unknown>;
+    for (const [propName, metadata] of properties) {
+      // Skip certain types
+      if (metadata.type === 'ephemeralProperty') continue;
+      if (metadata.type === 'referenceModel') continue;
+      if (metadata.type === 'referenceCollection') continue;
+
+      const value = self[propName];
+      if (value !== undefined) {
+        result[propName] = value;
       }
     }
 
@@ -946,14 +942,12 @@ export abstract class Model {
       const modelName = this.getModelName();
       const properties = getActiveRegistry().getProperties(modelName);
 
-      if (properties) {
-        const self = this as Record<string, unknown>;
-        for (const [propName, metadata] of properties) {
-          if (metadata.type === 'referenceCollection') {
-            const collection = self[propName] as Disposable | undefined;
-            if (collection?.dispose) {
-              collection.dispose();
-            }
+      const self = this as Record<string, unknown>;
+      for (const [propName, metadata] of properties) {
+        if (metadata.type === 'referenceCollection') {
+          const collection = self[propName] as Disposable | undefined;
+          if (collection) {
+            collection.dispose();
           }
         }
       }
@@ -983,11 +977,9 @@ export abstract class Model {
     const modelName = this.getModelName();
     const properties = getActiveRegistry().getProperties(modelName);
 
-    if (properties) {
-      const json = this.toJSON();
-      for (const [propName] of properties) {
-        snapshot[propName] = json[propName];
-      }
+    const json = this.toJSON();
+    for (const [propName] of properties) {
+      snapshot[propName] = json[propName];
     }
 
     return snapshot;
@@ -1034,19 +1026,17 @@ export abstract class Model {
 
     const properties = getActiveRegistry().getProperties(this.getModelName());
     const self = this as Record<string, unknown>;
-    if (properties) {
-      for (const [propName, metadata] of properties) {
-        if (
-          metadata.type === 'ephemeralProperty' ||
-          metadata.type === 'referenceModel' ||
-          metadata.type === 'referenceCollection'
-        ) {
-          continue;
-        }
-        // Reading through the observable getter is the point: it subscribes the
-        // enclosing MobX reaction to this field.
-        snapshot[propName] = self[propName];
+    for (const [propName, metadata] of properties) {
+      if (
+        metadata.type === 'ephemeralProperty' ||
+        metadata.type === 'referenceModel' ||
+        metadata.type === 'referenceCollection'
+      ) {
+        continue;
       }
+      // Reading through the observable getter is the point: it subscribes the
+      // enclosing MobX reaction to this field.
+      snapshot[propName] = self[propName];
     }
 
     for (const name of this.getDerivedGetterNames()) {

package/src/local/NetworkMonitor.ts

@@ -14,6 +14,8 @@ export class NetworkMonitor extends EventEmitter {
   // Only `navigator.onLine === false` means offline. Node 18+ exposes a global
   // `navigator` with `onLine === undefined`, so the naive `navigator.onLine`
   // would seed `false` (offline) on every server client — start optimistic.
+  // DOM types say `onLine` is boolean, but Node exposes it as undefined.
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-boolean-literal-compare
   private isOnline = !(typeof navigator !== 'undefined' && navigator.onLine === false);
   private lastOnlineCheck: Date = new Date();
 

package/src/local/RuntimeContext.ts

@@ -106,6 +106,8 @@ export const browserOnlineStatus: OnlineStatusProvider = {
     // signal. Don't use `!navigator.onLine`: Node 18+ exposes a global
     // `navigator` whose `onLine` is `undefined`, which `!` would read as offline —
     // wedging every Node/server client (agents, worker, MCP) into a false offline.
+    // DOM types say `onLine` is boolean, but Node exposes it as undefined.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-boolean-literal-compare
     return !(typeof navigator !== 'undefined' && navigator.onLine === false);
   },
 };