@abloatai/humans 0.59.2 → 0.61.0

package/dist/local/transactions/mutations/MutationQueue.d.ts

@@ -111,6 +111,7 @@ export declare class MutationQueue extends EventEmitter {
     private pendingPersistenceStages;
     private persistenceStageScheduled;
     private pendingDrainPromise;
+    private modelProcessingPromise;
     private executionQueue;
     private isProcessing;
     private processTimer?;
@@ -153,7 +154,6 @@ export declare class MutationQueue extends EventEmitter {
     private get failureHandlingContext();
     private get conflictResolutionContext();
     private get processingSchedulerContext();
-    private get pendingDrainContext();
     private get durableCommitRestoreContext();
     private get persistenceContext();
     private nextCommitSequence;
@@ -225,7 +225,6 @@ export declare class MutationQueue extends EventEmitter {
      */
     private scheduleReplicationLagTimeout;
     private takeNextExecutionBatch;
-    private takePendingDrainBatch;
     /**
      * Resolvers for per-transaction `confirmation` promises. Populated in
      * `attachConfirmation` at staging time, consumed by the constructor-time
@@ -477,7 +476,7 @@ export declare class MutationQueue extends EventEmitter {
         awaitingDeltaCount: number;
         awaitingDeltaTransactions: {
             id: string;
-            type: "archive" | "create" | "delete" | "unarchive" | "update";
+            type: "update" | "create" | "delete" | "archive" | "unarchive";
             modelName: string;
             modelId: string;
             syncIdNeeded: number | undefined;
@@ -486,13 +485,13 @@ export declare class MutationQueue extends EventEmitter {
         }[];
         pendingTransactions: {
             id: string;
-            type: "archive" | "create" | "delete" | "unarchive" | "update";
+            type: "update" | "create" | "delete" | "archive" | "unarchive";
             modelName: string;
             modelId: string;
         }[];
         executingTransactions: {
             id: string;
-            type: "archive" | "create" | "delete" | "unarchive" | "update";
+            type: "update" | "create" | "delete" | "archive" | "unarchive";
             modelName: string;
             modelId: string;
         }[];

package/dist/local/transactions/mutations/MutationQueue.js

@@ -34,9 +34,8 @@ import { enqueueTransaction } from './queueCoalescing.js';
 import { processBatch } from './batchProcessing.js';
 import { handleFailure } from './failureHandling.js';
 import { handleConflict as resolveConflict, isPermanentError as classifyPermanentError, isDefinitiveRejection as classifyDefinitiveRejection } from './failurePolicy.js';
-import { takeNextExecutionBatch as selectExecutionBatch, takePendingDrainBatch as selectPendingDrainBatch } from './executionSelection.js';
+import { takeNextExecutionBatch as selectExecutionBatch } from './executionSelection.js';
 import { scheduleProcessing as scheduleProcessingExternal } from './processingScheduler.js';
-import { drainPendingConfirmations, } from './pendingDrain.js';
 import { restoreDurableCommits as restoreDurableCommitsExternal } from './durableCommitRestore.js';
 export class MutationQueue extends EventEmitter {
     // Keep one hour of clock/network margin inside the server's 24-hour ledger.
@@ -70,6 +69,7 @@ export class MutationQueue extends EventEmitter {
     pendingPersistenceStages = [];
     persistenceStageScheduled = false;
     pendingDrainPromise = null;
+    modelProcessingPromise = null;
     executionQueue = [];
     isProcessing = false;
     processTimer;
@@ -303,32 +303,6 @@ export class MutationQueue extends EventEmitter {
             logger: this.runtime.logger,
         };
     }
-    get pendingDrainContext() {
-        return {
-            runtime: this.runtime,
-            config: { deltaConfirmationTimeout: this.config.deltaConfirmationTimeout },
-            store: this.store,
-            executionQueue: this.executionQueue,
-            optimisticUpdates: this.localMutationPort.updates,
-            assertDurableReplayOpen: () => { this.assertDurableReplayOpen(); },
-            processCommitLane: () => this.processCommitLane(),
-            takePendingDrainBatch: (pending) => this.takePendingDrainBatch(pending),
-            ensureCommitEnvelope: (batch) => this.ensureCommitEnvelope(batch),
-            ensureDerivedFields: (transaction) => { this.ensureDerivedFields(transaction); },
-            sourceMutationIdsFor: (batch) => this.sourceMutationIdsFor(batch),
-            sealDurableCommit: (input) => this.sealDurableCommit(input),
-            assertEnvelopeInsideReplayWindow: (envelope) => { this.assertEnvelopeInsideReplayWindow(envelope); },
-            parseMutationCommitResult: (value) => this.parseMutationCommitResult(value),
-            dispatchCommitBounded: (...args) => this.dispatchCommitBounded(...args),
-            persistDurableCommitAcceptance: (envelope, result) => this.persistDurableCommitAcceptance(envelope, result),
-            removeDurableCommit: (idempotencyKey) => this.removeDurableCommit(idempotencyKey),
-            scheduleReplicationLagTimeout: (transactionId, clientTxId, correlationId) => { this.scheduleReplicationLagTimeout(transactionId, clientTxId, correlationId); },
-            scheduleDeltaConfirmationTimeout: (transaction, timeoutMs) => { this.scheduleDeltaConfirmationTimeout(transaction, timeoutMs); },
-            enqueue: (transaction) => { this.enqueue(transaction); },
-            recentDeltaCorrelations: this.recentDeltaCorrelations,
-            emit: (event, payload) => this.emit(event, payload),
-        };
-    }
     get durableCommitRestoreContext() {
         return {
             config: this.config,
@@ -738,9 +712,6 @@ export class MutationQueue extends EventEmitter {
         this.executionQueue = selected.remaining;
         return selected.batch;
     }
-    takePendingDrainBatch(pending) {
-        return selectPendingDrainBatch(pending, this.config.maxBatchSize);
-    }
     /**
      * Resolvers for per-transaction `confirmation` promises. Populated in
      * `attachConfirmation` at staging time, consumed by the constructor-time
@@ -1004,25 +975,15 @@ export class MutationQueue extends EventEmitter {
         return this.pendingDrainPromise;
     }
     async drainPendingInternal() {
-        // The normal batch scheduler and the explicit/reconnect drain are two
-        // ways to drive the same durable queue. They must never seal the same
-        // staged source records concurrently: the first seal consumes those
-        // records, so the second would correctly reject them as already claimed.
-        //
-        // `isProcessing` is acquired synchronously before either path awaits,
-        // making it the queue-wide execution lock. If the normal lane already
-        // owns it, that lane will finish the pending work; callers waiting on a
-        // specific confirmation remain attached to the exact transaction.
-        if (this.isProcessing)
-            return;
-        this.isProcessing = true;
-        try {
-            await drainPendingConfirmations(this.pendingDrainContext);
-        }
-        finally {
-            this.isProcessing = false;
-            if (this.executionQueue.length > 0)
-                this.scheduleProcessing(true);
+        // Explicit flushes and reconnects are merely another trigger for the one
+        // model-mutation execution lane. A second sealing implementation can race
+        // the scheduled lane, consume its journal sources, and later dispatch the
+        // same transaction again. Move every staged row to the owned queue, then
+        // drive the normal lane until the queue has handed off all current work.
+        this.commitCreatedTransactions();
+        await this.processCommitLane();
+        while (this.executionQueue.length > 0 || this.modelProcessingPromise) {
+            await this.processBatch();
         }
     }
     async create(model, context, writeOptions, sourceMutationId) {
@@ -1055,7 +1016,20 @@ export class MutationQueue extends EventEmitter {
         scheduleProcessingExternal(this.processingSchedulerContext, immediate);
     }
     async processBatch() {
-        await processBatch(this.batchProcessingContext);
+        if (this.modelProcessingPromise) {
+            await this.modelProcessingPromise;
+            if (this.executionQueue.length > 0)
+                await this.processBatch();
+            return;
+        }
+        const processing = processBatch(this.batchProcessingContext);
+        const tracked = processing.finally(() => {
+            if (this.modelProcessingPromise === tracked) {
+                this.modelProcessingPromise = null;
+            }
+        });
+        this.modelProcessingPromise = tracked;
+        await tracked;
     }
     rememberDeltaCorrelation(correlationId, syncId) {
         // Refresh insertion order when a replay repeats the same correlation id.

package/dist/local/transactions/mutations/batchProcessing.js

@@ -64,16 +64,29 @@ export async function processBatch(ctx) {
             if (batchOps.length > 0) {
                 let dispatchStarted = false;
                 try {
-                    const durableEnvelope = await ctx.sealDurableCommit({
-                        idempotencyKey: commitIdempotencyKey,
-                        origin: 'model_batch',
-                        operations: batchOps.map(({ op }) => op),
-                        sourceMutationIds: ctx.sourceMutationIdsFor(batch),
-                        commitOptions: { reads: collectQueuedReads(batch) },
-                        createdAt: Math.min(...batch.map((transaction) => transaction.createdAt)),
-                        sealedAt: batch[0]?.commitEnvelope?.sealedAt ?? Date.now(),
-                        sequence: batch[0]?.commitEnvelope?.sequence,
-                    });
+                    let durableEnvelope = batch[0]?.durableEnvelope;
+                    if (durableEnvelope) {
+                        const mismatched = batch.some((transaction) => transaction.durableEnvelope?.idempotencyKey !==
+                            durableEnvelope?.idempotencyKey);
+                        if (mismatched || durableEnvelope.idempotencyKey !== commitIdempotencyKey) {
+                            throw new Error('Cannot replay a model batch with inconsistent durable envelopes');
+                        }
+                    }
+                    else {
+                        durableEnvelope = await ctx.sealDurableCommit({
+                            idempotencyKey: commitIdempotencyKey,
+                            origin: 'model_batch',
+                            operations: batchOps.map(({ op }) => op),
+                            sourceMutationIds: ctx.sourceMutationIdsFor(batch),
+                            commitOptions: { reads: collectQueuedReads(batch) },
+                            createdAt: Math.min(...batch.map((transaction) => transaction.createdAt)),
+                            sealedAt: batch[0]?.commitEnvelope?.sealedAt ?? Date.now(),
+                            sequence: batch[0]?.commitEnvelope?.sequence,
+                        });
+                        for (const transaction of batch) {
+                            transaction.durableEnvelope = durableEnvelope;
+                        }
+                    }
                     const operations = durableEnvelope.operations;
                     // Capture lastSyncId from the server response for threshold-based
                     // confirmation.

package/dist/local/transactions/mutations/commitPayload.d.ts

@@ -11,7 +11,7 @@
 import type { RuntimeContext } from '../../RuntimeContext.js';
 import { MutationOperationType } from '@abloatai/transaction/types';
 import type { MutationOptions, WriteOptions } from '../../interfaces/index.js';
-import type { CommitEnvelopeMember } from '@abloatai/transaction/commit';
+import type { CommitEnvelopeMember, DurableCommitEnvelope } from '@abloatai/transaction/commit';
 export interface UserContext {
     userId: string;
     organizationId: string;
@@ -69,6 +69,13 @@ export interface QueuedMutation {
      * re-batching its operations under a fresh key.
      */
     commitEnvelope?: CommitEnvelopeMember;
+    /**
+     * The exact durable request produced by the first successful local seal.
+     * Runtime retries dispatch this object directly. Asking the outbox to seal
+     * again is both unnecessary and unsafe after a concurrent authoritative
+     * completion has begun cleaning up the stored envelope.
+     */
+    durableEnvelope?: DurableCommitEnvelope;
     /** Pending-mutation journal entries atomically consumed by this envelope. */
     sourceMutationIds?: string[];
     /** Completed locally without a server operation; no sync echo will arrive. */
@@ -122,7 +129,7 @@ export declare const stripModelSuffix: (modelName: string) => string;
  * foreign-key ordering because the row already exists, so they all share the
  * configured default non-create priority.
  */
-export declare const computePriorityScore: (type: QueuedMutation['type'], modelName: string, runtime?: RuntimeContext) => number;
+export declare const computePriorityScore: (type: QueuedMutation["type"], modelName: string, runtime?: RuntimeContext) => number;
 export declare const TX_TYPE_TO_MUTATION_OP: Record<QueuedMutation['type'], MutationOperationType>;
 export declare function hasStaleWriteOptions(options?: WriteOptions): boolean;
 /** Options whose identity/audit semantics forbid merging two caller writes. */

package/dist/local/transactions/mutations/commitTransport.js

@@ -95,7 +95,9 @@ export function dispatchCommitBounded(ctx, ...args) {
     if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
         return dispatched;
     return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => reject(new AbloConnectionError('The mutation transport did not acknowledge the commit in time; its outcome remains pending and is safe to retry.', { code: 'commit_no_result' })), timeoutMs);
+        const timer = setTimeout(() => {
+            reject(new AbloConnectionError('The mutation transport did not acknowledge the commit in time; its outcome remains pending and is safe to retry.', { code: 'commit_no_result' }));
+        }, timeoutMs);
         dispatched.then((value) => { clearTimeout(timer); resolve(value); }, (error) => { clearTimeout(timer); reject(error instanceof Error ? error : new Error(String(error))); });
     });
 }

