@abloatai/humans 0.56.0 → 0.58.0

package/src/local/client/options.ts

@@ -19,8 +19,8 @@ import type { AbloPersistence } from '../persistence.js';
 import type {
   DurableWriteStore,
   DurableWritesConfig,
-} from '@abloatai/transaction/durableWrites';
-import type { CommitOutboxScope } from '@abloatai/transaction/transactions/confirmation/commitEnvelope';
+} from '@abloatai/transaction/commit';
+import type { CommitOutboxScope } from '@abloatai/transaction/commit';
 
 // ── Options ───────────────────────────────────────────────────────────────
 

package/src/local/client/reactiveEngine.ts

@@ -17,7 +17,7 @@ import { omittedModelError } from '@abloatai/transaction/schema/select';
 import {
   durableCommitOperationSchema,
   type DurableCommitOperation,
-} from '@abloatai/transaction/transactions/confirmation/commitEnvelope';
+} from '@abloatai/transaction/commit';
 import { AbloAuthenticationError, AbloConnectionError, AbloValidationError, claimedError } from '@abloatai/transaction/errors';
 import type { ModelTarget, ModelClaim } from '@abloatai/transaction/coordination/schema';
 import type { BatchFence } from '@abloatai/transaction/coordination';
@@ -41,11 +41,14 @@ import type { StoreCluster } from './storeCluster.js';
 import { startStoreLifecycle } from './storeLifecycle.js';
 import type { SyncWebSocket, CoreSyncEventMap } from '../sync/SyncWebSocket.js';
 import { createClaimStream } from '../sync/createClaimStream.js';
-import { awaitClaimGrant } from '@abloatai/transaction/coordination/awaitClaimGrant';
-import { createSnapshot } from '../sync/createSnapshot.js';
+import { awaitClaimGrant } from '@abloatai/transaction/claims';
+import {
+  bindClaimLifetime,
+  claimLifetimeOf,
+} from '@abloatai/transaction/claims/lifetime';
 import { createParticipantManager } from '../sync/participants.js';
 import type { AttachablePresenceStream } from '../../presenceStream.js';
-import type { ClaimWaitOptions, Snapshot } from '@abloatai/transaction/types/streams';
+import type { ClaimWaitOptions } from '@abloatai/transaction/types/streams';
 import type { Claim } from '@abloatai/transaction/types/streams';
 import type { CredentialProvider } from '@abloatai/transaction/auth/apiKey';
 import { resolveApiKeyValue, resolveBootstrapBaseUrl } from '@abloatai/transaction/auth/apiKey';
