@abloatai/transaction 0.56.0 → 0.57.0

package/src/source/subjectAuthorization.ts

@@ -0,0 +1,182 @@
+import { AbloPermissionError, AbloValidationError } from '../errors.js';
+import {
+  composeEntitySyncGroups,
+  syncGroupsForRow,
+  InvalidRecordSubjectError,
+  scopeKindOf,
+  subjectAuthorized,
+  type Schema,
+  type SchemaRecord,
+  type SubjectRule,
+} from '../schema/index.js';
+import type { AdapterReadRequest, Row } from './adapter.js';
+import type { ChangeSet, Operation } from './contract.js';
+
+function sourceModelEntry<S extends SchemaRecord>(schema: Schema<S>, model: string) {
+  return Object.entries(schema.models).find(([key, def]) =>
+    key === model || key.toLowerCase() === model.toLowerCase() ||
+    def.typename === model || def.typename?.toLowerCase() === model.toLowerCase(),
+  );
+}
+
+function deny(): never {
+  throw new AbloPermissionError('The resolved scope does not cover the requested row.', {
+    code: 'capability_scope_denied',
+    httpStatus: 403,
+  });
+}
+
+export function sourceSubjectRule<S extends SchemaRecord>(
+  schema: Schema<S>,
+  model: string,
+): SubjectRule | undefined {
+  const entry = sourceModelEntry(schema, model);
+  return entry?.[1].subject;
+}
+
+/** Derive the durable record routes while the row is transactionally visible. */
+export function sourceSyncGroups<S extends SchemaRecord>(
+  schema: Schema<S>,
+  model: string,
+  row: Row,
+): readonly string[] {
+  const entry = sourceModelEntry(schema, model);
+  if (!entry) return [];
+  const [key, definition] = entry;
+  const parents: { kind: string; field: string }[] = [];
+  const selfKind = scopeKindOf(definition, key);
+  for (const relation of Object.values(definition.relations ?? {})) {
+    if (relation.type !== 'belongsTo' || relation.options?.parent !== true) continue;
+    const target = schema.models[relation.target];
+    const kind = target && scopeKindOf(target, relation.target);
+    if (kind) parents.push({ kind, field: relation.foreignKey });
+  }
+  try {
+    return syncGroupsForRow(
+      {
+        selfKind,
+        parents,
+        ...(definition.subject
+          ? { subject: { kind: definition.subject.group, field: definition.subject.field } }
+          : {}),
+      },
+      row,
+      composeEntitySyncGroups(row, definition),
+    );
+  } catch (error) {
+    if (!(error instanceof InvalidRecordSubjectError)) throw error;
+    throw new AbloValidationError(
+      `Source row ${model}/${String(row.id ?? '')} lacks subject field "${error.field}".`,
+      { code: 'source_event_invalid', cause: error },
+    );
+  }
+}
+
+/** Subject values represented by a trusted group set, preserving group order. */
+export function sourceSubjectValues(
+  rule: SubjectRule | undefined,
+  groups: readonly string[] | undefined,
+): readonly string[] | undefined {
+  if (!rule) return undefined;
+  const prefix = `${rule.group}:`;
+  return [...new Set(
+    (groups ?? [])
+      .filter((group) => group.startsWith(prefix))
+      .map((group) => group.slice(prefix.length))
+      .filter((value) => value.length > 0),
+  )];
+}
+
+/**
+ * Stable absent-row lock keys for caller-selected subject-scoped CREATE ids.
+ * Adapters acquire these in sorted order before loading current rows, so two
+ * authorized writers cannot both observe an absent id. Database uniqueness is
+ * still the final boundary against external writers that ignore this lock.
+ */
+function sourceSubjectCreateLockOperations<S extends SchemaRecord>(
+  schema: Schema<S>,
+  change: ChangeSet,
+): readonly Operation[] {
+  return change.operations
+    .filter((operation) =>
+      operation.type === 'CREATE' &&
+      typeof operation.id === 'string' &&
+      operation.id.length > 0 &&
+      sourceSubjectRule(schema, operation.model) !== undefined)
+    .sort((left, right) =>
+      `${left.model.toLowerCase()}\u0000${left.id}`.localeCompare(
+        `${right.model.toLowerCase()}\u0000${right.id}`,
+      ));
+}
+
+export function sourceSubjectCreateLockKey(operation: Operation): string {
+  return `ablo:subject-create:${operation.model.toLowerCase()}:${operation.id ?? ''}`;
+}
+
+/** Acquire every absent-key CREATE lock in canonical order. */
+export async function lockSourceSubjectCreates<S extends SchemaRecord>(
+  schema: Schema<S>,
+  change: ChangeSet,
+  acquire: (operation: Operation, key: string) => Promise<void>,
+): Promise<void> {
+  for (const operation of sourceSubjectCreateLockOperations(schema, change)) {
+    await acquire(operation, sourceSubjectCreateLockKey(operation));
+  }
+}
+
+function errorCode(error: unknown): unknown {
+  return error && typeof error === 'object' ? (error as { code?: unknown }).code : undefined;
+}
+
+/** Translate ORM/driver primary-key conflicts without exposing the winning row. */
+export function rethrowStrictCreateConflict(error: unknown, operation: Operation): never {
+  const code = errorCode(error) ?? errorCode(
+    error && typeof error === 'object' ? (error as { cause?: unknown }).cause : undefined,
+  );
+  if (code === '23505' || code === 'P2002') {
+    throw new AbloValidationError(
+      `A row already exists for ${operation.model}/${operation.id ?? ''}.`,
+      { code: 'entity_already_exists', httpStatus: 409, cause: error },
+    );
+  }
+  throw error;
+}
+
+export function authorizeSourceRead<S extends SchemaRecord>(
+  schema: Schema<S>,
+  req: AdapterReadRequest,
+  rows: readonly Row[],
+): readonly Row[] {
+  const rule = sourceSubjectRule(schema, req.model);
+  if (!rule) return rows;
+  const groups = req.scope?.syncGroups;
+  const authorized = rows.filter((row) => subjectAuthorized(rule, row, groups));
+  if (req.kind === 'load' && rows.length > 0 && authorized.length === 0) deny();
+  return authorized;
+}
+
+function authorizePayload(rule: SubjectRule, row: Row, groups: readonly string[] | undefined): void {
+  if (!subjectAuthorized(rule, row, groups)) deny();
+}
+
+export async function authorizeSourceChange<S extends SchemaRecord>(
+  schema: Schema<S>,
+  change: ChangeSet,
+  load: (operation: Operation) => Promise<Row | null>,
+): Promise<void> {
+  for (const operation of change.operations) {
+    const rule = sourceSubjectRule(schema, operation.model);
+    if (!rule) continue;
+    const current = operation.id ? await load(operation) : null;
+    if (current) authorizePayload(rule, current, change.scope?.syncGroups);
+    if (operation.type === 'CREATE') {
+      authorizePayload(rule, operation.input ?? {}, change.scope?.syncGroups);
+    } else if (!current) {
+      deny();
+    }
+    if (current && operation.input && Object.hasOwn(operation.input, rule.field) &&
+        !Object.is(current[rule.field], operation.input[rule.field])) {
+      deny();
+    }
+  }
+}

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

@@ -47,13 +47,6 @@ import { z } from 'zod';
 export const logPositionSchema = z.number().int().nonnegative();
 export type LogPosition = z.infer<typeof logPositionSchema>;
 
-/** @deprecated One position type, one name: use {@link logPositionSchema}.
- *  This spelling is removed in 0.57.0. It resolves to the definition above, so
- *  the two cannot drift while both are exported. */
-export const deltaPositionSchema = logPositionSchema;
-/** @deprecated One position type, one name: use {@link LogPosition}. Removed in 0.57.0. */
-export type DeltaPosition = LogPosition;
-
 export const clientMutationIdSchema = z.string().min(1).max(255);
 export type ClientMutationId = z.infer<typeof clientMutationIdSchema>;
 

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,
+      },
+    },
+  );
+}