@abloatai/humans 0.56.0 → 0.58.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,30 +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 } from '@abloatai/transaction/resources/writeOptionsSchema';
-import { 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.
  *
@@ -142,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
@@ -165,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 }
@@ -173,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.
@@ -276,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
@@ -310,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,
@@ -340,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);
@@ -355,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 } : {}),
@@ -376,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.
@@ -427,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,
@@ -440,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,
@@ -466,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);
@@ -479,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 } : {}),
@@ -499,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
@@ -533,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
@@ -562,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);
         },
@@ -575,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) {
@@ -590,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.
@@ -639,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 });
@@ -648,129 +671,170 @@ 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' });
+    });
+    /**
+     * Creates many rows as one atomic commit, and returns them in caller order.
+     */
+    const createManyRows = async (params) => {
+        if (params.data.length === 0)
+            return [];
+        if (!collaboration) {
+            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, 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 }
+                    : {}),
+            ...(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`.
+    const createImpl = guardWrite(async (params) => {
+        if (Array.isArray(params.data)) {
+            return createManyRows(params);
+        }
+        const single = params;
+        const id = resolveCreateId(single.id, single.data) ?? Model.generateId();
+        const claim = single.claim;
+        let autoLease;
+        if (claim && !isClaimHandle(claim)) {
+            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' });
             }
-            capturePointRead(readSetContext, readSetClientIdentity, wireModel, id, row, stamp);
+            // Write intent: enter the new row's entity scope before acquiring the
+            // create-claim so the holder's claim presence broadcasts to everyone
+            // already in this entity group (closing the subscribe-versus-broadcast
+            // race — see `takeClaim`). Released with the lease in the `finally`
+            // below. Awaited for broadcast ordering; still best-effort.
+            await collaboration.pinScope?.({ [schemaKey]: id });
+            const contention = resolveClaimContentionOptions(claim);
+            autoLease = await collaboration.createClaim({
+                target: {
+                    model: wireModel,
+                    id,
+                    ...subTarget(claim, schemaKey),
+                },
+                description: claimDescription(claim, 'creating'),
+                ttl: claim.ttl,
+                queue: contention.wait,
+                maxQueueDepth: contention.maxDepth,
+                waitTimeoutMs: contention.timeoutMs,
+                signal: contention.signal,
+                onStatus: contention.onStatus,
+            });
+        }
+        // Default `organizationId` from the client's identity, matching the other
+        // write path — without this, a caller that omits it would create an
+        // org-unscoped row on one write path but not the other. An explicit value
+        // in `data` still wins via the spread.
+        const orgDefault = params.data.organizationId ??
+            syncClient.getOrganizationId();
+        const model = new ModelClass({
+            id,
+            ...(orgDefault != null ? { organizationId: orgDefault } : {}),
+            ...params.data,
+            createdAt: new Date(),
+            updatedAt: new Date(),
+        });
+        try {
+            const effective = {
+                ...preparedMutation(single),
+                ...(autoLease
+                    ? {
+                        claimRef: { id: autoLease.id },
+                        ...(autoLease.fenceToken !== undefined
+                            ? { fenceToken: autoLease.fenceToken }
+                            : {}),
+                    }
+                    : {}),
+                ...(isClaimHandle(claim)
+                    ? {
+                        claimRef: { id: claim.id },
+                        ...(claim.fenceToken !== undefined
+                            ? { fenceToken: claim.fenceToken }
+                            : {}),
+                    }
+                    : {}),
+            };
+            syncClient.add(model, effective);
+            await waitForMutation(model);
+            return modelAsRow(model);
+        }
+        finally {
+            await autoLease?.release?.().catch(() => { });
         }
-        return page;
     });
+    function createRows(params) {
+        return createImpl(params);
+    }
     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,
-        create: guardWrite(async (params) => {
-            const id = params.id ?? Model.generateId();
-            const claim = params.claim;
-            let autoLease;
-            if (claim && !isClaimHandle(claim)) {
-                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' });
-                }
-                // Write intent: enter the new row's entity scope before acquiring the
-                // create-claim so the holder's claim presence broadcasts to everyone
-                // already in this entity group (closing the subscribe-versus-broadcast
-                // race — see `takeClaim`). Released with the lease in the `finally`
-                // below. Awaited for broadcast ordering; still best-effort.
-                await collaboration.pinScope?.({ [schemaKey]: id });
-                const contention = resolveClaimContentionOptions(claim);
-                autoLease = await collaboration.createClaim({
-                    target: {
-                        model: wireModel,
-                        id,
-                        ...subTarget(claim, schemaKey),
-                    },
-                    description: claimDescription(claim, 'creating'),
-                    ttl: claim.ttl,
-                    queue: contention.wait,
-                    maxQueueDepth: contention.maxDepth,
-                    waitTimeoutMs: contention.timeoutMs,
-                    signal: contention.signal,
-                    onStatus: contention.onStatus,
-                });
-            }
-            // Default `organizationId` from the client's identity, matching the other
-            // write path — without this, a caller that omits it would create an
-            // org-unscoped row on one write path but not the other. An explicit value
-            // in `data` still wins via the spread.
-            const orgDefault = params.data.organizationId ??
-                syncClient.getOrganizationId();
-            const model = new ModelClass({
-                id,
-                ...(orgDefault != null ? { organizationId: orgDefault } : {}),
-                ...params.data,
-                createdAt: new Date(),
-                updatedAt: new Date(),
-            });
-            let prepared;
-            try {
-                const resolved = preparedMutation(params);
-                prepared = resolved.prepared;
-                const effective = {
-                    ...resolved.options,
-                    ...(autoLease
-                        ? {
-                            claimRef: { id: autoLease.id },
-                            ...(autoLease.fenceToken !== undefined
-                                ? { fenceToken: autoLease.fenceToken }
-                                : {}),
-                        }
-                        : {}),
-                    ...(isClaimHandle(claim)
-                        ? {
-                            claimRef: { id: claim.id },
-                            ...(claim.fenceToken !== undefined
-                                ? { fenceToken: claim.fenceToken }
-                                : {}),
-                        }
-                        : {}),
-                };
-                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(() => { });
-            }
+        listAll: guard(async (options = {}) => {
+            const { maxPages, signal, ...readOptions } = options;
+            signal?.throwIfAborted();
+            return collectModelList(await list(readOptions), { maxPages, signal });
         }),
+        create: createRows,
         // `update` is overloaded — classic `update({ id, data })` + functional
         // `update(id, current => next)`. The IIFE keeps the shared error-guard
         // wrapping while exposing the two public signatures (a plain `guard(...)`
@@ -813,32 +877,28 @@ 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);
                         },
                     });
                 }
                 const params = arg;
+                // Named before anything reads it. Without this the row lookup below
+                // reports `Entity not found: Model/undefined`, which sends the reader
+                // looking for a missing row rather than at the unaddressed write.
+                assertWriteTarget('update', registeredModelName, params.id);
                 const autoClaim = params.claim && !isClaimHandle(params.claim) ? params.claim : null;
                 if (autoClaim) {
                     const handle = await takeClaim({ ...autoClaim, id: params.id });
@@ -858,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);
@@ -912,6 +951,9 @@ hydration, collaboration, readSetContext) {
             return update;
         })(),
         delete: guardWrite(async (params) => {
+            // Before the idempotent "ensure absent" below can read this as a row that
+            // is simply not here. An unaddressed delete is a mistake, not an absence.
+            assertWriteTarget('delete', registeredModelName, params.id);
             const autoClaim = params.claim && !isClaimHandle(params.claim) ? params.claim : null;
             if (autoClaim) {
                 const handle = await takeClaim({ ...autoClaim, id: params.id });
@@ -937,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' });