@@ -66,9 +69,9 @@ import type {
 import {
   claimAttemptFailure,
   emitClaimStatus,
-} from '@abloatai/transaction/resources/modelOperations';
-import { createModelProxy, type ModelOperations } from './createModelProxy.js';
-import { assertWriteOptions } from '@abloatai/transaction/resources/writeOptionsSchema';
+} from '@abloatai/transaction/client/resources/modelOperations';
+import { createModelOperations, type ModelOperations } from './createModelOperations.js';
+import { assertWriteOptions } from '@abloatai/transaction/client/resources/writeOptionsSchema';
 import type { AbloClient as Ablo } from '../../client.js';
 import {
   modelReadResponseSchema,
@@ -76,8 +79,17 @@ import {
   commitRecordListSchema,
   commitRecordWhereSchema,
 } from '@abloatai/transaction/wire';
-import { translateHttpError } from '@abloatai/transaction/errors';
-import { kReadEvidence } from '@abloatai/transaction/internal/read-set';
+import {
+  translateHttpError,
+  type AbloStaleContextError,
+} from '@abloatai/transaction/errors';
+import {
+  kReadEvidence,
+  prepareReadSet,
+} from '@abloatai/transaction/internal/read-set';
+import { contextOnChange } from '../sync/contextOnChange.js';
+import type { ReadDependency } from '@abloatai/transaction/coordination';
+import type { CapturedRow } from '@abloatai/transaction/transport/http';
 
 /**
  * What the reactive build is fed: the factory's pass over the options bag
@@ -296,7 +308,7 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
 
 	  function normalizeCommitOperation(
 	    op: CommitOperationInput,
-	    defaults: Pick<CommitCreateOptions, 'readAt' | 'onStale'>,
+	    defaults: Pick<CommitCreateOptions, 'readAt'>,
 	    fence: BatchFence | null,
 	    claim: Claim | null,
 	  ): DurableCommitOperation {
@@ -311,14 +323,13 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
 	      claimId:
 	        op.claimId ?? claimIdFor(claim?.target, claim?.id, op.model, op.id ?? null) ?? undefined,
 	      readAt: op.readAt ?? defaults.readAt ?? undefined,
-	      onStale: op.onStale ?? defaults.onStale ?? undefined,
 	      fenceToken:
 	        op.fenceToken ?? fenceTokenFor(fence, op.model, op.id ?? null) ?? undefined,
 	    });
 	  }
 
 	  function normalizeCommitOperations(
-	    commitOptions: CommitCreateOptions,
+	    commitOptions: Pick<CommitCreateOptions, 'operations' | 'readAt' | 'claim'>,
 	    fence: BatchFence | null,
 	  ): DurableCommitOperation[] {
 	    if (commitOptions.operations.length === 0) {
@@ -457,7 +468,7 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
 	    // the one `awaitClaimGrant` read there; retain the handle fallback for
 	    // wire-compatible transports that already stamped it locally.
 	    const resolvedFenceToken = fenceToken ?? claim.fenceToken;
-	    return {
+	    const wrapped = {
 	      object: 'claim',
 	      id: claim.id,
 	      description: claim.description,
@@ -472,7 +483,9 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
 	      // silently dropped from the public claim.
 	      heartbeat: claim.heartbeat,
 	      [Symbol.asyncDispose]: release,
-	    };
+	    } satisfies Claim;
+	    const lifetime = claimLifetimeOf(claim);
+	    return lifetime ? bindClaimLifetime(wrapped, lifetime) : wrapped;
 	  }
 
 	  const publicClaims: ClaimResource = Object.assign(claimStream, {
@@ -580,7 +593,7 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
   const modelProxies: Record<string, ModelOperations<unknown, unknown>> = {};
   for (const [schemaKey, modelDef] of Object.entries(schema.models)) {
     const registeredModelName = modelDef.typename ?? schemaKey;
-    modelProxies[schemaKey] = createModelProxy(
+    modelProxies[schemaKey] = createModelOperations(
       schemaKey,
       registeredModelName,
       objectPool,
@@ -589,21 +602,15 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
       hydration,
       {
         createClaim: (claimOptions) => publicClaims.create(claimOptions),
+        // Lazily referenced: `commits` is declared below this loop, and this
+        // only runs when someone actually writes a batch.
+        commitBatch: (commitOptions) => commits.create(commitOptions),
         readPoint,
-        createSnapshot: (modelKey, id) =>
-          createSnapshot({
-            pool: objectPool,
-            transport,
-            // `position.readFloor` is the value claims and snapshots stamp as
-            // `readAt` (max of the pool-applied cursor and the acked
-            // watermark for our own writes — see logPosition.ts).
-            // Stamping a bare stream cursor made a claim taken right after
-            // an ack-confirmed write stale against that write's own delta.
-            // The socket/store cursors are persistence-gated and therefore
-            // never ahead of `applied` — no extra max() needed here.
-            getLastSyncId: () => syncClient.position.readFloor,
-            entities: { [modelKey]: id },
-          }),
+        // A claim needs the post-read watermark, not the legacy snapshot
+        // object. `readFloor` is max(applied, acked-own-write), so a claim
+        // taken immediately after its own confirmed mutation is not stale
+        // against an echo that has not materialised locally yet.
+        currentReadAt: () => syncClient.position.readFloor,
         queue: (target) =>
           publicClaims.queueFor(streamTarget(target)),
         reorder: (target, order) =>
@@ -653,31 +660,39 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
     );
   }
 
-	  const commits: CommitResource = {
-	    async create(commitOptions: CommitCreateOptions): Promise<CommitReceipt> {
+	  const commits: CommitResource<ReadDependency | CapturedRow> = {
+	    async create(
+        commitOptions: CommitCreateOptions<ReadDependency | CapturedRow>,
+      ): Promise<CommitReceipt> {
 	      await ready();
+	      const prepared = prepareReadSet(
+          cluster.readSetContext,
+          syncClient as object,
+          commitOptions.readAt,
+          commitOptions.idempotencyKey,
+          commitOptions.reads,
+        );
 	      // Same runtime contract as the per-model writes — one schema.
 	      assertWriteOptions(
 	        {
-	          idempotencyKey: commitOptions.idempotencyKey,
-	          readAt: commitOptions.readAt,
-	          onStale: commitOptions.onStale,
+	          idempotencyKey: prepared.idempotencyKey,
+	          readAt: prepared.readAt,
 	          wait: commitOptions.wait,
 	          claim: commitOptions.claim,
+	          reads: prepared.reads,
 	        },
 	        'commits.create',
 	      );
-	      const clientTxId = createClientTxId(commitOptions.idempotencyKey);
+	      const clientTxId = createClientTxId(prepared.idempotencyKey);
 	      // A claim handle supplies the batch stale-guard defaults — same
 	      // semantics as `ablo.<model>.update({ id, data, claim })`, so the
 	      // two write doors speak one claim vocabulary. Explicit options win.
 	      const claim = commitOptions.claim ?? null;
 	      const operations = normalizeCommitOperations(
 	        {
-	          ...commitOptions,
-	          readAt: commitOptions.readAt ?? claim?.readAt ?? null,
-	          onStale:
-	            commitOptions.onStale ?? (claim?.readAt !== undefined ? 'reject' : null),
+	          operations: commitOptions.operations,
+	          ...(commitOptions.claim !== undefined ? { claim: commitOptions.claim } : {}),
+	          readAt: prepared.readAt ?? claim?.readAt ?? null,
 	        },
 	        batchFence(claim?.target, claim?.fenceToken),
 	      );
@@ -693,22 +708,21 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
 	      // no need to leak an accessor through BaseSyncedStore.
 	      const queue = syncClient.getMutationQueue();
 	      await queue.enqueueCommit(clientTxId, operations, {
-	        ...(commitOptions.reads ? { reads: [...commitOptions.reads] } : {}),
-	        ...(commitOptions.track ? { track: [...commitOptions.track] } : {}),
+	        ...(prepared.reads ? { reads: [...prepared.reads] } : {}),
 	      });
 
 	      if (wait === 'queued') {
 	        return { id: clientTxId, status: 'queued' };
 	      }
 
-	      const { lastSyncId, notifications, missingIds } =
+	      const { lastSyncId, missingIds, operationResults } =
 	        await queue.waitForCommitReceipt(clientTxId);
 	      return {
 	        id: clientTxId,
 	        status: 'confirmed',
 	        lastSyncId,
-	        ...(notifications && notifications.length > 0 ? { notifications } : {}),
 	        ...(missingIds && missingIds.length > 0 ? { missingIds } : {}),
+	        ...(operationResults && operationResults.length > 0 ? { operationResults } : {}),
 	      };
 	    },
 	    async get({ id }) {
@@ -901,6 +915,7 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
         const sessionParams = {
           agent: { id },
           can: params.can,
+          ...(params.onBehalfOf ? { onBehalfOf: params.onBehalfOf } : {}),
           ...(params.syncGroups ? { syncGroups: params.syncGroups } : {}),
           ...(params.ttlSeconds !== undefined ? { ttlSeconds: params.ttlSeconds } : {}),
           ...(userMeta ? { userMeta } : {}),
@@ -1014,21 +1029,18 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
 
 	    commits,
 
-    /** Context-staleness snapshot — see `engine.snapshot(...)` JSDoc. */
-    snapshot<ModelName extends keyof S & string>(
-      entities: Readonly<Record<ModelName, string | readonly string[]>>,
-    ): Snapshot<Schema<S>, ModelName> {
-      return createSnapshot<Schema<S>, ModelName>({
-        pool: objectPool,
-        transport,
-        getLastSyncId: () => transport.getLastSyncId(),
-        entities,
-      });
-    },
   } as Ablo<S>;
 
   Object.defineProperty(engine, kReadEvidence, {
-    value: { context: cluster.readSetContext, client: syncClient as object },
+    value: {
+      context: cluster.readSetContext,
+      client: syncClient as object,
+      onChange: (
+        reads: readonly ReadDependency[],
+        listener: (error: AbloStaleContextError) => void,
+      ) =>
+        contextOnChange(syncClient, objectPool, reads, listener),
+    },
     enumerable: false,
   });
 

