@abloatai/humans 0.64.5 → 0.65.0

package/dist/local/client/createModelOperations.js

@@ -11,7 +11,7 @@
  * lookup table from one of these per model.
  */
 import { autorun } from 'mobx';
-import { AbloClaimedError, AbloValidationError, toAbloError, } from '@abloatai/transaction/errors';
+import { AbloClaimedError, AbloStaleContextError, AbloValidationError, toAbloError, } from '@abloatai/transaction/errors';
 import { reconcileFunctionalUpdate, } from '@abloatai/transaction/client/resources/functionalUpdate';
 import { claimDescription, } from '@abloatai/transaction/coordination/schema';
 import { Model, modelAsRow } from '../Model.js';
@@ -31,7 +31,7 @@ import { ModelScope } from '@abloatai/transaction/types';
 import { bindClaimLifetime, claimLifetimeOf, } from '@abloatai/transaction/claims/lifetime';
 import { claimQueueView, resolveClaimContentionOptions, } from '@abloatai/transaction/client/resources/modelOperations';
 import { modelEventInputSchema } from '@abloatai/transaction/collaboration';
-import { capturePointRead, prepareReadSet, } from '@abloatai/transaction/internal/read-set';
+import { capturePointRead, prepareReadSet, targetGuardForRow, } from '@abloatai/transaction/internal/read-set';
 const ignoreSeparatelyObservedMutationFailure = () => undefined;
 const ignoreBestEffortClaimReleaseFailure = () => undefined;
 const ignoreBestEffortScopeFailure = () => undefined;
@@ -215,8 +215,9 @@ hydration, collaboration, readSetContext) {
         typeof value.id === 'string' &&
         typeof value.release === 'function';
     const preparedMutation = (params) => {
-        const prepared = prepareReadSet(readSetContext, readSetClientIdentity, undefined, params.idempotencyKey, params.reads);
+        const prepared = prepareReadSet(readSetContext, readSetClientIdentity, params.readAt, params.idempotencyKey, params.reads);
         const rest = {
+            ...(prepared.readAt !== undefined ? { readAt: prepared.readAt } : {}),
             ...(prepared.idempotencyKey !== undefined
                 ? { idempotencyKey: prepared.idempotencyKey }
                 : params.idempotencyKey !== undefined
@@ -225,9 +226,7 @@ hydration, collaboration, readSetContext) {
             ...(params.label !== undefined ? { label: params.label } : {}),
             ...(prepared.reads !== undefined
                 ? { reads: prepared.reads === null ? null : [...prepared.reads] }
-                : params.reads !== undefined
-                    ? { reads: params.reads }
-                    : {}),
+                : {}),
         };
         // The write-options schema — the runtime twin of the compile-time params.
         // Catches plain-JavaScript callers at the call site with a typed error
@@ -235,6 +234,15 @@ hydration, collaboration, readSetContext) {
         assertWriteOptions(rest, `${schemaKey} write`);
         return rest;
     };
+    const guardedMutation = (params) => {
+        if (params.ifUnchanged === undefined)
+            return params;
+        const { ifUnchanged, ...rest } = params;
+        return {
+            ...rest,
+            ...targetGuardForRow(readSetContext, readSetClientIdentity, wireModel, ifUnchanged),
+        };
+    };
     const releaseClaim = async (claimId) => {
         const held = removeActiveClaim(claimId);
         if (!held)
@@ -969,7 +977,7 @@ hydration, collaboration, readSetContext) {
                         },
                     });
                 }
-                const params = arg;
+                const params = guardedMutation(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.
@@ -991,6 +999,9 @@ hydration, collaboration, readSetContext) {
                 }
                 const { id } = params;
                 const model = ownRowOrThrow(id);
+                if (!model && params.readAt !== undefined) {
+                    throw new AbloStaleContextError(`Update rejected: ${registeredModelName}/${id} changed since read. Re-read and retry.`, { code: 'stale_context', httpStatus: 409 });
+                }
                 if (!model)
                     throw new AbloValidationError(`Entity not found: ${registeredModelName}/${id}`, { code: 'entity_not_found' });
                 const opts = preparedMutation(params);
@@ -1025,7 +1036,8 @@ hydration, collaboration, readSetContext) {
             }
             return update;
         })(),
