@abloatai/humans 0.61.0 → 0.63.0

package/dist/Ablo.d.ts

@@ -57,7 +57,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 declare function Ablo<const S extends SchemaRecord, const P extends readonly AbloPlugin[]>(options: AbloOptions<S> & {
     plugins: P;
@@ -97,10 +97,10 @@ export declare namespace Ablo {
     type ClaimTarget = _Streams.ClaimTarget;
     type PresenceTarget = _Streams.PresenceTarget;
     type Duration = _Streams.Duration;
-    type PresenceStream = _Streams.PresenceStream;
+    type Presence = import('./presence/index.js').ReactivePresence;
+    type PresenceSession = import('@abloatai/transaction/presence').PresenceSession;
+    type PresenceActivity = import('@abloatai/transaction/presence').PresenceActivity;
     type ClaimStream = _Streams.ClaimStream;
-    type Peer = _Streams.Peer;
-    type Activity = _Streams.Activity;
     type Claim = _Streams.Claim;
     type ClaimRejection = _Streams.ClaimRejection;
     type ClaimLost = _Streams.ClaimLost;

package/dist/Ablo.js

@@ -39,7 +39,7 @@ export function Ablo(options) {
     //    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
     //    plugin holds for the client's lifetime. It holds no socket until
@@ -55,6 +55,7 @@ export function Ablo(options) {
             baseUrl: url,
             kind,
             getAuthToken: authCredentials.getAuthToken,
+            presenceSession,
             collaborationEvents: [...(internalOptions.collaborationEvents ?? [])],
             syncGroups: [...(internalOptions.syncGroups ?? [])],
             deferConnect: true,

package/dist/client.d.ts

@@ -11,7 +11,6 @@
  * the factory back and creating a cycle.
  */
 import type { Schema, SchemaRecord, Model, 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';
@@ -21,6 +20,7 @@ import type { ClaimResource, CommitResource } from '@abloatai/transaction/client
 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 */
 export type AbloClient<S extends SchemaRecord> = {
@@ -197,19 +197,14 @@ 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
      * accessor is the internal stream that surface is built on and is not part of

package/dist/humans.d.ts

@@ -6,10 +6,10 @@
  * contracts.
  */
 import type { PluginContext, AppliedChange } from './plugin.js';
-import { type AttachablePresenceStream } from './presenceStream.js';
+import { type AttachablePresence } from './presence/index.js';
 import { kStoreCluster, type InternalAbloOptions, type StoreCluster } from './local/client/storeCluster.js';
 export interface HumansSurface {
-    readonly presence: AttachablePresenceStream;
+    readonly presence: AttachablePresence;
     readonly [kStoreCluster]?: StoreCluster;
 }
 export declare function humans(): {

package/dist/humans.js

@@ -1,5 +1,5 @@
 import { AbloValidationError } from '@abloatai/transaction/errors';
-import { createPresenceStream } from './presenceStream.js';
+import { createPresence } from './presence/index.js';
 import { buildStoreCluster, kStoreCluster, } from './local/client/storeCluster.js';
 export function humans() {
     let applyChanges = null;
@@ -22,11 +22,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/dist/index.d.ts

@@ -2,6 +2,7 @@ export { Ablo } from './Ablo.js';
 export type { AbloOptions, AbloReads, CredentialProvider, InternalAbloOptions, ModelClaim, ModelTarget, } from './Ablo.js';
 export { humans, type HumansSurface } from './humans.js';
 export type { AbloClient } from './client.js';
+export type { CollaborationEventContext } from '@abloatai/transaction/collaboration';
 export type { AbloPlugin, MergedSurface, PipelineStage, PluginById, TransportCapabilities, } from './plugin.js';
 export { defineMutators, type MutatorDefs, type MutatorFn, } from './local/mutators/defineMutators.js';
 export { createTransaction, type Transaction, type ReaderFindOptions, } from './local/mutators/Transaction.js';

package/dist/local/BaseSyncedStore.d.ts

@@ -18,7 +18,7 @@ import type { SyncClient } from './SyncClient.js';
 import type { Database, BootstrapResult, BootstrapRequirements } from './Database.js';
 import type { InstanceCache } from './InstanceCache.js';
 import { ModelRegistry } from './ModelRegistry.js';
-import { SyncWebSocket, type SyncDelta, type SyncGroupChangePayload, type GroupAddedPayload, type GroupRemovedPayload, type BootstrapHint, type BootstrapDataEvent, type PresenceUpdate, type EventMap, type DefaultCollaborationEvents, type SyncWebSocketEventMap } from './sync/SyncWebSocket.js';
+import { SyncWebSocket, type SyncDelta, type SyncGroupChangePayload, type GroupAddedPayload, type GroupRemovedPayload, type BootstrapHint, type BootstrapDataEvent, type EventMap, type DefaultCollaborationEvents, type SyncWebSocketEventMap } from './sync/SyncWebSocket.js';
 import { QueryProcessor } from './query/QueryProcessor.js';
 import { Model } from './Model.js';
 import type { RuntimeContext } from './RuntimeContext.js';
@@ -153,7 +153,7 @@ export declare const BOOTSTRAP_CONFIG: {
     readonly RETRY_DELAY_MS: 500;
 };
 export { ModelScope };
-export type { SyncDelta, SyncGroupChangePayload, GroupAddedPayload, GroupRemovedPayload, BootstrapHint, BootstrapDataEvent, PresenceUpdate, };
+export type { SyncDelta, SyncGroupChangePayload, GroupAddedPayload, GroupRemovedPayload, BootstrapHint, BootstrapDataEvent, };
 export { deriveSyncPlanFromSchema } from './sync/syncPlan.js';
 /**
  * The abstract base class that application-specific sync stores extend. It
@@ -791,8 +791,6 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     protected handleBootstrapRequired(_hint: BootstrapHint): void;
     /** Handle bootstrap_data event. Override in subclass. */
     protected handleBootstrapData(_data: BootstrapDataEvent): void;
-    /** Handle presence_update event. Override in subclass. */
-    protected handlePresenceUpdate(_data: PresenceUpdate): void;
     protected incrementPendingChanges(): void;
     protected decrementPendingChanges(): void;
     protected updateSyncStatus(updates: Partial<SyncStatus>): void;

package/dist/local/BaseSyncedStore.js

@@ -1105,7 +1105,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(); },
@@ -1466,8 +1465,6 @@ export class BaseSyncedStore {
     handleBootstrapData(_data) {
         this.updateSyncStatus({ state: 'syncing' });
     }
-    /** Handle presence_update event. Override in subclass. */
-    handlePresenceUpdate(_data) { }
     // ── Pending changes tracking ─────────────────────────────────────────────
     incrementPendingChanges() {
         runInAction(() => { this.syncStatus.pendingChanges++; });

package/dist/local/InstanceCache.js

@@ -1019,7 +1019,7 @@ export class InstanceCache {
         });
     }
     startGC() {
-        if (this.gcTimer)
+        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

package/dist/local/SyncClient.d.ts

@@ -392,7 +392,7 @@ export declare class SyncClient extends EventEmitter {
             awaitingDeltaCount: number;
             awaitingDeltaTransactions: {
                 id: string;
-                type: "update" | "create" | "delete" | "archive" | "unarchive";
+                type: "create" | "update" | "delete" | "archive" | "unarchive";
                 modelName: string;
                 modelId: string;
                 syncIdNeeded: number | undefined;
@@ -401,13 +401,13 @@ export declare class SyncClient extends EventEmitter {
             }[];
             pendingTransactions: {
                 id: string;
-                type: "update" | "create" | "delete" | "archive" | "unarchive";
+                type: "create" | "update" | "delete" | "archive" | "unarchive";
                 modelName: string;
                 modelId: string;
             }[];
             executingTransactions: {
                 id: string;
-                type: "update" | "create" | "delete" | "archive" | "unarchive";
+                type: "create" | "update" | "delete" | "archive" | "unarchive";
                 modelName: string;
                 modelId: string;
             }[];

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

@@ -15,6 +15,7 @@ import type { ParticipantKind } from '@abloatai/transaction/types/participant';
 import type { Logger } from '@abloatai/transaction/logger';
 import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
 import { type AuthCredentialSource } from '@abloatai/transaction/auth/credentialSource';
+import { type PresenceSessionSource } from '@abloatai/transaction/presence';
 import { type CredentialProvider } from '@abloatai/transaction/auth/apiKey';
 import type { AbloOptions, InternalAbloOptions } from './options.js';
 /** What one pass over the options bag settles, for the builders downstream. */
@@ -31,6 +32,7 @@ export interface ClientPrelude<S extends SchemaRecord> {
      */
     readonly credentialResolver: CredentialProvider | null;
     readonly authCredentials: AuthCredentialSource;
+    readonly presenceSession: PresenceSessionSource;
     readonly logger: Logger;
     readonly url: string;
     /**

package/dist/local/client/clientPrelude.js

@@ -11,7 +11,9 @@
  * `./Ablo.ts` calls this once and hands the result to whichever client the
  * plugin list selected.
  */
+import { AbloValidationError } from '@abloatai/transaction/errors';
 import { createAuthCredentialSource, } from '@abloatai/transaction/auth/credentialSource';
+import { createPresenceSessionSource, } from '@abloatai/transaction/presence';
 import { assertBrowserSafety, readProcessEnv, rejectRemovedDatabaseUrlOption, resolveApiKey, resolveAuthToken, resolveBaseURL, resolveCredentialResolver, warnIfCliKeyMismatch, } from '@abloatai/transaction/auth/apiKey';
 import { createConsoleLogger, resolveLogLevel } from './consoleLogger.js';
 /**
@@ -22,6 +24,14 @@ import { createConsoleLogger, resolveLogLevel } from './consoleLogger.js';
  * different project than the one being addressed (a warning, not a throw).
  */
 export function resolveClientPrelude(options) {
+    // 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,
@@ -32,9 +42,10 @@ export function resolveClientPrelude(options) {
     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);
+    internalOptions.capabilityToken ?? configuredAuthToken, presenceSession);
     rejectRemovedDatabaseUrlOption(options);
     assertBrowserSafety({
         apiKey: configuredApiKey,
@@ -56,6 +67,7 @@ export function resolveClientPrelude(options) {
         configuredAuthToken,
         credentialResolver,
         authCredentials,
+        presenceSession,
         logger,
         url: resolveBaseURL(authInput),
         participantId,

package/dist/local/client/createInternalComponents.js

@@ -39,6 +39,7 @@ export function createInternalComponents(input) {
         syncGroups: options.syncGroups,
         instantModels: deriveInstantModels(schema),
         getAuthToken: auth?.getAuthToken,
+        presenceSession: auth?.presenceSession,
         runtime,
     });
     const database = new Database(modelRegistry, bootstrapHelper, {
@@ -61,6 +62,7 @@ export function createInternalComponents(input) {
         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/dist/local/client/createModelOperations.d.ts

@@ -22,10 +22,17 @@ 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 { 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[];
+        subscribe(listener: () => void): () => void;
+        read(recordId: string): () => void;
+    };
 }
 export declare function getModelClientMeta(modelClient: unknown): ModelClientMeta | undefined;
 /**
@@ -34,6 +41,15 @@ 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[];
+    /** 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;
@@ -135,6 +151,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
@@ -187,6 +205,10 @@ export interface LocalReads<T> {
 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
@@ -217,6 +239,10 @@ interface ReactiveModelSurface<T, Fields = T> {
     /** Subscribe to changes; the callback runs on every change. */
     onChange(callback: (entities: T[]) => void, options?: LocalReadOptions<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;
+}
 /**
  * Everything reachable as `ablo.<model>` on a reactive client.
  *

package/dist/local/client/createModelOperations.js

@@ -30,15 +30,40 @@ import { declaredMeta } from '@abloatai/transaction/claims';
 import { ModelScope } from '@abloatai/transaction/types';
 import { bindClaimLifetime, claimLifetimeOf, } from '@abloatai/transaction/claims/lifetime';
 import { claimQueueView, resolveClaimContentionOptions, } from '@abloatai/transaction/client/resources/modelOperations';
+import { modelEventInputSchema } from '@abloatai/transaction/collaboration';
 import { capturePointRead, prepareReadSet, } from '@abloatai/transaction/internal/read-set';
 const ignoreSeparatelyObservedMutationFailure = () => undefined;
 const ignoreBestEffortClaimReleaseFailure = () => undefined;
+const ignoreBestEffortScopeFailure = () => undefined;
 const modelClientMeta = new WeakMap();
 export function getModelClientMeta(modelClient) {
     if (typeof modelClient !== 'object' || modelClient === null)
         return undefined;
     return modelClientMeta.get(modelClient);
 }
+function subscribeInModelScope(collaboration, scope, subscribe) {
+    let stopped = false;
+    let entered = false;
+    let unsubscribe = 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);
+    };
+}
 export function createModelOperations(schemaKey, registeredModelName, objectPool, syncClient, registry, 
 /**
  * The one thing this factory asks of the loader: fetch rows for a model.
@@ -829,6 +854,51 @@ hydration, collaboration, readSetContext) {
     }
     const operations = {
         local,
+        presence: (recordId) => 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,
         // No automatic scope enrolment on bulk `list`: that would subscribe to an
@@ -1018,6 +1088,21 @@ hydration, collaboration, readSetContext) {
     modelClientMeta.set(operations, {
         key: schemaKey,
         typename: registeredModelName,
+        ...(collaboration
+            ? {
+                presence: {
+                    get: (recordId) => collaboration.presence(registeredModelName, recordId),
+                    subscribe: (listener) => collaboration.onPresenceChange(listener),
+                    read: (recordId) => {
+                        const scope = { [schemaKey]: recordId };
+                        return subscribeInModelScope(collaboration, scope, () => collaboration.startReadPresence({
+                            model: registeredModelName,
+                            id: recordId,
+                        }));
+                    },
+                },
+            }
+            : {}),
     });
     return operations;
 }

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

@@ -14,7 +14,7 @@
 import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
 import type { StoreCluster } from './storeCluster.js';
 import type { SyncWebSocket } from '../sync/SyncWebSocket.js';
-import type { AttachablePresenceStream } from '../../presenceStream.js';
+import { type AttachablePresence } from '../../presence/index.js';
 import type { AbloOptions } from './options.js';
 import type { ClientPrelude } from './clientPrelude.js';
 import type { AbloClient as Ablo } from '../../client.js';
@@ -36,7 +36,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

package/dist/local/client/reactiveEngine.js

@@ -20,6 +20,7 @@ import { startStoreLifecycle } from './storeLifecycle.js';
 import { createClaimStream } from '../sync/createClaimStream.js';
 import { awaitClaimGrant } from '@abloatai/transaction/claims';
 import { bindClaimLifetime, claimLifetimeOf, } from '@abloatai/transaction/claims/lifetime';
+import { attachPresenceToClient, } from '../../presence/index.js';
 import { resolveApiKeyValue, resolveBootstrapBaseUrl } from '@abloatai/transaction/auth/apiKey';
 import { claimAttemptFailure, emitClaimStatus, } from '@abloatai/transaction/client/resources/modelOperations';
 import { createModelOperations } from './createModelOperations.js';
@@ -28,6 +29,7 @@ import { modelReadResponseSchema, commitRecordSchema, commitRecordListSchema, co
 import { translateHttpError, } from '@abloatai/transaction/errors';
 import { kReadEvidence, prepareReadSet, } from '@abloatai/transaction/internal/read-set';
 import { contextOnChange } from '../sync/contextOnChange.js';
+import { resolveScopeGroups } from '../sync/scopeGroups.js';
 export function buildReactiveEngine(inputs) {
     const { options, internalOptions, url, logger, configuredApiKey, configuredAuthToken, credentialResolver, authCredentials, transport, participantId, kind, presence, cluster, } = inputs;
     const schema = options.schema;
@@ -80,7 +82,7 @@ export function buildReactiveEngine(inputs) {
     // 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
     //    into `store.syncStatus` (the single source of truth).
@@ -131,17 +133,11 @@ export function buildReactiveEngine(inputs) {
         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;
@@ -398,6 +394,21 @@ 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),
+            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.
@@ -436,6 +447,7 @@ export function buildReactiveEngine(inputs) {
             // 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);
     }
@@ -599,6 +611,10 @@ export function buildReactiveEngine(inputs) {
         get syncStatus() {
             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 ─────────────────
         // These expose internal components for consumers that need direct
@@ -611,13 +627,11 @@ export function buildReactiveEngine(inputs) {
         get _pool() { return objectPool; },
         /** 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,
         commits,
     };
+    attachPresenceToClient(engine, presenceStream);
     Object.defineProperty(engine, kReadEvidence, {
         value: {
             context: cluster.readSetContext,

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

@@ -15,6 +15,7 @@ import type { QueryBatch, QueryBatchResult } from './types.js';
 import { type RecoveryClass } from '@abloatai/transaction/errorCodes';
 import { type AuthTokenGetter } from '@abloatai/transaction/auth/credentialSource';
 import type { RuntimeContext } from '../RuntimeContext.js';
+import type { PresenceSessionSource } from '@abloatai/transaction/presence';
 export interface PostQueryOptions {
     /**
      * Full base URL of the sync server including the `/api` prefix.
@@ -38,6 +39,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
      * query comes back with a 401, its {@link RecoveryClass} is passed here: a

package/dist/local/query/client.js

@@ -74,7 +74,7 @@ export async function postQuery(options, batch) {
         try {
             // Recomputed per attempt: `withAuthHeaders` reads the live credential
             // source, so a replay after recovery carries the freshly-minted key.
-            const headers = withAuthHeaders(options.getAuthToken, { 'Content-Type': 'application/json' }, options.capabilityToken);
+            const headers = withAuthHeaders(options.getAuthToken, { 'Content-Type': 'application/json' }, options.capabilityToken, options.presenceSession);
             const response = await fetch(url, {
                 method: 'POST',
                 headers,

package/dist/local/sync/BootstrapFetcher.d.ts

@@ -94,6 +94,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;
 }