@abloatai/humans 0.56.0 → 0.58.0

package/src/local/client/{createModelProxy.ts → createModelOperations.ts}

@@ -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`.
@@ -21,12 +21,11 @@ import {
   reconcileFunctionalUpdate,
   type ModelUpdater,
   type FunctionalUpdateOptions,
-} from '@abloatai/transaction/resources/functionalUpdate';
+} from '@abloatai/transaction/client/resources/functionalUpdate';
 import type { MutationOptions } from '../interfaces/index.js';
 import {
   claimDescription,
   type ReadDependency,
-  type TrackDependency,
 } from '@abloatai/transaction/coordination/schema';
 import { Model, modelAsRow } from '../Model.js';
 import { toMs } from '@abloatai/transaction/utils/duration';
@@ -36,15 +35,32 @@ import {
   resolveHeartbeatOptions,
   resolveHeartbeatPlan,
   startClaimHeartbeatLoop,
-} from '@abloatai/transaction/coordination/claimHeartbeatLoop';
-import { assertWriteOptions } from '@abloatai/transaction/resources/writeOptionsSchema';
-import { modelList, type ModelList } from '@abloatai/transaction/resources/httpResources';
+} from '@abloatai/transaction/claims';
+import {
+  assertWriteOptions,
+  assertWriteTarget,
+} from '@abloatai/transaction/client/resources/writeOptionsSchema';
+import {
+  createModelId,
+  resolveCreatedRows,
+  resolveCreateId,
+} from '@abloatai/transaction/client/resources/modelCreate';
+import type {
+  CommitCreateOptions,
+  CommitReceipt,
+} from '@abloatai/transaction/client/resources/httpResources';
+import type { HttpModelMutationParams } from '@abloatai/transaction/transport/http';
+import {
+  collectModelList,
+  modelList,
+  type 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 type { ModelTarget } from '@abloatai/transaction/coordination/schema';
 import type { ModelRegistry } from '../ModelRegistry.js';
 import type { InstanceCache } from '../InstanceCache.js';
@@ -61,23 +77,24 @@ import type {
   HeldLease,
   ClaimWaitOptions,
   ClaimTarget,
-  Snapshot,
 } from '@abloatai/transaction/types/streams';
+import {
+  bindClaimLifetime,
+  claimLifetimeOf,
+} from '@abloatai/transaction/claims/lifetime';
 
 // The request contract — every option and parameter shape a caller passes to a
 // read, a write, or a claim — lives in the confirmation core (ADR 0016). This
 // factory binds it to reactive model instances; the shapes themselves are
-// transport- and consumer-agnostic. Re-exported so `./createModelProxy` stays a
+// transport- and consumer-agnostic. Re-exported so `./createModelOperations` stays a
 // working import path for the whole surface.
 export type {
   ModelListScope,
-  ModelTrackParams,
-  ModelTrackResult,
   LocalReadOptions,
   LocalCountOptions,
   ServerReadOptions,
-  ServerGetOptions,
-  ServerRetrieveOptions,
+  ListAllOptions,
+  ServerPointReadOptions,
   ClaimTargetOptions,
   ClaimParams,
   ClaimContentionOptions,
@@ -91,12 +108,12 @@ export type {
   ClaimReadApi,
   AwaitedClaimMethod,
   ClaimApi,
-  ModelRetrieveParams,
+  ModelReadParams,
   ModelCreateParams,
   ModelUpdateParams,
   ModelDeleteParams,
   JoinOptions,
-} from '@abloatai/transaction/resources/modelOperations';
+} from '@abloatai/transaction/client/resources/modelOperations';
 export type { Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, HeldLease };
 
 import type {
@@ -112,29 +129,26 @@ import type {
   JoinOptions,
   LocalCountOptions,
   LocalReadOptions,
+  ModelCreateManyParams,
   ModelCreateParams,
   ModelDeleteParams,
-  ModelRetrieveParams,
-  ModelTrackParams,
-  ModelTrackResult,
+  ModelReadParams,
   ModelUpdateParams,
   ServerReadOptions,
-} from '@abloatai/transaction/resources/modelOperations';
+  ListAllOptions,
+} from '@abloatai/transaction/client/resources/modelOperations';
 import {
   claimQueueView,
   resolveClaimContentionOptions,
-} from '@abloatai/transaction/resources/modelOperations';
+} from '@abloatai/transaction/client/resources/modelOperations';
 import type {
   CapturedRow,
   HttpModelClient,
-} from '@abloatai/transaction/transport/httpClient';
+} from '@abloatai/transaction/transport/http';
 import type { ParticipantKind } from '@abloatai/transaction/types/participant';
 import {
-  abortReadSetCommit,
   capturePointRead,
-  consumeReadSet,
   prepareReadSet,
-  type PreparedReadSet,
   type ReadSetContext,
 } from '@abloatai/transaction/internal/read-set';
 
@@ -165,6 +179,17 @@ type EntityHalf = Pick<ModelTarget, 'model' | 'id'>;
 export interface ModelCollaboration {
   /** Exact point evidence from the HTTP read boundary (stamp captured before data). */
   readPoint(model: string, id: string): Promise<{ data: unknown; stamp: number }>;
+  /**
+   * The batch commit lane, for a create handed a list of rows.
+   *
+   * A reactive client's single writes go through the mutation queue and land
+   * optimistically, because a rejected write rolls one row back. A batch
+   * cannot: it is atomic, so applying the rows one at a time would paint a
+   * half-written state the server may then decline whole. It goes down the
+   * same commit door the stateless client uses and the rows arrive on the
+   * ordinary stream, the way a teammate's would.
+   */
+  commitBatch(options: CommitCreateOptions): Promise<CommitReceipt>;
   createClaim(options: {
     /**
      * The locator, in the spelling the SDK surface and the HTTP routes use.
@@ -191,7 +216,8 @@ export interface ModelCollaboration {
     /** Request-scoped queued / granted / skipped / failed status events. */
     onStatus?: (event: ClaimAttemptEvent) => void;
   }): Promise<Claim>;
-  createSnapshot(modelKey: string, id: string): Snapshot;
+  /** Current applied/acked watermark, captured after a claim's fresh read. */
+  currentReadAt(): number;
   /**
    * Current coordination state on a target — who (if anyone) holds it.
    * Synchronous reactive snapshot read off the presence/claim stream;
@@ -262,7 +288,7 @@ export interface ModelCollaboration {
    * Opens a presence and claim subscription on this model's sync group(s) and
    * returns the live participant handle. Backs `ablo.<model>.join(ids)`.
    * WebSocket only, since presence needs a live socket; it is absent on other
-   * client constructions, where the proxy throws a clear error.
+   * client constructions, where the surface throws a clear error.
    */
   createJoin?(
     modelKey: string,
@@ -277,7 +303,7 @@ export interface ModelCollaboration {
  *
  * Every verb mirrors its asynchronous sibling on the base surface, and the one
  * word in front is the whole difference. It is a narrowing, not a claim about
- * the other side: `get` consults the local graph and then the network,
+ * the other side: `read` consults the local graph and then the network,
  * while `local.get` is restricted to what is already resident — which is
  * also why it can return a value instead of a promise. There is nothing to
  * await.
@@ -394,7 +420,7 @@ export type ModelOperations<T, CreateInput> = Omit<
 > &
   ReactiveModelSurface<T, CreateInput>;
 
-export function createModelProxy<T, C>(
+export function createModelOperations<T, C>(
   schemaKey: string,
   registeredModelName: string,
   objectPool: Pick<InstanceCache, 'get' | 'getByType' | 'getOfType'>,
@@ -402,7 +428,6 @@ export function createModelProxy<T, C>(
     SyncClient,
     | 'add'
     | 'delete'
-    | 'getMutationQueue'
     | 'getOrganizationId'
     | 'syncNow'
     | 'update'
@@ -536,27 +561,66 @@ export function createModelProxy<T, C>(
     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.
+  // Claims this model surface currently holds, keyed by the exact grant id.
+  // Several disjoint sub-row claims may coexist on one entity, so entity id is
+  // an index, never the identity of a lease. The old Map<entityId, claim>
+  // silently overwrote the first handle when the same participant claimed a
+  // second field and then released/guarded whichever happened to be last.
   //
   // `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