package/src/local/client/resourceTypes.ts

@@ -8,7 +8,7 @@
  * live participant handle.
  */
 
-export * from '@abloatai/transaction/resources/httpResources';
+export * from '@abloatai/transaction/client/resources/httpResources';
 
 // The request contract for `ablo.<model>` — also core, re-joined here so this
 // module stays the single import path for the whole resource surface.
@@ -17,7 +17,7 @@ export type {
   LocalReadOptions,
   ModelListScope,
   ServerReadOptions,
-  ModelRetrieveParams,
+  ModelReadParams,
   ModelWriteOptions,
   ModelCreateParams,
   ModelUpdateParams,
@@ -34,8 +34,8 @@ export type {
   ClaimHeartbeatOptions,
   HeldClaim,
   HeldLease,
-} from '@abloatai/transaction/resources/modelOperations';
+} from '@abloatai/transaction/client/resources/modelOperations';
 
 // `ModelOperations` binds the request contract to reactive model instances, so
 // it lives with the factory that builds it rather than with the core.
-export type { ModelOperations } from './createModelProxy.js';
+export type { ModelOperations } from './createModelOperations.js';

package/src/local/client/wsMutationExecutor.ts

@@ -5,19 +5,19 @@
  * client wires this up automatically unless you supply your own executor.
  */
 
