@abloatai/humans 0.46.0 → 0.48.0

package/dist/local/BaseSyncedStore.d.ts

@@ -32,6 +32,7 @@ import type { EnrichmentPlanEntry, ForeignKeyIndexSpec } from './sync/syncPlan.j
 import { type CredentialRefresher } from './sync/credentialLifecycle.js';
 import type { RehydrationStats } from './sync/bootstrapApply.js';
 import type { ParticipantKind } from '@abloatai/transaction/types/participant';
+import type { DeliveryPartitionRoute } from '@abloatai/transaction/auth/deliveryPartition';
 import type { QueuedMutation } from './transactions/mutations/MutationQueue.js';
 import type { CommitLatencySample } from './transactions/mutations/commitLatency.js';
 /** Constructor type for Model subclasses (accepts abstract classes) */
@@ -90,6 +91,8 @@ export interface UserContext {
     branchId: string;
     /** True only when branchId is the project's production root. */
     branchRoot?: boolean;
+    /** Server-resolved WebSocket gateway route; never an authorization claim. */
+    deliveryPartition?: DeliveryPartitionRoute | null;
     role?: string;
     teamIds?: string[];
     /** Participant kind on the wire. Default 'user' for browser
@@ -115,7 +118,7 @@ export interface UserContext {
      *  - `'none'`: open the WebSocket and process live deltas only.
      *    Reads go through `model.get()` / filtered subscriptions
      *    backfilled by `Covering` deltas. Suitable for transactional
-     *    participants — agent-worker, video-pipeline, routine runners —
+     *    participants — headless workers, video pipelines, routine runners —
      *    that don't need a local replica of the org's tenant plane.
      */
     bootstrapMode?: 'full' | 'none';

package/dist/local/BaseSyncedStore.js

@@ -1067,6 +1067,7 @@ export class BaseSyncedStore {
         }
         const syncGroups = this.resolveSyncGroups(context);
         this.syncWebSocket.setSyncGroups(syncGroups);
+        this.syncWebSocket.setDeliveryPartition(context.deliveryPartition ?? null);
         this.syncWebSocket.setLastSyncId(lastSyncId || 0);
         // The permanent base scopes for read interest — same set the connection
         // subscribes to at upgrade, so the two can never disagree.

package/dist/local/Database.js

@@ -791,7 +791,7 @@ export class Database {
         // ── inMemory short-circuit ───────────────────────────────────────
         //
         // The batched IDB transaction path below assumes `this.storeManager`
-        // and `workspaceDb`. In inMemory mode (agent-worker, tests) those
+        // and `workspaceDb`. In inMemory mode (headless workers, tests) those
         // don't exist. Without this branch, every live delta arriving over
         // the WebSocket is silently dropped — the local pool never updates,
         // `subscribe()` autoruns never re-fire, lazy-model dispatchers

package/dist/local/client/clientPrelude.js

@@ -22,8 +22,12 @@ import { createConsoleLogger, resolveLogLevel } from './consoleLogger.js';
  * different project than the one being addressed (a warning, not a throw).
  */
 export function resolveClientPrelude(options) {
-    const internalOptions = options;
     const env = readProcessEnv();
+    const internalOptions = {
+        ...options,
+        projectId: options.projectId ?? env.ABLO_PROJECT_ID,
+        branchId: options.branchId ?? env.ABLO_BRANCH_ID,
+    };
     const authInput = { options, env };
     const configuredApiKey = resolveApiKey(authInput);
     const configuredAuthToken = resolveAuthToken(authInput);

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

@@ -245,6 +245,4 @@ export declare function createModelProxy<T, C>(schemaKey: string, registeredMode
  * collaborator, a test most of all, is pushed into a cast through `unknown`
  * to supply the one method that is actually read.
  */
-hydration: Pick<OnDemandLoader, 'fetch'>, collaboration?: ModelCollaboration, 
-/** The client-wide `wait` default; a per-call `wait` still wins over it. */
-defaultWait?: 'queued' | 'confirmed'): ModelOperations<T, C>;
+hydration: Pick<OnDemandLoader, 'fetch'>, collaboration?: ModelCollaboration): ModelOperations<T, C>;

package/dist/local/client/createModelProxy.js

@@ -43,9 +43,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
  * collaborator, a test most of all, is pushed into a cast through `unknown`
  * to supply the one method that is actually read.
  */
-hydration, collaboration, 
-/** The client-wide `wait` default; a per-call `wait` still wins over it. */
-defaultWait) {
+hydration, collaboration) {
     /**
      * Resolve a row **this** resource owns.
      *
@@ -100,17 +98,30 @@ defaultWait) {
             }
         };
     };
+    const guardWrite = (fn) => {
+        const guarded = guard(fn);
+        return (...args) => {
+            const confirmation = guarded(...args);
+            // Optimistic writes are intentionally useful without awaiting them. The
+            // transaction pipeline already reports a later refusal through
+            // `onMutationFailure`; attach an observer here as well so choosing not to
+            // 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);
+            return confirmation;
+        };
+    };
     const load = async (options) => {
         const rows = await hydration.fetch(schemaKey, options);
         return rows.map((row) => modelAsRow(row));
     };
-    const waitForMutation = async (model, options) => {
-        // A per-call `wait` wins; otherwise the client-wide default decides. This
-        // is the single point that turns "confirmed" into actually waiting, so a
-        // client configured that way rejects on a refused write everywhere rather
-        // than in the one place a caller remembered to ask.
-        if ((options?.wait ?? defaultWait) !== 'confirmed')
-            return;
+    const waitForMutation = async (model) => {
+        // 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
+        // global mutation-failure handler; awaiting the promise never means merely
+        // "placed in the local queue".
         // Let sibling writes from the same synchronous burst enter the mutation
         // queue before forcing a drain. Without this yield, every confirmed
         // create/update calls syncNow() alone, defeating the queue's microtask
@@ -147,7 +158,6 @@ defaultWait) {
                 ? { idempotencyKey: params.idempotencyKey }
                 : {}),
             ...(params.label !== undefined ? { label: params.label } : {}),
-            ...(params.wait !== undefined ? { wait: params.wait } : {}),
             ...(params.readAt !== undefined ? { readAt: params.readAt } : {}),
             ...(params.onStale !== undefined ? { onStale: params.onStale } : {}),
             ...(params.fenceToken !== undefined ? { fenceToken: params.fenceToken } : {}),
@@ -614,7 +624,7 @@ defaultWait) {
         // No automatic scope enrolment on bulk `list`: that would subscribe to an
         // unbounded set of rows' entity groups.
         list: guard(load),
-        create: guard(async (params) => {
+        create: guardWrite(async (params) => {
             const id = params.id ?? Model.generateId();
             const opts = mutationOptions(params);
             const claim = params.claim;
@@ -665,7 +675,7 @@ defaultWait) {
             };
             try {
                 syncClient.add(model, effective);
-                await waitForMutation(model, effective);
+                await waitForMutation(model);
                 return modelAsRow(model);
             }
             finally {
@@ -677,7 +687,7 @@ defaultWait) {
         // wrapping while exposing the two public signatures (a plain `guard(...)`
         // would collapse them to one).
         update: (() => {
-            const updateImpl = guard(async (arg, updater, contention) => {
+            const updateImpl = guardWrite(async (arg, updater, contention) => {
                 // Functional form: update(id, current => next). Same guarantee as the
                 // HTTP client (shared reconcile loop), implemented with this transport's
                 // own read-fresh + confirmed compare-and-swap. A forced server round-trip
@@ -715,13 +725,12 @@ defaultWait) {
                                 throw new AbloValidationError(`Entity not found: ${registeredModelName}/${id}`, { code: 'entity_not_found' });
                             }
                             const effective = {
-                                wait: 'confirmed',
                                 readAt,
                                 onStale: 'reject',
                             };
                             model.applyChanges(patch);
                             syncClient.update(model, effective);
-                            await waitForMutation(model, effective);
+                            await waitForMutation(model);
                             return modelAsRow(model);
                         },
                     });
@@ -753,7 +762,6 @@ defaultWait) {
                 const handle = isClaimHandle(params.claim) ? params.claim : undefined;
                 const effective = claimed
                     ? {
-                        wait: 'confirmed',
                         readAt: claimed.lease.readAt ?? claimed.snapshot.stamp,
                         onStale: 'reject',
                         claimRef: { id: claimed.lease.id },
@@ -765,7 +773,6 @@ defaultWait) {
                         // works across clients (HTTP-minted handles included).
                         ...(handle?.readAt !== undefined
                             ? {
-                                wait: 'confirmed',
                                 readAt: handle.readAt,
                                 onStale: 'reject',
                                 ...(handle.fenceToken !== undefined
@@ -782,7 +789,7 @@ defaultWait) {
                 // the tracking, producing an empty `input: {}` no-op mutation.)
                 model.applyChanges(params.data);
                 syncClient.update(model, effective);
-                await waitForMutation(model, effective);
+                await waitForMutation(model);
                 return modelAsRow(model);
             });
             function update(arg, updater, contention) {
@@ -790,7 +797,7 @@ defaultWait) {
             }
             return update;
         })(),
-        delete: guard(async (params) => {
+        delete: guardWrite(async (params) => {
             const autoClaim = params.claim && !isClaimHandle(params.claim) ? params.claim : null;
             if (autoClaim) {
                 const handle = await takeClaim({ ...autoClaim, id: params.id });
@@ -823,7 +830,6 @@ defaultWait) {
             const handle = isClaimHandle(params.claim) ? params.claim : undefined;
             const effective = claimed
                 ? {
-                    wait: 'confirmed',
                     readAt: claimed.lease.readAt ?? claimed.snapshot.stamp,
                     onStale: 'reject',
                     claimRef: { id: claimed.lease.id },
@@ -835,7 +841,6 @@ defaultWait) {
                 : {
                     ...(handle?.readAt !== undefined
                         ? {
-                            wait: 'confirmed',
                             readAt: handle.readAt,
                             onStale: 'reject',
                         }
@@ -844,7 +849,7 @@ defaultWait) {
                     ...(handle ? { claim: { id: handle.id } } : {}),
                 };
             syncClient.delete(model, effective);
-            await waitForMutation(model, effective);
+            await waitForMutation(model);
         }),
         // `claim` is a callable namespace (take a claim) carrying the coordination
         // readers (`claim.state` / `claim.queue` / `claim.release` / `claim.reorder`).

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

@@ -68,6 +68,19 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      * this for you: only a structured `401 session_expired` means signed out.
      */
     apiKey?: string | CredentialProvider | 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.
+     * Defaults to `ABLO_PROJECT_ID`; `ablo dev` writes that value beside the key.
+     * This is an assertion, never a routing selector — the key remains authoritative.
+     */
+    projectId?: string | null | undefined;
+    /**
+     * Pins this client to one immutable Ablo branch. Defaults to
+     * `ABLO_BRANCH_ID`; `ablo dev` writes it beside the branch key. Like
+     * `projectId`, this is a startup assertion and never selects a branch.
+     */
+    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:
@@ -116,7 +129,7 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      * Ablo({
      *   schema,
      *   apiKey,
-     *   durableWrites: { store, namespace: 'agent-worker' },
+     *   durableWrites: { store, namespace: 'headless-worker' },
      * })
      * ```
      */
@@ -192,33 +205,6 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      * session token (`ek_`/`rk_`) or you route through a controlled server proxy.
      */
     dangerouslyAllowBrowser?: boolean | undefined;
-    /**
-     * How far a write goes before its promise settles, for every model write on
-     * this client. The same word each write already takes per call
-     * (`create({ …, wait: 'confirmed' })`); setting it here makes it the default
-     * instead of repeating it.
-     *
-     * A write resolves as soon as it is applied locally and queued. That is what
-     * makes the UI immediate, and it is right for most writes — but it means a
-     * write the server later REFUSES has no caller left to tell. The rejection
-     * reverts the local row and reaches `ablo.onMutationFailure(…)`, and an
-     * application that subscribes to neither shows the change, then loses it,
-     * with nothing thrown anywhere.
-     *
-     * ```ts
-     * const ablo = new Ablo({ schema, apiKey, wait: 'confirmed' });
-     * try {
-     *   await ablo.documents.update({ id, data });   // throws if refused
-     * } catch (err) {
-     *   if (err instanceof AbloError) show(err.message);
-     * }
-     * ```
-     *
-     * The cost is real: each write now waits for the server's answer, so it is a
-     * choice between immediacy and certainty rather than a strict improvement.
-     * A per-call `wait` still wins over this.
-     */
-    wait?: 'queued' | 'confirmed' | undefined;
 }
 export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
     /**
@@ -233,6 +219,8 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      * the original available as `cause`.
      */
     apiKey?: string | CredentialProvider | 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`.
@@ -435,13 +423,10 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      */
     organizationId?: string;
     /**
-     * Immutable branch selected by a self-hosted credential. Hosted clients
-     * receive this from the credential exchange.
+     * Expected immutable branch. Hosted clients compare it with the credential
+     * exchange; self-hosted clients use it as their locally selected branch.
      */
     branchId?: string;
     /** Whether the selected self-hosted branch is the project's root branch. */
     branchRoot?: boolean;
-    /** The client-wide write default — see {@link AbloOptions.wait}. Projected
-     *  from the public option rather than restated, so the two cannot diverge. */
-    wait?: AbloOptions['wait'];
 }

package/dist/local/client/reactiveEngine.js

@@ -429,9 +429,7 @@ export function buildReactiveEngine(inputs) {
                 scope: { [modelKey]: ids },
                 ...(options?.ttl !== undefined ? { ttl: options.ttl } : {}),
             }),
