@abloatai/humans 0.60.0 → 0.62.0

package/src/local/SyncClient.ts

@@ -18,7 +18,7 @@ import { deepEqual, snapshotJsonValue } from '@abloatai/transaction/utils/json';
 import { LoadStrategy } from '@abloatai/transaction/types';
 import { globalRuntime } from './context.js';
 import type { RuntimeContext } from './RuntimeContext.js';
-import { AbloAuthenticationError, AbloError, AbloValidationError } from '@abloatai/transaction/errors';
+import { AbloError, AbloValidationError } from '@abloatai/transaction/errors';
 import { EventEmitter } from 'events';
 import { NetworkMonitor } from './NetworkMonitor.js';
 import {
@@ -51,9 +51,16 @@ import {
   type SyncState,
 } from './syncClientTypes.js';
 import type { BootstrapSnapshot } from './syncClientTypes.js';
+import {
+  batchUploadFiles,
+  uploadFile,
+  type BatchFileUploadOptions,
+  type FileUploadContext,
+  type FileUploadOptions,
+} from './fileUploads.js';
 
 export type { BootstrapSnapshot, RehydrationStats } from './syncClientTypes.js';
-
+const ignoreSeparatelyObservedMutationFailure = (): undefined => undefined;
 export class SyncClient extends EventEmitter {
   private objectPool: InstanceCache;
   private database: Database;
@@ -1057,7 +1064,7 @@ export class SyncClient extends EventEmitter {
     if (capturedChanges === undefined) return;
 
     this.objectPool.upsert(model, ModelScope.live);
-    this.stageMutation('update', model, capturedChanges);
+    void this.stageMutation('update', model, capturedChanges);
     this.notifyObservers({
       type: 'update',
       modelType: model.getModelName(),
@@ -1080,128 +1087,30 @@ export class SyncClient extends EventEmitter {
     return this.mutate('delete', model, () => this.objectPool.remove(model.id), options);
   }
 
-  /**
-   * Upload a file and create its attachment record. The upload runs through
-   * the {@link MutationQueue}, and a model is built from the server's
-   * response and added to the pool.
-   */
-  async uploadFile(
-    file: File,
-    options: {
-      id: string;
-      attachableType: string;
-      attachableId: string;
-      metadata?: Record<string, unknown>;
-    }
-  ): Promise<Model | null> {
-    if (!this.userId || !this.organizationId) {
-      throw new AbloAuthenticationError('Authentication required for file uploads', {
-        code: 'file_upload_auth_required',
-      });
-    }
-
-    try {
-      // Use MutationQueue to handle the upload mutation
-      const result = await this.mutationQueue.uploadAttachment(
-        file,
-        {
-          id: options.id,
-          attachableType: options.attachableType,
-          attachableId: options.attachableId,
-          metadata: options.metadata,
-        },
-        {
-          userId: this.userId,
-          organizationId: this.organizationId,
-        }
-      );
-
-      if (result) {
-        // Create model from response using ModelRegistry (generic — no concrete class import)
-        const model = this.objectPool.createFromData({
-          id: options.id,
-          ...result,
-        });
-
-        if (model) {
-          this.objectPool.add(model, ModelScope.live);
-          this.notifyObservers({
-            type: 'create',
-            modelType: model.getModelName(),
-            model,
-          });
-          return model;
-        }
-      }
-
-      return null;
-    } catch (error) {
-      this.runtime.observability.captureMutationFailure({
-        context: 'file-upload',
-        error: error instanceof Error ? error : new Error(String(error)),
-      });
-      throw error;
-    }
-  }
-
-  /**
-   * Batch upload files — single GraphQL call + parallel S3 PUTs.
-   *
-   * Returns the raw `Model[]` built by the object pool (typename is
-   * determined by the payload the server returns — currently always
-   * `Attachment`). The SDK has no knowledge of app-specific model classes,
-   * so it cannot honestly claim a narrower return type; consumers that
-   * need an `Attachment[]` project through their own typed accessor
-   * (e.g. `store.query.attachments.findMany({ where: { id: IN ids } })`)
-   * after the upload resolves.
-   */
-  async batchUploadFiles(
-    files: File[],
-    options: {
-      ids: string[];
-      attachableType: string;
-      attachableId: string;
-      metadata?: Record<string, unknown>;
-    }
-  ): Promise<Model[]> {
-    if (!this.userId || !this.organizationId) {
-      throw new AbloAuthenticationError('Authentication required for file uploads', {
-        code: 'file_upload_auth_required',
-      });
-    }
-
-    const items = options.ids.map((id) => ({
-      id,
-      attachableType: options.attachableType,
-      attachableId: options.attachableId,
-      metadata: options.metadata,
-    }));
-
-    const results = await this.mutationQueue.batchUploadAttachments(files, items, {
+  private fileUploadContext(): FileUploadContext {
+    return {
       userId: this.userId,
       organizationId: this.organizationId,
-    });
+      mutationQueue: this.mutationQueue,
+      objectPool: this.objectPool,
+      observability: this.runtime.observability,
+      notifyCreated: (model) => {
+        this.notifyObservers({ type: 'create', modelType: model.getModelName(), model });
+      },
+    };
+  }
 
-    const models: Model[] = [];
-    for (const result of results) {
-      const model = this.objectPool.createFromData({ ...result });
-      if (model) {
-        this.objectPool.add(model, ModelScope.live);
-        this.notifyObservers({
-          type: 'create',
-          modelType: model.getModelName(),
-          model,
-        });
-        models.push(model);
-      }
-    }
+  uploadFile(file: File, options: FileUploadOptions): Promise<Model | null> {
+    return uploadFile(this.fileUploadContext(), file, options);
+  }
 
-    return models;
+  batchUploadFiles(files: File[], options: BatchFileUploadOptions): Promise<Model[]> {
+    return batchUploadFiles(this.fileUploadContext(), files, options);
   }
 
   /** Archive model (ARCHIVE) - works offline */
-  archive(model: Model): void {
-    this.mutate('archive', model, () => { this.objectPool.updateScope(model.id, ModelScope.archived); });
+  archive(model: Model): Promise<void> | undefined {
+    return this.mutate('archive', model, () => { this.objectPool.updateScope(model.id, ModelScope.archived); });
   }
 
   /**
@@ -1243,7 +1152,7 @@ export class SyncClient extends EventEmitter {
     // Most internal callers intentionally use fire-and-forget writes. Observe
     // their rejection without replacing the exact promise returned to model
     // operations that need authoritative per-transaction confirmation.
-    void confirmation.catch(() => undefined);
+    void confirmation.catch(ignoreSeparatelyObservedMutationFailure);
     const pending = staging.then(() => undefined).catch((error: Error) => {
       this.runtime.observability.captureMutationFailure({
         context: `stage-mutation-${type}`,
@@ -1495,14 +1404,11 @@ export class SyncClient extends EventEmitter {
   markConnected(): void {
     this.setConnectionState('connected');
     // Browser online state may have marked the client connected before the
-    // WebSocket itself was ready. Always kick both durable lanes on the real
-    // socket event, even when the high-level state did not change.
-    void this.drainPendingConfirmations().catch((error: unknown) => {
-      this.runtime.observability.captureMutationFailure({
-        context: 'restore-commit-outbox',
-        error: error instanceof Error ? error : new Error(String(error)),
-      });
-    });
+    // WebSocket itself was ready. Kick the durable lanes through the staging
+    // barrier: a model mutation enters the in-memory store before its journal
+    // row finishes saving, so a direct reconnect drain can otherwise try to
+    // seal a source record that does not exist yet. The pending drain also
+    // starts the atomic commit lane, so one ordered entry point covers both.
     void this.processPendingMutations();
   }
 

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,12 +143,16 @@ import type {
   HttpModelClient,
 } from '@abloatai/transaction/transport/http';
 import type { ParticipantKind } from '@abloatai/transaction/types/participant';
+import type { PresenceSession } from '@abloatai/transaction/presence';
 import {
   capturePointRead,
   prepareReadSet,
   type ReadSetContext,
 } from '@abloatai/transaction/internal/read-set';
 
+const ignoreSeparatelyObservedMutationFailure = (): undefined => undefined;
+const ignoreBestEffortClaimReleaseFailure = (): undefined => undefined;
+
 export interface ModelClientMeta {
   readonly key: string;
   readonly typename: string;
@@ -174,6 +178,8 @@ 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[];
   /** Exact point evidence from the HTTP read boundary (stamp captured before data). */
   readPoint(model: string, id: string): Promise<{ data: unknown; stamp: number }>;
   /**
@@ -333,6 +339,9 @@ 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[];
+
   /**
    * 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
@@ -490,7 +499,7 @@ export function createModelOperations<T, C>(
       // await does not create an unhandled-rejection process error. Returning
       // the original promise preserves normal rejection for callers that do
       // await or attach their own catch handler.
-      void confirmation.catch(() => undefined);
+      void confirmation.catch(ignoreSeparatelyObservedMutationFailure);
       return confirmation;
     };
   };
@@ -660,9 +669,9 @@ export function createModelOperations<T, C>(
     // This runs after authoritative confirmation. A best-effort abandon frame
     // cannot turn a committed write into an apparent failure; the server has
     // already fulfilled the participant's claims as part of that commit.
-    await releaseClaimsForEntity(entityId).catch(() => undefined);
+    await releaseClaimsForEntity(entityId).catch(ignoreBestEffortClaimReleaseFailure);
     if (explicit && !explicitWasLocal) {
-      await explicit.release?.().catch(() => undefined);
+      await explicit.release?.().catch(ignoreBestEffortClaimReleaseFailure);
     }
   };
 
@@ -1376,7 +1385,7 @@ export function createModelOperations<T, C>(
         await waitForMutation(model, confirmation);
         return modelAsRow<T>(model);
       } finally {
-        await autoLease?.release?.().catch(() => {});
+        await autoLease?.release?.().catch(ignoreBestEffortClaimReleaseFailure);
       }
   });
 
@@ -1400,6 +1409,8 @@ export function createModelOperations<T, C>(
   const operations: ModelOperations<T, C> = {
     local,
 
+    presence: (recordId?: string) => collaboration?.presence(registeredModelName, recordId) ?? [],
+
     get,
     read,
 
@@ -1501,7 +1512,7 @@ export function createModelOperations<T, C>(
               const confirmation = syncClient.update(
                 model,
                 effective,
-                patch as Record<string, unknown>,
+                patch,
               );
               await waitForMutation(model, confirmation);
               return modelAsRow<T>(model);
@@ -1562,7 +1573,7 @@ export function createModelOperations<T, C>(
         const confirmation = syncClient.update(
           model,
           effective,
-          params.data as Record<string, unknown>,
+          params.data,
         );
         await waitForMutation(model, confirmation);
         const updated = modelAsRow<T>(model);

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';
@@ -96,7 +99,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 +186,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 +246,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 +574,7 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
       modelRegistry,
       hydration,
       {
+        presence: (model, recordId) => presenceStream.forModel(model, recordId),
         createClaim: (claimOptions) => publicClaims.create(claimOptions),
         // Lazily referenced: `commits` is declared below this loop, and this
         // only runs when someone actually writes a batch.
@@ -831,6 +833,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 +855,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 +862,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/fileUploads.ts

@@ -0,0 +1,97 @@
+/** File-upload behavior owned beneath the SyncClient boundary. */
+
+import { AbloAuthenticationError } from '@abloatai/transaction/errors';
+import type { RuntimeContext } from './RuntimeContext.js';
+import { Model } from './Model.js';
+import { InstanceCache, ModelScope } from './InstanceCache.js';
+import type { MutationQueue } from './transactions/mutations/MutationQueue.js';
+
+export interface FileUploadOptions {
+  readonly id: string;
+  readonly attachableType: string;
+  readonly attachableId: string;
+  readonly metadata?: Record<string, unknown>;
+}
+
+export interface BatchFileUploadOptions {
+  readonly ids: string[];
+  readonly attachableType: string;
+  readonly attachableId: string;
+  readonly metadata?: Record<string, unknown>;
+}
+
+export interface FileUploadContext {
+  readonly userId: string | null;
+  readonly organizationId: string | null;
+  readonly mutationQueue: MutationQueue;
+  readonly objectPool: InstanceCache;
+  readonly observability: RuntimeContext['observability'];
+  readonly notifyCreated: (model: Model) => void;
+}
+
+function authenticatedContext(context: FileUploadContext): {
+  readonly userId: string;
+  readonly organizationId: string;
+} {
+  if (!context.userId || !context.organizationId) {
+    throw new AbloAuthenticationError('Authentication required for file uploads', {
+      code: 'file_upload_auth_required',
+    });
+  }
+  return { userId: context.userId, organizationId: context.organizationId };
+}
+
+function acceptUploadedModel(
+  context: FileUploadContext,
+  data: Record<string, unknown>,
+): Model | null {
+  const model = context.objectPool.createFromData(data);
+  if (!model) return null;
+  context.objectPool.add(model, ModelScope.live);
+  context.notifyCreated(model);
+  return model;
+}
+
+export async function uploadFile(
+  context: FileUploadContext,
+  file: File,
+  options: FileUploadOptions,
+): Promise<Model | null> {
+  const identity = authenticatedContext(context);
+  try {
+    const result = await context.mutationQueue.uploadAttachment(file, {
+      id: options.id,
+      attachableType: options.attachableType,
+      attachableId: options.attachableId,
+      metadata: options.metadata,
+    }, identity);
+    return result
+      ? acceptUploadedModel(context, { id: options.id, ...result })
+      : null;
+  } catch (error) {
+    context.observability.captureMutationFailure({
+      context: 'file-upload',
+      error: error instanceof Error ? error : new Error(String(error)),
+    });
+    throw error;
+  }
+}
+
+export async function batchUploadFiles(
+  context: FileUploadContext,
+  files: File[],
+  options: BatchFileUploadOptions,
+): Promise<Model[]> {
+  const identity = authenticatedContext(context);
+  const items = options.ids.map((id) => ({
+    id,
+    attachableType: options.attachableType,
+    attachableId: options.attachableId,
+    metadata: options.metadata,
+  }));
+  const results = await context.mutationQueue.batchUploadAttachments(files, items, identity);
+  return results.flatMap((result) => {
+    const model = acceptUploadedModel(context, { ...result });
+    return model ? [model] : [];
+  });
+}

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] },
     );