@abloatai/humans 0.57.0 → 0.59.0

package/dist/local/client/{createModelProxy.js → createModelOperations.js}

@@ -3,7 +3,7 @@
  * `ablo.<model>`.
  *
  * Each schema model gets one {@link ModelOperations}: the async server reads
- * `get` and `list`, with the same point lookup restricted to the local graph under
+ * `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`.
@@ -12,31 +12,32 @@
  */
 import { autorun } from 'mobx';
 import { AbloClaimedError, AbloValidationError, toAbloError, } from '@abloatai/transaction/errors';
-import { reconcileFunctionalUpdate, } from '@abloatai/transaction/resources/functionalUpdate';
+import { reconcileFunctionalUpdate, } from '@abloatai/transaction/client/resources/functionalUpdate';
 import { claimDescription, } from '@abloatai/transaction/coordination/schema';
 import { Model, modelAsRow } from '../Model.js';
 import { toMs } from '@abloatai/transaction/utils/duration';
 import { LEASE_TTL_MS } from '@abloatai/transaction/wire/protocol';
-import { heartbeatCadenceMs, resolveHeartbeatOptions, resolveHeartbeatPlan, startClaimHeartbeatLoop, } from '@abloatai/transaction/coordination/claimHeartbeatLoop';
-import { assertWriteOptions, assertWriteTarget, } from '@abloatai/transaction/resources/writeOptionsSchema';
-import { createModelId, resolveCreatedRows, resolveCreateId, } from '@abloatai/transaction/resources/modelCreate';
-import { collectModelList, modelList, } from '@abloatai/transaction/resources/httpResources';
+import { heartbeatCadenceMs, resolveHeartbeatOptions, resolveHeartbeatPlan, startClaimHeartbeatLoop, } from '@abloatai/transaction/claims';
+import { assertWriteOptions, assertWriteTarget, } from '@abloatai/transaction/client/resources/writeOptionsSchema';
+import { createModelId, resolveCreatedRows, resolveCreateId, } from '@abloatai/transaction/client/resources/modelCreate';
+import { collectModelList, modelList, } from '@abloatai/transaction/client/resources/httpResources';
 import { subTarget } from '@abloatai/transaction/coordination';
 // A named claim-meta crossing (see `claim-meta-crossings-are-enumerated` in
-// .dependency-cruiser.cjs): the reactive proxy's self-claim targets are
+// .dependency-cruiser.cjs): the reactive model surface's self-claim targets are
 // decodes that build a public claim, so their `meta` converts wire→declared
 // here like the other enumerated crossings.
-import { declaredMeta } from '@abloatai/transaction/coordination/claimMeta';
+import { declaredMeta } from '@abloatai/transaction/claims';
 import { ModelScope } from '@abloatai/transaction/types';
-import { claimQueueView, resolveClaimContentionOptions, } from '@abloatai/transaction/resources/modelOperations';
-import { abortReadSetCommit, capturePointRead, consumeReadSet, prepareReadSet, } from '@abloatai/transaction/internal/read-set';
+import { bindClaimLifetime, claimLifetimeOf, } from '@abloatai/transaction/claims/lifetime';
+import { claimQueueView, resolveClaimContentionOptions, } from '@abloatai/transaction/client/resources/modelOperations';
+import { capturePointRead, prepareReadSet, } from '@abloatai/transaction/internal/read-set';
 const modelClientMeta = new WeakMap();
 export function getModelClientMeta(modelClient) {
     if (typeof modelClient !== 'object' || modelClient === null)
         return undefined;
     return modelClientMeta.get(modelClient);
 }
