@abloatai/humans 0.61.0 → 0.63.0

package/src/local/InstanceCache.ts

@@ -1257,7 +1257,7 @@ export class InstanceCache {
   }
 
   private startGC(): void {
-    if (this.gcTimer) return;
+    if (this.gcTimer || this.config.gcInterval <= 0) return;
     this.gcTimer = setInterval(() => this.gc(), this.config.gcInterval);
     // Don't hold a headless Node process open just for pool GC — without
     // this, an agent that never calls disconnect() can never exit. No-op in

package/src/local/client/clientPrelude.ts

@@ -13,12 +13,17 @@
  */
 
 import type { ParticipantKind } from '@abloatai/transaction/types/participant';
+import { AbloValidationError } from '@abloatai/transaction/errors';
 import type { Logger } from '@abloatai/transaction/logger';
 import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
 import {
   createAuthCredentialSource,
   type AuthCredentialSource,
 } from '@abloatai/transaction/auth/credentialSource';
+import {
+  createPresenceSessionSource,
+  type PresenceSessionSource,
+} from '@abloatai/transaction/presence';
 import {
   assertBrowserSafety,
   readProcessEnv,
@@ -47,6 +52,7 @@ export interface ClientPrelude<S extends SchemaRecord> {
    */
   readonly credentialResolver: CredentialProvider | null;
   readonly authCredentials: AuthCredentialSource;
+  readonly presenceSession: PresenceSessionSource;
   readonly logger: Logger;
   readonly url: string;
   /**
@@ -69,6 +75,17 @@ export interface ClientPrelude<S extends SchemaRecord> {
 export function resolveClientPrelude<S extends SchemaRecord>(
   options: AbloOptions<S>,
 ): ClientPrelude<S> {
+  // This package owns the reactive materialiser, not transport selection.
+  // TypeScript can miss excess properties on generic calls and object spreads,
+  // so reject a misplaced selector before resolving any credentials or
+  // constructing local state. The core `Ablo` client owns `transport`.
+  if ('transport' in options) {
+    throw new AbloValidationError(
+      "The reactive client does not accept `transport`. Import `Ablo` from " +
+        "'@abloatai/ablo' when selecting HTTP or WebSocket transport.",
+      { code: 'invalid_options', param: 'transport' },
+    );
+  }
   const env = readProcessEnv();
   const internalOptions = {
     ...options,
@@ -79,9 +96,11 @@ export function resolveClientPrelude<S extends SchemaRecord>(
   const configuredApiKey = resolveApiKey(authInput);
   const configuredAuthToken = resolveAuthToken(authInput);
   const credentialResolver = resolveCredentialResolver(configuredApiKey);
+  const presenceSession = createPresenceSessionSource();
   const authCredentials = createAuthCredentialSource(
     // eslint-disable-next-line @typescript-eslint/no-deprecated -- load-bearing on the self-hosted path; server-internal cap-mint (Phase 3) not shipped
     internalOptions.capabilityToken ?? configuredAuthToken,
+    presenceSession,
   );
   rejectRemovedDatabaseUrlOption(options);
   assertBrowserSafety({
@@ -108,6 +127,7 @@ export function resolveClientPrelude<S extends SchemaRecord>(
     configuredAuthToken,
     credentialResolver,
     authCredentials,
+    presenceSession,
     logger,
     url: resolveBaseURL(authInput),
     participantId,

package/src/local/client/createInternalComponents.ts

@@ -90,6 +90,7 @@ export function createInternalComponents<S extends SchemaRecord>(
     syncGroups: options.syncGroups,
     instantModels: deriveInstantModels(schema),
     getAuthToken: auth?.getAuthToken,
+    presenceSession: auth?.presenceSession,
     runtime,
   });
 
@@ -120,6 +121,7 @@ export function createInternalComponents<S extends SchemaRecord>(
     schema,
     baseUrl: bootstrapBaseUrl,
     getAuthToken: auth?.getAuthToken,
+    presenceSession: auth?.presenceSession,
     runtime,
     // The one canonical log position; the loader reads its floor when a query
     // leaves so a late answer cannot overwrite a row the pool already knows to

package/src/local/client/createModelOperations.ts

@@ -143,6 +143,14 @@ 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 {
+  CollaborationEventContext,
+  ModelEventEnvelope,
+  ModelEventInput,
+  ModelEventTarget,
+} from '@abloatai/transaction/collaboration';
+import { modelEventInputSchema } from '@abloatai/transaction/collaboration';
 import {
   capturePointRead,
   prepareReadSet,
@@ -151,10 +159,16 @@ import {
 
 const ignoreSeparatelyObservedMutationFailure = (): undefined => undefined;
 const ignoreBestEffortClaimReleaseFailure = (): undefined => undefined;
+const ignoreBestEffortScopeFailure = (): undefined => undefined;
 
 export interface ModelClientMeta {
   readonly key: string;
   readonly typename: string;
+  readonly presence?: {
+    get(recordId: string): readonly PresenceSession[];
+    subscribe(listener: () => void): () => void;
+    read(recordId: string): () => void;
+  };
 }
 
 const modelClientMeta = new WeakMap<object, ModelClientMeta>();
@@ -177,6 +191,15 @@ type EntityHalf = Pick<ModelTarget, 'model' | 'id'>;
 // `ModelCollaboration<Item>` and `ModelCollaboration<Invoice>` the same type
 // 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[];
+  /** Subscribe once to the connection-owned presence projection. */
+  onPresenceChange(listener: () => void): () => void;
+  /** Start one session-owned read activity and return its cleanup. */
+  startReadPresence(target: EntityHalf): () => void;
+  modelEventTarget(recordId: string): ModelEventTarget;
+  sendModelEvent(input: ModelEventInput): void;
+  onModelEvent(listener: (event: ModelEventEnvelope) => void): () => void;
   /** Exact point evidence from the HTTP read boundary (stamp captured before data). */
   readPoint(model: string, id: string): Promise<{ data: unknown; stamp: number }>;
   /**
@@ -278,6 +301,8 @@ export interface ModelCollaboration {
    * test doubles can omit it.
    */
   enterScope?(scope: Record<string, string>): void | Promise<void>;
+  /** Release read interest previously acquired through {@link enterScope}. */
+  leaveScope?(scope: Record<string, string>): void | Promise<void>;
   /**
    * Pins a scope's sync group(s) — write intent: a row this client holds an
    * active claim on stays subscribed regardless of navigation. Same
@@ -336,6 +361,12 @@ interface ReactiveModelSurface<T, Fields = T> {
   /** The synchronous local-graph reads. */
   local: LocalReads<T>;
 
+  /** Sessions currently active on this model, optionally narrowed to one record. */
+  presence(recordId?: string): readonly PresenceSession[];
+
+  /** Lossy, model-record-addressed application events such as cursor or selection. */
+  events: ModelEvents;
+
   /**
    * Claim a row so other writers wait or are rejected until you're done, and
    * inspect or manage that coordination through the same namespace. Call it to
@@ -371,6 +402,50 @@ interface ReactiveModelSurface<T, Fields = T> {
   ): () => void;
 }
 
+export interface ModelEvents {
+  send(
+    recordId: string,
+    event: string,
+    payload: Readonly<Record<string, unknown>>,
+  ): void;
+  subscribe(
+    recordId: string,
+    event: string,
+    handler: (
+      payload: Readonly<Record<string, unknown>>,
+      context: CollaborationEventContext,
+    ) => void,
+  ): () => void;
+}
+
+function subscribeInModelScope(
+  collaboration: ModelCollaboration,
+  scope: Record<string, string>,
+  subscribe: () => () => void,
+): () => void {
+  let stopped = false;
+  let entered = false;
+  let unsubscribe: (() => void) | null = null;
+
+  void Promise.resolve(collaboration.enterScope?.(scope))
+    .then(() => {
+      entered = true;
+      if (stopped) {
+        void collaboration.leaveScope?.(scope);
+        return;
+      }
+      unsubscribe = subscribe();
+    })
+    .catch(ignoreBestEffortScopeFailure);
+
+  return () => {
+    if (stopped) return;
+    stopped = true;
+    unsubscribe?.();
+    if (entered) void collaboration.leaveScope?.(scope);
+  };
+}
+
 /**
  * Everything reachable as `ablo.<model>` on a reactive client.
  *
@@ -1403,6 +1478,54 @@ export function createModelOperations<T, C>(
   const operations: ModelOperations<T, C> = {
     local,
 
+    presence: (recordId?: string) => collaboration?.presence(registeredModelName, recordId) ?? [],
+
+    events: {
+      send(recordId, event, payload) {
+        if (!collaboration) return;
+        const target = collaboration.modelEventTarget(recordId);
+        const parsed = modelEventInputSchema.safeParse({ target, event, payload });
+        if (!parsed.success) {
+          throw new AbloValidationError('Invalid model event.', {
+            code: 'invalid_request',
+            param: 'event',
+            cause: parsed.error,
+          });
+        }
+        const scope = { [schemaKey]: recordId };
+        void Promise.resolve(collaboration.enterScope?.(scope))
+          .then(() => { collaboration.sendModelEvent(parsed.data); })
+          .finally(() => { void collaboration.leaveScope?.(scope); });
+      },
+      subscribe(recordId, event, handler) {
+        if (!collaboration) return () => undefined;
+        const target = collaboration.modelEventTarget(recordId);
+        const parsed = modelEventInputSchema.safeParse({ target, event, payload: {} });
+        if (!parsed.success) {
+          throw new AbloValidationError('Invalid model event subscription.', {
+            code: 'invalid_request',
+            param: 'event',
+            cause: parsed.error,
+          });
+        }
+        const scope = { [schemaKey]: recordId };
+        return subscribeInModelScope(collaboration, scope, () =>
+          collaboration.onModelEvent((incoming) => {
+            if (
+              incoming.target.model !== target.model ||
+              incoming.target.id !== target.id ||
+              incoming.target.syncGroup !== target.syncGroup ||
+              incoming.event !== parsed.data.event
+            ) return;
+            handler(incoming.payload, {
+              sender: incoming.sender,
+              sentAt: incoming.sentAt,
+            });
+          }),
+        );
+      },
+    },
+
     get,
     read,
 
@@ -1658,6 +1781,23 @@ export function createModelOperations<T, C>(
   modelClientMeta.set(operations, {
     key: schemaKey,
     typename: registeredModelName,
+    ...(collaboration
+      ? {
+          presence: {
+            get: (recordId: string) => collaboration.presence(registeredModelName, recordId),
+            subscribe: (listener: () => void) => collaboration.onPresenceChange(listener),
+            read: (recordId: string) => {
+              const scope = { [schemaKey]: recordId };
+              return subscribeInModelScope(collaboration, scope, () =>
+                collaboration.startReadPresence({
+                  model: registeredModelName,
+                  id: recordId,
+                }),
+              );
+            },
+          },
+        }
+      : {}),
   });
 
   return operations;

package/src/local/client/reactiveEngine.ts

@@ -39,7 +39,10 @@ import {
   bindClaimLifetime,
   claimLifetimeOf,
 } from '@abloatai/transaction/claims/lifetime';
-import type { AttachablePresenceStream } from '../../presenceStream.js';
+import {
+  attachPresenceToClient,
+  type AttachablePresence,
+} from '../../presence/index.js';
 import type { ClaimWaitOptions } from '@abloatai/transaction/types/streams';
 import type { Claim } from '@abloatai/transaction/types/streams';
 import { resolveApiKeyValue, resolveBootstrapBaseUrl } from '@abloatai/transaction/auth/apiKey';
@@ -75,6 +78,7 @@ import {
   prepareReadSet,
 } from '@abloatai/transaction/internal/read-set';
 import { contextOnChange } from '../sync/contextOnChange.js';
+import { resolveScopeGroups } from '../sync/scopeGroups.js';
 import type { ReadDependency } from '@abloatai/transaction/coordination';
 import type { CapturedRow } from '@abloatai/transaction/transport/http';
 
@@ -96,7 +100,7 @@ export interface ReactiveEngineInputs<S extends SchemaRecord> extends ClientPrel
   transport: SyncWebSocket;
   /** The humans() plugin's contribution — built by its `init`, already
    *  attached to the connection the context carried. */
-  presence: AttachablePresenceStream;
+  presence: AttachablePresence;
   /**
    * The store cluster `humans().init` constructed from the widened context:
    * this client's runtime, the component graph, and the store. The engine
@@ -183,7 +187,11 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
   // filter own echoes by participant id, seeded in `ready()` alongside the
   // locals above.
   const presenceStream = presence;
-  const claimStream = createClaimStream({ participantId, logger }, transport);
+  const claimStream = createClaimStream(
+    { logger },
+    transport,
+    presenceStream,
+  );
 
   // 6. Validate options up front — fail loudly on obviously wrong inputs so
   //    strangers don't get silent empty results. Validation errors are written
@@ -239,17 +247,11 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
     kind,
     logger,
     validationError: _validationError,
-    onIdentityResolved: ({ userId, participantKind, accountScope, syncGroups, authority }) => {
+    onIdentityResolved: ({ userId, participantKind, accountScope, authority }) => {
       selfParticipantId = userId;
       selfParticipantKind = participantKind;
       _resolvedOrganizationId = accountScope;
       _resolvedIdentity = authority;
-      presenceStream.setParticipant({
-        id: userId,
-        kind: participantKind,
-        syncGroups: [...syncGroups],
-      });
-      claimStream.setParticipant({ id: userId });
     },
   });
   const ready = lifecycle.ready;
@@ -573,6 +575,21 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
       modelRegistry,
       hydration,
       {
+        presence: (model, recordId) => presenceStream.forModel(model, recordId),
+        onPresenceChange: (listener) => presenceStream.onChange(listener),
+        startReadPresence: (target) => presenceStream.startRead(target),
+        modelEventTarget: (recordId) => {
+          const syncGroup = resolveScopeGroups({ [schemaKey]: recordId }, schema)[0];
+          if (syncGroup === undefined) {
+            throw new AbloValidationError('A model event requires a record scope.', {
+              code: 'invalid_request',
+              param: 'recordId',
+            });
+          }
+          return { model: registeredModelName, id: recordId, syncGroup };
+        },
+        sendModelEvent: (input) => { transport.sendModelEvent(input); },
+        onModelEvent: (listener) => transport.subscribe('model_event', listener),
         createClaim: (claimOptions) => publicClaims.create(claimOptions),
         // Lazily referenced: `commits` is declared below this loop, and this
         // only runs when someone actually writes a batch.
@@ -615,6 +632,7 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
         // stay fire-and-forget. It's soft either way — the store swallows
         // reconcile errors so read interest never makes a read reject or stall.
         enterScope: (scope) => store.enterScope(scope),
+        leaveScope: (scope) => store.leaveScope(scope),
         pinScope: (scope) => store.pinScope(scope),
       },
       readSetContext,
@@ -831,6 +849,11 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
       return store.syncStatus;
     },
 
+    // The humans capability owns the connection-backed presence projection.
+    // Keep it on the base client as well as in the plugin surface so the
+    // concrete AbloClient contract and runtime object agree before layering.
+    presence: presenceStream,
+
     schema,
 
     // ── Internal accessors for framework integration ─────────────────
@@ -848,10 +871,6 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
     /** The SyncWebSocket — for collaboration events (selection, cursors). */
     get _ws() { return store.getSyncWebSocket(); },
 
-    /** Presence livestream — same socket as entity sync, no second
-     *  connection. Stable reference across the engine's lifetime. */
-    presence: presenceStream,
-
 	    /** Claim livestream — same socket. Stable reference. */
 	    claims: publicClaims,
 
@@ -859,6 +878,8 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
 
   } as Ablo<S>;
 
+  attachPresenceToClient(engine, presenceStream);
+
   Object.defineProperty(engine, kReadEvidence, {
     value: {
       context: cluster.readSetContext,

package/src/local/query/client.ts

@@ -20,6 +20,7 @@ import { classifyRecovery, type RecoveryClass } from '@abloatai/transaction/erro
 import { withAuthHeaders, type AuthTokenGetter } from '@abloatai/transaction/auth/credentialSource';
 import { globalRuntime } from '../context.js';
 import type { RuntimeContext } from '../RuntimeContext.js';
+import type { PresenceSessionSource } from '@abloatai/transaction/presence';
 
 // ── Response validation ─────────────────────────────────────────────────
 //
@@ -78,6 +79,8 @@ export interface PostQueryOptions {
    * effect without rebuilding the client.
    */
   capabilityToken?: string;
+  /** Server-bound attribution shared with the owning WebSocket. */
+  presenceSession?: PresenceSessionSource;
 
   /**
    * An optional hook that tries to recover from a rejected credential. When a
@@ -128,6 +131,7 @@ export async function postQuery(
         options.getAuthToken,
         { 'Content-Type': 'application/json' },
         options.capabilityToken,
+        options.presenceSession,
       );
       const response = await fetch(url, {
         method: 'POST',

package/src/local/sync/BootstrapFetcher.ts

@@ -97,6 +97,8 @@ export interface BootstrapOptions {
    * {@link BootstrapFetcher.setAuthToken}.
    */
   getAuthToken?: AuthTokenGetter;
+  /** Server-bound attribution shared with the owning WebSocket. */
+  presenceSession?: import('@abloatai/transaction/presence').PresenceSessionSource;
   /** The owning client's runtime. Defaults to the module-global bridge. */
   runtime?: RuntimeContext;
 }
@@ -186,13 +188,14 @@ function classifyRequestFailure(
 }
 
 export class BootstrapFetcher {
-	  private options: Required<Omit<BootstrapOptions, 'baseUrl' | 'instantModels' | 'organizationId' | 'cacheScope' | 'getAuthToken' | 'runtime'>> & {
+	  private options: Required<Omit<BootstrapOptions, 'baseUrl' | 'instantModels' | 'organizationId' | 'cacheScope' | 'getAuthToken' | 'presenceSession' | 'runtime'>> & {
 	    baseUrl: string;
 	    instantModels?: string[];
 	    cacheScope: string | null;
 	    organizationId?: string;
 	    authToken?: string;
 	    getAuthToken?: AuthTokenGetter;
+	    presenceSession?: import('@abloatai/transaction/presence').PresenceSessionSource;
 	    runtime?: RuntimeContext;
 	  };
 
@@ -311,7 +314,12 @@ export class BootstrapFetcher {
     try {
       const res = await fetch(`${this.options.baseUrl}/schema`, {
         method: 'GET',
-        headers: withAuthHeaders(this.options.getAuthToken, {}, this.options.authToken),
+        headers: withAuthHeaders(
+          this.options.getAuthToken,
+          {},
+          this.options.authToken,
+          this.options.presenceSession,
+        ),
       });
       if (!res.ok) throw new Error(`schema read-back ${res.status}`);
       const body = (await res.json()) as { models?: unknown };
@@ -768,6 +776,7 @@ export class BootstrapFetcher {
 	      this.options.getAuthToken,
 	      { 'Content-Type': 'application/json' },
 	      this.options.authToken,
+	      this.options.presenceSession,
 	    );
 
     const controller = new AbortController();
@@ -977,7 +986,7 @@ export class BootstrapFetcher {
 	          'Content-Type': 'application/json',
 	          'Cache-Control': 'no-cache, no-store, must-revalidate',
 	          Pragma: 'no-cache',
-	        }, this.options.authToken),
+	        }, this.options.authToken, this.options.presenceSession),
         signal: controller.signal,
         cache: 'no-store', // Force browser to not cache
       });
@@ -1049,7 +1058,7 @@ export class BootstrapFetcher {
         method: 'GET',
         headers: withAuthHeaders(this.options.getAuthToken, {
           'Content-Type': 'application/json',
-        }, this.options.authToken),
+        }, this.options.authToken, this.options.presenceSession),
         signal: controller.signal,
       });
     } catch (error) {

package/src/local/sync/OnDemandLoader.ts

@@ -41,6 +41,7 @@ import type { LoadWhere, Query, WhereClause, WhereOp } from '../query/types.js';
 import { normalizeWhere } from '@abloatai/transaction/client/resources/where';
 import type { Schema } from '@abloatai/transaction/schema/schema';
 import type { LogPositionPort } from '../logPosition.js';
+import type { PresenceSessionSource } from '@abloatai/transaction/presence';
 
 export interface OnDemandLoaderOptions {
   readonly objectPool: InstanceCache;
@@ -58,6 +59,7 @@ export interface OnDemandLoaderOptions {
    * propagate without re-instantiating the coordinator.
    */
   readonly getAuthToken?: () => string | null;
+  readonly presenceSession?: PresenceSessionSource;
   /** @deprecated Use `getAuthToken`. */
   readonly getCapabilityToken?: () => string | null;
   /** The owning client's runtime. Defaults to the module-global bridge. */
@@ -647,6 +649,7 @@ export class OnDemandLoader {
         getAuthToken: this.authTokenProvider ?? undefined,
         recoverCredential: this.credentialRecovery ?? undefined,
         runtime: this.opts.runtime,
+        presenceSession: this.opts.presenceSession,
       },
       { queries: [query] },
     );

package/src/local/sync/SyncWebSocket.ts

@@ -36,7 +36,6 @@ export type {
   SyncCapabilities,
   BootstrapHint,
   BootstrapDataEvent,
-  PresenceUpdate,
   CoreSyncEventMap,
   DefaultCollaborationEvents,
   EventMap,
@@ -129,14 +128,10 @@ export class SyncWebSocket<
 
   /**
    * The open ritual, run by the transport between its `connected` emit and the
-   * heartbeat start: announce presence, tell the server where we left off,
+   * heartbeat start: tell the server where we left off,
    * request the deltas we missed, and start the catch-up poll.
    */
   protected override onOpened(): void {
-    // Send presence update with timezone (server sets presence to "online" on connect,
-    // this improves localTime accuracy by providing the user's actual timezone)
-    this.sendPresenceUpdate('online');
-
     // Immediately request incremental sync based on our stored cursor.
     // `requestIncrementalSync` is async — a bare call inside try/catch is a
     // rejection hole (the catch never sees it); route failures through
@@ -323,42 +318,6 @@ export class SyncWebSocket<
     this.sendAck(syncId);
   }
 
-  /**
-   * Send presence update to server.
-   * Use this for:
-   * - Updating timezone (improves localTime accuracy shown to other users)
-   * - Manual status changes (away, custom status)
-   *
-   * Note: "online" status is automatically set by server on WebSocket connect,
-   * and "offline" is set on disconnect. You don't need to call this for basic online/offline.
-   *
-   * @param status - "online", "away", or custom status string
-   * @param customStatus - Optional custom status message
-   */
-  sendPresenceUpdate(
-    status: 'online' | 'away' | 'offline' = 'online',
-    customStatus?: string
-  ): void {
-    if (!this.isConnected()) return;
-
-    const timezone = (() => {
-      try {
-        return Intl.DateTimeFormat().resolvedOptions().timeZone;
-      } catch {
-        return 'UTC';
-      }
-    })();
-
-    this.send({
-      type: 'presence_update',
-      payload: {
-        status,
-        timezone,
-        ...(customStatus ? { customStatus } : {}),
-      },
-    });
-  }
-
   /**
    * Stop the periodic catchup interval
    */