-import type { ReadDependency, TrackDependency } from '@abloatai/transaction/coordination/schema';
+import type { ReadDependency } from '@abloatai/transaction/coordination/schema';
 import type {
   MutationExecutor,
   MutationOperation,
   MutationOptions,
 } from '../interfaces/index.js';
 import type { CommitAck } from '../sync/commitFrames.js';
-import type { CommitReceiptWire } from '@abloatai/transaction/wire/commit';
+import type { CommitReceiptWire } from '@abloatai/transaction/commit';
 import {
   recordWebSocketCommitReceipt,
   type ReadSetContext,
 } from '@abloatai/transaction/internal/read-set';
-import { commitAckSchema } from '@abloatai/transaction/wire/commit';
+import { commitAckSchema } from '@abloatai/transaction/commit';
 import { AbloError, AbloConnectionError } from '@abloatai/transaction/errors';
 
 // ── Default mutation executor (wire: `commit` frame over WebSocket) ──────
@@ -44,14 +44,12 @@ import { AbloError, AbloConnectionError } from '@abloatai/transaction/errors';
 	      clientTxId: string,
 	      timeoutMs?: number,
 	      reads?: readonly ReadDependency[] | null,
-	      track?: readonly TrackDependency[] | null,
 	    ) => Promise<CommitReceiptWire>;
 	    sendCommit?: (
 	      operations: readonly MutationOperation[],
 	      clientTxId: string,
 	      timeoutMs?: number,
 	      reads?: readonly ReadDependency[] | null,
-	      track?: readonly TrackDependency[] | null,
 	    ) => Promise<CommitAck>;
 	  } | null,
 	  readSetContext?: ReadSetContext,