-export function createModelProxy(schemaKey, registeredModelName, objectPool, syncClient, registry, 
+export function createModelOperations(schemaKey, registeredModelName, objectPool, syncClient, registry, 
 /**
  * The one thing this factory asks of the loader: fetch rows for a model.
  *
@@ -143,18 +144,36 @@ hydration, collaboration, readSetContext) {
         await syncClient.syncNow();
         await syncClient.waitForConfirmation(model.getModelName(), model.id);
     };
-    // Claims this proxy currently holds, keyed by entity id. Lets the flat
-    // `release({ id })` and `update({ id, data })` find the lease and snapshot a
-    // `claim({ id })` took, without a per-call handle. Released on dispose,
-    // explicit release, or TTL expiry.
-    //
-    // `target`, `description`, and `expiresAt` are kept alongside the lease so
-    // `claim.state` can synthesize a self-claim: the server excludes a holder's
-    // own presence frames, so this proxy is the only place that knows the client
-    // holds the row. `expiresAt` is the client's best estimate from the requested
-    // TTL (a real epoch-millisecond expiry, not a fabricated watermark), defaulting
-    // to the server's keepalive lease window when no TTL was requested.
     const activeClaims = new Map();
+    const claimIdsByEntity = new Map();
+    const claimsForEntity = (entityId) => [...(claimIdsByEntity.get(entityId) ?? [])].flatMap((claimId) => {
+        const held = activeClaims.get(claimId);
+        return held ? [held] : [];
+    });
+    const addActiveClaim = (claimId, held) => {
+        activeClaims.set(claimId, held);
+        const ids = claimIdsByEntity.get(held.entityId) ?? new Set();
+        ids.add(claimId);
+        claimIdsByEntity.set(held.entityId, ids);
+    };
+    const removeActiveClaim = (claimId) => {
+        const held = activeClaims.get(claimId);
+        if (!held)
+            return undefined;
+        activeClaims.delete(claimId);
+        const ids = claimIdsByEntity.get(held.entityId);
+        ids?.delete(claimId);
+        if (ids?.size === 0)
+            claimIdsByEntity.delete(held.entityId);
+        held.stopHeartbeat?.();
+        return held;
+    };
+    const implicitClaimForEntity = (entityId) => {
+        const held = claimsForEntity(entityId);
+        if (held.length <= 1)
+            return held[0];
+        throw new AbloValidationError(`${registeredModelName}/${entityId} has ${held.length} local claims on different parts of the row. Pass the exact claim handle to the write so Ablo can use the intended grant.`, { code: 'write_options_invalid', param: 'claim' });
+    };
     // Server keepalive lease window — the same `LEASE_TTL_MS` the wire protocol
     // declares, so the client's estimate and the server's lease cannot drift.
     // This is the fallback expiry estimate when a claim is taken without an
@@ -166,7 +185,7 @@ hydration, collaboration, readSetContext) {
         typeof value.id === 'string' &&
         typeof value.release === 'function';
     const preparedMutation = (params) => {
-        const prepared = prepareReadSet(readSetContext, readSetClientIdentity, params.readAt, params.onStale, params.idempotencyKey, params.reads);
+        const prepared = prepareReadSet(readSetContext, readSetClientIdentity, undefined, params.idempotencyKey, params.reads);
         const rest = {
             ...(prepared.idempotencyKey !== undefined
                 ? { idempotencyKey: prepared.idempotencyKey }
@@ -174,54 +193,46 @@ hydration, collaboration, readSetContext) {
                     ? { idempotencyKey: params.idempotencyKey }
                     : {}),
             ...(params.label !== undefined ? { label: params.label } : {}),
-            ...(prepared.readAt !== undefined
-                ? { readAt: prepared.readAt }
-                : params.readAt !== undefined
-                    ? { readAt: params.readAt }
-                    : {}),
-            ...(prepared.onStale !== undefined
-                ? { onStale: prepared.onStale }
-                : params.onStale !== undefined
-                    ? { onStale: params.onStale }
-                    : {}),
-            ...(params.fenceToken !== undefined ? { fenceToken: params.fenceToken } : {}),
-            ...(params.claimRef !== undefined ? { claimRef: params.claimRef } : {}),
             ...(prepared.reads !== undefined
                 ? { reads: prepared.reads === null ? null : [...prepared.reads] }
                 : params.reads !== undefined
                     ? { reads: params.reads }
                     : {}),
-            ...(params.track !== undefined ? { track: params.track } : {}),
         };
         // The write-options schema — the runtime twin of the compile-time params.
-        // Catches plain-JavaScript callers (for example `onStale: 'rejct'`) at the
-        // call site with a typed error instead of a silent no-op or a server 400.
-        try {
-            assertWriteOptions(rest, `${schemaKey} write`);
-        }
-        catch (error) {
-            abortReadSetCommit(readSetContext, prepared.automaticCommit);
-            throw error;
-        }
-        return { options: rest, prepared };
+        // Catches plain-JavaScript callers at the call site with a typed error
+        // instead of a silent no-op or a server 400.
+        assertWriteOptions(rest, `${schemaKey} write`);
+        return rest;
     };
-    const releaseClaim = async (id) => {
-        const held = activeClaims.get(id);
+    const releaseClaim = async (claimId) => {
+        const held = removeActiveClaim(claimId);
         if (!held)
             return;
-        activeClaims.delete(id);
         await held.lease.release?.();
     };
+    const releaseClaimsForEntity = async (entityId) => {
+        const ids = [...(claimIdsByEntity.get(entityId) ?? [])];
+        await Promise.all(ids.map((claimId) => releaseClaim(claimId)));
+    };
+    const settleClaimsAfterWrite = async (entityId, explicit) => {
+        const explicitWasLocal = explicit ? activeClaims.has(explicit.id) : false;
+        // The server fulfills every claim this participant holds on the written
+        // entity. Mirror that terminal transition locally so claim.state/list and
+        // heartbeat bookkeeping do not describe leases the commit already ended.
+        // This runs after authoritative confirmation. A best-effort abandon frame
+        // cannot turn a committed write into an apparent failure; the server has
+        // already fulfilled the participant's claims as part of that commit.
+        await releaseClaimsForEntity(entityId).catch(() => undefined);
+        if (explicit && !explicitWasLocal) {
+            await explicit.release?.().catch(() => undefined);
+        }
+    };
     const takeClaim = async (params) => {
         if (!collaboration) {
             throw new AbloValidationError(`Model "${schemaKey}" was built without the collaboration runtime, so claim() is unavailable here. Claiming needs no per-model config — use the standard Ablo({ schema, apiKey }) client and every model is claimable.`, { code: 'model_claim_not_configured' });
         }
         const { id, ...options } = params;
-        // Read the local snapshot only to decide whether a post-grant re-read may
-        // be needed. Admission itself always goes to the server: a local presence
-        // snapshot may be stale or incomplete across instances.
-        const held = collaboration.state({ model: wireModel, id });
-        const contended = !!held && held.heldBy !== collaboration.selfParticipantId;
         const contention = resolveClaimContentionOptions(options);
         const failFast = !contention.wait;
         // Ensure the row exists locally before claiming.
@@ -277,24 +288,25 @@ hydration, collaboration, readSetContext) {
             }
             throw normalized;
         }
-        // Only when the claim actually waited behind another holder can the row have
-        // changed underneath us — re-read so the claimed snapshot reflects what that
-        // holder committed before releasing. Either of two signals suffices:
-        //   - `lease.waited` — the server granted the claim after the client
-        //     provably queued behind a holder. Authoritative; it works even when the
-        //     local snapshot is blind, since claim fan-out is entity-scoped and a
-        //     broadly-subscribed client never observes peers' claims.
-        //   - `contended` — the local snapshot saw a holder up front. Kept for the
-        //     no-queue paths, where no grant frame exists.
-        if ((contended || lease.waited === true) && !failFast) {
-            // `type: 'complete'` forces the round-trip: the hydration ledger would
-            // otherwise serve the local row for an already-hydrated id, and the
-            // holder's final write may not have fanned out yet — the exact
-            // stale-snapshot race this re-read closes.
-            await load({ where: [['id', id]], type: 'complete' });
-            model = ownRowOrThrow(id) ?? model;
-        }
-        const snapshot = collaboration.createSnapshot(schemaKey, id);
+        // Re-read on grant, never on contention. Holding the lease is the moment
+        // this snapshot becomes the premise an expensive step is about to be spent
+        // against, so it is read then — whether or not the claim queued, and
+        // whether or not a local presence snapshot saw a holder.
+        //
+        // Gating this on contention assumed only a prior holder could have moved
+        // the row, which holds while every writer passes the chokepoint and the
+        // default policy refuses a non-holder's write. It does not hold for a row
+        // fed by the WAL: a write that landed straight in the customer's database
+        // never met a claim, so "nobody contended" was never evidence the row had
+        // not changed. The HTTP claim has always read unconditionally here.
+        //
+        // `type: 'complete'` forces the round-trip: the hydration ledger would
+        // otherwise serve the local row for an already-hydrated id, and a peer's
+        // final write may not have fanned out yet — the exact stale-snapshot race
+        // this closes.
+        await load({ where: [['id', id]], type: 'complete' });
+        model = ownRowOrThrow(id) ?? model;
+        const readAt = lease.readAt ?? collaboration.currentReadAt();
         const description = claimDescription(options);
         // The self-claim's `ClaimTarget` mirrors what a peer's `claim.state` would
         // report (`state` maps `held.target.model` to `type`), so a holder and a
@@ -311,13 +323,15 @@ hydration, collaboration, readSetContext) {
         };
         const ttlMs = options.ttl !== undefined ? toMs(options.ttl) : DEFAULT_LEASE_TTL_MS;
         const expiresAt = Date.now() + ttlMs;
-        activeClaims.set(id, {
+        const active = {
+            entityId: id,
             lease,
-            snapshot,
+            readAt,
             target: selfTarget,
             description,
             expiresAt,
-        });
+        };
+        addActiveClaim(lease.id, active);
         const { meta: targetMeta, ...targetNarrowed } = subTarget(options, schemaKey);
         const target = {
             type: schemaKey,
@@ -341,7 +355,7 @@ hydration, collaboration, readSetContext) {
                 ttl: resolved.ttl ?? options.ttl,
                 ...(resolved.details !== undefined ? { details: resolved.details } : {}),
             });
-            const held = activeClaims.get(id);
+            const held = activeClaims.get(lease.id);
             if (held)
                 held.expiresAt = beat.expiresAt;
             plan.onBeat?.(beat);
@@ -356,14 +370,18 @@ hydration, collaboration, readSetContext) {
                 ...(plan.onLost ? { onLost: plan.onLost } : {}),
             })
             : undefined;
+        active.stopHeartbeat = stopHeartbeatLoop;
+        const lifetime = claimLifetimeOf(lease);
+        lifetime?.onEnd(() => {
+            removeActiveClaim(lease.id);
+        });
         const release = () => {
-            stopHeartbeatLoop?.();
-            return releaseClaim(id);
+            return releaseClaim(lease.id);
         };
-        return {
+        const handle = {
             object: 'claim',
             id: lease.id,
-            readAt: lease.readAt ?? snapshot.stamp,
+            readAt,
             // The fencing token the server minted for this grant, forwarded from the
             // lease so writes taken under this handle carry it (Option B).
             ...(lease.fenceToken !== undefined ? { fenceToken: lease.fenceToken } : {}),
@@ -377,6 +395,7 @@ hydration, collaboration, readSetContext) {
             heartbeat,
             [Symbol.asyncDispose]: release,
         };
+        return lifetime ? bindClaimLifetime(handle, lifetime) : handle;
     };
     // The row-free sibling of `takeClaim`: locks a key by id alone, for a row that
     // lives only in the customer's own database and was never synced into Ablo.
@@ -428,11 +447,10 @@ hydration, collaboration, readSetContext) {
             }
             throw normalized;
         }
-        // A watermark-only snapshot: `createSnapshot` still reads the engine's
-        // current `lastSyncId` even though the pool holds no row (the bucket is
-        // empty). It costs nothing extra and gives a write taken under this lease a
-        // real `readAt` to guard against changes since the lease was acquired.
-        const snapshot = collaboration.createSnapshot(schemaKey, id);
+        // A row-free claim still captures the engine's current read floor. It gives
+        // a later write under this lease a real `readAt` without constructing the
+        // legacy row snapshot object (there is no row to put in one).
+        const readAt = lease.readAt ?? collaboration.currentReadAt();
         const description = claimDescription(options);
         const selfTarget = {
             type: wireModel,
@@ -441,13 +459,15 @@ hydration, collaboration, readSetContext) {
         };
         const ttlMs = options.ttl !== undefined ? toMs(options.ttl) : DEFAULT_LEASE_TTL_MS;
         const expiresAt = Date.now() + ttlMs;
-        activeClaims.set(id, {
+        const active = {
+            entityId: id,
             lease,
-            snapshot,
+            readAt,
             target: selfTarget,
             description,
             expiresAt,
-        });
+        };
+        addActiveClaim(lease.id, active);
         const target = {
             type: schemaKey,
             id,
@@ -467,7 +487,7 @@ hydration, collaboration, readSetContext) {
                 ttl: resolved.ttl ?? options.ttl,
                 ...(resolved.details !== undefined ? { details: resolved.details } : {}),
             });
-            const held = activeClaims.get(id);
+            const held = activeClaims.get(lease.id);
             if (held)
                 held.expiresAt = beat.expiresAt;
             plan.onBeat?.(beat);
@@ -480,14 +500,18 @@ hydration, collaboration, readSetContext) {
                 ...(plan.onLost ? { onLost: plan.onLost } : {}),
             })
             : undefined;
+        active.stopHeartbeat = stopHeartbeatLoop;
+        const lifetime = claimLifetimeOf(lease);
+        lifetime?.onEnd(() => {
+            removeActiveClaim(lease.id);
+        });
         const release = () => {
-            stopHeartbeatLoop?.();
-            return releaseClaim(id);
+            return releaseClaim(lease.id);
         };
-        return {
+        const handle = {
             object: 'claim',
             id: lease.id,
-            readAt: snapshot.stamp,
+            readAt,
             // Forward the grant's fencing token so writes under this row-free lease
             // carry it (Option B), exactly as the row-bearing claim does.
             ...(lease.fenceToken !== undefined ? { fenceToken: lease.fenceToken } : {}),
@@ -500,6 +524,7 @@ hydration, collaboration, readSetContext) {
             heartbeat,
             [Symbol.asyncDispose]: release,
         };
+        return lifetime ? bindClaimLifetime(handle, lifetime) : handle;
     };
     // `claim` overloads on its first argument: an options object claims a synced
     // row and resolves to a HeldClaim (carrying `.data`); a bare id claims a key
@@ -534,24 +559,19 @@ hydration, collaboration, readSetContext) {
      * they do it through here so the two answers cannot describe the same
      * holding differently.
      */
-    const ownClaimState = (id) => {
-        const own = activeClaims.get(id);
-        if (!own)
-            return null;
-        return {
-            object: 'claim',
-            id: own.lease.id,
-            status: 'active',
-            target: own.target,
-            description: own.description,
-            heldBy: collaboration?.selfParticipantId ?? '',
-            participantKind: collaboration?.selfParticipantKind ?? 'user',
-            expiresAt: own.expiresAt,
-            // Symmetric with the peer projection: a holder reading its own claim
-            // sees the same `meta` an observer does.
-            ...(own.target.meta !== undefined ? { meta: own.target.meta } : {}),
-        };
-    };
+    const ownClaimStates = (id) => claimsForEntity(id).map((own) => ({
+        object: 'claim',
+        id: own.lease.id,
+        status: 'active',
+        target: own.target,
+        description: own.description,
+        heldBy: collaboration?.selfParticipantId ?? '',
+        participantKind: collaboration?.selfParticipantKind ?? 'user',
+        expiresAt: own.expiresAt,
+        // Symmetric with the peer projection: a holder reading its own claim
+        // sees the same `meta` an observer does.
+        ...(own.target.meta !== undefined ? { meta: own.target.meta } : {}),
+    }));
     const claimReaders = {
         state(params) {
             // Read interest: a passive observer of a row's claim state must enter that
@@ -563,7 +583,7 @@ hydration, collaboration, readSetContext) {
             // the client skips them, so `state` would return null for a row this client
             // holds. Synthesize the active claim from the stored lease so the holder
             // sees its own claim, honoring the documented contract on `claim.state`.
-            return (ownClaimState(params.id) ??
+            return (ownClaimStates(params.id)[0] ??
                 collaboration?.state({ model: wireModel, id: params.id }) ??
                 null);
         },
@@ -576,13 +596,13 @@ hydration, collaboration, readSetContext) {
          */
         list(params) {
             void collaboration?.enterScope?.({ [schemaKey]: params.id });
-            const own = ownClaimState(params.id);
+            const own = ownClaimStates(params.id);
             const peers = collaboration?.holders({ model: wireModel, id: params.id }) ?? [];
             return {
                 object: 'list',
                 // Own claim first: the server excludes a holder's own presence frames,
                 // so it is never among `peers` and the two never duplicate.
-                data: own ? [own, ...peers] : [...peers],
+                data: [...own, ...peers],
             };
         },
         queue(params) {
@@ -591,7 +611,9 @@ hydration, collaboration, readSetContext) {
         reorder(params) {
             collaboration?.reorder({ model: wireModel, id: params.id }, params.order);
         },
-        release: guard((params) => releaseClaim(isClaimHandle(params) ? params.target.id : params.id)),
+        release: guard((params) => isClaimHandle(params)
+            ? releaseClaim(params.id)
+            : releaseClaimsForEntity(params.id)),
     };
     // The one place the caller's `meta` parameter is applied — see the note on
     // `claimReaders`. Everything else about this object is checked structurally.
@@ -640,7 +662,7 @@ hydration, collaboration, readSetContext) {
             return local.list(options).length;
         },
     };
-    const get = guard(async (params) => {
+    const pointRead = async (params, capture) => {
         // Read-interest enrolment: authoritative point reads enter the same
         // entity scope as the claim stream, while remaining settled reads.
         void collaboration?.enterScope?.({ [schemaKey]: params.id });
@@ -649,42 +671,28 @@ hydration, collaboration, readSetContext) {
             where: [['id', params.id]],
             limit: 1,
         });
-        if (readSetContext?.getStore() && collaboration) {
-            const read = await collaboration.readPoint(schemaKey, params.id);
-            const data = (read.data ?? undefined);
-            capturePointRead(readSetContext, readSetClientIdentity, wireModel, params.id, data, read.stamp);
+        if (collaboration) {
+            const result = await collaboration.readPoint(schemaKey, params.id);
+            const data = (result.data ?? undefined);
+            if (!capture)
+                return data;
+            capturePointRead(readSetContext, readSetClientIdentity, wireModel, params.id, data, result.stamp);
             return data;
         }
         return rows[0];
-    });
+    };
+    const get = guard(async (params) => pointRead(params, false));
+    const read = guard(async (params) => pointRead(params, true));
     const list = guard(async (options) => {
-        const registry = readSetContext?.getStore();
         const rows = await load(options);
         // This transport loads a working set rather than pages, so there is no
         // cursor to hand back. `limit` can still cut the set short, and a full
         // count is exactly the case where the caller cannot tell: report it rather
         // than claim completeness this read cannot vouch for.
-        const page = modelList(rows, {
+        return modelList(rows, {
             hasMore: options?.limit !== undefined && rows.length >= options.limit,
             nextCursor: null,
         });
-        if (!registry)
-            return page;
-        for (const row of rows) {
-            const stamp = hydration.getReadEvidence?.(row);
-            if (stamp === undefined) {
-                // Local-first/lazy rows remain valid reads, but cannot later be used as
-                // guarded dependencies. `prepareReadSet` rejects them if supplied in
-                // `reads`; authoritative complete reads carry evidence here.
-                continue;
-            }
-            const id = row.id;
-            if (typeof id !== 'string' || id.length === 0) {
-                throw new AbloValidationError(`${registeredModelName}.list returned a row without an id.`, { code: 'commit_no_result' });
-            }
-            capturePointRead(readSetContext, readSetClientIdentity, wireModel, id, row, stamp);
-        }
-        return page;
     });
     /**
      * Creates many rows as one atomic commit, and returns them in caller order.
@@ -696,51 +704,43 @@ hydration, collaboration, readSetContext) {
             throw new AbloValidationError(`Model "${schemaKey}" was built without the collaboration runtime, so a batch ` +
                 `create is unavailable here. Use the standard Ablo({ schema, apiKey }) client.`, { code: 'model_claim_not_configured' });
         }
-        const prepared = prepareReadSet(readSetContext, readSetClientIdentity, undefined, undefined, params.idempotencyKey, params.reads);
-        try {
-            const organizationId = syncClient.getOrganizationId() ?? undefined;
-            const ids = [];
-            const operations = params.data.map((row) => {
-                const fields = row;
-                const id = resolveCreateId(undefined, fields) ??
-                    createModelId(registeredModelName, params.idempotencyKey ? `${params.idempotencyKey}:${ids.length}` : null);
-                ids.push(id);
-                return {
-                    action: 'create',
-                    model: registeredModelName,
-                    data: { organizationId: fields.organizationId ?? organizationId, ...fields, id },
-                    id,
-                };
-            });
-            const receipt = await collaboration.commitBatch({
-                operations,
-                wait: 'confirmed',
-                ...(prepared.idempotencyKey
-                    ? { idempotencyKey: prepared.idempotencyKey }
-                    : params.idempotencyKey
-                        ? { idempotencyKey: params.idempotencyKey }
-                        : {}),
-                ...(prepared.reads
-                    ? { reads: [...prepared.reads] }
+        const prepared = prepareReadSet(readSetContext, readSetClientIdentity, undefined, params.idempotencyKey, params.reads);
+        const organizationId = syncClient.getOrganizationId() ?? undefined;
+        const ids = [];
+        const operations = params.data.map((row) => {
+            const fields = row;
+            const id = resolveCreateId(undefined, fields) ??
+                createModelId(registeredModelName, params.idempotencyKey ? `${params.idempotencyKey}:${ids.length}` : null);
+            ids.push(id);
+            return {
+                action: 'create',
+                model: registeredModelName,
+                data: { organizationId: fields.organizationId ?? organizationId, ...fields, id },
+                id,
+            };
+        });
+        const receipt = await collaboration.commitBatch({
+            operations,
+            wait: 'confirmed',
+            ...(prepared.idempotencyKey
+                ? { idempotencyKey: prepared.idempotencyKey }
+                : params.idempotencyKey
+                    ? { idempotencyKey: params.idempotencyKey }
                     : {}),
-                ...(params.track ? { track: [...params.track] } : {}),
-            });
-            const rows = await resolveCreatedRows({
-                modelName: registeredModelName,
-                ids,
-                operationResults: receipt.operationResults,
-                readRow: async (id) => {
-                    const read = await collaboration.readPoint(registeredModelName, id);
-                    return read.data;
-                },
-            });
-            consumeReadSet(readSetContext, readSetClientIdentity, prepared.consumed, prepared.automaticCommit);
-            return rows;
-        }
-        catch (error) {
-            abortReadSetCommit(readSetContext, prepared.automaticCommit);
-            throw error;
-        }
+            ...(prepared.reads
+                ? { reads: [...prepared.reads] }
+                : {}),
+        });
+        const rows = await resolveCreatedRows({
+            modelName: registeredModelName,
+            ids,
+            operationResults: receipt.operationResults,
+            readRow: async (id) => {
+                const read = await collaboration.readPoint(registeredModelName, id);
+                return read.data;
+            },
+        });
+        return rows;
     };
     // `create` takes one row or a list of them. The list form is atomic and
     // is therefore NOT applied optimistically: see `createManyRows`.
@@ -791,12 +791,9 @@ hydration, collaboration, readSetContext) {
             createdAt: new Date(),
             updatedAt: new Date(),
         });
-        let prepared;
         try {
-            const resolved = preparedMutation(single);
-            prepared = resolved.prepared;
             const effective = {
-                ...resolved.options,
+                ...preparedMutation(single),
                 ...(autoLease
                     ? {
                         claimRef: { id: autoLease.id },
@@ -816,13 +813,8 @@ hydration, collaboration, readSetContext) {
             };
             syncClient.add(model, effective);
             await waitForMutation(model);
-            consumeReadSet(readSetContext, readSetClientIdentity, prepared.consumed, prepared.automaticCommit);
             return modelAsRow(model);
         }
-        catch (error) {
-            abortReadSetCommit(readSetContext, prepared?.automaticCommit ?? false);
-            throw error;
-        }
         finally {
             await autoLease?.release?.().catch(() => { });
         }
@@ -833,7 +825,7 @@ hydration, collaboration, readSetContext) {
     const operations = {
         local,
         get,
-        retrieve: get,
+        read,
         // No automatic scope enrolment on bulk `list`: that would subscribe to an
         // unbounded set of rows' entity groups.
         list,
@@ -885,28 +877,20 @@ hydration, collaboration, readSetContext) {
                             if (!model) {
                                 throw new AbloValidationError(`Entity not found: ${registeredModelName}/${id}`, { code: 'entity_not_found' });
                             }
-                            const prepared = prepareReadSet(readSetContext, readSetClientIdentity, undefined, 'reject', undefined, contention?.reads);
-                            try {
-                                const effective = {
-                                    readAt: prepared.readAt ?? readAt,
-                                    onStale: prepared.onStale ?? 'reject',
-                                    ...(prepared.idempotencyKey
-                                        ? { idempotencyKey: prepared.idempotencyKey }
-                                        : {}),
-                                    ...(prepared.reads !== undefined
-                                        ? { reads: prepared.reads === null ? null : [...prepared.reads] }
-                                        : {}),
-                                };
-                                model.applyChanges(patch);
-                                syncClient.update(model, effective);
-                                await waitForMutation(model);
-                                consumeReadSet(readSetContext, readSetClientIdentity, prepared.consumed, prepared.automaticCommit);
-                                return modelAsRow(model);
-                            }
-                            catch (error) {
-                                abortReadSetCommit(readSetContext, prepared.automaticCommit);
-                                throw error;
-                            }
+                            const prepared = prepareReadSet(readSetContext, readSetClientIdentity, undefined, undefined, contention?.reads);
+                            const effective = {
+                                readAt: prepared.readAt ?? readAt,
+                                ...(prepared.idempotencyKey
+                                    ? { idempotencyKey: prepared.idempotencyKey }
+                                    : {}),
+                                ...(prepared.reads !== undefined
+                                    ? { reads: prepared.reads === null ? null : [...prepared.reads] }
+                                    : {}),
+                            };
+                            model.applyChanges(patch);
+                            syncClient.update(model, effective);
+                            await waitForMutation(model);
+                            return modelAsRow(model);
                         },
                     });
                 }
@@ -934,53 +918,32 @@ hydration, collaboration, readSetContext) {
                 const model = ownRowOrThrow(id);
                 if (!model)
                     throw new AbloValidationError(`Entity not found: ${registeredModelName}/${id}`, { code: 'entity_not_found' });
-                // If we hold a claim on this row, guard the write with its snapshot
-                // watermark + lease so it's stale-rejected and attributed to the claim.
-                const claimed = activeClaims.get(id);
-                const resolved = preparedMutation(params);
-                const opts = resolved.options;
+                const opts = preparedMutation(params);
                 const handle = isClaimHandle(params.claim) ? params.claim : undefined;
-                const effective = claimed
-                    ? {
-                        readAt: claimed.lease.readAt ?? claimed.snapshot.stamp,
-                        onStale: 'reject',
-                        claimRef: { id: claimed.lease.id },
-                        ...(claimed.lease.fenceToken !== undefined
-                            ? { fenceToken: claimed.lease.fenceToken }
-                            : {}),
-                        ...opts,
-                    }
-                    : {
-                        // A carried handle engages the same stale guard as a claim this
-                        // proxy took itself — the watermark rides on the handle, so it
-                        // works across clients (HTTP-minted handles included).
-                        ...(handle?.readAt !== undefined
-                            ? {
-                                readAt: handle.readAt,
-                                onStale: 'reject',
-                                ...(handle.fenceToken !== undefined
-                                    ? { fenceToken: handle.fenceToken }
-                                    : {}),
-                            }
-                            : {}),
-                        ...opts,
-                        ...(handle ? { claimRef: { id: handle.id } } : {}),
-                    };
+                // An exact carried handle always wins. Without one, the convenience
+                // path may use the sole local claim on this row; several disjoint local
+                // claims are intentionally ambiguous and require the caller to pass one.
+                const claimed = handle ? activeClaims.get(handle.id) : implicitClaimForEntity(id);
+                const selected = handle ?? claimed?.lease;
+                const selectedReadAt = handle?.readAt ?? claimed?.readAt;
+                const effective = {
+                    ...(selectedReadAt !== undefined ? { readAt: selectedReadAt } : {}),
+                    ...(selected?.fenceToken !== undefined
+                        ? { fenceToken: selected.fenceToken }
+                        : {}),
+                    ...opts,
+                    ...(selected ? { claimRef: { id: selected.id } } : {}),
+                };
                 // Local user update: `applyChanges` keeps change tracking on so the
                 // edited fields land in `modifiedProperties` and are actually sent to
                 // the server. (`updateFromData` is the hydration path and would discard
                 // the tracking, producing an empty `input: {}` no-op mutation.)
-                try {
-                    model.applyChanges(params.data);
-                    syncClient.update(model, effective);
-                    await waitForMutation(model);
-                    consumeReadSet(readSetContext, readSetClientIdentity, resolved.prepared.consumed, resolved.prepared.automaticCommit);
-                    return modelAsRow(model);
-                }
-                catch (error) {
-                    abortReadSetCommit(readSetContext, resolved.prepared.automaticCommit);
-                    throw error;
-                }
+                model.applyChanges(params.data);
+                syncClient.update(model, effective);
+                await waitForMutation(model);
+                const updated = modelAsRow(model);
+                await settleClaimsAfterWrite(id, handle);
+                return updated;
             });
             function update(arg, updater, contention) {
                 return updateImpl(arg, updater, contention);
@@ -1016,67 +979,31 @@ hydration, collaboration, readSetContext) {
             // no-op success rather than an `entity_not_found` error. This matches the
             // HTTP client and makes delete safe to retry or race (two actors deleting
             // the same row).
-            if (!model)
+            if (!model) {
+                const handle = isClaimHandle(params.claim) ? params.claim : undefined;
+                await settleClaimsAfterWrite(id, handle);
                 return;
-            const claimed = activeClaims.get(id);
-            const resolved = preparedMutation(params);
-            const opts = resolved.options;
-            const handle = isClaimHandle(params.claim) ? params.claim : undefined;
-            const effective = claimed
-                ? {
-                    readAt: claimed.lease.readAt ?? claimed.snapshot.stamp,
-                    onStale: 'reject',
-                    claimRef: { id: claimed.lease.id },
-                    ...(claimed.lease.fenceToken !== undefined
-                        ? { fenceToken: claimed.lease.fenceToken }
-                        : {}),
-                    ...opts,
-                }
-                : {
-                    ...(handle?.readAt !== undefined
-                        ? {
-                            readAt: handle.readAt,
-                            onStale: 'reject',
-                            ...(handle.fenceToken !== undefined
-                                ? { fenceToken: handle.fenceToken }
-                                : {}),
-                        }
-                        : {}),
-                    ...opts,
-                    ...(handle ? { claimRef: { id: handle.id } } : {}),
-                };
-            try {
-                syncClient.delete(model, effective);
-                await waitForMutation(model);
-                consumeReadSet(readSetContext, readSetClientIdentity, resolved.prepared.consumed, resolved.prepared.automaticCommit);
-            }
-            catch (error) {
-                abortReadSetCommit(readSetContext, resolved.prepared.automaticCommit);
-                throw error;
             }
+            const opts = preparedMutation(params);
+            const handle = isClaimHandle(params.claim) ? params.claim : undefined;
+            const claimed = handle ? activeClaims.get(handle.id) : implicitClaimForEntity(id);
+            const selected = handle ?? claimed?.lease;
+            const selectedReadAt = handle?.readAt ?? claimed?.readAt;
+            const effective = {
+                ...(selectedReadAt !== undefined ? { readAt: selectedReadAt } : {}),
+                ...(selected?.fenceToken !== undefined
+                    ? { fenceToken: selected.fenceToken }
+                    : {}),
+                ...opts,
+                ...(selected ? { claimRef: { id: selected.id } } : {}),
+            };
+            syncClient.delete(model, effective);
+            await waitForMutation(model);
+            await settleClaimsAfterWrite(id, handle);
         }),
         // `claim` is a callable namespace (take a claim) carrying the coordination
         // readers (`claim.state` / `claim.queue` / `claim.release` / `claim.reorder`).
         claim: claimApi,
-        track: guard(async (params) => {
-            const dep = {
-                model: wireModel,
-                id: params.id,
-                ...(params.readAt !== undefined ? { readAt: params.readAt } : {}),
-            };
-            // A track carries no write, so it rides the commit lane as a zero-operation
-            // commit: the queue tolerates disconnects and de-dupes replays, and the
-            // server's track-only path registers the premise and reports anything
-            // that already fired. Reuse the same lane the batch `commits.create` door
-            // uses rather than opening a bespoke transport.
-            const clientTxId = typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
-                ? crypto.randomUUID()
-                : `tx_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
-            const queue = syncClient.getMutationQueue();
-            await queue.enqueueCommit(clientTxId, [], { track: [dep] });
-            const { notifications } = await queue.waitForCommitReceipt(clientTxId);
-            return notifications && notifications.length > 0 ? { notifications } : {};
-        }),
         join: guard((ids, options) => {
             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' });