+  // own presence frames, so this surface 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.
+  interface ActiveClaim {
+    readonly entityId: string;
+    readonly lease: Claim;
+    readonly readAt: number;
+    readonly target: ClaimTarget;
+    readonly description: string;
+    expiresAt: number;
+    stopHeartbeat?: () => void;
+  }
+
   const activeClaims = new Map<
     string,
-    {
-      lease: Claim;
-      snapshot: Snapshot;
-      target: ClaimTarget;
-      description: string;
-      expiresAt: number;
-    }
+    ActiveClaim
   >();
+  const claimIdsByEntity = new Map<string, Set<string>>();
+
+  const claimsForEntity = (entityId: string): ActiveClaim[] =>
+    [...(claimIdsByEntity.get(entityId) ?? [])].flatMap((claimId) => {
+      const held = activeClaims.get(claimId);
+      return held ? [held] : [];
+    });
+
+  const addActiveClaim = (claimId: string, held: ActiveClaim): void => {
+    activeClaims.set(claimId, held);
+    const ids = claimIdsByEntity.get(held.entityId) ?? new Set<string>();
+    ids.add(claimId);
+    claimIdsByEntity.set(held.entityId, ids);
+  };
+
+  const removeActiveClaim = (claimId: string): ActiveClaim | undefined => {
+    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: string): ActiveClaim | undefined => {
+    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.
@@ -576,12 +640,11 @@ export function createModelProxy<T, C>(
       | ModelCreateParams<T, C>
       | ModelUpdateParams<T, C>
       | ModelDeleteParams<T, C>,
-  ): { options: MutationOptions; prepared: PreparedReadSet } => {
+  ): MutationOptions => {
     const prepared = prepareReadSet(
       readSetContext,
       readSetClientIdentity,
-      params.readAt,
-      params.onStale,
+      undefined,
       params.idempotencyKey,
       params.reads,
     );
@@ -592,44 +655,47 @@ export function createModelProxy<T, C>(
           ? { 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: string): Promise<void> => {
-    const held = activeClaims.get(id);
+  const releaseClaim = async (claimId: string): Promise<void> => {
+    const held = removeActiveClaim(claimId);
     if (!held) return;
-    activeClaims.delete(id);
     await held.lease.release?.();
   };
 
+  const releaseClaimsForEntity = async (entityId: string): Promise<void> => {
+    const ids = [...(claimIdsByEntity.get(entityId) ?? [])];
+    await Promise.all(ids.map((claimId) => releaseClaim(claimId)));
+  };
+
+  const settleClaimsAfterWrite = async (
+    entityId: string,
+    explicit?: Pick<Claim<T>, 'id' | 'release'>,
+  ): Promise<void> => {
+    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: ClaimParams<C>,
   ): Promise<HeldClaim<T> | null> => {
@@ -640,11 +706,6 @@ export function createModelProxy<T, C>(
       );
     }
     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;
 
@@ -708,25 +769,26 @@ export function createModelProxy<T, C>(
       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
@@ -744,13 +806,15 @@ export function createModelProxy<T, C>(
     const ttlMs =
       options.ttl !== undefined ? toMs(options.ttl) : DEFAULT_LEASE_TTL_MS;
     const expiresAt = Date.now() + ttlMs;
-    activeClaims.set(id, {
+    const active: ActiveClaim = {
+      entityId: id,
       lease,
-      snapshot,
+      readAt,
       target: selfTarget,
       description,
       expiresAt,
-    });
+    };
+    addActiveClaim(lease.id, active);
     const { meta: targetMeta, ...targetNarrowed } = subTarget(options, schemaKey);
     const target = {
       type: schemaKey,
@@ -779,7 +843,7 @@ export function createModelProxy<T, C>(
         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);
       return beat;
@@ -795,14 +859,19 @@ export function createModelProxy<T, C>(
         })
       : 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 } : {}),
@@ -815,7 +884,8 @@ export function createModelProxy<T, C>(
       },
       heartbeat,
       [Symbol.asyncDispose]: release,
-    };
+    } satisfies HeldClaim<T>;
+    return lifetime ? bindClaimLifetime(handle, lifetime) : handle;
   };
 
   // The row-free sibling of `takeClaim`: locks a key by id alone, for a row that
@@ -878,11 +948,10 @@ export function createModelProxy<T, C>(
       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: ClaimTarget = {
       type: wireModel,
@@ -892,13 +961,15 @@ export function createModelProxy<T, C>(
     const ttlMs =
       options.ttl !== undefined ? toMs(options.ttl) : DEFAULT_LEASE_TTL_MS;
     const expiresAt = Date.now() + ttlMs;
-    activeClaims.set(id, {
+    const active: ActiveClaim = {
+      entityId: id,
       lease,
-      snapshot,
+      readAt,
       target: selfTarget,
       description,
       expiresAt,
-    });
+    };
+    addActiveClaim(lease.id, active);
     const target = {
       type: schemaKey,
       id,
@@ -923,7 +994,7 @@ export function createModelProxy<T, C>(
         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);
       return beat;
@@ -937,14 +1008,19 @@ export function createModelProxy<T, C>(
         })
       : 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 } : {}),
@@ -956,7 +1032,8 @@ export function createModelProxy<T, C>(
       },
       heartbeat,
       [Symbol.asyncDispose]: release,
-    };
+    } satisfies HeldLease;
+    return lifetime ? bindClaimLifetime(handle, lifetime) : handle;
   };
 
   // `claim` overloads on its first argument: an options object claims a synced
