@abloatai/humans 0.60.0 → 0.62.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/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(); },
@@ -1334,10 +1333,10 @@ 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);
         }
     }
     /** Save with an atomic server mutation (e.g., createSectionWithBlocks) */
@@ -1350,19 +1349,19 @@ 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(entity) {
         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(entity) {
         const model = rowAsModel(entity);
         model.archivedAt = null;
-        this.syncClient.update(model);
+        await this.syncClient.update(model);
     }
     // ── Query API ────────────────────────────────────────────────────────────
     // `ablo.<model>.local.get` / `.local.list` is the read surface for
@@ -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/Model.js

@@ -311,7 +311,7 @@ export class Model {
         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;
             }
@@ -358,25 +358,23 @@ export class Model {
         const errors = [];
         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);
                 }
             }
         }
@@ -679,20 +677,18 @@ export class Model {
         if (this.archivedAt !== undefined) {
             result.archivedAt = this.archivedAt?.toISOString() ?? null;
         }
-        if (properties) {
-            const self = this;
-            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;
+        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;
             }
         }
         return result;
@@ -793,14 +789,12 @@ export class Model {
         if (hasActiveRegistry()) {
             const modelName = this.getModelName();
             const properties = getActiveRegistry().getProperties(modelName);
-            if (properties) {
-                const self = this;
-                for (const [propName, metadata] of properties) {
-                    if (metadata.type === 'referenceCollection') {
-                        const collection = self[propName];
-                        if (collection?.dispose) {
-                            collection.dispose();
-                        }
+            const self = this;
+            for (const [propName, metadata] of properties) {
+                if (metadata.type === 'referenceCollection') {
+                    const collection = self[propName];
+                    if (collection) {
+                        collection.dispose();
                     }
                 }
             }
@@ -825,11 +819,9 @@ export class Model {
         const snapshot = {};
         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;
     }
@@ -874,17 +866,15 @@ export class Model {
             snapshot.archivedAt = this.archivedAt;
         const properties = getActiveRegistry().getProperties(this.getModelName());
         const self = this;
-        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()) {
             Object.defineProperty(snapshot, name, {

package/dist/local/NetworkMonitor.js

@@ -12,6 +12,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
     isOnline = !(typeof navigator !== 'undefined' && navigator.onLine === false);
     lastOnlineCheck = new Date();
     constructor(runtime = globalRuntime) {

package/dist/local/RuntimeContext.js

@@ -47,6 +47,8 @@ export const browserOnlineStatus = {
         // 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);
     },
 };

package/dist/local/SyncClient.d.ts

@@ -21,6 +21,7 @@ import type { WriteOptions } from './interfaces/index.js';
 import { LogPosition } from './logPosition.js';
 import { type RehydrationStats, type SyncObserver, type SyncState } from './syncClientTypes.js';
 import type { BootstrapSnapshot } from './syncClientTypes.js';
+import { type BatchFileUploadOptions, type FileUploadOptions } from './fileUploads.js';
 export type { BootstrapSnapshot, RehydrationStats } from './syncClientTypes.js';
 export declare class SyncClient extends EventEmitter {
     private readonly runtime;
@@ -201,36 +202,11 @@ export declare class SyncClient extends EventEmitter {
     get gql(): import("./interfaces/index.js").MutationExecutor;
     /** Delete model (DELETE) - works offline */
     delete(model: Model, options?: WriteOptions): Promise<void> | undefined;
-    /**
-     * 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.
-     */
-    uploadFile(file: File, options: {
-        id: string;
-        attachableType: string;
-        attachableId: string;
-        metadata?: Record<string, unknown>;
-    }): Promise<Model | null>;
-    /**
-     * 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.
-     */
-    batchUploadFiles(files: File[], options: {
-        ids: string[];
-        attachableType: string;
-        attachableId: string;
-        metadata?: Record<string, unknown>;
-    }): Promise<Model[]>;
+    private fileUploadContext;
+    uploadFile(file: File, options: FileUploadOptions): Promise<Model | null>;
+    batchUploadFiles(files: File[], options: BatchFileUploadOptions): Promise<Model[]>;
     /** Archive model (ARCHIVE) - works offline */
-    archive(model: Model): void;
+    archive(model: Model): Promise<void> | undefined;
     /**
      * Append a mutation to the pending queue and schedule its sync work.
      *
@@ -416,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;
@@ -425,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/SyncClient.js

@@ -14,7 +14,7 @@ import { deepEqual, snapshotJsonValue } from '@abloatai/transaction/utils/json';
 // ModelRegistry instance accessed via this.objectPool.registry
 import { LoadStrategy } from '@abloatai/transaction/types';
 import { globalRuntime } from './context.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 { MutationQueue, } from './transactions/mutations/MutationQueue.js';
@@ -25,6 +25,8 @@ import { createLocalMutationPort } from './transactions/localMutation.js';
 import { createReconnectDrain } from './transactions/reconnectDrain.js';
 import { DatabaseCommitOutboxStore } from './transactions/databaseCommitOutbox.js';
 import { toEpochMs, } from './syncClientTypes.js';
+import { batchUploadFiles, uploadFile, } from './fileUploads.js';
+const ignoreSeparatelyObservedMutationFailure = () => undefined;
 export class SyncClient extends EventEmitter {
     runtime;
     objectPool;
@@ -856,7 +858,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(),
@@ -876,99 +878,27 @@ export class SyncClient extends EventEmitter {
         this.mutationQueue.cancelTransactionsForModel(model.id);
         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, options) {
-        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, options) {
-        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, {
+    fileUploadContext() {
+        return {
             userId: this.userId,
             organizationId: this.organizationId,
-        });
-        const models = [];
-        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);
-            }
-        }
-        return models;
+            mutationQueue: this.mutationQueue,
+            objectPool: this.objectPool,
+            observability: this.runtime.observability,
+            notifyCreated: (model) => {
+                this.notifyObservers({ type: 'create', modelType: model.getModelName(), model });
+            },
+        };
+    }
+    uploadFile(file, options) {
+        return uploadFile(this.fileUploadContext(), file, options);
+    }
+    batchUploadFiles(files, options) {
+        return batchUploadFiles(this.fileUploadContext(), files, options);
     }
     /** Archive model (ARCHIVE) - works offline */
     archive(model) {
-        this.mutate('archive', model, () => { this.objectPool.updateScope(model.id, ModelScope.archived); });
+        return this.mutate('archive', model, () => { this.objectPool.updateScope(model.id, ModelScope.archived); });
     }
     /**
      * Append a mutation to the pending queue and schedule its sync work.
@@ -999,7 +929,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) => {
             this.runtime.observability.captureMutationFailure({
                 context: `stage-mutation-${type}`,
@@ -1225,14 +1155,11 @@ export class SyncClient extends EventEmitter {
     markConnected() {
         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) => {
-            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();
     }
     drainPendingConfirmations() {

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;
     /**