-        }, 
-        // The client-wide `wait` default; a per-call `wait` still wins.
-        internalOptions.wait);
+        });
     }
     const commits = {
         async create(commitOptions) {

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

@@ -8,5 +8,5 @@
  * live participant handle.
  */
 export * from '@abloatai/transaction/resources/httpResources';
-export type { LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimContentionOptions, ClaimAttemptEvent, ClaimQueueView, ClaimLookupParams, ClaimReorderParams, Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, HeldLease, } from '@abloatai/transaction/resources/modelOperations';
+export type { LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelWriteOptions, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimContentionOptions, ClaimAttemptEvent, ClaimQueueView, ClaimLookupParams, ClaimReorderParams, Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, HeldLease, } from '@abloatai/transaction/resources/modelOperations';
 export type { ModelOperations } from './createModelProxy.js';

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

@@ -51,6 +51,10 @@ export interface StoreLifecycleDeps<S extends SchemaRecord> {
     /** Seeds resolved identity into the engine's own state: the self locals and the streams. */
     readonly onIdentityResolved: (seed: IdentitySeed) => void;
 }
+/** Refuse a credential for another project before the store opens its socket. */
+export declare function assertExpectedProject(expectedProjectId: string | null | undefined, actualProjectId: string | null): void;
+/** Refuse a credential for another branch before the store opens its socket. */
+export declare function assertExpectedBranch(expectedBranchId: string | null | undefined, actualBranchId: string | null): void;
 /**
  * Wires the credential machinery onto the cluster and returns the `ready`
  * the client exposes. Wiring happens now — the refresh lifecycle, the

package/dist/local/client/storeLifecycle.js

@@ -10,6 +10,32 @@
  */
 import { resolveParticipantIdentity } from '@abloatai/transaction/auth/identity';
 import { AbloAuthenticationError, AbloConnectionError, toAbloError, } from '@abloatai/transaction/errors';
+/** Refuse a credential for another project before the store opens its socket. */
+export function assertExpectedProject(expectedProjectId, actualProjectId) {
+    const expected = expectedProjectId?.trim();
+    if (!expected || actualProjectId === expected)
+        return;
+    throw new AbloAuthenticationError(`ABLO_API_KEY belongs to project ${actualProjectId ?? '(none)'}, but this app is pinned to ${expected} by projectId/ABLO_PROJECT_ID.`, {
+        code: 'project_scope_denied',
+        details: {
+            expectedProjectId: expected,
+            actualProjectId,
+        },
+    });
+}
+/** Refuse a credential for another branch before the store opens its socket. */
+export function assertExpectedBranch(expectedBranchId, actualBranchId) {
+    const expected = expectedBranchId?.trim();
+    if (!expected || actualBranchId === expected)
+        return;
+    throw new AbloAuthenticationError(`ABLO_API_KEY belongs to branch ${actualBranchId ?? '(none)'}, but this app is pinned to ${expected} by branchId/ABLO_BRANCH_ID.`, {
+        code: 'branch_scope_denied',
+        details: {
+            expectedBranchId: expected,
+            actualBranchId,
+        },
+    });
+}
 /**
  * Wires the credential machinery onto the cluster and returns the `ready`
  * the client exposes. Wiring happens now — the refresh lifecycle, the
@@ -107,7 +133,9 @@ export function startStoreLifecycle(deps) {
                     auth: authCredentials,
                     logger,
                 });
-                const { userId, accountScope, projectId, branchId, branchRoot, teamIds, capabilityToken, syncGroups, participantKind, } = resolved;
+                const { userId, accountScope, projectId, branchId, branchRoot, teamIds, capabilityToken, syncGroups, participantKind, deliveryPartition, } = resolved;
+                assertExpectedProject(internalOptions.projectId, projectId);
+                assertExpectedBranch(internalOptions.branchId, branchId);
                 // Fail-loud guard: detect the degenerate "no real sync groups
                 // resolved" state before opening the socket. It is the same class of bug as
                 // a sensible-looking default that's functionally broken: the
@@ -168,6 +196,7 @@ export function startStoreLifecycle(deps) {
                     kind: participantKind,
                     capabilityToken,
                     syncGroups,
+                    deliveryPartition,
                     bootstrapMode: resolvedBootstrapMode,
                 });
                 let current = gen.next();

package/dist/local/sync/initialize.js

@@ -42,7 +42,7 @@ export function* initialize(host, context, signal) {
         host.setupWebSocketSync(context, lastSyncId);
         // Bootstrap from server if needed.
         //
-        // `bootstrapMode: 'none'` participants (agent-worker, headless
+        // `bootstrapMode: 'none'` participants (headless workers and
         // task runners) skip baseline replication — they read via
         // `model.get()` round-trips and rely on covering deltas
         // from filtered subscriptions to populate the pool lazily. The
@@ -54,7 +54,7 @@ export function* initialize(host, context, signal) {
             // `setupWebSocketSync` above creates the SyncWebSocket and
             // initiates the upgrade, but it does NOT await the 'connected'
             // event — it returns synchronously after wiring listeners.
-            // For bootstrapMode='none' consumers (agent-worker, headless
+            // For bootstrapMode='none' consumers (headless workers and
             // task runners), this branch is the entire body of initialize()
             // after the WS is set up, so `ready()` would otherwise resolve
             // while the WS is still in 'connecting' state. The very next

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

@@ -230,7 +230,7 @@ export declare class MutationQueue extends EventEmitter {
     private dispatchCommitBounded;
     private clearReplicationLagState;
     /**
-     * Bounds the public `wait: 'confirmed'` promise without changing the
+     * Bounds the public model-write confirmation promise without changing the
      * accepted write's lifecycle. A lag timeout is not a rejection from the
      * source database, so it must never emit `transaction:failed`, roll back
      * optimistic state, or remove the durable replay envelope.

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

@@ -740,7 +740,7 @@ export class MutationQueue extends EventEmitter {
         this.replicationLagErrors.delete(transactionId);
     }
     /**
-     * Bounds the public `wait: 'confirmed'` promise without changing the
+     * Bounds the public model-write confirmation promise without changing the
      * accepted write's lifecycle. A lag timeout is not a rejection from the
      * source database, so it must never emit `transaction:failed`, roll back
      * optimistic state, or remove the durable replay envelope.

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

@@ -101,8 +101,8 @@ export async function handleFailure(ctx, transaction, error) {
             await ctx.rollbackOptimistic(transaction, 'permanent_error', error);
         }
         ctx.emit('transaction:failed', { transaction, error, permanent: true });
-        // The id-suffixed event is what `waitForConfirmation` (the
-        // `wait:'confirmed'` path) listens on — without it a permanently
+        // The id-suffixed event is what the awaited model-write promise listens
+        // on through `waitForConfirmation` — without it a permanently
         // rejected write left the caller's promise hanging forever.
         ctx.emit(`transaction:failed:${transaction.id}`, { error });
         return;

package/dist/surface.d.ts

@@ -30,7 +30,7 @@ export declare const PUBLIC_LIST_OPTION_KEYS: readonly ["where", "filter", "orde
  * The keys of the client constructor options, {@link AbloOptions}. Only
  * `schema` is required; every other key is optional.
  */
-export declare const PUBLIC_ABLO_OPTION_KEYS: readonly ["schema", "apiKey", "authEndpoint", "authTimeoutMs", "allowCrossOriginAuthEndpoint", "persistence", "durableWrites", "commitOutbox", "commitOutboxScope", "debug", "logLevel", "logger", "authToken", "baseURL", "fetch", "defaultHeaders", "defaultQuery", "dangerouslyAllowBrowser", "collaborationEvents", "plugins", "wait"];
+export declare const PUBLIC_ABLO_OPTION_KEYS: readonly ["schema", "apiKey", "projectId", "branchId", "authEndpoint", "authTimeoutMs", "allowCrossOriginAuthEndpoint", "persistence", "durableWrites", "commitOutbox", "commitOutboxScope", "debug", "logLevel", "logger", "authToken", "baseURL", "fetch", "defaultHeaders", "defaultQuery", "dangerouslyAllowBrowser", "collaborationEvents", "plugins"];
 export type ModelVerb = (typeof PUBLIC_MODEL_VERBS)[number];
 export type ListOptionKey = (typeof PUBLIC_LIST_OPTION_KEYS)[number];
 export type AbloOptionKey = (typeof PUBLIC_ABLO_OPTION_KEYS)[number];

package/dist/surface.js

@@ -55,6 +55,8 @@ export const PUBLIC_LIST_OPTION_KEYS = [
 export const PUBLIC_ABLO_OPTION_KEYS = [
     'schema',
     'apiKey',
+    'projectId',
+    'branchId',
     'authEndpoint',
     'authTimeoutMs',
     'allowCrossOriginAuthEndpoint',
@@ -73,5 +75,4 @@ export const PUBLIC_ABLO_OPTION_KEYS = [
     'dangerouslyAllowBrowser',
     'collaborationEvents',
     'plugins',
-    'wait',
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/humans",
-  "version": "0.46.0",
+  "version": "0.48.0",
   "description": "The optional human-facing local-state package for Ablo: presence, live queries, and React bindings.",
   "license": "Apache-2.0",
   "type": "module",
@@ -84,7 +84,7 @@
     "directory": "packages/humans"
   },
   "dependencies": {
-    "@abloatai/transaction": "^0.46.0",
+    "@abloatai/transaction": "^0.48.0",
     "mobx": "^6.13.7",
     "uuid": "^11.1.0",
     "zod": "^4.4.3"
@@ -99,6 +99,7 @@
   },
   "devDependencies": {
     "@jest/globals": "^30.2.0",
+    "@testing-library/dom": "^10.0.0",
     "@testing-library/react": "^16.0.0",
     "@types/jest": "^30.0.0",
     "@types/react": "^19.0.0",

package/src/local/BaseSyncedStore.ts

@@ -73,6 +73,7 @@ import type { PoolContext, RehydrationStats } from './sync/bootstrapApply.js';
 import * as deltaPipeline from './sync/deltaPipeline.js';
 import type { DeltaPipelineContext } from './sync/deltaPipeline.js';
 import type { ParticipantKind } from '@abloatai/transaction/types/participant';
+import type { DeliveryPartitionRoute } from '@abloatai/transaction/auth/deliveryPartition';
 import { queryByClass as runQueryByClass, countModels } from './store/queryApi.js';
 import type { QueuedMutation } from './transactions/mutations/MutationQueue.js';
 import type { CommitLatencySample } from './transactions/mutations/commitLatency.js';
@@ -150,6 +151,8 @@ export interface UserContext {
   branchId: string;
   /** True only when branchId is the project's production root. */
   branchRoot?: boolean;
+  /** Server-resolved WebSocket gateway route; never an authorization claim. */
+  deliveryPartition?: DeliveryPartitionRoute | null;
   role?: string;
   teamIds?: string[];
   /** Participant kind on the wire. Default 'user' for browser
@@ -175,7 +178,7 @@ export interface UserContext {
    *  - `'none'`: open the WebSocket and process live deltas only.
    *    Reads go through `model.get()` / filtered subscriptions
    *    backfilled by `Covering` deltas. Suitable for transactional
-   *    participants — agent-worker, video-pipeline, routine runners —
+   *    participants — headless workers, video pipelines, routine runners —
    *    that don't need a local replica of the org's tenant plane.
    */
   bootstrapMode?: 'full' | 'none';
@@ -1457,6 +1460,7 @@ export class BaseSyncedStore<
     }
     const syncGroups = this.resolveSyncGroups(context);
     this.syncWebSocket.setSyncGroups(syncGroups);
+    this.syncWebSocket.setDeliveryPartition(context.deliveryPartition ?? null);
     this.syncWebSocket.setLastSyncId(lastSyncId || 0);
     // The permanent base scopes for read interest — same set the connection
     // subscribes to at upgrade, so the two can never disagree.

package/src/local/Database.ts

@@ -1125,7 +1125,7 @@ export class Database {
     // ── inMemory short-circuit ───────────────────────────────────────
     //
     // The batched IDB transaction path below assumes `this.storeManager`
-    // and `workspaceDb`. In inMemory mode (agent-worker, tests) those
+    // and `workspaceDb`. In inMemory mode (headless workers, tests) those
     // don't exist. Without this branch, every live delta arriving over
     // the WebSocket is silently dropped — the local pool never updates,
     // `subscribe()` autoruns never re-fire, lazy-model dispatchers

package/src/local/client/clientPrelude.ts

@@ -69,8 +69,12 @@ export interface ClientPrelude<S extends SchemaRecord> {
 export function resolveClientPrelude<S extends SchemaRecord>(
   options: AbloOptions<S>,
 ): ClientPrelude<S> {
-  const internalOptions = options as InternalAbloOptions<S>;
   const env = readProcessEnv();
+  const internalOptions = {
+    ...options,
+    projectId: options.projectId ?? env.ABLO_PROJECT_ID,
+    branchId: options.branchId ?? env.ABLO_BRANCH_ID,
+  } as InternalAbloOptions<S>;
   const authInput = { options, env };
   const configuredApiKey = resolveApiKey(authInput);
   const configuredAuthToken = resolveAuthToken(authInput);

package/src/local/client/createModelProxy.ts

@@ -405,8 +405,6 @@ export function createModelProxy<T, C>(
    */
   hydration: Pick<OnDemandLoader, 'fetch'>,
   collaboration?: ModelCollaboration,
-  /** The client-wide `wait` default; a per-call `wait` still wins over it. */
-  defaultWait?: 'queued' | 'confirmed',
 ): ModelOperations<T, C> {
   /**
    * Resolve a row **this** resource owns.
@@ -471,20 +469,34 @@ export function createModelProxy<T, C>(
     };
   };
 
+  const guardWrite = <A extends unknown[], R>(
+    fn: (...args: A) => Promise<R>,
+  ): ((...args: A) => Promise<R>) => {
+    const guarded = guard(fn);
+    return (...args: A): Promise<R> => {
+      const confirmation = guarded(...args);
+      // Optimistic writes are intentionally useful without awaiting them. The
+      // transaction pipeline already reports a later refusal through
+      // `onMutationFailure`; attach an observer here as well so choosing not to
+      // 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);
+      return confirmation;
+    };
+  };
+
   const load = async (options?: ServerReadOptions<T>): Promise<T[]> => {
     const rows = await hydration.fetch<T>(schemaKey, options);
     return rows.map((row) => modelAsRow<T>(row));
   };
 
-  const waitForMutation = async (
-    model: Model,
-    options?: MutationOptions,
-  ): Promise<void> => {
-    // A per-call `wait` wins; otherwise the client-wide default decides. This
-    // is the single point that turns "confirmed" into actually waiting, so a
-    // client configured that way rejects on a refused write everywhere rather
-    // than in the one place a caller remembered to ask.
-    if ((options?.wait ?? defaultWait) !== 'confirmed') return;
+  const waitForMutation = async (model: Model): 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
+    // global mutation-failure handler; awaiting the promise never means merely
+    // "placed in the local queue".
     // Let sibling writes from the same synchronous burst enter the mutation
     // queue before forcing a drain. Without this yield, every confirmed
     // create/update calls syncNow() alone, defeating the queue's microtask
@@ -540,7 +552,6 @@ export function createModelProxy<T, C>(
         ? { idempotencyKey: params.idempotencyKey }
         : {}),
       ...(params.label !== undefined ? { label: params.label } : {}),
-      ...(params.wait !== undefined ? { wait: params.wait } : {}),
       ...(params.readAt !== undefined ? { readAt: params.readAt } : {}),
       ...(params.onStale !== undefined ? { onStale: params.onStale } : {}),
       ...(params.fenceToken !== undefined ? { fenceToken: params.fenceToken } : {}),
@@ -1086,7 +1097,7 @@ export function createModelProxy<T, C>(
     // unbounded set of rows' entity groups.
     list: guard(load),
 
-    create: guard(async (params: ModelCreateParams<T, C>): Promise<T> => {
+    create: guardWrite(async (params: ModelCreateParams<T, C>): Promise<T> => {
       const id = params.id ?? Model.generateId();
       const opts = mutationOptions(params);
       const claim = params.claim;
@@ -1142,7 +1153,7 @@ export function createModelProxy<T, C>(
       };
       try {
         syncClient.add(model, effective);
-        await waitForMutation(model, effective);
+        await waitForMutation(model);
         return modelAsRow<T>(model);
       } finally {
         await autoLease?.release?.().catch(() => {});
@@ -1154,7 +1165,7 @@ export function createModelProxy<T, C>(
     // wrapping while exposing the two public signatures (a plain `guard(...)`
     // would collapse them to one).
     update: ((): ModelOperations<T, C>['update'] => {
-      const updateImpl = guard(
+      const updateImpl = guardWrite(
         async (
           arg: ModelUpdateParams<T, C> | string,
           updater?: ModelUpdater<T>,
@@ -1206,13 +1217,12 @@ export function createModelProxy<T, C>(
                 );
               }
               const effective: MutationOptions = {
-                wait: 'confirmed',
                 readAt,
                 onStale: 'reject',
               };
               model.applyChanges(patch);
               syncClient.update(model, effective);
-              await waitForMutation(model, effective);
+              await waitForMutation(model);
               return modelAsRow<T>(model);
             },
           });
@@ -1250,7 +1260,6 @@ export function createModelProxy<T, C>(
         const handle = isClaimHandle(params.claim) ? params.claim : undefined;
         const effective: MutationOptions | undefined = claimed
           ? {
-              wait: 'confirmed',
               readAt: claimed.lease.readAt ?? claimed.snapshot.stamp,
               onStale: 'reject',
               claimRef: { id: claimed.lease.id },
@@ -1262,7 +1271,6 @@ export function createModelProxy<T, C>(
               // works across clients (HTTP-minted handles included).
               ...(handle?.readAt !== undefined
                 ? {
-                    wait: 'confirmed' as const,
                     readAt: handle.readAt,
                     onStale: 'reject' as const,
                     ...(handle.fenceToken !== undefined
@@ -1279,7 +1287,7 @@ export function createModelProxy<T, C>(
         // the tracking, producing an empty `input: {}` no-op mutation.)
         model.applyChanges(params.data);
         syncClient.update(model, effective);
-        await waitForMutation(model, effective);
+        await waitForMutation(model);
         return modelAsRow<T>(model);
         },
       );
@@ -1299,7 +1307,7 @@ export function createModelProxy<T, C>(
       return update;
     })(),
 
-    delete: guard(async (params: ModelDeleteParams<T, C>): Promise<void> => {
+    delete: guardWrite(async (params: ModelDeleteParams<T, C>): Promise<void> => {
       const autoClaim =
         params.claim && !isClaimHandle(params.claim) ? params.claim : null;
       if (autoClaim) {
@@ -1334,7 +1342,6 @@ export function createModelProxy<T, C>(
       const handle = isClaimHandle(params.claim) ? params.claim : undefined;
       const effective: MutationOptions | undefined = claimed
         ? {
-            wait: 'confirmed',
             readAt: claimed.lease.readAt ?? claimed.snapshot.stamp,
             onStale: 'reject',
             claimRef: { id: claimed.lease.id },
@@ -1346,7 +1353,6 @@ export function createModelProxy<T, C>(
         : {
             ...(handle?.readAt !== undefined
               ? {
-                  wait: 'confirmed' as const,
                   readAt: handle.readAt,
                   onStale: 'reject' as const,
                 }
@@ -1355,7 +1361,7 @@ export function createModelProxy<T, C>(
             ...(handle ? { claim: { id: handle.id } } : {}),
           };
       syncClient.delete(model, effective);
-      await waitForMutation(model, effective);
+      await waitForMutation(model);
     }),
 
     // `claim` is a callable namespace (take a claim) carrying the coordination

package/src/local/client/options.ts

@@ -87,6 +87,21 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
    */
   apiKey?: string | CredentialProvider | 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.
+   * Defaults to `ABLO_PROJECT_ID`; `ablo dev` writes that value beside the key.
+   * This is an assertion, never a routing selector — the key remains authoritative.
+   */
+  projectId?: string | null | undefined;
+
+  /**
+   * Pins this client to one immutable Ablo branch. Defaults to
+   * `ABLO_BRANCH_ID`; `ablo dev` writes it beside the branch key. Like
+   * `projectId`, this is a startup assertion and never selects a branch.
+   */
+  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:
@@ -139,7 +154,7 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
    * Ablo({
    *   schema,
    *   apiKey,
-   *   durableWrites: { store, namespace: 'agent-worker' },
+   *   durableWrites: { store, namespace: 'headless-worker' },
    * })
    * ```
    */
@@ -230,34 +245,6 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
    * session token (`ek_`/`rk_`) or you route through a controlled server proxy.
    */
   dangerouslyAllowBrowser?: boolean | undefined;
-
-  /**
-   * How far a write goes before its promise settles, for every model write on
-   * this client. The same word each write already takes per call
-   * (`create({ …, wait: 'confirmed' })`); setting it here makes it the default
-   * instead of repeating it.
-   *
-   * A write resolves as soon as it is applied locally and queued. That is what
-   * makes the UI immediate, and it is right for most writes — but it means a
-   * write the server later REFUSES has no caller left to tell. The rejection
-   * reverts the local row and reaches `ablo.onMutationFailure(…)`, and an
-   * application that subscribes to neither shows the change, then loses it,
-   * with nothing thrown anywhere.
-   *
-   * ```ts
-   * const ablo = new Ablo({ schema, apiKey, wait: 'confirmed' });
-   * try {
-   *   await ablo.documents.update({ id, data });   // throws if refused
-   * } catch (err) {
-   *   if (err instanceof AbloError) show(err.message);
-   * }
-   * ```
-   *
-   * The cost is real: each write now waits for the server's answer, so it is a
-   * choice between immediacy and certainty rather than a strict improvement.
-   * A per-call `wait` still wins over this.
-   */
-  wait?: 'queued' | 'confirmed' | undefined;
 }
 
 export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
@@ -274,6 +261,9 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
    */
   apiKey?: string | CredentialProvider | 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`.
@@ -521,15 +511,11 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
   organizationId?: string;
 
   /**
-   * Immutable branch selected by a self-hosted credential. Hosted clients
-   * receive this from the credential exchange.
+   * Expected immutable branch. Hosted clients compare it with the credential
+   * exchange; self-hosted clients use it as their locally selected branch.
    */
   branchId?: string;
 
   /** Whether the selected self-hosted branch is the project's root branch. */
   branchRoot?: boolean;
-
-  /** The client-wide write default — see {@link AbloOptions.wait}. Projected
-   *  from the public option rather than restated, so the two cannot diverge. */
-  wait?: AbloOptions['wait'];
 }

package/src/local/client/reactiveEngine.ts

@@ -607,8 +607,6 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
             ...(options?.ttl !== undefined ? { ttl: options.ttl } : {}),
           }),
       },
-      // The client-wide `wait` default; a per-call `wait` still wins.
-      internalOptions.wait,
     );
   }
 

package/src/local/client/resourceTypes.ts

@@ -18,6 +18,7 @@ export type {
   ModelListScope,
   ServerReadOptions,
   ModelRetrieveParams,
+  ModelWriteOptions,
   ModelCreateParams,
   ModelUpdateParams,
   ModelDeleteParams,

package/src/local/client/storeLifecycle.ts

@@ -63,6 +63,44 @@ export interface StoreLifecycleDeps<S extends SchemaRecord> {
   readonly onIdentityResolved: (seed: IdentitySeed) => void;
 }
 
+/** Refuse a credential for another project before the store opens its socket. */
+export function assertExpectedProject(
+  expectedProjectId: string | null | undefined,
+  actualProjectId: string | null
+): void {
+  const expected = expectedProjectId?.trim();
+  if (!expected || actualProjectId === expected) return;
+  throw new AbloAuthenticationError(
+    `ABLO_API_KEY belongs to project ${actualProjectId ?? '(none)'}, but this app is pinned to ${expected} by projectId/ABLO_PROJECT_ID.`,
+    {
+      code: 'project_scope_denied',
+      details: {
+        expectedProjectId: expected,
+        actualProjectId,
+      },
+    }
+  );
+}
+
+/** Refuse a credential for another branch before the store opens its socket. */
+export function assertExpectedBranch(
+  expectedBranchId: string | null | undefined,
+  actualBranchId: string | null
+): void {
+  const expected = expectedBranchId?.trim();
+  if (!expected || actualBranchId === expected) return;
+  throw new AbloAuthenticationError(
+    `ABLO_API_KEY belongs to branch ${actualBranchId ?? '(none)'}, but this app is pinned to ${expected} by branchId/ABLO_BRANCH_ID.`,
+    {
+      code: 'branch_scope_denied',
+      details: {
+        expectedBranchId: expected,
+        actualBranchId,
+      },
+    }
+  );
+}
+
 /**
  * Wires the credential machinery onto the cluster and returns the `ready`
  * the client exposes. Wiring happens now — the refresh lifecycle, the
@@ -200,8 +238,12 @@ export function startStoreLifecycle<S extends SchemaRecord>(
           capabilityToken,
           syncGroups,
           participantKind,
+          deliveryPartition,
         } = resolved;
 
+        assertExpectedProject(internalOptions.projectId, projectId);
+        assertExpectedBranch(internalOptions.branchId, branchId);
+
         // Fail-loud guard: detect the degenerate "no real sync groups
         // resolved" state before opening the socket. It is the same class of bug as
         // a sensible-looking default that's functionally broken: the
@@ -274,6 +316,7 @@ export function startStoreLifecycle<S extends SchemaRecord>(
           kind: participantKind,
           capabilityToken,
           syncGroups,
+          deliveryPartition,
           bootstrapMode: resolvedBootstrapMode,
         });
         let current = gen.next();

package/src/local/sync/initialize.ts

@@ -91,7 +91,7 @@ export function* initialize<TCollaboration extends EventMap<TCollaboration>>(
 
       // Bootstrap from server if needed.
       //
-      // `bootstrapMode: 'none'` participants (agent-worker, headless
+      // `bootstrapMode: 'none'` participants (headless workers and
       // task runners) skip baseline replication — they read via
       // `model.get()` round-trips and rely on covering deltas
       // from filtered subscriptions to populate the pool lazily. The
@@ -109,7 +109,7 @@ export function* initialize<TCollaboration extends EventMap<TCollaboration>>(
         // `setupWebSocketSync` above creates the SyncWebSocket and
         // initiates the upgrade, but it does NOT await the 'connected'
         // event — it returns synchronously after wiring listeners.
-        // For bootstrapMode='none' consumers (agent-worker, headless
+        // For bootstrapMode='none' consumers (headless workers and
         // task runners), this branch is the entire body of initialize()
         // after the WS is set up, so `ready()` would otherwise resolve
         // while the WS is still in 'connecting' state. The very next

package/src/local/transactions/mutations/MutationQueue.ts

@@ -175,8 +175,8 @@ export interface MutationQueueConfig {
   maxExecutingTransactions: number;
   // How long to wait, in milliseconds, for a change's confirming sync delta
   // before the retry-and-reconciliation cycle begins. For a source-forwarded
-  // write this is also the public `wait: 'confirmed'` deadline: expiry rejects
-  // the waiter with `replication_lag_timeout` while the accepted write remains
+  // write this is also the awaited model-write deadline: expiry rejects the
+  // waiter with `replication_lag_timeout` while the accepted write remains
   // pending. Defaults to 30000 (30 seconds); raise it for slow networks.
   deltaConfirmationTimeout: number;
   /**
@@ -1087,7 +1087,7 @@ export class MutationQueue extends EventEmitter {
   }
 
   /**
-   * Bounds the public `wait: 'confirmed'` promise without changing the
+   * Bounds the public model-write confirmation promise without changing the
    * accepted write's lifecycle. A lag timeout is not a rejection from the
    * source database, so it must never emit `transaction:failed`, roll back
    * optimistic state, or remove the durable replay envelope.

package/src/local/transactions/mutations/failureHandling.ts

@@ -131,8 +131,8 @@ export async function handleFailure(ctx: FailureHandlingContext, transaction: Qu
       }
 
       ctx.emit('transaction:failed', { transaction, error, permanent: true });
-      // The id-suffixed event is what `waitForConfirmation` (the
-      // `wait:'confirmed'` path) listens on — without it a permanently
+      // The id-suffixed event is what the awaited model-write promise listens
+      // on through `waitForConfirmation` — without it a permanently
       // rejected write left the caller's promise hanging forever.
       ctx.emit(`transaction:failed:${transaction.id}`, { error });
       return;

package/src/surface.ts

@@ -76,6 +76,8 @@ type _ListOptionKeysExact = Expect<
 export const PUBLIC_ABLO_OPTION_KEYS = [
   'schema',
   'apiKey',
+  'projectId',
+  'branchId',
   'authEndpoint',
   'authTimeoutMs',
   'allowCrossOriginAuthEndpoint',
@@ -94,7 +96,6 @@ export const PUBLIC_ABLO_OPTION_KEYS = [
   'dangerouslyAllowBrowser',
   'collaborationEvents',
   'plugins',
-  'wait',
 ] as const;
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 type _AbloOptionKeysExact = Expect<