package/dist/local/transactions/mutations/executionSelection.d.ts

@@ -3,4 +3,3 @@ export declare function takeNextExecutionBatch(executionQueue: QueuedMutation[],
     batch: QueuedMutation[];
     remaining: QueuedMutation[];
 };
-export declare function takePendingDrainBatch(pending: QueuedMutation[], maxBatchSize: number): QueuedMutation[];

package/dist/local/transactions/mutations/executionSelection.js

@@ -1,6 +1,10 @@
 export function takeNextExecutionBatch(executionQueue, maxBatchSize) {
+    // Cancellation, delta confirmation, and failure settlement can all make a
+    // queued reference terminal before its scheduler callback runs. Terminal or
+    // currently executing rows have no authority to cross the dispatch boundary.
+    const pendingQueue = executionQueue.filter((tx) => tx.status === 'pending');
     const retryGroups = new Map();
-    for (const tx of executionQueue) {
+    for (const tx of pendingQueue) {
         const envelope = tx.commitEnvelope;
         if (!envelope)
             continue;
@@ -13,30 +17,18 @@ export function takeNextExecutionBatch(executionQueue, maxBatchSize) {
         const expectedCount = members[0]?.commitEnvelope?.operationCount;
         if (expectedCount === undefined || members.length !== expectedCount)
             continue;
-        const remaining = executionQueue.filter((tx) => tx.commitEnvelope?.idempotencyKey !== idempotencyKey);
+        const remaining = pendingQueue.filter((tx) => tx.commitEnvelope?.idempotencyKey !== idempotencyKey);
         members.sort((a, b) => (a.commitEnvelope?.operationIndex ?? 0) - (b.commitEnvelope?.operationIndex ?? 0));
         return { batch: members, remaining };
     }
-    const fresh = executionQueue.filter((tx) => !tx.commitEnvelope);
+    const fresh = pendingQueue.filter((tx) => !tx.commitEnvelope);
     const firstFresh = fresh[0];
     if (!firstFresh)
-        return { batch: [], remaining: executionQueue };
+        return { batch: [], remaining: pendingQueue };
     const explicitIndex = fresh.findIndex((tx) => typeof tx.writeOptions?.idempotencyKey === 'string');
     const selected = explicitIndex === 0
         ? [firstFresh]
         : fresh.slice(0, Math.min(maxBatchSize, explicitIndex > 0 ? explicitIndex : fresh.length));
     const selectedIds = new Set(selected.map((tx) => tx.id));
-    return { batch: selected, remaining: executionQueue.filter((tx) => !selectedIds.has(tx.id)) };
-}
-export function takePendingDrainBatch(pending, maxBatchSize) {
-    const first = pending[0];
-    if (!first)
-        return [];
-    const envelope = first.commitEnvelope;
-    if (envelope)
-        return pending.filter((tx) => tx.commitEnvelope?.idempotencyKey === envelope.idempotencyKey);
-    if (typeof first.writeOptions?.idempotencyKey === 'string')
-        return [first];
-    const explicitIndex = pending.findIndex((tx) => typeof tx.writeOptions?.idempotencyKey === 'string');
-    return pending.slice(0, Math.min(maxBatchSize, explicitIndex > 0 ? explicitIndex : pending.length));
+    return { batch: selected, remaining: pendingQueue.filter((tx) => !selectedIds.has(tx.id)) };
 }

package/dist/local/transactions/mutations/failureHandling.js

@@ -13,6 +13,15 @@ export function transientRetryDelayMs(error, attempt, retryBackoff) {
     return Math.floor(Math.random() * ceiling);
 }
 export async function handleFailure(ctx, transaction, error) {
+    // The dispatch owner may lose its acknowledgement while an authoritative
+    // delta concurrently completes the same transaction. Completion is
+    // terminal: a late catch path must not turn that row back into `pending`
+    // and schedule a second seal after its durable sources were cleaned up.
+    if (transaction.status === 'completed' ||
+        transaction.status === 'failed' ||
+        transaction.status === 'rolled_back' ||
+        transaction.status === 'awaiting_delta')
+        return;
     transaction.attempts++;
     // Check whether this is a permanent error that should not be retried.
     if (ctx.isPermanentError(error)) {

package/dist/local/transactions/mutations/localMutation.js

@@ -12,9 +12,9 @@ export function createLocalMutationPort(emitter) {
     const updates = new Map();
     return {
         updates,
-        applyCreate: (model, transaction) => applyOptimisticCreate(updates, emitter, model, transaction),
-        applyUpdate: (model, transaction) => applyOptimisticUpdate(updates, emitter, model, transaction),
-        applyDelete: (model, transaction) => applyOptimisticDelete(updates, emitter, model, transaction),
+        applyCreate: (model, transaction) => { applyOptimisticCreate(updates, emitter, model, transaction); },
+        applyUpdate: (model, transaction) => { applyOptimisticUpdate(updates, emitter, model, transaction); },
+        applyDelete: (model, transaction) => { applyOptimisticDelete(updates, emitter, model, transaction); },
         rollback: (transaction, reason, error) => rollbackOptimistic(updates, emitter, transaction, reason, error),
     };
 }

package/dist/local/transactions/mutations/queueCoalescing.js

@@ -1,6 +1,14 @@
 import { mergeUpdateData } from './coalesceRules.js';
 import { hasCommitCoalescingBarrier } from './commitPayload.js';
 export function enqueueTransaction(ctx, transaction) {
+    // Only the pending state may cross into the execution owner. A late timer,
+    // reconnect callback, or stale staging callback must not resurrect a row
+    // that is already executing or terminal, and repeated triggers must not put
+    // the same source mutation into the queue twice.
+    if (transaction.status !== 'pending')
+        return;
+    if (ctx.executionQueue.some((candidate) => candidate.id === transaction.id))
+        return;
     ctx.ensureDerivedFields(transaction);
     const modelKey = `${transaction.modelName}:${transaction.modelId}`;
     if (transaction.type === 'update' && transaction.attempts === 0 && !transaction.commitEnvelope) {

package/dist/local/transactions/mutations/replayValidation.d.ts

@@ -27,11 +27,11 @@ import type { RuntimeContext } from '../../RuntimeContext.js';
 export declare const persistedTransactionSchema: z.ZodObject<{
     id: z.ZodString;
     type: z.ZodEnum<{
-        archive: "archive";
+        update: "update";
         create: "create";
         delete: "delete";
+        archive: "archive";
         unarchive: "unarchive";
-        update: "update";
     }>;
     modelName: z.ZodString;
     modelId: z.ZodString;
@@ -95,10 +95,10 @@ export declare function deserializePersistedTransaction(row: unknown, runtime?:
 export declare const persistedMutationSchema: z.ZodObject<{
     mutationId: z.ZodOptional<z.ZodString>;
     type: z.ZodEnum<{
-        archive: "archive";
+        update: "update";
         create: "create";
         delete: "delete";
-        update: "update";
+        archive: "archive";
     }>;
     modelData: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     modelName: z.ZodString;
@@ -133,14 +133,15 @@ export declare const PENDING_MUTATION_RECORD_PREFIX = "pending-mutation:";
 export declare const PENDING_MUTATION_REPLAY_WINDOW_MS: number;
 /** Scope-less records written by the first aggregate-journal release. */
 export declare const legacyPendingMutationRecordSchema: z.ZodObject<{
+    storageVersion: z.ZodLiteral<1>;
     id: z.ZodString;
     type: z.ZodLiteral<"pending_mutation">;
     mutation: z.ZodObject<{
         type: z.ZodEnum<{
-            archive: "archive";
+            update: "update";
             create: "create";
             delete: "delete";
-            update: "update";
+            archive: "archive";
         }>;
         modelData: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         modelName: z.ZodString;
@@ -167,17 +168,22 @@ export declare const legacyPendingMutationRecordSchema: z.ZodObject<{
         mutationId: z.ZodString;
     }, z.core.$loose>;
     timestamp: z.ZodNumber;
-    storageVersion: z.ZodLiteral<1>;
 }, z.core.$strict>;
 export declare const pendingMutationRecordSchema: z.ZodObject<{
+    storageVersion: z.ZodLiteral<2>;
+    scope: z.ZodObject<{
+        organizationId: z.ZodString;
+        participantId: z.ZodString;
+        namespace: z.ZodString;
+    }, z.core.$strict>;
     id: z.ZodString;
     type: z.ZodLiteral<"pending_mutation">;
     mutation: z.ZodObject<{
         type: z.ZodEnum<{
-            archive: "archive";
+            update: "update";
             create: "create";
             delete: "delete";
-            update: "update";
+            archive: "archive";
         }>;
         modelData: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         modelName: z.ZodString;
@@ -204,12 +210,6 @@ export declare const pendingMutationRecordSchema: z.ZodObject<{
         mutationId: z.ZodString;
     }, z.core.$loose>;
     timestamp: z.ZodNumber;
-    storageVersion: z.ZodLiteral<2>;
-    scope: z.ZodObject<{
-        organizationId: z.ZodString;
-        participantId: z.ZodString;
-        namespace: z.ZodString;
-    }, z.core.$strict>;
 }, z.core.$strict>;
 export type PendingMutationRecord = z.infer<typeof pendingMutationRecordSchema>;
 export declare function pendingMutationRecordId(mutationId: string): string;

package/dist/react/AbloProvider.d.ts

@@ -1,8 +1,8 @@
 import { type ReactNode } from 'react';
 import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
 import type { AbloClient as Ablo } from '../client.js';
-import type { Claim, Duration, Peer } from '@abloatai/transaction/types/streams';
-import type { EngineParticipant, ParticipantScope, ParticipantStatus } from '../local/sync/participants.js';
+import type { Peer } from '@abloatai/transaction/types/streams';
+import type { GroupScope } from '../local/sync/scopeGroups.js';
 import { type SyncStoreContract } from './context.js';
 /**
  * Ablo umbrella provider — owns the sync engine, multiplayer, and
@@ -13,9 +13,8 @@ import { type SyncStoreContract } from './context.js';
  *
  *   - **One component, one import.** Consumers write the provider
  *     once at the root; nothing else needs to plumb the engine.
- *   - **Multiplayer is default.** React consumers are always browsers doing
- *     multiplayer UI, so `useJoin()` / `useAblo()` are always
- *     available. No opt-in prop.
+ *   - **Multiplayer is default.** React consumers share the client's scoped
+ *     groups, presence stream, and model surface without another join step.
  *   - **Declarative props for app glue.** `preventUnsavedChanges`,
  *     `onSessionExpired`, `postBootstrap`, `resolveUsers` — each
  *     absorbs a class of integration code that previously lived in
@@ -35,7 +34,7 @@ import { type SyncStoreContract } from './context.js';
  * // Build once at module scope — a new instance per render tears down the socket.
  * // The endpoint string points at your session-mint route (`ablo init`
  * // scaffolds it); the SDK fetches it and keeps the token fresh.
- * const ablo = Ablo({ schema, authEndpoint: '/api/ablo-session' });
+ * const ablo = Ablo({ schema, session: { endpoint: '/api/ablo-session' } });
  *
  * <AbloProvider client={ablo}>
  *   <App />
@@ -108,82 +107,11 @@ export interface AbloProviderProps<R extends SchemaRecord = SchemaRecord> {
     children: ReactNode;
 }
 export declare function AbloProvider<R extends SchemaRecord = SchemaRecord>(props: AbloProviderProps<R>): React.ReactElement;
-export type { EngineParticipant, ParticipantScope, ParticipantStatus };
-/**
- * Options for `useJoin`. The hook reuses the engine's single
- * WebSocket and opens a scoped claim on it when `scope` is provided:
- * one TCP connection, N logical sub-syncgroup participants.
- */
-export interface UseJoinOptions {
-    readonly scope?: ParticipantScope;
-    /**
-     * Lease TTL for the participant claim, as a compact duration (`'5m'`) or a
-     * number of seconds. The same dial and the same spelling as
-     * `ablo.<model>.join(ids, { ttl })` and every other lease in the SDK.
-     */
-    readonly ttl?: Duration;
-    /**
-     * @deprecated Use `ttl`. Removed in 0.37.0.
-     *
-     * The same rename as on `ParticipantJoinOptions`: one lease, and the seconds
-     * spelling was the one that misled, because it accepted duration strings too.
-     */
-    readonly ttlSeconds?: number | string | null;
-    /** Tear down + don't re-join while true. */
-    readonly paused?: boolean;
-    /**
-     * Acquire a write-claim CLAIM on the scope, in addition to read interest.
-     *
-     * Default `false`: opening a scope subscribes the connection to its deltas
-     * (read interest, via `update_subscription`) but does NOT claim it — a
-     * viewer is not a claimant. Set `true` when the participant intends to
-     * WRITE (editing a report, an agent staking work): the claim is sent so peers
-     * observe it, and the scope is pinned so it stays subscribed (never warms)
-     * for as long as the claim is held.
-     */
-    readonly claim?: boolean;
-    /**
-     * Backfill the scope's CURRENT state into the pool on enter, in addition to
-     * tailing live changes.
-     *
-     * Default `false`: entering a scope subscribes to its FUTURE deltas only — if
-     * the scope's rows aren't already loaded, the view is empty until something
-     * changes. Set `true` when opening an entity that may not be loaded yet (a
-     * deep-linked report, a never-opened ledger) so its current rows are fetched and
-     * injected once, then kept fresh by the live tail. The fetch is single-flight
-     * and runs once per group; a failure soft-fails (the live tail still flows).
-     */
-    readonly hydrate?: boolean;
-}
-export interface UseJoinReturn {
-    readonly participant: EngineParticipant | null;
-    /** Everyone else on the engine's sync groups (`participant.presence.others`), bridged to React. */
-    readonly peers: readonly Peer[];
-    /** Active claim claims by peers (`participant.claims.others`), bridged to React. */
-    readonly claims: readonly Claim[];
-    readonly status: ParticipantStatus;
-    readonly error: Error | null;
-}
-/**
- * Join multiplayer for a given scope. Returns the participant and its
- * lifecycle status. Auto-cleans up on unmount or when `paused`
- * flips to true.
- *
- * `useJoin` is the React form of `ablo.<model>.join` — scope-level
- * read-interest + presence; returns the reactive participant facade
- * (peers/claims/status).
- *
- * The returned `participant` is an `EngineParticipant` — `.presence`
- * + `.claims` only — backed by the engine's existing socket. For
- * headless-bot patterns (a separate identity in the same browser
- * tab), construct a second `Ablo({ kind: 'agent', ... })` directly.
- */
-export declare function useJoin(opts: UseJoinOptions): UseJoinReturn;
+export type { GroupScope };
 /**
  * Read-only presence: the OTHER participants currently visible to this
- * connection, bridged to React. Unlike {@link useJoin}, this does
- * NOT enter/leave a scope (no `update_subscription`, no warm-TTL churn) —
- * it is a pure reader of the engine's already-flowing presence stream.
+ * connection, bridged to React. This is a pure reader of the engine's
+ * already-flowing presence stream; it does not mutate connection groups.
  *
  * Pass `scope` to narrow to the peers on that scope's sync group(s); omit
  * it to get everyone on the engine's groups. Membership is driven entirely
@@ -191,18 +119,15 @@ export declare function useJoin(opts: UseJoinOptions): UseJoinReturn;
  * cursor/collaboration traffic), so reading it never affects what the
  * connection is subscribed to and can't deadlock against a gated channel.
  *
- * Use this to answer "is anyone else here?" — e.g. suppressing live-cursor
- * broadcasts while alone — when some OTHER mount already owns the scope's
- * read interest (scope `leave` is not reference-counted, so a second
- * `useJoin` on the same scope would warm-drop the owner's
- * subscription on unmount).
+ * Use this to answer "is anyone else here?", for example to suppress
+ * live-cursor broadcasts while alone.
  *
  * ```ts
  * const peers = usePeers({ reports: reportId });
  * const alone = !peers.some((p) => p.participantKind === 'user');
  * ```
  */
-export declare function usePeers(scope?: ParticipantScope): readonly Peer[];
+export declare function usePeers(scope?: GroupScope): readonly Peer[];
 /**
  * Returns the raw `SyncEngine` proxy. Typically you want the typed
  * hooks (`useQuery`, `useOne`, `useMutate`) — this is for rare cases