@abloatai/transaction 0.57.0 → 0.58.0

package/src/{wire/commit.ts → commit/contract.ts}

@@ -20,15 +20,8 @@
 import { z } from 'zod';
 import { logPositionSchema } from '../syncLog/contract.js';
 import {
-  onStaleModeSchema,
-  MAX_READ_SET_ENTRIES,
   readDependencyListSchema,
-  readSetRowTargetSchema,
-  readSetProjectionEntryCount,
-  readSetSchema,
   participantKindSchema,
-  staleNotificationSchema,
-  trackDependencyListSchema,
 } from '../coordination/schema.js';
 import type { ErrorCode } from '../errorCodes.js';
 import { requiredCapabilityWireSchema } from '../errors.js';
@@ -100,7 +93,6 @@ export const commitWaitSchema = z.union([queuedStatusSchema, confirmedStatusSche
 export type CommitWait = z.infer<typeof commitWaitSchema>;
 
 const missingIdsSchema = z.array(z.string().min(1));
-const notificationsSchema = z.array(staleNotificationSchema);
 
 export const commitOperationOutcomeSchema = z.enum([
   'created',
@@ -143,7 +135,12 @@ export type CommitAttempt = z.infer<typeof commitAttemptSchema>;
 
 export const commitClaimReferenceSchema = z.strictObject({
   id: z.string().min(1),
-  target: readSetRowTargetSchema,
+  target: z.strictObject({
+    scope: z.literal('row'),
+    model: z.string(),
+    id: z.string(),
+    fields: z.array(z.string()).readonly().optional(),
+  }),
   fenceToken: z.number().int().nonnegative(),
 });
 export type CommitClaimReference = z.infer<typeof commitClaimReferenceSchema>;
@@ -178,7 +175,6 @@ const successfulReceiptCommonShape = {
   success: z.literal(true),
   ops: z.number().int().nonnegative(),
   authority: effectiveAuthoritySchema,
-  notifications: notificationsSchema.optional(),
   missingIds: missingIdsSchema.optional(),
   /** Exact rows returned by the writing transaction; absent on durable replay. */
   operationResults: operationResultsSchema.optional(),
@@ -266,7 +262,6 @@ const executionEvidenceShape = {
     firstSyncId: z.number().int().nonnegative(),
     createdAt: commitTimestampSchema,
     confirmationTransactionIds: confirmationTransactionIdsSchema.optional(),
-    notifications: notificationsSchema.optional(),
     missingIds: missingIdsSchema.optional(),
 } as const;
 
@@ -341,7 +336,6 @@ export type CommitExecutionResultInput = z.input<typeof commitExecutionResultSch
 export type CommitExecutionResult = z.infer<typeof commitExecutionResultSchema>;
 
 const ackCommonShape = {
-  notifications: notificationsSchema.optional(),
   missingIds: missingIdsSchema.optional(),
   operationResults: operationResultsSchema.optional(),
 } as const;
@@ -376,7 +370,6 @@ export const clientCommitReceiptSchema = z.strictObject({
   id: z.string().min(1),
   status: z.union([queuedStatusSchema, confirmedStatusSchema]),
   lastSyncId: logPositionSchema.optional(),
-  notifications: notificationsSchema.optional(),
   missingIds: missingIdsSchema.optional(),
   operationResults: operationResultsSchema.optional(),
 });
@@ -401,7 +394,6 @@ export const commitOperationControlShape = {
   transactionId: z.string().nullish(),
   claimId: z.string().min(1).nullish(),
   readAt: logPositionSchema.nullish(),
-  onStale: onStaleModeSchema.nullish(),
   fenceToken: z.number().nullish(),
 };
 
@@ -442,7 +434,6 @@ export const commitReceiptEvidenceSchema = z.strictObject({
   clientTxId: z.string().min(1),
   serverTxId: z.string(),
   ops: z.number().int().nonnegative().optional(),
-  notifications: notificationsSchema.optional(),
   missingIds: missingIdsSchema.optional(),
   error: commitErrorSchema.optional(),
 });
@@ -451,18 +442,13 @@ export type CommitReceiptEvidence = z.infer<typeof commitReceiptEvidenceSchema>;
 /**
  * The `POST /v1/commits` request body.
  *
- * `operations` carries the writes; `track` registers durable premises.
- * Neither is required on its own, because a body with `track` and no
- * `operations` is how a caller starts watching a row without writing to it.
- * Request identity travels in the `Idempotency-Key` header.
+ * `operations` carries the writes and `reads` carries the compact row evidence
+ * those writes were based on. Request identity travels in the
+ * `Idempotency-Key` header.
  */
 export const commitRequestSchema = z.strictObject({
-  operations: z.array(commitOperationBodySchema).min(1).optional(),
+  operations: z.array(commitOperationBodySchema).min(1),
   reads: readDependencyListSchema.nullish(),
-  track: trackDependencyListSchema.nullish(),
-}).refine((value) => readSetProjectionEntryCount(value) <= MAX_READ_SET_ENTRIES, {
-  path: ['reads'],
-  message: `reads and track may contain at most ${MAX_READ_SET_ENTRIES} entries combined`,
 });
 export type CommitRequest = z.infer<typeof commitRequestSchema>;
 
@@ -474,7 +460,7 @@ const commitRecordEvidenceShape = {
     id: z.string().min(1),
     ...commitEvidenceShape,
     createdAt: commitTimestampSchema,
-    readSet: readSetSchema,
+    reads: readDependencyListSchema.readonly(),
     operations: z.array(commitRecordOperationSchema).readonly(),
     receipt: commitReceiptEvidenceSchema,
 } as const;

package/src/{durableWrites.ts → commit/durableWrites.ts}

@@ -2,18 +2,18 @@
  * The durable-write port and the option that installs it.
  *
  * Owns the persistence contract behind `Ablo({ durableWrites })` — a behavior
- * contract of methods, not a serialized shape, which is why it lives here
- * rather than in `transactions/confirmation/`. The records that cross this port
- * are owned by `pendingWriteSchema` there; this module never redescribes them.
+ * contract of methods, not a serialized shape, which is why it lives beside
+ * rather than inside `confirmation/`. The records that cross this port
+ * are owned by `confirmation/pendingWrite.ts`; this module never redescribes them.
  *
  * The engine consumes the port through `commitOutboxStore`, and the HTTP client
- * accepts the same option through `transport/httpOptions`.
+ * accepts the same option through `transport/http/options`.
  */
 
 import { z } from 'zod';
-import { AbloValidationError } from './errors.js';
-import type { CommitOutboxScope } from './transactions/confirmation/commitEnvelope.js';
-import type { PendingWrite } from './transactions/confirmation/pendingWrite.js';
+import { AbloValidationError } from '../errors.js';
+import type { CommitOutboxScope } from './confirmation/commitEnvelope.js';
+import type { PendingWrite } from './confirmation/pendingWrite.js';
 
 /**
  * Persistence port used by `Ablo({ durableWrites })`.

package/src/{transport/httpCommitRequest.ts → commit/httpRequest.ts}

@@ -12,12 +12,12 @@
  */
 
 import { AbloConnectionError, AbloValidationError } from '../errors.js';
-import type { BatchFence } from '../coordination/locator.js';
-import { claimIdFor, fenceTokenFor } from '../coordination/locator.js';
+import type { BatchFence } from '../claims/locator.js';
+import { claimIdFor, fenceTokenFor } from '../claims/locator.js';
 import type { Claim } from '../types/streams.js';
-import type { CommitCreateOptions, CommitOperationInput } from '../resources/httpResources.js';
-import type { CommitReceiptWire } from '../wire/commit.js';
-import type { DurableHttpCommitMethod } from '../transactions/confirmation/httpCommitEnvelope.js';
+import type { CommitCreateOptions, CommitOperationInput } from '../client/resources/httpResources.js';
+import type { CommitReceiptWire } from './contract.js';
+import type { DurableHttpCommitMethod } from './confirmation/httpCommitEnvelope.js';
 
 /**
  * One commit, exactly as it will be sent and re-sent. A replay that changed any
@@ -45,7 +45,7 @@ export function createClientTxId(idempotencyKey?: string | null): string {
 /** One operation with the batch's defaults resolved onto it. */
 export function normalizeCommitOperation(
   op: CommitOperationInput,
-  defaults: Pick<CommitCreateOptions, 'readAt' | 'onStale'>,
+  defaults: Pick<CommitCreateOptions, 'readAt'>,
   fence: BatchFence | null,
   claim: Claim | null,
 ): CommitOperationInput {
@@ -58,7 +58,6 @@ export function normalizeCommitOperation(
     transactionId: op.transactionId ?? null,
     claimId: op.claimId ?? claimIdFor(claim?.target, claim?.id, op.model, op.id ?? null),
     readAt: op.readAt ?? defaults.readAt ?? null,
-    onStale: op.onStale ?? defaults.onStale ?? null,
     fenceToken: op.fenceToken ?? fenceTokenFor(fence, op.model, op.id ?? null),
   };
 }

package/src/commit/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Commit subsystem.
+ *
+ * Start here and descend through the lifecycle contract, durable confirmation
+ * records, persistence port, request normalization, and runtime observation.
+ * Transport mechanisms consume this boundary; they do not own commit meaning.
+ */
+export * from './contract.js';
+export * from './durableWrites.js';
+export * from './httpRequest.js';
+export * from './recordRuntime.js';
+export * from './readSetContext.js';
+export * from './confirmation/commitEnvelope.js';
+export * from './confirmation/httpCommitEnvelope.js';
+export * from './confirmation/idempotencyKey.js';
+export * from './confirmation/pendingWrite.js';

package/src/{readSetContext.ts → commit/readSetContext.ts}

@@ -5,14 +5,9 @@
  * but this is not an execution context: it has no async carrier and no ambient
  * scope. Evidence is keyed only by the exact object returned to the caller.
  */
-import {
-  readDependencySchema,
-  type CommitReadSetEntry,
-  type OnStaleMode,
-  type ReadDependency,
-} from './coordination/schema.js';
-import { AbloValidationError } from './errors.js';
-import type { CommitRecord } from './wire/commit.js';
+import { readDependencySchema, type ReadDependency } from '../coordination/schema.js';
+import { AbloValidationError, type AbloStaleContextError } from '../errors.js';
+import type { CommitRecord } from './contract.js';
 
 type ClientIdentity = object;
 
@@ -22,7 +17,7 @@ export const kReadEvidence = Symbol.for('ablo.transaction.read-evidence');
 /** @internal One exact returned-row assertion. */
 export interface CapturedReadEvidence {
   readonly client: ClientIdentity;
-  readonly entry: CommitReadSetEntry;
+  readonly entry: ReadDependency;
   readonly row: object;
 }
 
@@ -42,6 +37,11 @@ export interface ReadSetContext {
 export interface ReadEvidenceBinding {
   readonly context: ReadSetContext;
   readonly client: ClientIdentity;
+  /** @internal Transport-owned live check for the same exact reads. */
+  readonly onChange?: (
+    reads: readonly ReadDependency[],
+    listener: (error: AbloStaleContextError) => void,
+  ) => () => void;
 }
 
 /** @internal Reads the private evidence binding without occupying a model name. */
@@ -68,10 +68,7 @@ export function evidenceForRow(
 
 export interface PreparedReadSet {
   readonly readAt?: number;
-  readonly onStale?: OnStaleMode;
   readonly reads?: readonly ReadDependency[] | null;
-  readonly consumed: readonly CapturedReadEvidence[];
-  readonly automaticCommit: false;
   readonly idempotencyKey?: string;
 }
 
@@ -124,10 +121,9 @@ export function capturePointRead(
     client,
     row: rowObject,
     entry: {
-      target: { scope: 'row', model, id },
-      watermark: readAt,
-      lifetime: 'commit',
-      onStale: 'reject',
+      model,
+      id,
+      readAt,
     },
   });
 }
@@ -137,12 +133,10 @@ export function prepareReadSet(
   context: ReadSetContext | undefined,
   client: ClientIdentity,
   explicitReadAt: number | null | undefined,
-  explicitOnStale: OnStaleMode | null | undefined,
   explicitIdempotencyKey: string | null | undefined,
   reads: readonly unknown[] | null | undefined,
 ): PreparedReadSet {
   const registry = context?.getStore();
-  const consumed: CapturedReadEvidence[] = [];
   const resolvedReads: ReadDependency[] = [];
 
   for (const entry of reads ?? []) {
@@ -151,18 +145,16 @@ export function prepareReadSet(
         ? registry.byRow.get(entry)
         : undefined;
     if (captured?.client === client) {
-      const target = captured.entry.target;
-      if (target.scope !== 'row') {
+      if ('group' in captured.entry) {
         throw new AbloValidationError('Captured read evidence must name a row.', {
           code: 'write_options_invalid', param: 'reads',
         });
       }
       resolvedReads.push({
-        model: target.model,
-        id: target.id,
-        readAt: captured.entry.watermark,
+        model: captured.entry.model,
+        id: captured.entry.id,
+        readAt: captured.entry.readAt,
       });
-      consumed.push(captured);
       continue;
     }
     const canonical = readDependencySchema.safeParse(entry);
@@ -178,24 +170,7 @@ export function prepareReadSet(
 
   return {
     ...(explicitReadAt != null ? { readAt: explicitReadAt } : {}),
-    ...(explicitOnStale != null ? { onStale: explicitOnStale } : {}),
     ...(reads !== undefined ? { reads: reads === null ? null : resolvedReads } : {}),
-    consumed,
-    automaticCommit: false,
     ...(explicitIdempotencyKey != null ? { idempotencyKey: explicitIdempotencyKey } : {}),
   };
 }
-
-/** @internal Commit identity is the explicit request idempotency identity. */
-export function commitRecordIdentity(
-  _context: ReadSetContext | undefined,
-  attemptId: string,
-): { readonly id: string } {
-  return { id: attemptId };
-}
-
-/** @internal Explicit row evidence is reusable; successful writes do not consume it. */
-export function consumeReadSet(..._args: readonly unknown[]): void {}
-
-/** @internal There is no ambient automatic-commit reservation to release. */
-export function abortReadSetCommit(..._args: readonly unknown[]): void {}

package/src/{commitRecordRuntime.ts → commit/recordRuntime.ts}

@@ -1,12 +1,5 @@
+import type { ReadDependency } from '../coordination/schema.js';
 import {
-  DEFAULT_TRACK_ON_STALE,
-  type CommitReadSetEntry,
-  type ReadDependency,
-  type ReadSetEntry,
-  type TrackDependency,
-} from './coordination/schema.js';
-import {
-  commitRecordIdentity,
   publishCommitRecord,
   type ReadSetContext,
 } from './readSetContext.js';
@@ -14,7 +7,7 @@ import {
   commitRecordSchema,
   type CommitOperationBody,
   type CommitReceiptWire,
-} from './wire/commit.js';
+} from './contract.js';
 
 interface HttpCommitObservation {
   readonly receipt: CommitReceiptWire;
@@ -32,41 +25,9 @@ interface WebSocketCommitObservation {
     readonly input?: Record<string, unknown>;
     readonly claimId?: string | null;
     readonly readAt?: number | null;
-    readonly onStale?: CommitOperationBody['onStale'] | null;
     readonly fenceToken?: number | null;
   }[];
   readonly reads?: readonly ReadDependency[] | null;
-  readonly track?: readonly TrackDependency[] | null;
-}
-
-function commitEntry(dependency: ReadDependency): CommitReadSetEntry {
-  return {
-    target: 'group' in dependency
-      ? { scope: 'group', group: dependency.group }
-      : {
-          scope: 'row',
-          model: dependency.model,
-          id: dependency.id,
-          ...(dependency.fields ? { fields: dependency.fields } : {}),
-        },
-    watermark: dependency.readAt,
-    lifetime: 'commit',
-    onStale: dependency.onStale ?? 'reject',
-  };
-}
-
-function persistedEntry(
-  dependency: TrackDependency,
-  defaultWatermark: number,
-): ReadSetEntry {
-  return {
-    target: 'group' in dependency
-      ? { scope: 'group', group: dependency.group }
-      : { scope: 'row', model: dependency.model, id: dependency.id },
-    watermark: dependency.readAt ?? defaultWatermark,
-    lifetime: 'persisted',
-    onStale: dependency.onStale ?? DEFAULT_TRACK_ON_STALE,
-  };
 }
 
 function bodyRecord(value: unknown): Record<string, unknown> {
@@ -126,9 +87,6 @@ function operationFromModelRequest(
       ? { data: body.data as Record<string, unknown> }
       : {}),
     ...(typeof body.readAt === 'number' ? { readAt: body.readAt } : {}),
-    ...(typeof body.onStale === 'string'
-      ? { onStale: body.onStale as CommitOperationBody['onStale'] }
-      : {}),
     ...(typeof body.fenceToken === 'number' ? { fenceToken: body.fenceToken } : {}),
     ...(typeof body.claim === 'string' ? { claimId: body.claim } : {}),
   }];
@@ -145,21 +103,18 @@ export function recordHttpCommitReceipt(
     ? body.operations as CommitOperationBody[]
     : operationFromModelRequest(observation, body);
   const reads = Array.isArray(body.reads) ? body.reads as ReadDependency[] : [];
-  const track = Array.isArray(body.track) ? body.track as TrackDependency[] : [];
-  const readSet: ReadSetEntry[] = reads.map(commitEntry);
+  const retainedReads: ReadDependency[] = [...reads];
   for (const operation of operations) {
     if (typeof operation.readAt !== 'number' || !operation.id) continue;
-    readSet.push(commitEntry({
+    retainedReads.push({
       model: operation.model,
       id: operation.id,
       readAt: operation.readAt,
-      onStale: operation.onStale ?? 'reject',
-    }));
+    });
   }
-  readSet.push(...track.map((entry) => persistedEntry(entry, observation.receipt.lastSyncId)));
 
   const record = commitRecordSchema.parse({
-    id: commitRecordIdentity(context, observation.receipt.clientTxId).id,
+    id: observation.receipt.clientTxId,
     createdAt: observation.receipt.createdAt,
     status: observation.receipt.status,
     statusAt: observation.receipt.statusAt,
@@ -167,7 +122,7 @@ export function recordHttpCommitReceipt(
     ...(observation.receipt.correlationId
       ? { correlationId: observation.receipt.correlationId }
       : {}),
-    readSet,
+    reads: retainedReads,
     operations: retainedOperations(operations),
     ...commitEvidence(observation.receipt, operations, 'http'),
     authority: observation.receipt.authority,
@@ -175,9 +130,6 @@ export function recordHttpCommitReceipt(
       clientTxId: observation.receipt.clientTxId,
       serverTxId: observation.receipt.serverTxId,
       ops: observation.receipt.ops,
-      ...(observation.receipt.notifications
-        ? { notifications: observation.receipt.notifications }
-        : {}),
       ...(observation.receipt.missingIds
         ? { missingIds: observation.receipt.missingIds }
         : {}),
@@ -199,25 +151,21 @@ export function recordWebSocketCommitReceipt(
     ...(operation.input ? { data: operation.input } : {}),
     ...(operation.claimId ? { claimId: operation.claimId } : {}),
     ...(typeof operation.readAt === 'number' ? { readAt: operation.readAt } : {}),
-    ...(operation.onStale ? { onStale: operation.onStale } : {}),
     ...(typeof operation.fenceToken === 'number'
       ? { fenceToken: operation.fenceToken }
       : {}),
   }));
-  const readSet: ReadSetEntry[] = (observation.reads ?? []).map(commitEntry);
+  const retainedReads: ReadDependency[] = [...(observation.reads ?? [])];
   for (const operation of operations) {
     if (typeof operation.readAt !== 'number' || !operation.id) continue;
-    readSet.push(commitEntry({
+    retainedReads.push({
       model: operation.model,
       id: operation.id,
       readAt: operation.readAt,
-      onStale: operation.onStale ?? 'reject',
-    }));
+    });
   }
-  readSet.push(...(observation.track ?? []).map((entry) =>
-    persistedEntry(entry, observation.receipt.lastSyncId)));
   const record = commitRecordSchema.parse({
-    id: commitRecordIdentity(context, observation.receipt.clientTxId).id,
+    id: observation.receipt.clientTxId,
     createdAt: observation.receipt.createdAt,
     status: observation.receipt.status,
     statusAt: observation.receipt.statusAt,
@@ -225,7 +173,7 @@ export function recordWebSocketCommitReceipt(
     ...(observation.receipt.correlationId
       ? { correlationId: observation.receipt.correlationId }
       : {}),
-    readSet,
+    reads: retainedReads,
     operations: retainedOperations(operations),
     ...commitEvidence(observation.receipt, operations, 'websocket'),
     authority: observation.receipt.authority,
@@ -233,9 +181,6 @@ export function recordWebSocketCommitReceipt(
       clientTxId: observation.receipt.clientTxId,
       serverTxId: observation.receipt.serverTxId,
       ops: observation.receipt.ops,
-      ...(observation.receipt.notifications
-        ? { notifications: observation.receipt.notifications }
-        : {}),
       ...(observation.receipt.missingIds
         ? { missingIds: observation.receipt.missingIds }
         : {}),

package/src/coordination/index.ts

@@ -21,28 +21,11 @@ export {
   DEFAULT_CLAIM_DESCRIPTION,
   targetRefSchema,
   // Layer 3 — optimistic stale-context
-  onStaleModeSchema,
   MAX_READ_SET_ENTRIES,
-  readSetRowTargetSchema,
-  readSetGroupTargetSchema,
-  commitReadSetTargetSchema,
-  persistedReadSetRowTargetSchema,
-  persistedReadSetTargetSchema,
-  commitReadSetEntrySchema,
-  persistedReadSetEntrySchema,
-  readSetEntrySchema,
-  readSetSchema,
   writeGuardSchema,
-  staleNotificationSchema,
-  rowStaleNotificationSchema,
-  groupStaleNotificationSchema,
-  stalePropagationSchema,
 
   readDependencySchema,
   readDependencyListSchema,
-  readSetProjectionEntryCount,
-  trackDependencySchema,
-  trackDependencyListSchema,
   // Layer 2 — pessimistic claim / claim-lease
   claimStatusSchema,
   wireClaimStatusSchema,
@@ -92,45 +75,14 @@ export {
   presenceUpdateFrameSchema,
 } from './schema.js';
 
-// Conflict-policy runtime — the engine detects a conflict, and the policy
-// decides what to do about it. These are re-exported here so that server-side
-// code can reach both the coordination vocabulary and its default conflict
-// resolution from this one subpath, without importing the full client from the
-// package root.
-export { defaultPolicy, capabilityPreemptPolicy, interpretConflictAxis } from '../policy/types.js';
-export type {
-  Conflict,
-  ConflictAxis,
-  ConflictDecision,
-  ConflictKind,
-  ConflictOperation,
-  ConflictPolicy,
-  StaleContextConflict,
-  ClaimHeldConflict,
-} from '../policy/types.js';
-
 // Inferred types, one per schema (plus the standalone aliases).
 export type {
   // Shared primitives
   ParticipantKind,
   TargetRef,
   // Layer 3 — optimistic stale-context
-  OnStaleMode,
-  ReadSetRowTarget,
-  ReadSetGroupTarget,
-  CommitReadSetTarget,
-  PersistedReadSetTarget,
-  CommitReadSetEntry,
-  PersistedReadSetEntry,
-  ReadSetEntry,
-  ReadSet,
   WriteGuard,
-  StaleNotification,
-  RowStaleNotification,
-  GroupStaleNotification,
-  StalePropagation,
   ReadDependency,
-  TrackDependency,
   // Layer 2 — pessimistic claim / claim-lease
   ClaimStatus,
   WireClaimStatus,
@@ -182,12 +134,12 @@ export type {
   ClaimCounterparty,
   ConflictEvent,
   CoordinationObserver,
-} from './events.js';
+} from '../claims/events.js';
 
 // The conflict rule itself — whether two claims on one row collide. It is the
 // protocol's decision, not the server's deployment of it, so it lives here and
 // every claim authority imports it.
-export { targetsConflict } from './targetConflict.js';
+export { targetsConflict } from '../claims/targetConflict.js';
 
 // The locator itself — what a claim points at, and the projections that keep
 // its three entity spellings (`entityType`/`entityId`, `model`/`id`,
@@ -197,7 +149,7 @@ export type {
   ClaimTargetDetails,
   ClaimTargetSource,
   EntityLocator,
-} from './locator.js';
+} from '../claims/locator.js';
 export {
   batchFence,
   claimIdFor,
@@ -207,4 +159,4 @@ export {
   wireTarget,
   modelTarget,
   streamTarget,
-} from './locator.js';
+} from '../claims/locator.js';