@abloatai/humans 0.59.0 → 0.59.1

package/dist/local/interfaces/index.d.ts

@@ -141,7 +141,7 @@ import type { MutationOptions } from '@abloatai/transaction/client/resources/mut
  * `claim` are deliberately absent: both are resolved on the client before a write
  * is staged, so neither reaches this layer.
  */
-export type WriteOptions = Pick<MutationOptions, 'readAt' | 'idempotencyKey' | 'label' | 'fenceToken' | 'claimRef'>;
+export type WriteOptions = Pick<MutationOptions, 'readAt' | 'reads' | 'idempotencyKey' | 'label' | 'fenceToken' | 'claimRef'>;
 /** A single mutation within a batch. Its `options` travel with it so the server
  *  can cache and replay the operation for idempotent retries. */
 export interface MutationOperation {

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

@@ -1,5 +1,5 @@
 import { AbloError, AbloNotFoundError } from '@abloatai/transaction/errors';
-import { applyWriteOptions, normalizeModelKey, TX_TYPE_TO_MUTATION_OP } from './commitPayload.js';
+import { applyWriteOptions, collectQueuedReads, normalizeModelKey, TX_TYPE_TO_MUTATION_OP } from './commitPayload.js';
 export async function processBatch(ctx) {
     if (ctx.durableReplayBlock)
         return;
@@ -69,6 +69,7 @@ export async function processBatch(ctx) {
                         origin: 'model_batch',
                         operations: batchOps.map(({ op }) => op),
                         sourceMutationIds: ctx.sourceMutationIdsFor(batch),
+                        commitOptions: { reads: collectQueuedReads(batch) },
                         createdAt: Math.min(...batch.map((transaction) => transaction.createdAt)),
                         sealedAt: batch[0]?.commitEnvelope?.sealedAt ?? Date.now(),
                         sequence: batch[0]?.commitEnvelope?.sequence,
@@ -84,6 +85,9 @@ export async function processBatch(ctx) {
                     dispatchStarted = true;
                     const result = ctx.parseMutationCommitResult(await ctx.dispatchCommitBounded(operations, {
                         idempotencyKey: commitIdempotencyKey,
+                        ...(durableEnvelope.commitOptions.reads !== undefined
+                            ? { reads: durableEnvelope.commitOptions.reads }
+                            : {}),
                     }));
                     await ctx.persistDurableCommitAcceptance(durableEnvelope, result);
                     const lastSyncId = result.lastSyncId;

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

@@ -105,6 +105,8 @@ export interface QueuedMutation {
      */
     confirmation?: Promise<void>;
 }
+/** Merge per-write premises into the one batch-level read set sent on wire. */
+export declare function collectQueuedReads(transactions: readonly QueuedMutation[]): MutationOptions['reads'] | undefined;
 export declare const normalizeModelKey: (modelName: string) => string;
 export declare const stripModelSuffix: (modelName: string) => string;
 /**

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

@@ -75,6 +75,20 @@ export function projectCommitPayload(modelName, source, opts, runtime = globalRu
     }
     return snapshotJsonValue(out, '$.input');
 }
+/** Merge per-write premises into the one batch-level read set sent on wire. */
+export function collectQueuedReads(transactions) {
+    const declared = transactions
+        .map((transaction) => transaction.writeOptions?.reads)
+        .filter((reads) => reads !== undefined);
+    if (declared.length === 0)
+        return undefined;
+    const unique = new Map();
+    for (const dependency of declared.flatMap((reads) => reads ?? [])) {
+        unique.set(JSON.stringify(dependency), dependency);
+    }
+    const reads = [...unique.values()];
+    return reads.length > 0 ? reads : null;
+}
 export const normalizeModelKey = (modelName) => modelName.replace('Model', '').toLowerCase();
 export const stripModelSuffix = (modelName) => modelName.replace('Model', '');
 /**

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

@@ -1,4 +1,4 @@
-import { applyWriteOptions, TX_TYPE_TO_MUTATION_OP } from './commitPayload.js';
+import { applyWriteOptions, collectQueuedReads, TX_TYPE_TO_MUTATION_OP } from './commitPayload.js';
 export async function drainPendingConfirmations(ctx) {
     ctx.assertDurableReplayOpen();
     // Kick the commit lane too: atomic envelopes from `commits.create()` may
@@ -39,6 +39,7 @@ export async function drainPendingConfirmations(ctx) {
                 origin: 'model_batch',
                 operations: projectedOperations,
                 sourceMutationIds: ctx.sourceMutationIdsFor(batch),
+                commitOptions: { reads: collectQueuedReads(batch) },
                 createdAt: Math.min(...batch.map((transaction) => transaction.createdAt)),
                 sealedAt: batch[0]?.commitEnvelope?.sealedAt ?? Date.now(),
                 sequence: batch[0]?.commitEnvelope?.sequence,
@@ -46,6 +47,9 @@ export async function drainPendingConfirmations(ctx) {
             ctx.assertEnvelopeInsideReplayWindow(durableEnvelope);
             const result = ctx.parseMutationCommitResult(await ctx.dispatchCommitBounded(durableEnvelope.operations, {
                 idempotencyKey,
+                ...(durableEnvelope.commitOptions.reads !== undefined
+                    ? { reads: durableEnvelope.commitOptions.reads }
+                    : {}),
             }));
             await ctx.persistDurableCommitAcceptance(durableEnvelope, result);
             if (result.status === 'queued') {

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

@@ -56,6 +56,15 @@ export declare const persistedTransactionSchema: z.ZodObject<{
     sourceMutationIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
     writeOptions: z.ZodOptional<z.ZodObject<{
         readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        reads: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            model: z.ZodString;
+            id: z.ZodString;
+            fields: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+            readAt: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            group: z.ZodTemplateLiteral<`${string}:${string}`>;
+            readAt: z.ZodNumber;
+        }, z.core.$strip>]>>>>;
         idempotencyKey: z.ZodOptional<z.ZodString>;
         label: z.ZodOptional<z.ZodString>;
         fenceToken: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
@@ -97,6 +106,15 @@ export declare const persistedMutationSchema: z.ZodObject<{
     capturedChanges: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     writeOptions: z.ZodOptional<z.ZodObject<{
         readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        reads: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            model: z.ZodString;
+            id: z.ZodString;
+            fields: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+            readAt: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            group: z.ZodTemplateLiteral<`${string}:${string}`>;
+            readAt: z.ZodNumber;
+        }, z.core.$strip>]>>>>;
         idempotencyKey: z.ZodOptional<z.ZodString>;
         label: z.ZodOptional<z.ZodString>;
         fenceToken: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
@@ -131,6 +149,15 @@ export declare const legacyPendingMutationRecordSchema: z.ZodObject<{
         capturedChanges: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         writeOptions: z.ZodOptional<z.ZodObject<{
             readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            reads: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                model: z.ZodString;
+                id: z.ZodString;
+                fields: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+                readAt: z.ZodNumber;
+            }, z.core.$strip>, z.ZodObject<{
+                group: z.ZodTemplateLiteral<`${string}:${string}`>;
+                readAt: z.ZodNumber;
+            }, z.core.$strip>]>>>>;
             idempotencyKey: z.ZodOptional<z.ZodString>;
             label: z.ZodOptional<z.ZodString>;
             fenceToken: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
@@ -164,6 +191,15 @@ export declare const pendingMutationRecordSchema: z.ZodObject<{
         capturedChanges: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         writeOptions: z.ZodOptional<z.ZodObject<{
             readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            reads: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                model: z.ZodString;
+                id: z.ZodString;
+                fields: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+                readAt: z.ZodNumber;
+            }, z.core.$strip>, z.ZodObject<{
+                group: z.ZodTemplateLiteral<`${string}:${string}`>;
+                readAt: z.ZodNumber;
+            }, z.core.$strip>]>>>>;
             idempotencyKey: z.ZodOptional<z.ZodString>;
             label: z.ZodOptional<z.ZodString>;
             fenceToken: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;

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

@@ -18,10 +18,12 @@ import { z } from 'zod';
 import { computePriorityScore, normalizeModelKey } from './commitPayload.js';
 import { globalRuntime } from '../../context.js';
 import { commitEnvelopeMemberSchema, commitOutboxScopeSchema, } from '@abloatai/transaction/commit';
+import { readDependencySchema } from '@abloatai/transaction/coordination/schema';
 /** The subset of a write's options that is stored with each transaction or queued mutation. */
 const persistedWriteOptionsSchema = z
     .object({
     readAt: z.number().nullable().optional(),
+    reads: z.array(readDependencySchema).nullable().optional(),
     idempotencyKey: z.string().optional(),
     label: z.string().optional(),
     // Aligned with the `WriteOptions` type: a claimed write persisted locally

package/package.json

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

package/src/local/interfaces/index.ts

@@ -242,7 +242,7 @@ import type { MutationOptions } from '@abloatai/transaction/client/resources/mut
  */
 export type WriteOptions = Pick<
   MutationOptions,
-  'readAt' | 'idempotencyKey' | 'label' | 'fenceToken' | 'claimRef'
+  'readAt' | 'reads' | 'idempotencyKey' | 'label' | 'fenceToken' | 'claimRef'
 >;
 
 /** A single mutation within a batch. Its `options` travel with it so the server

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

@@ -7,7 +7,7 @@ import type { DeltaConfirmationTracker } from './deltaConfirmation.js';
 import type { MutationCommitResult } from '@abloatai/transaction/commit';
 import type { DurableCommitEnvelope } from '@abloatai/transaction/commit';
 import { AbloError, AbloNotFoundError } from '@abloatai/transaction/errors';
-import { applyWriteOptions, normalizeModelKey, TX_TYPE_TO_MUTATION_OP, type WriteOperationFields } from './commitPayload.js';
+import { applyWriteOptions, collectQueuedReads, normalizeModelKey, TX_TYPE_TO_MUTATION_OP, type WriteOperationFields } from './commitPayload.js';
 import type { MutationOperationType } from '@abloatai/transaction/types';
 
 export interface BatchProcessingContext {
@@ -138,6 +138,7 @@ export async function processBatch(ctx: BatchProcessingContext): Promise<void> {
                 origin: 'model_batch',
                 operations: batchOps.map(({ op }) => op),
                 sourceMutationIds: ctx.sourceMutationIdsFor(batch),
+                commitOptions: { reads: collectQueuedReads(batch) },
                 createdAt: Math.min(...batch.map((transaction) => transaction.createdAt)),
                 sealedAt: batch[0]?.commitEnvelope?.sealedAt ?? Date.now(),
                 sequence: batch[0]?.commitEnvelope?.sequence,
@@ -155,6 +156,9 @@ export async function processBatch(ctx: BatchProcessingContext): Promise<void> {
               const result = ctx.parseMutationCommitResult(
                 await ctx.dispatchCommitBounded(operations, {
                   idempotencyKey: commitIdempotencyKey,
+                  ...(durableEnvelope.commitOptions.reads !== undefined
+                    ? { reads: durableEnvelope.commitOptions.reads }
+                    : {}),
                 }),
               );
               await ctx.persistDurableCommitAcceptance(

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

@@ -160,6 +160,23 @@ export interface QueuedMutation {
   confirmation?: Promise<void>;
 }
 
+/** Merge per-write premises into the one batch-level read set sent on wire. */
+export function collectQueuedReads(
+  transactions: readonly QueuedMutation[],
+): MutationOptions['reads'] | undefined {
+  const declared = transactions
+    .map((transaction) => transaction.writeOptions?.reads)
+    .filter((reads) => reads !== undefined);
+  if (declared.length === 0) return undefined;
+
+  const unique = new Map<string, NonNullable<MutationOptions['reads']>[number]>();
+  for (const dependency of declared.flatMap((reads) => reads ?? [])) {
+    unique.set(JSON.stringify(dependency), dependency);
+  }
+  const reads = [...unique.values()];
+  return reads.length > 0 ? reads : null;
+}
+
 export const normalizeModelKey = (modelName: string): string =>
   modelName.replace('Model', '').toLowerCase();
 export const stripModelSuffix = (modelName: string): string => modelName.replace('Model', '');

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

@@ -4,7 +4,7 @@ import type { MutationStore } from './MutationStore.js';
 import type { OptimisticUpdateEntry } from './localMutation.js';
 import type { MutationCommitResult } from '@abloatai/transaction/commit';
 import type { DurableCommitEnvelope } from '@abloatai/transaction/commit';
-import { applyWriteOptions, TX_TYPE_TO_MUTATION_OP } from './commitPayload.js';
+import { applyWriteOptions, collectQueuedReads, TX_TYPE_TO_MUTATION_OP } from './commitPayload.js';
 
 export interface PendingDrainContext {
   readonly runtime: RuntimeContext;
@@ -81,6 +81,7 @@ export async function drainPendingConfirmations(ctx: PendingDrainContext): Promi
           origin: 'model_batch',
           operations: projectedOperations,
           sourceMutationIds: ctx.sourceMutationIdsFor(batch),
+          commitOptions: { reads: collectQueuedReads(batch) },
           createdAt: Math.min(...batch.map((transaction) => transaction.createdAt)),
           sealedAt: batch[0]?.commitEnvelope?.sealedAt ?? Date.now(),
           sequence: batch[0]?.commitEnvelope?.sequence,
@@ -89,6 +90,9 @@ export async function drainPendingConfirmations(ctx: PendingDrainContext): Promi
         const result = ctx.parseMutationCommitResult(
           await ctx.dispatchCommitBounded(durableEnvelope.operations, {
             idempotencyKey,
+            ...(durableEnvelope.commitOptions.reads !== undefined
+              ? { reads: durableEnvelope.commitOptions.reads }
+              : {}),
           }),
         );
         await ctx.persistDurableCommitAcceptance(durableEnvelope, result);

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

@@ -24,11 +24,13 @@ import {
   commitEnvelopeMemberSchema,
   commitOutboxScopeSchema,
 } from '@abloatai/transaction/commit';
+import { readDependencySchema } from '@abloatai/transaction/coordination/schema';
 
 /** The subset of a write's options that is stored with each transaction or queued mutation. */
 const persistedWriteOptionsSchema = z
   .object({
     readAt: z.number().nullable().optional(),
+    reads: z.array(readDependencySchema).nullable().optional(),
     idempotencyKey: z.string().optional(),
     label: z.string().optional(),
     // Aligned with the `WriteOptions` type: a claimed write persisted locally