@abloatai/humans 0.59.2 → 0.60.0

package/src/local/BaseSyncedStore.ts

@@ -18,9 +18,9 @@ import { ConnectionManager } from './sync/ConnectionManager.js';
 import { contextLogger, contextSocketObservability } from './sync/contextPorts.js';
 import { SubscriptionManager } from './sync/SubscriptionManager.js';
 import {
-  resolveParticipantSyncGroups,
-  type ParticipantScope,
-} from './sync/participants.js';
+  resolveScopeGroups,
+  type GroupScope,
+} from './sync/scopeGroups.js';
 import type { SyncClient } from './SyncClient.js';
 import type { Database, BootstrapResult, BootstrapRequirements } from './Database.js';
 import type { BootstrapData } from './sync/BootstrapFetcher.js';
@@ -394,8 +394,8 @@ export class BaseSyncedStore<
   // {@link SubscriptionManager.reconcile}); the on-connect `resync` pushes
   // whatever interest accumulated.
 
-  private scopeToGroups(scope: ParticipantScope): string[] {
-    return resolveParticipantSyncGroups(scope, this.schema);
+  private scopeToGroups(scope: GroupScope): string[] {
+    return resolveScopeGroups(scope, this.schema);
   }
 
   /**
@@ -406,7 +406,7 @@ export class BaseSyncedStore<
    * Hydration is best-effort — a failed backfill never rejects `enterScope`,
    * and the live delta stream keeps flowing regardless.
    */
-  enterScope(scope: ParticipantScope, opts?: { hydrate?: boolean }): Promise<void> {
+  enterScope(scope: GroupScope, opts?: { hydrate?: boolean }): Promise<void> {
     const groups = this.scopeToGroups(scope);
     const subscribed = Promise.all(groups.map((g) => this.areaOfInterest.enter(g))).then(
       () => undefined,
@@ -456,21 +456,21 @@ export class BaseSyncedStore<
   }
 
   /** Leave a scope → its groups go warm (hysteresis), then drop on sweep. */
-  leaveScope(scope: ParticipantScope): Promise<void> {
+  leaveScope(scope: GroupScope): Promise<void> {
     return Promise.all(
       this.scopeToGroups(scope).map((g) => this.areaOfInterest.leave(g)),
     ).then(() => undefined);
   }
 
   /** Pin a scope (active claim / prominence) → never warms while pinned. */
-  pinScope(scope: ParticipantScope): Promise<void> {
+  pinScope(scope: GroupScope): Promise<void> {
     return Promise.all(
       this.scopeToGroups(scope).map((g) => this.areaOfInterest.pin(g)),
     ).then(() => undefined);
   }
 
   /** Release a pin → the group transitions to warm rather than dropping. */
-  unpinScope(scope: ParticipantScope): Promise<void> {
+  unpinScope(scope: GroupScope): Promise<void> {
     return Promise.all(
       this.scopeToGroups(scope).map((g) => this.areaOfInterest.unpin(g)),
     ).then(() => undefined);

package/src/local/SyncClient.ts

@@ -935,7 +935,8 @@ export class SyncClient extends EventEmitter {
     model: Model,
     poolAction: () => void,
     writeOptions?: WriteOptions,
-  ): void {
+    capturedChangesOverride?: Record<string, unknown>,
+  ): Promise<void> | undefined {
     // No-op UPDATE guard (O(1)). An update with no dirty fields would travel
     // to the server, get dropped by `coalesceOperations` Rule 4 (empty input),
     // and — if it was the only op — come back as `lastSyncId: 0`. That trips
@@ -949,24 +950,32 @@ export class SyncClient extends EventEmitter {
     // is false → we fall through to the normal path rather than risk dropping a
     // real write. Only a genuine Model with an empty dirty-set is skipped.
     const hasChanges: unknown = model.hasChanges;
-    if (type === 'update' && hasChanges === false) {
-      return;
+    if (
+      type === 'update' &&
+      hasChanges === false &&
+      capturedChangesOverride === undefined
+    ) {
+      return Promise.resolve();
     }
 
     // Capture changes before the pool action runs. Pool operations —
     // upsert in particular — can clear the model's local changes, so
     // capturing first ensures they are never lost.
-    const capturedChanges =
-      type === 'update' || type === 'create' ? this.captureModelChanges(model) : undefined;
+    const capturedChanges = capturedChangesOverride !== undefined
+      ? Object.freeze({ ...capturedChangesOverride })
+      : type === 'update' || type === 'create'
+        ? this.captureModelChanges(model)
+        : undefined;
 
     poolAction();
-    this.stageMutation(type, model, capturedChanges, writeOptions);
+    const confirmation = this.stageMutation(type, model, capturedChanges, writeOptions);
     this.notifyObservers({
       type,
       modelType: model.getModelName(),
       model: type !== 'delete' ? model : undefined,
       modelId: model.id,
     });
+    return confirmation;
 
     // QueryProcessor uses `models:changed` to invalidate caches. Coalesce
     // to one event per microtask: a paste of 100 rows should re-run
@@ -1004,13 +1013,23 @@ export class SyncClient extends EventEmitter {
   }
 
   /** Add new model (CREATE) - works offline */
-  add(model: Model, options?: WriteOptions): void {
-    this.mutate('create', model, () => { this.objectPool.add(model, ModelScope.live); }, options);
+  add(model: Model, options?: WriteOptions): Promise<void> | undefined {
+    return this.mutate('create', model, () => { this.objectPool.add(model, ModelScope.live); }, options);
   }
 
   /** Update existing model (UPDATE) - works offline */
-  update(model: Model, options?: WriteOptions): void {
-    this.mutate('update', model, () => { this.objectPool.upsert(model, ModelScope.live); }, options);
+  update(
+    model: Model,
+    options?: WriteOptions,
+    capturedChanges?: Record<string, unknown>,
+  ): Promise<void> | undefined {
+    return this.mutate(
+      'update',
+      model,
+      () => { this.objectPool.upsert(model, ModelScope.live); },
+      options,
+      capturedChanges,
+    );
   }
 
   /**
@@ -1055,10 +1074,10 @@ export class SyncClient extends EventEmitter {
   }
 
   /** Delete model (DELETE) - works offline */
-  delete(model: Model, options?: WriteOptions): void {
+  delete(model: Model, options?: WriteOptions): Promise<void> | undefined {
     // Clear pending mutations first to prevent "not found" errors on fast delete
     this.mutationQueue.cancelTransactionsForModel(model.id);
-    this.mutate('delete', model, () => this.objectPool.remove(model.id), options);
+    return this.mutate('delete', model, () => this.objectPool.remove(model.id), options);
   }
 
   /**
@@ -1204,8 +1223,8 @@ export class SyncClient extends EventEmitter {
     model: Model,
     capturedChanges?: Record<string, unknown>,
     writeOptions?: WriteOptions,
-  ): void {
-    if (this.isDisposed) return;
+  ): Promise<void> | undefined {
+    if (this.isDisposed) return Promise.resolve();
     if (!this.userId || !this.organizationId) {
       this.mutationQueue.deferMutation(type, model, capturedChanges, writeOptions);
       return;
@@ -1218,6 +1237,13 @@ export class SyncClient extends EventEmitter {
       capturedChanges,
       writeOptions,
     );
+    const confirmation = staging.then(async (transaction) => {
+      await transaction.confirmation;
+    });
+    // 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);
     const pending = staging.then(() => undefined).catch((error: Error) => {
       this.runtime.observability.captureMutationFailure({
         context: `stage-mutation-${type}`,
@@ -1228,6 +1254,7 @@ export class SyncClient extends EventEmitter {
     });
     this.pendingStages.add(pending);
     void pending.finally(() => this.pendingStages.delete(pending));
+    return confirmation;
   }
 
   private scheduleSync(): void {

package/src/local/client/createModelOperations.ts

@@ -6,7 +6,7 @@
  * `read` and `list`, with the same point lookup restricted to the local graph under
  * `local`, the writes `create`, `update`, and `delete`, the coordination
  * namespace `claim` (callable as `claim({ id })`, plus `claim.state`,
- * `claim.queue`, `claim.release`, and `claim.reorder`), `join`, and `onChange`.
+ * `claim.queue`, `claim.release`, and `claim.reorder`), and `onChange`.
  * The factory returns a plain object; the client assembles the `ablo.<model>`
  * lookup table from one of these per model.
  */
@@ -66,7 +66,6 @@ import type { ModelRegistry } from '../ModelRegistry.js';
 import type { InstanceCache } from '../InstanceCache.js';
 import type { SyncClient } from '../SyncClient.js';
 import type { OnDemandLoader } from '../sync/OnDemandLoader.js';
-import type { JoinedParticipant } from '../sync/participants.js';
 import { ModelScope } from '@abloatai/transaction/types';
 import type {
   Duration,
@@ -112,7 +111,6 @@ export type {
   ModelCreateParams,
   ModelUpdateParams,
   ModelDeleteParams,
-  JoinOptions,
 } from '@abloatai/transaction/client/resources/modelOperations';
 export type { Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, HeldLease };
 
@@ -126,7 +124,6 @@ import type {
   ClaimAttemptEvent,
   ClaimQueueView,
   ClaimReorderParams,
-  JoinOptions,
   LocalCountOptions,
   LocalReadOptions,
   ModelCreateManyParams,
@@ -284,17 +281,6 @@ export interface ModelCollaboration {
    * fire-and-forget, best-effort semantics as `enterScope`.
    */
   pinScope?(scope: Record<string, string>): void | Promise<void>;
-  /**
-   * Opens a presence and claim subscription on this model's sync group(s) and
-   * returns the live participant handle. Backs `ablo.<model>.join(ids)`.
-   * WebSocket only, since presence needs a live socket; it is absent on other
-   * client constructions, where the surface throws a clear error.
-   */
-  createJoin?(
-    modelKey: string,
-    ids: string | readonly string[],
-    options?: JoinOptions,
-  ): Promise<JoinedParticipant>;
 }
 
 
@@ -375,26 +361,6 @@ interface ReactiveModelSurface<T, Fields = T> {
    */
   claim: ClaimApi<T, Fields>;
 
-  /**
-   * Joins the sync group(s) for one or more rows of this model and returns a
-   * live participant handle — presence (`.peers`), the scoped claim stream
-   * (`.claims`), and `.leave()` / `await using` disposal. This is a presence
-   * subscription: it reports who else is here and what they hold, not row
-   * values changing — for the latter, use `onChange`.
-   *
-   * WebSocket only: presence needs a live socket, so this is absent on HTTP
-   * clients and throws on any non-WebSocket construction.
-   *
-   * ```ts
-   * await using participant = await ablo.sections.join(sectionIds, { ttl: '5m' });
-   * participant.peers; // who else is here
-   * ```
-   */
-  join(
-    ids: string | readonly string[],
-    options?: JoinOptions,
-  ): Promise<JoinedParticipant>;
-
   /** Subscribe to changes; the callback runs on every change. */
   onChange(
     callback: (entities: T[]) => void,
@@ -546,7 +512,10 @@ export function createModelOperations<T, C>(
     return rows.map((row) => modelAsRow<T>(row));
   };
 
-  const waitForMutation = async (model: Model): Promise<void> => {
+  const waitForMutation = async (
+    model: Model,
+    exactConfirmation?: Promise<void>,
+  ): Promise<void> => {
     // Model writes are optimistic locally, but their promise has one stable
     // meaning: authoritative confirmation. Callers that do not need the
     // barrier can keep using the row immediately and leave the promise to the
@@ -558,7 +527,8 @@ export function createModelOperations<T, C>(
     // coalescer and producing one SQL transaction per delta.
     await Promise.resolve();
     await syncClient.syncNow();
-    await syncClient.waitForConfirmation(model.getModelName(), model.id);
+    if (exactConfirmation) await exactConfirmation;
+    else await syncClient.waitForConfirmation(model.getModelName(), model.id);
   };
 
   // Claims this model surface currently holds, keyed by the exact grant id.
@@ -1402,8 +1372,8 @@ export function createModelOperations<T, C>(
               }
             : {}),
         };
-        syncClient.add(model, effective);
-        await waitForMutation(model);
+        const confirmation = syncClient.add(model, effective);
+        await waitForMutation(model, confirmation);
         return modelAsRow<T>(model);
       } finally {
         await autoLease?.release?.().catch(() => {});
@@ -1528,8 +1498,12 @@ export function createModelOperations<T, C>(
                   : {}),
               };
               model.applyChanges(patch);
-              syncClient.update(model, effective);
-              await waitForMutation(model);
+              const confirmation = syncClient.update(
+                model,
+                effective,
+                patch as Record<string, unknown>,
+              );
+              await waitForMutation(model, confirmation);
               return modelAsRow<T>(model);
             },
           });
@@ -1585,8 +1559,12 @@ export function createModelOperations<T, C>(
         // the server. (`updateFromData` is the hydration path and would discard
         // the tracking, producing an empty `input: {}` no-op mutation.)
         model.applyChanges(params.data);
-        syncClient.update(model, effective);
-        await waitForMutation(model);
+        const confirmation = syncClient.update(
+          model,
+          effective,
+          params.data as Record<string, unknown>,
+        );
+        await waitForMutation(model, confirmation);
         const updated = modelAsRow<T>(model);
         await settleClaimsAfterWrite(id, handle);
         return updated;
@@ -1658,8 +1636,8 @@ export function createModelOperations<T, C>(
         ...opts,
         ...(selected ? { claimRef: { id: selected.id } } : {}),
       };
-      syncClient.delete(model, effective);
-      await waitForMutation(model);
+      const confirmation = syncClient.delete(model, effective);
+      await waitForMutation(model, confirmation);
       await settleClaimsAfterWrite(id, handle);
     }),
 
@@ -1667,21 +1645,6 @@ export function createModelOperations<T, C>(
     // readers (`claim.state` / `claim.queue` / `claim.release` / `claim.reorder`).
     claim: claimApi,
 
-    join: guard(
-      (
-        ids: string | readonly string[],
-        options?: JoinOptions,
-      ): Promise<JoinedParticipant> => {
-        if (!collaboration?.createJoin) {
-          throw new AbloValidationError(
-            `Model "${schemaKey}" was built without a WebSocket runtime, so join() is unavailable here. Presence needs a live socket — use the standard Ablo({ schema, apiKey }) client (not the HTTP transport).`,
-            { code: 'model_join_not_configured' },
-          );
-        }
-        return collaboration.createJoin(schemaKey, ids, options);
-      },
-    ),
-
     onChange(callback, options): () => void {
       return autorun(() => {
         callback(local.list(options));

package/src/local/client/options.ts

@@ -32,6 +32,11 @@ import type { CommitOutboxScope } from '@abloatai/transaction/commit';
  */
 export type { CredentialProvider } from '@abloatai/transaction/auth/apiKey';
 import type { CredentialProvider } from '@abloatai/transaction/auth/apiKey';
+import type {
+  SessionCredential,
+  SessionEndpoint,
+  SessionProvider,
+} from '@abloatai/transaction/sessions';
 import type { AbloPlugin } from '../../plugin.js';
 import type { ParticipantKind } from '@abloatai/transaction/types/participant';
 
@@ -74,19 +79,21 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
    *    `ABLO_API_KEY` environment variable, so you usually pass nothing. A
    *    long-lived key needs no refresh; the client uses it as-is.
    *
-   *  - **An async resolver** `() => Promise<string | null>` — the escape hatch for
-   *    when the exchange needs custom headers, a request body, or a non-HTTP mint
-   *    (vault rotation, a cloud token service, an existing auth session). It uses
-   *    the same renewal machinery as the endpoint form.
-   *
-   * The endpoint and resolver forms share one contract: return a token; return
-   * `null` when the login itself is gone (terminal — the client signs out and
-   * fails `ready()` with `session_expired`); or throw on a transient failure, which
-   * backs off and retries without signing out. The endpoint form maps HTTP onto
-   * this for you: only a structured `401 session_expired` means signed out.
+   *  - **An async resolver** for advanced process-owned key rotation, such as a
+   *    vault or workload-identity exchange. Scoped actor renewal belongs in
+   *    `session` instead.
    */
   apiKey?: string | CredentialProvider | null | undefined;
 
+  /**
+   * Scoped actor identity. Pass a session returned by `sessions.create()` for
+   * bounded work, a provider that re-mints it for a long-lived client, or
+   * `{ endpoint: '/api/ablo-session' }` in a browser. Endpoint responses use
+   * the canonical credential protocol; only a structured `401
+   * session_expired` ends the underlying login.
+   */
+  session?: SessionCredential | SessionProvider | SessionEndpoint | null | undefined;
+
   /**
    * Pins this client to one Ablo project. During `ready()` the server resolves
    * the API key's actual project and the client refuses to start when it differs.
@@ -105,33 +112,6 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
    */
   branchId?: string | null | undefined;
 
-  /**
-   * The session-mint endpoint — the browser-side auth field, and the named
-   * endpoint for the route that mints the signed-in user's short-lived token:
-   *
-   * ```ts
-   * const ablo = Ablo({ schema, authEndpoint: '/api/ablo-session' });
-   * ```
-   *
-   * The client owns the whole exchange: it POSTs the route (same-origin, cookies
-   * included), validates the canonical auth response contract, keeps it fresh
-   * ahead of expiry, and re-mints when the server reports the token stale. Only
-   * a structured `401 session_expired` response means signed out. It also
-   * accepts an async resolver `() => Promise<string | null>` when the exchange
-   * needs custom headers or a body — the same contract as the resolver form of
-   * `apiKey`.
-   *
-   * Mutually exclusive with `apiKey`: a server holds a key, a browser holds a mint
-   * route, and passing both is a validation error.
-   */
-  authEndpoint?: string | CredentialProvider | null | undefined;
-
-  /** Timeout for a session-mint request. @default 10000 */
-  authTimeoutMs?: number | undefined;
-
-  /** Explicit opt-in for a cross-origin session-mint endpoint. */
-  allowCrossOriginAuthEndpoint?: boolean | undefined;
-
   /**
    * Local persistence mode. Pass `indexeddb` only when you want offline
    * queueing and a reload-surviving browser cache.
@@ -264,15 +244,12 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
    */
   apiKey?: string | CredentialProvider | null | undefined;
 
+  /** A scoped session, or a provider that re-mints it for a long-lived client. */
+  session?: SessionCredential | SessionProvider | SessionEndpoint | null | undefined;
+
   /** Expected project assertion; see {@link AbloOptions.projectId}. */
   projectId?: string | null | undefined;
 
-  /**
-   * Session-mint endpoint (string or async resolver) — see
-   * {@link AbloOptions.authEndpoint}. Mutually exclusive with `apiKey`.
-   */
-  authEndpoint?: string | CredentialProvider | null | undefined;
-
   /**
    * A bearer auth token, sent as `Authorization: Bearer <token>` on every request.
    *