@@ -1005,10 +1082,8 @@ export function createModelProxy<T, C>(
    * they do it through here so the two answers cannot describe the same
    * holding differently.
    */
-  const ownClaimState = (id: string): Claim | null => {
-    const own = activeClaims.get(id);
-    if (!own) return null;
-    return {
+  const ownClaimStates = (id: string): Claim[] =>
+    claimsForEntity(id).map((own) => ({
       object: 'claim',
       id: own.lease.id,
       status: 'active',
@@ -1020,8 +1095,7 @@ export function createModelProxy<T, C>(
       // 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: ClaimLookupParams<T>): Claim | null {
@@ -1035,7 +1109,7 @@ export function createModelProxy<T, C>(
       // 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) ??
+        ownClaimStates(params.id)[0] ??
         collaboration?.state({ model: wireModel, id: params.id }) ??
         null
       );
@@ -1050,13 +1124,13 @@ export function createModelProxy<T, C>(
      */
     list(params: ClaimLookupParams<T>): { readonly object: 'list'; readonly data: readonly Claim[] } {
       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],
       };
     },
 
@@ -1071,7 +1145,9 @@ export function createModelProxy<T, C>(
     },
 
     release: guard((params: ClaimLookupParams<T> | Claim<T>): Promise<void> =>
-      releaseClaim(isClaimHandle(params) ? params.target.id : params.id),
+      isClaimHandle(params)
+        ? releaseClaim(params.id)
+        : releaseClaimsForEntity(params.id),
     ),
   };
 
@@ -1130,8 +1206,10 @@ export function createModelProxy<T, C>(
     },
   };
 
-  const get = guard(
-    async (params: ModelRetrieveParams): Promise<CapturedRow<T> | undefined> => {
+  const pointRead = async (
+    params: ModelReadParams,
+    capture: boolean,
+  ): Promise<T | undefined> => {
       // 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 });
@@ -1140,77 +1218,125 @@ export function createModelProxy<T, C>(
         where: [['id', params.id]],
         limit: 1,
       });
-      if (readSetContext?.getStore() && collaboration) {
-        const read = await collaboration.readPoint(schemaKey, params.id);
-        const data = (read.data ?? undefined) as T | undefined;
+      if (collaboration) {
+        const result = await collaboration.readPoint(schemaKey, params.id);
+        const data = (result.data ?? undefined) as T | undefined;
+        if (!capture) return data;
         capturePointRead(
           readSetContext,
           readSetClientIdentity,
           wireModel,
           params.id,
           data,
-          read.stamp,
+          result.stamp,
         );
-        return data as CapturedRow<T> | undefined;
+        return data;
       }
-      return rows[0] as CapturedRow<T> | undefined;
-    },
+      return rows[0];
+  };
+
+  const get = guard(
+    async (params: ModelReadParams): Promise<T | undefined> => pointRead(params, false),
+  );
+
+  const read = guard(
+    async (params: ModelReadParams): Promise<CapturedRow<T> | undefined> =>
+      pointRead(params, true) as Promise<CapturedRow<T> | undefined>,
   );
 
   const list = guard(async (
     options?: ServerReadOptions<T>,
-  ): Promise<ModelList<CapturedRow<T>>> => {
-    const registry = readSetContext?.getStore();
+  ): Promise<ModelList<T>> => {
     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<CapturedRow<T>>(rows as CapturedRow<T>[], {
+    return modelList<T>(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 as object);
-      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 as { id?: unknown }).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,
+  });
+
+  /**
+   * Creates many rows as one atomic commit, and returns them in caller order.
+   */
+  const createManyRows = async (
+    params: HttpModelMutationParams<ModelCreateManyParams<C>>,
+  ): Promise<T[]> => {
+    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' },
       );
     }
-    return page;
-  });
 
-  const operations: ModelOperations<T, C> = {
-    local,
+    const prepared = prepareReadSet(
+      readSetContext,
+      readSetClientIdentity,
+      undefined,
+      params.idempotencyKey,
+      params.reads,
+    );
+    const organizationId = syncClient.getOrganizationId() ?? undefined;
+    const ids: string[] = [];
+    const operations = params.data.map((row) => {
+      const fields = row as Record<string, unknown>;
+      const id =
+        resolveCreateId(undefined, fields) ??
+        createModelId(
+          registeredModelName,
+          params.idempotencyKey ? `${params.idempotencyKey}:${ids.length}` : null,
+        );
+      ids.push(id);
+      return {
+        action: 'create' as const,
+        model: registeredModelName,
+        data: { organizationId: fields.organizationId ?? organizationId, ...fields, id },
+        id,
+      };
+    });
 
-    get,
-    retrieve: get,
+    const receipt = await collaboration.commitBatch({
+      operations,
+      wait: 'confirmed',
+      ...(prepared.idempotencyKey
+        ? { idempotencyKey: prepared.idempotencyKey }
+        : params.idempotencyKey
+          ? { idempotencyKey: params.idempotencyKey }
+          : {}),
+      ...(prepared.reads
+        ? { reads: [...prepared.reads] }
+        : {}),
+    });
 
-    // No automatic scope enrolment on bulk `list`: that would subscribe to an
-    // unbounded set of rows' entity groups.
-    list,
+    const rows = await resolveCreatedRows<T>({
+      modelName: registeredModelName,
+      ids,
+      operationResults: receipt.operationResults,
+      readRow: async (id) => {
+        const read = await collaboration.readPoint(registeredModelName, id);
+        return read.data as T | undefined;
+      },
+    });
+    return rows;
+  };
 
-    create: guardWrite(async (params: ModelCreateParams<T, C>): Promise<T> => {
-      const id = params.id ?? Model.generateId();
-      const claim = params.claim;
+  // `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:
+      | HttpModelMutationParams<ModelCreateParams<T, C>>
+      | HttpModelMutationParams<ModelCreateManyParams<C>>,
+  ): Promise<T | T[]> => {
+    if (Array.isArray(params.data)) {
+      return createManyRows(params as HttpModelMutationParams<ModelCreateManyParams<C>>);
+    }
+    const single = params as ModelCreateParams<T, C>;
+      const id = resolveCreateId(single.id, single.data) ?? Model.generateId();
+      const claim = single.claim;
       let autoLease: Claim | undefined;
       if (claim && !isClaimHandle(claim)) {
         if (!collaboration) {
@@ -1256,12 +1382,9 @@ export function createModelProxy<T, C>(
         createdAt: new Date(),
         updatedAt: new Date(),
       });
-      let prepared: PreparedReadSet | undefined;
       try {
-        const resolved = preparedMutation(params);
-        prepared = resolved.prepared;
         const effective: MutationOptions = {
-          ...resolved.options,
+          ...preparedMutation(single),
           ...(autoLease
             ? {
                 claimRef: { id: autoLease.id },
@@ -1281,21 +1404,46 @@ export function createModelProxy<T, C>(
         };
         syncClient.add(model, effective);
         await waitForMutation(model);
-        consumeReadSet(
-          readSetContext,
-          readSetClientIdentity,
-          prepared.consumed,
-          prepared.automaticCommit,
-        );
         return modelAsRow<T>(model);
-      } catch (error) {
-        abortReadSetCommit(readSetContext, prepared?.automaticCommit ?? false);
-        throw error;
       } finally {
         await autoLease?.release?.().catch(() => {});
       }
+  });
+
+  // Two public signatures over one implementation. A property arrow would
+  // collapse them to their union, and a single create would start
+  // resolving to `T | T[]` for every caller.
+  function createRows(
+    params: HttpModelMutationParams<ModelCreateParams<T, C>>,
+  ): Promise<T>;
+  function createRows(
+    params: HttpModelMutationParams<ModelCreateManyParams<C>>,
+  ): Promise<T[]>;
+  function createRows(
+    params:
+      | HttpModelMutationParams<ModelCreateParams<T, C>>
+      | HttpModelMutationParams<ModelCreateManyParams<C>>,
+  ): Promise<T | T[]> {
+    return createImpl(params);
+  }
+
+  const operations: ModelOperations<T, C> = {
+    local,
+
+    get,
+    read,
+
+    // No automatic scope enrolment on bulk `list`: that would subscribe to an
+    // unbounded set of rows' entity groups.
+    list,
+    listAll: guard(async (options: ListAllOptions<T> = {}) => {
+      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(...)`
@@ -1367,39 +1515,30 @@ export function createModelProxy<T, C>(
                 readSetContext,
                 readSetClientIdentity,
                 undefined,
-                'reject',
                 undefined,
                 contention?.reads,
               );
-              try {
-                const effective: MutationOptions = {
-                  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<T>(model);
-              } catch (error) {
-                abortReadSetCommit(readSetContext, prepared.automaticCommit);
-                throw error;
-              }
+              const effective: MutationOptions = {
+                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<T>(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) {
@@ -1425,57 +1564,32 @@ export function createModelProxy<T, C>(
             `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: MutationOptions | undefined = 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' as const,
-                    ...(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: MutationOptions = {
+          ...(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<T>(model);
-        } catch (error) {
-          abortReadSetCommit(readSetContext, resolved.prepared.automaticCommit);
-          throw error;
-        }
+        model.applyChanges(params.data);
+        syncClient.update(model, effective);
+        await waitForMutation(model);
+        const updated = modelAsRow<T>(model);
+        await settleClaimsAfterWrite(id, handle);
+        return updated;
         },
       );
       function update(params: ModelUpdateParams<T, C>): Promise<T>;
@@ -1495,6 +1609,9 @@ export function createModelProxy<T, C>(
     })(),
 
     delete: guardWrite(async (params: ModelDeleteParams<T, C>): Promise<void> => {
+      // 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) {
@@ -1523,74 +1640,33 @@ export function createModelProxy<T, C>(
       // 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) return;
-      const claimed = activeClaims.get(id);
-      const resolved = preparedMutation(params);
-      const opts = resolved.options;
-      const handle = isClaimHandle(params.claim) ? params.claim : undefined;
-      const effective: MutationOptions | undefined = 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' as const,
-                    ...(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;
+      if (!model) {
+        const handle = isClaimHandle(params.claim) ? params.claim : undefined;
+        await settleClaimsAfterWrite(id, handle);
+        return;
       }
+      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: MutationOptions = {
+        ...(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: ModelTrackParams): Promise<ModelTrackResult> => {
-      const dep: TrackDependency = {
-        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: string | readonly string[],