@abloatai/transaction 0.55.0 → 0.57.0

package/src/source/types.ts

@@ -80,8 +80,9 @@ export type SourceListResult<Row> =
  * see. Ablo attaches this so your `authorize` and model handlers can reject
  * calls that fall outside the participant's permitted sync groups.
  *
- * It is advisory. Because the canonical data lives in your database, your
- * handlers are the only place that can actually enforce these limits.
+ * The ORM adapters enforce schema-declared subject rules from this trusted
+ * scope. Custom handlers receive the same signed facts; Ablo also checks their
+ * returned rows and preflights writes before forwarding the customer transaction.
  */
 export interface SourceRequestContext {
   readonly participantId?: string;
@@ -91,6 +92,14 @@ export interface SourceRequestContext {
   readonly branchId?: string;
   /** Trusted project selected by the authenticating credential. */
   readonly projectId?: string;
+  readonly syncGroups?: readonly string[];
+  /**
+   * @deprecated Renamed to {@link SourceRequestContext.syncGroups}. Removed in
+   * 0.58.0. Ablo populates both spellings with the same value for this release,
+   * so an adapter still reading this one gets the groups rather than
+   * `undefined`, which on a routing field would read as "no groups" rather than
+   * as a missing field.
+   */
   readonly requiredSyncGroups?: readonly string[];
 }
 
@@ -122,6 +131,8 @@ export interface SourceDelta {
   readonly type: SourceOperation['type'];
   /** The changed row, in the key shape {@link SourceEvent.data} defines. */
   readonly data?: Record<string, unknown> | null;
+  /** Exact record routes derived inside the write transaction. */
+  readonly syncGroups?: readonly string[];
   readonly transactionId?: string | null;
 }
 
@@ -162,6 +173,8 @@ export interface SourceEvent {
    * a tenant boundary.
    */
   readonly data?: Record<string, unknown> | null;
+  /** Exact record routes captured while the changed row was transactionally visible. */
+  readonly syncGroups: readonly string[];
   /**
    * The tenant this event belongs to. Populate it from the row's organization
    * column for multi-tenant data; a single-tenant source may omit it and let
@@ -206,6 +219,8 @@ export interface SourceEventForOperationOptions {
    * valid but leaves less for clients to hydrate from in realtime.
    */
   readonly data?: Record<string, unknown> | null;
+  /** Exact record routes derived inside the write transaction. */
+  readonly syncGroups: readonly string[];
   /**
    * @deprecated Legacy echo identity. Prefer the explicit correlation fields.
    */
@@ -243,6 +258,7 @@ export function sourceEventForOperation(
     entityId,
     type: options.operation.type,
     ...(options.data !== undefined ? { data: options.data } : {}),
+    syncGroups: options.syncGroups,
     ...(options.organizationId ? { organizationId: options.organizationId } : {}),
     ...(options.clientTxId ? { clientTxId: options.clientTxId } : {}),
     ...(options.correlationId ? { correlationId: options.correlationId } : {}),
@@ -423,6 +439,18 @@ export interface SourceModelHandlers<Row, CreateInput, TAuth = unknown> {
     | Promise<SourceListResult<Row>>
     | SourceListResult<Row>;
 
+  /**
+   * Subject-aware list boundary. The handler MUST apply `subject.values` in
+   * its database predicate before ordering, cursoring, or limiting. A model
+   * declaring `subject` is served only through this hook; plain `list()` is
+   * deliberately not accepted because post-page filtering is incomplete.
+   */
+  subjectList?(params: {
+    readonly query: SourceListQuery;
+    readonly subject: { readonly field: string; readonly values: readonly string[] };
+    readonly context: SourceHandlerContext<TAuth>;
+  }): Promise<SourceListResult<Row>> | SourceListResult<Row>;
+
   /**
    * Apply one or more operations for this model within your own database
    * transaction. Your handler must be idempotent on the scoped server
@@ -446,6 +474,32 @@ export type SourceCommitHandler<TAuth = unknown> = (
   params: SourceCommitParams<TAuth>,
 ) => Promise<SourceCommitResult> | SourceCommitResult;
 
+export interface SourceSubjectTransactionBoundary {
+  /**
+   * Serialize a caller-selected CREATE id even when no row exists yet. This
+   * must be an absent-key-capable transaction lock (for example a Postgres
+   * transaction advisory lock), acquired on the SAME transaction as load and
+   * commit. It coordinates framework writers; `commit` must still reject a
+   * database uniqueness conflict as `entity_already_exists`, because external
+   * writers do not participate in advisory locking.
+   */
+  readonly lockCreate: (operation: SourceOperation) => Promise<void>;
+  /** Lock and return the current row on the SAME transaction used by commit. */
+  readonly load: (operation: SourceOperation) => Promise<Record<string, unknown> | null>;
+  /** Apply the complete batch on that transaction after authorization succeeds. */
+  readonly commit: () => Promise<SourceCommitResult>;
+}
+
+/**
+ * Transaction owner for hand-written subject-scoped commits. Open one database
+ * transaction, then call `run` with load/commit functions bound to it. `run`
+ * performs authorization first and invokes commit only after it succeeds.
+ */
+export type SourceSubjectTransactionHandler<TAuth = unknown> = (
+  params: SourceCommitParams<TAuth>,
+  run: (boundary: SourceSubjectTransactionBoundary) => Promise<SourceCommitResult>,
+) => Promise<SourceCommitResult>;
+
 export type SourceApiKey =
   | string
   | ((context: SourceAuthorizeContext) => Promise<string> | string);

package/src/syncLog/contract.ts

@@ -1,9 +1,51 @@
-/** Canonical sync-log identity and position contracts shared by client/server. */
+/**
+ * Canonical sync-log identity and position contracts shared by client/server.
+ *
+ * ## A log position means ONE thing
+ *
+ * It is an ordinal in `sync_deltas`: a point in the single, totally ordered
+ * log. Nothing else. Every number in this engine that answers "how far along"
+ * is this type, and there is one definition of it, below.
+ *
+ * What varies is never the meaning. It is **who is making the claim**, and the
+ * owner belongs in the field name, never in a second type:
+ *
+ * | Owner                              | Claims                                    |
+ * | ---------------------------------- | ----------------------------------------- |
+ * | `current_settled_sync_id()`        | nothing at or below is still in flight    |
+ * | `getCommittedSyncId`               | committed, without waiting for the barrier|
+ * | `sync_broadcast_cursors.published_through` | the fan-out published through     |
+ * | `Client.lastSentSyncId`            | this recipient was offered through        |
+ * | `Client.lastAckedSyncId`           | this recipient confirmed through          |
+ * | `LogPosition.applied`              | the client processed on arrival through   |
+ * | `LogPosition.persisted`            | the client durably holds through, in
+ *                                        DELIVERED order, not numeric order       |
+ * | `RowWatermarks`                    | this one row reflects the log through     |
+ * | `sync_state_checkpoint.up_to_sync_id` | the checkpoint folded through          |
+ *
+ * ## The comparison that is not safe
+ *
+ * `current_settled_sync_id` takes a per-plane advisory lock but reads the
+ * GLOBAL sequence, so its value moves for writers in other planes. Every other
+ * owner above is scoped: to a plane, a project, a recipient, or a row. "The
+ * head of the log" and "how far I have been served" are therefore different
+ * questions, and a scoped cursor sitting below the global head is the normal
+ * resting state, not a gap.
+ *
+ * Treating one as the other is what left every client permanently short of its
+ * own head, re-taking the plane lock on every catch-up poll
+ * (docs/plans/delivery-verify-at-read.md). Before comparing two positions, say
+ * out loud which owner each belongs to.
+ */
 
 import { z } from 'zod';
 
-export const deltaPositionSchema = z.number().int().nonnegative();
-export type DeltaPosition = z.infer<typeof deltaPositionSchema>;
+/**
+ * A point in the sync log. The one definition; every other position name in
+ * the codebase derives from this one rather than restating the primitive.
+ */
+export const logPositionSchema = z.number().int().nonnegative();
+export type LogPosition = z.infer<typeof logPositionSchema>;
 
 export const clientMutationIdSchema = z.string().min(1).max(255);
 export type ClientMutationId = z.infer<typeof clientMutationIdSchema>;
@@ -21,8 +63,8 @@ export const commitDispatchMarkerSchema = z.strictObject({
   kind: z.literal('sync_deltas'),
   organizationId: z.string().min(1),
   branchId: z.string().min(1),
-  firstSyncId: deltaPositionSchema,
-  lastSyncId: deltaPositionSchema,
+  firstSyncId: logPositionSchema,
+  lastSyncId: logPositionSchema,
 }).superRefine((value, ctx) => {
   if (value.firstSyncId <= 0 || value.lastSyncId < value.firstSyncId) {
     ctx.addIssue({ code: 'custom', message: 'invalid delta position range' });

package/src/testing/fixtures/httpResponses.ts

@@ -53,6 +53,12 @@ export function confirmedCommitReceiptResponse(args: {
   lastSyncId?: number;
   serverTxId?: string;
   ops?: number;
+  /** The exact rows the writing transaction returned, one per operation. */
+  operationResults?: {
+    transactionId: string;
+    outcome: 'created' | 'updated' | 'deleted' | 'archived' | 'unarchived';
+    row: Record<string, unknown>;
+  }[];
 }): CommitReceiptWire {
   const lastSyncId = args.lastSyncId ?? 0;
   return {
@@ -65,6 +71,7 @@ export function confirmedCommitReceiptResponse(args: {
     status: 'confirmed',
     lastSyncId,
     ops: args.ops ?? 1,
+    ...(args.operationResults ? { operationResults: args.operationResults } : {}),
   } satisfies CommitReceiptWire;
 }
 

package/src/transport/httpClient.ts

@@ -37,11 +37,14 @@ import type {
   AbloSession,
   SessionResource,
 } from '../resources/httpResources.js';
-import { modelList } from '../resources/httpResources.js';
+import { collectModelList, modelList } from '../resources/httpResources.js';
+import { resolveCreateId } from '../resources/modelCreate.js';
 import type {
   ModelCreateParams,
+  ModelCreateManyParams,
   ModelDeleteParams,
   ServerReadOptions,
+  ListAllOptions,
   ModelRetrieveParams,
   ModelTrackParams,
   ModelTrackResult,
@@ -136,6 +139,8 @@ export interface HttpModelClient<T, C = T> {
    * back as `cursor`, with the same `where` and `orderBy`, to walk it.
    */
   list(options?: ServerReadOptions<T>): Promise<ModelList<CapturedRow<T>>>;
+  /** Reads every matching row, following cursors with a bounded traversal. */
+  listAll(options?: ListAllOptions<T>): Promise<CapturedRow<T>[]>;
   /**
    * Creates a row and returns it, including any framework-applied defaults.
    * Passing an id that already exists is idempotent: the existing row is
@@ -148,6 +153,11 @@ export interface HttpModelClient<T, C = T> {
    * of `update` and `delete`.
    */
   create(params: HttpModelMutationParams<ModelCreateParams<T, C>>): Promise<T>;
+  /**
+   * Creates many rows as one atomic commit, and resolves to them in the order
+   * they were given. One rejected row declines the batch.
+   */
+  create(params: HttpModelMutationParams<ModelCreateManyParams<C>>): Promise<T[]>;
   update(params: HttpModelMutationParams<ModelUpdateParams<T, C>>): Promise<T>;
   /**
    * Updates a row with a function of its latest value — `update(id, current =>
@@ -434,6 +444,65 @@ function createHttpModelClient<T, C = T>(
     return read.data as CapturedRow<T> | undefined;
   };
 
+  // `create` is overloaded: one row, or a list of them as one atomic commit.
+  // A real overloaded function rather than a property arrow, so both public
+  // signatures survive — the same reason `updateModel` is written this way.
+  function createModel(
+    params: HttpModelMutationParams<ModelCreateParams<T, C>>,
+  ): Promise<CapturedRow<T>>;
+  function createModel(
+    params: HttpModelMutationParams<ModelCreateManyParams<C>>,
+  ): Promise<CapturedRow<T>[]>;
+  async function createModel(
+    params:
+      | HttpModelMutationParams<ModelCreateParams<T, C>>
+      | HttpModelMutationParams<ModelCreateManyParams<C>>,
+  ): Promise<CapturedRow<T> | CapturedRow<T>[]> {
+    const prepared = preparedMutation(params);
+    try {
+      // The list form is one atomic commit through the protocol's batch door.
+      // Same verb because it is the same act; the argument says how many.
+      if (Array.isArray(params.data)) {
+        const rows = await protocol.createMany({
+          data: params.data as readonly Record<string, unknown>[],
+          ...(prepared.options.idempotencyKey
+            ? { idempotencyKey: prepared.options.idempotencyKey }
+            : {}),
+          ...(prepared.options.reads
+            ? { reads: [...prepared.options.reads] }
+            : {}),
+          ...(prepared.options.track
+            ? { track: [...prepared.options.track] }
+            : {}),
+        });
+        consumeReadSet(
+          readSetContext,
+          clientIdentity,
+          prepared.consumed,
+          prepared.automaticCommit,
+        );
+        return rows as CapturedRow<T>[];
+      }
+      const single = params as HttpModelMutationParams<ModelCreateParams<T, C>>;
+      const resolvedId = resolveCreateId(single.id, single.data);
+      const row = await protocol.create({
+        ...prepared.options,
+        ...(resolvedId !== undefined ? { id: resolvedId } : {}),
+        data: single.data as Record<string, unknown>,
+      });
+      consumeReadSet(
+        readSetContext,
+        clientIdentity,
+        prepared.consumed,
+        prepared.automaticCommit,
+      );
+      return row as CapturedRow<T>;
+    } catch (error) {
+      abortReadSetCommit(readSetContext, prepared.automaticCommit);
+      throw error;
+    }
+  }
+
   const list = async (
     options?: ServerReadOptions<T>,
   ): Promise<ModelList<CapturedRow<T>>> => {
@@ -441,6 +510,10 @@ function createHttpModelClient<T, C = T>(
     const page = modelList<CapturedRow<T>>(
       snapshot.data as readonly CapturedRow<T>[],
       snapshot,
+      // Following pages re-enter this same read, so each one is captured into
+      // the read set exactly as the first was. A `for await` over the result
+      // therefore carries the same evidence a manual cursor walk would.
+      (cursor) => list({ ...options, cursor }),
     );
     const registry = readSetContext?.getStore();
     if (!registry) return page;
@@ -467,6 +540,15 @@ function createHttpModelClient<T, C = T>(
     return page;
   };
 
+  const listAll = async (
+    options: ListAllOptions<T> = {},
+  ): Promise<CapturedRow<T>[]> => {
+    const { maxPages, signal, ...readOptions } = options;
+    signal?.throwIfAborted();
+    const first = await list(readOptions);
+    return collectModelList(first, { maxPages, signal });
+  };
+
   // Claim acquisition performs its authoritative read only after the grant.
   // Preserve that exact post-grant watermark while retaining the callable
   // namespace and all of its state/queue/release members through the proxy.
@@ -493,28 +575,8 @@ function createHttpModelClient<T, C = T>(
     get,
     retrieve: get,
     list,
-    async create(params): Promise<T> {
-      const id = params.id ?? '';
-      const prepared = preparedMutation(params);
-      let row: T;
-      try {
-        row = await protocol.create({
-          ...prepared.options,
-          ...(params.id !== undefined ? { id: params.id } : {}),
-          data: params.data as Record<string, unknown>,
-        });
-      } catch (error) {
-        abortReadSetCommit(readSetContext, prepared.automaticCommit);
-        throw error;
-      }
-      consumeReadSet(
-        readSetContext,
-        clientIdentity,
-        prepared.consumed,
-        prepared.automaticCommit,
-      );
-      return row;
-    },
+    listAll,
+    create: createModel,
     update,
     async delete(params): Promise<void> {
       const prepared = preparedMutation(params);

package/src/transport/httpCommitRequest.ts

@@ -0,0 +1,104 @@
+/**
+ * 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 '../coordination/locator.js';
+import { claimIdFor, fenceTokenFor } from '../coordination/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';
+
+/**
+ * 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' | 'onStale'>,
+  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,
+    onStale: op.onStale ?? defaults.onStale ?? 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,
+      },
+    },
+  );
+}