@@ -80,21 +78,19 @@ import { AbloError, AbloConnectionError } from '@abloatai/transaction/errors';
 	          clientTxId,
 	          undefined,
 	          options?.reads,
-	          options?.track,
 	        );
 	        recordWebSocketCommitReceipt(readSetContext, {
 	          receipt,
 	          operations,
 	          reads: options?.reads,
-	          track: options?.track,
 	        });
 	        return commitAckSchema.parse({
 	          status: receipt.status,
 	          statusAt: receipt.statusAt,
 	          lastSyncId: receipt.lastSyncId,
 	          ...(receipt.correlationId ? { correlationId: receipt.correlationId } : {}),
-	          ...(receipt.notifications ? { notifications: receipt.notifications } : {}),
 	          ...(receipt.missingIds ? { missingIds: receipt.missingIds } : {}),
+	          ...(receipt.operationResults ? { operationResults: receipt.operationResults } : {}),
 	        });
 	      }
 	      if (!ws.sendCommit) {
@@ -107,7 +103,6 @@ import { AbloError, AbloConnectionError } from '@abloatai/transaction/errors';
 	        clientTxId,
 	        undefined, // use sendCommit's built-in 15s default; no per-call override
 	        options?.reads,
-	        options?.track,
 	      );
     } catch (err) {
       // Wrap transport-level failures as connection errors so the transaction

package/src/local/coordination/ClaimLog.ts

@@ -6,11 +6,11 @@
  * without leaking bootstrap, storage, or WebSocket vocabulary into the core.
  */
 
-import { ClaimLog as CoordinationClaimLog } from '@abloatai/transaction/coordination/trace';
+import { ClaimLog as CoordinationClaimLog } from '@abloatai/transaction/claims';
 import type { ObservabilityProvider } from '../interfaces/index.js';
 
-export { formatClaim, formatConflict } from '@abloatai/transaction/coordination/trace';
-export type { ClaimLogEntry } from '@abloatai/transaction/coordination/trace';
+export { formatClaim, formatConflict } from '@abloatai/transaction/claims';
+export type { ClaimLogEntry } from '@abloatai/transaction/claims';
 
 export class ClaimLog extends CoordinationClaimLog implements ObservabilityProvider {
   // Client-lifecycle hooks the claim log has no notion of. Every body below is

package/src/local/interfaces/index.ts

@@ -7,9 +7,8 @@
  * mutations to your backend. The SDK ships sensible no-op defaults where it can.
  */
 
-import type { MutationCommitResultInput } from '@abloatai/transaction/wire/commit';
-import type { OnStaleMode } from '@abloatai/transaction/coordination/schema';
-export type { ClaimEvent, ConflictEvent } from '@abloatai/transaction/coordination/events';
+import type { MutationCommitResultInput } from '@abloatai/transaction/commit';
+export type { ClaimEvent, ConflictEvent } from '@abloatai/transaction/claims/events';
 import type { CoordinationObservability } from '@abloatai/transaction/observability';
 export type { CoordinationObservability } from '@abloatai/transaction/observability';
 
@@ -231,8 +230,8 @@ export type MutationCommitResult = MutationCommitResultInput;
 // re-exports without binding X in this module's scope, and `Pick<X, K>` on an
 // unbound X silently yields all-required properties rather than a missing-name
 // error at the Pick site.
-export type { MutationOptions } from '@abloatai/transaction/resources/mutationOptions';
-import type { MutationOptions } from '@abloatai/transaction/resources/mutationOptions';
+export type { MutationOptions } from '@abloatai/transaction/client/resources/mutationOptions';
+import type { MutationOptions } from '@abloatai/transaction/client/resources/mutationOptions';
 
 /**
  * The subset of {@link MutationOptions} that travels with each write as it is
@@ -243,7 +242,7 @@ import type { MutationOptions } from '@abloatai/transaction/resources/mutationOp
  */
 export type WriteOptions = Pick<
   MutationOptions,
-  'readAt' | 'onStale' | 'idempotencyKey' | 'label' | 'fenceToken' | 'claimRef'
+  'readAt' | 'idempotencyKey' | 'label' | 'fenceToken' | 'claimRef'
 >;
 
 /** A single mutation within a batch. Its `options` travel with it so the server
@@ -268,7 +267,6 @@ export interface MutationOperation {
   /** Server-issued claim identity the operation is attributed to. */
   claimId?: string | null;
   readAt?: number | null;
-  onStale?: OnStaleMode | null;
   /**
    * The fencing token (Option B) carried on the wire for this op — the held
    * claim's token, validated against the entity's high-water at commit.

package/src/local/mutators/mutateActions.ts

@@ -23,8 +23,9 @@ type UpdatePatch<S extends Schema, K extends keyof S['models'] & string> =
 
 export interface MutateActions<S extends Schema, K extends keyof S['models'] & string> {
   /**
-   * Create one entity, or an array of entities in a single tick. ID,
-   * createdAt, updatedAt, organizationId default automatically per row.
+   * Create one entity, or an array of entities in a single tick. The id and
+   * the tenancy value default per row; every other column, audit timestamps
+   * included, comes from the declared fields.
    */
   create(data: InferCreate<S, K>): Promise<InferModel<S, K>>;
   create(data: InferCreate<S, K>[]): Promise<InferModel<S, K>[]>;

package/src/local/query/types.ts

@@ -22,8 +22,8 @@ export type {
   WhereOp,
   WhereClause,
   LoadWhere,
-} from '@abloatai/transaction/resources/where';
-import type { WhereClause } from '@abloatai/transaction/resources/where';
+} from '@abloatai/transaction/client/resources/where';
+import type { WhereClause } from '@abloatai/transaction/client/resources/where';
 import type { ModelListEvidence } from '@abloatai/transaction/wire';
 
 /** A single structured fetch request. */

package/src/local/stores/syncAction.ts

@@ -6,7 +6,7 @@
  */
 
 import { z } from 'zod';
-import { syncDeltaActionSchema } from '@abloatai/transaction/wire/delta';
+import { syncDeltaActionSchema } from '@abloatai/transaction/observation';
 
 export const syncActionSchema = z.object({
   id: z.number(),

package/src/local/sync/ConnectionManager.ts

@@ -12,4 +12,4 @@ export {
   type ConnectionEvent,
   type ConnectionCallbacks,
   type ConnectionManagerOptions,
-} from '@abloatai/transaction/transport/connectionManager';
+} from '@abloatai/transaction/transport/connection';

package/src/local/sync/OnDemandLoader.ts

@@ -38,7 +38,7 @@ import type { RuntimeContext } from '../RuntimeContext.js';
 import { postQuery } from '../query/client.js';
 import type { RecoveryClass } from '@abloatai/transaction/errorCodes';
 import type { LoadWhere, Query, WhereClause, WhereOp } from '../query/types.js';
-import { normalizeWhere } from '@abloatai/transaction/resources/where';
+import { normalizeWhere } from '@abloatai/transaction/client/resources/where';
 import type { Schema } from '@abloatai/transaction/schema/schema';
 import type { LogPositionPort } from '../logPosition.js';
 

package/src/local/sync/SyncWebSocket.ts

@@ -11,14 +11,14 @@
  */
 
 import { getContext } from '../context.js';
-import { clientSyncDeltaSchema, type ClientSyncDelta } from '@abloatai/transaction/wire/delta';
+import { clientSyncDeltaSchema, type ClientSyncDelta } from '@abloatai/transaction/observation';
 import { drainProfilingEnabled, observeDrainStage } from './drainProfile.js';
 import {
   WsTransport,
   type WsTransportOptions,
   type EventMap,
   type DefaultCollaborationEvents,
-} from '@abloatai/transaction/transport/wsTransport';
+} from '@abloatai/transaction/transport/websocket';
 import { isRecord } from './wsFrameHandlers.js';
 // Sync-position state (lastSyncId watermark, version vector, server cursor).
 import { SyncCursor } from './syncCursor.js';
@@ -41,7 +41,7 @@ export type {
   DefaultCollaborationEvents,
   EventMap,
   SyncWebSocketEventMap,
-} from '@abloatai/transaction/transport/wsTransport';
+} from '@abloatai/transaction/transport/websocket';
 
 /**
  * How often, while connected, the client polls for any deltas whose best-effort

package/src/local/sync/commitFrames.ts

@@ -8,9 +8,8 @@
 
 export {
   buildCommitFrame,
-  parseNotifications,
   recordClaim,
   type CommitAck,
   type CommitFrameOperation,
   type ClaimTracePorts,
-} from '@abloatai/transaction/transport/commitFrames';
+} from '@abloatai/transaction/transport/websocket';

package/src/local/sync/contextOnChange.ts

@@ -0,0 +1,92 @@
+import type { ReadDependency } from '@abloatai/transaction/coordination';
+import { AbloStaleContextError } from '@abloatai/transaction/errors';
+import type { InstanceCache } from '../InstanceCache.js';
+import type { SyncDelta } from './SyncWebSocket.js';
+
+export interface ContextOnChangeTransport {
+  subscribe(event: string, listener: (value?: unknown) => void): () => void;
+}
+
+/** Match context reads on the reactive client's existing delta connection. */
+export function contextOnChange(
+  transport: ContextOnChangeTransport,
+  pool: Pick<InstanceCache, 'peek' | 'watermarks'>,
+  reads: readonly ReadDependency[],
+  listener: (error: AbloStaleContextError) => void,
+): () => void {
+  let stopped = false;
+  const rowReads = reads.filter(
+    (read): read is Extract<ReadDependency, { model: string }> => 'model' in read,
+  );
+
+  const stopDelta = transport.subscribe('delta', (value) => {
+    if (isDelta(value)) changedBy([value]);
+  });
+  const stopBatch = transport.subscribe('delta_batch', (value) => {
+    if (Array.isArray(value)) changedBy(value.filter(isDelta));
+  });
+
+  function stop(): void {
+    if (stopped) return;
+    stopped = true;
+    stopDelta();
+    stopBatch();
+  }
+
+  function changedBy(deltas: readonly SyncDelta[]): void {
+    if (stopped) return;
+    for (const delta of deltas) {
+      const read = rowReads.find(
+        (candidate) =>
+          candidate.model.toLowerCase() === delta.modelName.toLowerCase() &&
+          candidate.id === delta.modelId &&
+          delta.id > candidate.readAt,
+      );
+      if (!read) continue;
+      stop();
+      listener(staleError(read.model, read.id, read.readAt, delta.id));
+      return;
+    }
+  }
+
+  // Subscribe first, then inspect the resident row. A delta that lands between
+  // the original read and this attachment is either observed above or has
+  // already advanced this exact row in the pool.
+  for (const read of rowReads) {
+    const resident = pool.peek(read.id);
+    if (!resident || resident.getModelName().toLowerCase() !== read.model.toLowerCase()) {
+      continue;
+    }
+    const observed = pool.watermarks.of(resident);
+    if (observed !== undefined && observed > read.readAt) {
+      stop();
+      listener(staleError(read.model, read.id, read.readAt, observed));
+      break;
+    }
+  }
+
+  return stop;
+}
+
+function staleError(
+  model: string,
+  id: string,
+  readAt: number,
+  observedSyncId: number,
+): AbloStaleContextError {
+  return new AbloStaleContextError('Context changed after read.', {
+    code: 'stale_context',
+    readAt,
+    conflicts: [{ model, id, observedSyncId }],
+  });
+}
+
+function isDelta(value: unknown): value is SyncDelta {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as { id?: unknown }).id === 'number' &&
+    typeof (value as { modelName?: unknown }).modelName === 'string' &&
+    typeof (value as { modelId?: unknown }).modelId === 'string'
+  );
+}