-        delete: guardWrite(async (params) => {
+        delete: guardWrite(async (input) => {
+            const params = guardedMutation(input);
             // 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);
@@ -1055,6 +1067,9 @@ hydration, collaboration, readSetContext) {
             // HTTP client and makes delete safe to retry or race (two actors deleting
             // the same row).
             if (!model) {
+                if (params.readAt !== undefined) {
+                    throw new AbloStaleContextError(`Delete rejected: ${registeredModelName}/${id} changed since read. Re-read and retry.`, { code: 'stale_context', httpStatus: 409 });
+                }
                 const handle = isClaimHandle(params.claim) ? params.claim : undefined;
                 await settleClaimsAfterWrite(id, handle);
                 return;

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

@@ -73,6 +73,9 @@ export async function processBatch(ctx) {
                         }
                     }
                     else {
+                        for (const tx of batch) {
+                            ctx.emitCommitLifecycle('model:sealing', { clientTxId: tx.id });
+                        }
                         durableEnvelope = await ctx.sealDurableCommit({
                             idempotencyKey: commitIdempotencyKey,
                             origin: 'model_batch',
@@ -85,6 +88,7 @@ export async function processBatch(ctx) {
                         });
                         for (const transaction of batch) {
                             transaction.durableEnvelope = durableEnvelope;
+                            ctx.emitCommitLifecycle('model:sealed', { clientTxId: transaction.id });
                         }
                     }
                     const operations = durableEnvelope.operations;

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

@@ -34,7 +34,7 @@ export interface CommitEventSource {
 }
 /** One completed commit, broken into its local and remote halves. */
 export interface CommitLatencySample {
-    /** The commit's `clientTxId`, identical to its transaction id. */
+    /** Local transaction id; for atomic commits this is also the wire clientTxId. */
     clientTxId: string;
     /** Milliseconds sealing the durable envelope locally. */
     sealMs: number;

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

@@ -64,6 +64,9 @@ export function observeCommitLatency(source, onSample) {
         const id = readClientTxId(payload);
         if (id === null)
             return;
+        // Retain the first seal attempt across retries rather than hiding its wait.
+        if (pending.has(id))
+            return;
         // Map preserves insertion order, so the first key is the stalest entry.
         if (pending.size >= MAX_PENDING_COMMITS) {
             const oldest = pending.keys().next();
@@ -79,7 +82,7 @@ export function observeCommitLatency(source, onSample) {
         const timing = pending.get(id);
         if (timing === undefined)
             return;
-        timing.sealedAt = nowMs();
+        timing.sealedAt ??= nowMs();
     };
     const handleCompleted = (payload) => {
         const id = readTransactionId(payload);
@@ -116,12 +119,18 @@ export function observeCommitLatency(source, onSample) {
     };
     source.on('commit:staging', handleStaging);
     source.on('commit:created', handleCreated);
+    // Model batches share an envelope, but confirmation belongs to each local
+    // transaction. Restored envelopes have no observed seal and emit no sample.
+    source.on('model:sealing', handleStaging);
+    source.on('model:sealed', handleCreated);
     source.on('commit:seal_failed', handleSealFailed);
     source.on('transaction:completed', handleCompleted);
     source.on('transaction:failed', handleFailed);
     return () => {
         source.off('commit:staging', handleStaging);
         source.off('commit:created', handleCreated);
+        source.off('model:sealing', handleStaging);
+        source.off('model:sealed', handleCreated);
         source.off('commit:seal_failed', handleSealFailed);
         source.off('transaction:completed', handleCompleted);
         source.off('transaction:failed', handleFailed);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/humans",
-  "version": "0.64.5",
+  "version": "0.65.0",
   "description": "The optional human-facing local-state package for Ablo: presence, live queries, and React bindings.",
   "license": "Apache-2.0",
   "type": "module",
@@ -85,7 +85,7 @@
     "directory": "packages/humans"
   },
   "dependencies": {
-    "@abloatai/transaction": "0.64.5",
+    "@abloatai/transaction": "0.65.0",
     "events": "^3.3.0",
     "mobx": "^6.13.7",
     "uuid": "^11.1.0",

package/src/local/client/createModelOperations.ts

@@ -14,6 +14,7 @@
 import { autorun } from 'mobx';
 import {
   AbloClaimedError,
+  AbloStaleContextError,
   AbloValidationError,
   toAbloError,
 } from '@abloatai/transaction/errors';
@@ -49,7 +50,10 @@ import type {
   CommitCreateOptions,
   CommitReceipt,
 } from '@abloatai/transaction/client/resources/httpResources';
-import type { HttpModelMutationParams } from '@abloatai/transaction/transport/http';
+import type {
+  HttpGuardedMutationParams,
+  HttpModelMutationParams,
+} from '@abloatai/transaction/transport/http';
 import {
   collectModelList,
   modelList,
@@ -154,6 +158,7 @@ import { modelEventInputSchema } from '@abloatai/transaction/collaboration';
 import {
   capturePointRead,
   prepareReadSet,
+  targetGuardForRow,
   type ReadSetContext,
 } from '@abloatai/transaction/internal/read-set';
 
@@ -684,19 +689,22 @@ export function createModelOperations<T, C>(
     typeof (value as { release?: unknown }).release === 'function';
 
   const preparedMutation = (
-    params:
-      | ModelCreateParams<T, C>
-      | ModelUpdateParams<T, C>
-      | ModelDeleteParams<T, C>,
+    params: {
+      readonly idempotencyKey?: string | null;
+      readonly label?: string;
+      readonly readAt?: number;
+      readonly reads?: readonly unknown[] | null;
+    },
   ): MutationOptions => {
     const prepared = prepareReadSet(
       readSetContext,
       readSetClientIdentity,
-      undefined,
+      params.readAt,
       params.idempotencyKey,
       params.reads,
     );
     const rest: MutationOptions = {
+      ...(prepared.readAt !== undefined ? { readAt: prepared.readAt } : {}),
       ...(prepared.idempotencyKey !== undefined
         ? { idempotencyKey: prepared.idempotencyKey }
         : params.idempotencyKey !== undefined
@@ -705,9 +713,7 @@ export function createModelOperations<T, C>(
       ...(params.label !== undefined ? { label: params.label } : {}),
       ...(prepared.reads !== undefined
         ? { reads: prepared.reads === null ? null : [...prepared.reads] }
-        : params.reads !== undefined
-          ? { reads: params.reads }
-          : {}),
+        : {}),
     };
     // The write-options schema — the runtime twin of the compile-time params.
     // Catches plain-JavaScript callers at the call site with a typed error
@@ -716,6 +722,22 @@ export function createModelOperations<T, C>(
     return rest;
   };
 
+  const guardedMutation = <P extends { readonly ifUnchanged?: unknown }>(
+    params: P,
+  ): Omit<P, 'ifUnchanged'> & { readonly readAt?: number } => {
+    if (params.ifUnchanged === undefined) return params;
+    const { ifUnchanged, ...rest } = params;
+    return {
+      ...rest,
+      ...targetGuardForRow(
+        readSetContext,
+        readSetClientIdentity,
+        wireModel,
+        ifUnchanged,
+      ),
+    };
+  };
+
   const releaseClaim = async (claimId: string): Promise<void> => {
     const held = removeActiveClaim(claimId);
     if (!held) return;
@@ -1547,7 +1569,9 @@ export function createModelOperations<T, C>(
     update: ((): ModelOperations<T, C>['update'] => {
       const updateImpl = guardWrite(
         async (
-          arg: ModelUpdateParams<T, C> | string,
+          arg:
+            | HttpGuardedMutationParams<ModelUpdateParams<T, C>, T>
+            | string,
           updater?: ModelUpdater<T>,
           contention?: FunctionalUpdateOptions<ReadDependency | CapturedRow>,
         ): Promise<T | undefined> => {
@@ -1634,7 +1658,7 @@ export function createModelOperations<T, C>(
             },
           });
         }
-        const params = arg;
+        const params = guardedMutation(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.
@@ -1659,6 +1683,12 @@ export function createModelOperations<T, C>(
         }
         const { id } = params;
         const model = ownRowOrThrow(id);
+        if (!model && params.readAt !== undefined) {
+          throw new AbloStaleContextError(
+            `Update rejected: ${registeredModelName}/${id} changed since read. Re-read and retry.`,
+            { code: 'stale_context', httpStatus: 409 },
+          );
+        }
         if (!model)
           throw new AbloValidationError(
             `Entity not found: ${registeredModelName}/${id}`,
@@ -1696,14 +1726,18 @@ export function createModelOperations<T, C>(
         return updated;
         },
       );
-      function update(params: ModelUpdateParams<T, C>): Promise<T>;
+      function update(
+        params: HttpGuardedMutationParams<ModelUpdateParams<T, C>, T>,
+      ): Promise<T>;
       function update(
         id: string,
         updater: ModelUpdater<T>,
         options?: FunctionalUpdateOptions<ReadDependency | CapturedRow>,
       ): Promise<T | undefined>;
       function update(
-        arg: ModelUpdateParams<T, C> | string,
+        arg:
+          | HttpGuardedMutationParams<ModelUpdateParams<T, C>, T>
+          | string,
         updater?: ModelUpdater<T>,
         contention?: FunctionalUpdateOptions<ReadDependency | CapturedRow>,
       ): Promise<T | undefined> {
@@ -1712,7 +1746,10 @@ export function createModelOperations<T, C>(
       return update;
     })(),
 
-    delete: guardWrite(async (params: ModelDeleteParams<T, C>): Promise<void> => {
+    delete: guardWrite(async (
+      input: HttpGuardedMutationParams<ModelDeleteParams<T, C>, T>,
+    ): Promise<void> => {
+      const params = guardedMutation(input);
       // 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);
@@ -1745,6 +1782,12 @@ export function createModelOperations<T, C>(
       // HTTP client and makes delete safe to retry or race (two actors deleting
       // the same row).
       if (!model) {
+        if (params.readAt !== undefined) {
+          throw new AbloStaleContextError(
+            `Delete rejected: ${registeredModelName}/${id} changed since read. Re-read and retry.`,
+            { code: 'stale_context', httpStatus: 409 },
+          );
+        }
         const handle = isClaimHandle(params.claim) ? params.claim : undefined;
         await settleClaimsAfterWrite(id, handle);
         return;

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

@@ -144,6 +144,9 @@ export async function processBatch(ctx: BatchProcessingContext): Promise<void> {
                   throw new Error('Cannot replay a model batch with inconsistent durable envelopes');
                 }
               } else {
+                for (const tx of batch) {
+                  ctx.emitCommitLifecycle('model:sealing', { clientTxId: tx.id });
+                }
                 durableEnvelope = await ctx.sealDurableCommit({
                   idempotencyKey: commitIdempotencyKey,
                   origin: 'model_batch',
@@ -156,6 +159,7 @@ export async function processBatch(ctx: BatchProcessingContext): Promise<void> {
                 });
                 for (const transaction of batch) {
                   transaction.durableEnvelope = durableEnvelope;
+                  ctx.emitCommitLifecycle('model:sealed', { clientTxId: transaction.id });
                 }
               }
               const operations = durableEnvelope.operations;

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

@@ -36,7 +36,7 @@ export interface CommitEventSource {
 
 /** One completed commit, broken into its local and remote halves. */
 export interface CommitLatencySample {
-  /** The commit's `clientTxId`, identical to its transaction id. */
+  /** Local transaction id; for atomic commits this is also the wire clientTxId. */
   clientTxId: string;
   /** Milliseconds sealing the durable envelope locally. */
   sealMs: number;
@@ -98,6 +98,8 @@ export function observeCommitLatency(
   const handleStaging = (payload: unknown): void => {
     const id = readClientTxId(payload);
     if (id === null) return;
+    // Retain the first seal attempt across retries rather than hiding its wait.
+    if (pending.has(id)) return;
     // Map preserves insertion order, so the first key is the stalest entry.
     if (pending.size >= MAX_PENDING_COMMITS) {
       const oldest = pending.keys().next();
@@ -111,7 +113,7 @@ export function observeCommitLatency(
     if (id === null) return;
     const timing = pending.get(id);
     if (timing === undefined) return;
-    timing.sealedAt = nowMs();
+    timing.sealedAt ??= nowMs();
   };
 
   const handleCompleted = (payload: unknown): void => {
@@ -149,6 +151,10 @@ export function observeCommitLatency(
 
   source.on('commit:staging', handleStaging);
   source.on('commit:created', handleCreated);
+  // Model batches share an envelope, but confirmation belongs to each local
+  // transaction. Restored envelopes have no observed seal and emit no sample.
+  source.on('model:sealing', handleStaging);
+  source.on('model:sealed', handleCreated);
   source.on('commit:seal_failed', handleSealFailed);
   source.on('transaction:completed', handleCompleted);
   source.on('transaction:failed', handleFailed);
@@ -156,6 +162,8 @@ export function observeCommitLatency(
   return () => {
     source.off('commit:staging', handleStaging);
     source.off('commit:created', handleCreated);
+    source.off('model:sealing', handleStaging);
+    source.off('model:sealed', handleCreated);
     source.off('commit:seal_failed', handleSealFailed);
     source.off('transaction:completed', handleCompleted);
     source.off('transaction:failed', handleFailed);