@abloatai/transaction 0.56.0 → 0.58.0

package/src/commit/httpRequest.ts

@@ -0,0 +1,103 @@
+/**
+ * The HTTP commit as a VALUE: what it is keyed by, the operations it carries,
+ * the exact bytes it is replayed as, and the error when its echo never lands.
+ *
+ * None of this touches the transport's state. It was written inside
+ * `createHttpTransport` because that is where it was first needed, which made a
+ * two-thousand-line closure the only place the shape of a commit was stated.
+ * Read together here, the four say one thing: a commit is identified by its
+ * idempotency key, normalized once so every operation carries the same
+ * defaults, replayed byte for byte, and abandoned only when the source accepted
+ * it and the replication echo did not arrive.
+ */
+
+import { AbloConnectionError, AbloValidationError } from '../errors.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 '../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
+ * of these would be a different request wearing the same idempotency key.
+ */
+export interface ExactHttpCommitRequest {
+  readonly idempotencyKey: string;
+  readonly method: DurableHttpCommitMethod;
+  readonly path: string;
+  readonly body: string;
+  readonly sealedProtocolVersion?: number;
+}
+
+/**
+ * The key a commit is replayed under. A caller's idempotency key wins, because
+ * it is the caller's statement that two attempts are the same write.
+ */
+export function createClientTxId(idempotencyKey?: string | null): string {
+  if (idempotencyKey && idempotencyKey.length > 0) return idempotencyKey;
+  return typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
+    ? crypto.randomUUID()
+    : `tx_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+/** One operation with the batch's defaults resolved onto it. */
+export function normalizeCommitOperation(
+  op: CommitOperationInput,
+  defaults: Pick<CommitCreateOptions, 'readAt'>,
+  fence: BatchFence | null,
+  claim: Claim | null,
+): CommitOperationInput {
+  return {
+    action: op.action,
+    model: op.model,
+    id: op.id ?? null,
+    data: op.data ?? null,
+    where: op.where ?? null,
+    transactionId: op.transactionId ?? null,
+    claimId: op.claimId ?? claimIdFor(claim?.target, claim?.id, op.model, op.id ?? null),
+    readAt: op.readAt ?? defaults.readAt ?? null,
+    fenceToken: op.fenceToken ?? fenceTokenFor(fence, op.model, op.id ?? null),
+  };
+}
+
+/** Every operation in a batch, normalized against the batch's own options. */
+export function normalizeCommitOperations(
+  commitOptions: CommitCreateOptions,
+  fence: BatchFence | null,
+): readonly CommitOperationInput[] {
+  if (commitOptions.operations.length === 0) {
+    throw new AbloValidationError('Commit requires a non-empty `operations` array.', {
+      code: 'commit_operation_required',
+    });
+  }
+  return commitOptions.operations.map((op) =>
+    normalizeCommitOperation(op, commitOptions, fence, commitOptions.claim ?? null),
+  );
+}
+
+/**
+ * The source accepted the write and its replication echo did not arrive in
+ * time. `accepted: true` is the load-bearing detail: the row may well be
+ * written, so this is a confirmation timeout and never a reason to write again.
+ */
+export function replicationLagTimeout(
+  request: ExactHttpCommitRequest,
+  response: CommitReceiptWire,
+  requestTimeoutMs: number,
+): AbloConnectionError {
+  return new AbloConnectionError(
+    `The source accepted commit ${request.idempotencyKey}, but its replication echo did not arrive within ${requestTimeoutMs}ms.`,
+    {
+      code: 'replication_lag_timeout',
+      httpStatus: 504,
+      details: {
+        clientTxId: request.idempotencyKey,
+        ...(response.correlationId ? { correlationId: response.correlationId } : {}),
+        timeoutMs: requestTimeoutMs,
+        accepted: true,
+      },
+    },
+  );
+}

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;
 }
 
@@ -97,9 +94,15 @@ export function publishCommitRecord(
   registry.commitRecords.set(record.id, record);
   try {
     const observed = registry.onCommitRecord?.(record);
-    if (observed) void Promise.resolve(observed).catch(() => undefined);
-  } catch {
+    if (observed) {
+      void Promise.resolve(observed).catch((error) => {
+        // The observer is outside the transaction outcome by contract.
+        void error;
+      });
+    }
+  } catch (error) {
     // Observability must never change a commit's outcome.
+    void error;
   }
 }
 
@@ -118,10 +121,9 @@ export function capturePointRead(
     client,
     row: rowObject,
     entry: {
-      target: { scope: 'row', model, id },
-      watermark: readAt,
-      lifetime: 'commit',
-      onStale: 'reject',
+      model,
+      id,
+      readAt,
     },
   });
 }
@@ -131,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 ?? []) {
@@ -145,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);
@@ -172,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,29 +21,11 @@ export {
   DEFAULT_CLAIM_DESCRIPTION,
   targetRefSchema,
   // Layer 3 — optimistic stale-context
-  onStaleModeSchema,
-  readSetWatermarkSchema,
   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,
@@ -93,46 +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,
-  ReadSetWatermark,
-  ReadSetRowTarget,
-  ReadSetGroupTarget,
-  CommitReadSetTarget,
-  PersistedReadSetTarget,
-  CommitReadSetEntry,
-  PersistedReadSetEntry,
-  ReadSetEntry,
-  ReadSet,
   WriteGuard,
-  StaleNotification,
-  RowStaleNotification,
-  GroupStaleNotification,
-  StalePropagation,
   ReadDependency,
-  TrackDependency,
   // Layer 2 — pessimistic claim / claim-lease
   ClaimStatus,
   WireClaimStatus,
@@ -184,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`,
@@ -199,7 +149,7 @@ export type {
   ClaimTargetDetails,
   ClaimTargetSource,
   EntityLocator,
-} from './locator.js';
+} from '../claims/locator.js';
 export {
   batchFence,
   claimIdFor,
@@ -209,4 +159,4 @@ export {
   wireTarget,
   modelTarget,
   streamTarget,
-} from './locator.js';
+} from '../claims/locator.js';