@abloatai/transaction 0.52.0 → 0.54.0

package/src/resources/where.ts

@@ -18,7 +18,13 @@ import { z } from 'zod';
 import { AbloValidationError } from '../errors.js';
 
 /** Primitive operand types allowed in a where clause. */
-export type WherePrimitive = string | number | boolean | null;
+export const wherePrimitiveSchema = z.union([
+  z.string(),
+  z.number(),
+  z.boolean(),
+  z.null(),
+]);
+export type WherePrimitive = z.infer<typeof wherePrimitiveSchema>;
 
 /**
  * The comparison operators a {@link WhereClause} may use: equality and
@@ -93,6 +99,22 @@ export const WHERE_LIKE_OPS: ReadonlySet<WhereOp> = new Set<WhereOp>([
  * Returns the classification the caller needs next, so the check and the branch
  * are the same statement rather than two that can disagree.
  */
+/**
+ * Whether an operand is the array form the set operators take.
+ *
+ * `Array.isArray` answers this at runtime but not in the type system: its
+ * signature narrows to `any[]`, which drops both the `readonly` and the element
+ * type, so a compiler that reached for it lost the operand type it had just
+ * finished validating and handed `any` to everything downstream. Declared here
+ * because operand shape is this module's vocabulary — the same reason
+ * {@link classifyWhereOperand} lives here rather than in either plane.
+ */
+export function isWhereOperandList(
+  value: WherePrimitive | readonly WherePrimitive[] | undefined,
+): value is readonly WherePrimitive[] {
+  return Array.isArray(value);
+}
+
 export function classifyWhereOperand(
   op: WhereOp,
   value: unknown,
@@ -134,10 +156,27 @@ export function classifyWhereOperand(
  *
  * The value is a single primitive for scalar operators and an array of
  * primitives for IN/NOT IN.
+ *
+ * This is a schema rather than a bare type because the grammar crosses a
+ * boundary: a filtered read arrives at the collection route as text, and the
+ * route has to decide whether what it received is a clause before compiling it
+ * to SQL. Declaring the shape twice — once to check at the edge, once to type
+ * the interior — is how the two planes came to disagree about `IN`.
  */
-export type WhereClause =
-  | readonly [col: string, value: WherePrimitive]
-  | readonly [col: string, op: WhereOp, value: WherePrimitive | readonly WherePrimitive[]];
+export const whereClauseSchema = z.union([
+  z.tuple([z.string(), wherePrimitiveSchema]).readonly(),
+  z
+    .tuple([
+      z.string(),
+      whereOpSchema,
+      z.union([wherePrimitiveSchema, z.array(wherePrimitiveSchema).readonly()]),
+    ])
+    .readonly(),
+]);
+export type WhereClause = z.infer<typeof whereClauseSchema>;
+
+/** A whole filter as it travels: the AND-combined list of conditions. */
+export const whereClausesSchema = z.array(whereClauseSchema).readonly();
 
 /**
  * Client-facing where shape for `load({where})` and `deleteMany({where})`.
@@ -158,3 +197,30 @@ export type LoadWhere<T> =
   | Partial<T>
   | { [K in keyof T]?: T[K] | readonly T[K][] }
   | readonly WhereClause[];
+
+/**
+ * Collapse either accepted {@link LoadWhere} form to the canonical clause list.
+ * Tuple input passes through; object input becomes one `['col', '=', val]` per
+ * key, or `['col', 'IN', vals]` where the value is an array.
+ *
+ * Detection: an array is tuple form, an object is object form.
+ *
+ * Every transport funnels through this. It used to live beside the WebSocket
+ * loader, which left the HTTP transport to walk `Object.entries` itself — and
+ * that copy dropped any value it found to be an object, so an `IN` filter and
+ * every tuple-form clause were discarded in silence and the read came back
+ * unfiltered.
+ */
+export function normalizeWhere(where: unknown): readonly WhereClause[] {
+  if (where == null) return [];
+  // Tuple form — assumed to already use server-side column names.
+  if (Array.isArray(where)) return where as readonly WhereClause[];
+  if (typeof where === 'object') {
+    return Object.entries(where as Record<string, unknown>).map(([key, value]) =>
+      Array.isArray(value)
+        ? ([key, 'IN', value as readonly WherePrimitive[]] as WhereClause)
+        : ([key, value as WherePrimitive] as WhereClause),
+    );
+  }
+  return [];
+}

package/src/schema/index.ts

@@ -177,6 +177,9 @@ export {
   extractIdentityIds,
   extractEntityIds,
   syncGroup,
+  identityAnchor,
+  IDENTITY_ANCHOR_KINDS,
+  type IdentityAnchorKind,
   syncGroupSchema,
   syncGroupRefSchema,
   syncGroupInputSchema,

package/src/schema/openapi.ts

@@ -36,6 +36,7 @@ import {
   commitRecordListSchema,
   commitRecordWhereSchema,
 } from '../wire/commit.js';
+import { CURSOR_PARAM, CURSOR_PARAM_ALIAS } from '../wire/listEnvelope.js';
 import {
   claimRequestSchema,
   claimHeartbeatRequestSchema,
@@ -185,6 +186,43 @@ function fieldSchema(f: FieldMeta): Json {
 
 const pascal = (s: string): string => s.charAt(0).toUpperCase() + s.slice(1);
 const idParam = (): Json => ({ name: 'id', in: 'path', required: true, schema: { type: 'string' } });
+const idempotencyKeyParam = (): Json => ({
+  name: 'Idempotency-Key',
+  in: 'header',
+  schema: { type: 'string', maxLength: 255 },
+  description: 'Replay identity. Reuse the same key only for an identical request.',
+});
+const collectionPageParams = (): Json[] => [
+  {
+    name: 'limit',
+    in: 'query',
+    schema: { type: 'integer', minimum: 1, maximum: 100, default: 20 },
+  },
+  cursorParam(),
+  retiredCursorParam(),
+];
+
+/** The cursor parameter, named from the wire contract that issues its value. */
+const cursorParam = (): Json => ({
+  name: CURSOR_PARAM,
+  in: 'query',
+  schema: { type: 'string' },
+  description: 'The opaque next_cursor returned by the preceding page.',
+});
+
+/**
+ * The retired spelling, documented as deprecated so a caller still sending it
+ * can see it is going. Declared once: `queryParams` reaches for it too, and a
+ * second copy is how the model list came to document the same parameter without
+ * the deprecation the collection routes carried.
+ */
+const retiredCursorParam = (): Json => ({
+  name: CURSOR_PARAM_ALIAS,
+  in: 'query',
+  deprecated: true,
+  schema: { type: 'string' },
+  description: `Deprecated spelling of ${CURSOR_PARAM}, honoured until it is removed. Send ${CURSOR_PARAM}.`,
+});
 const jsonBody = (schema: Json): Json => ({
   required: true,
   content: { 'application/json': { schema } },
@@ -313,16 +351,22 @@ function withGenericRows(derived: Json): Json {
  */
 function queryParams(schema: z.ZodType): Json[] {
   const props = (derive(schema, 'input').properties ?? {}) as Record<string, Json>;
-  return Object.entries(props).map(([name, s]) => ({
-    name,
-    in: 'query',
-    // Query strings arrive at the server as text, but OpenAPI describes the
-    // caller-facing value before serialization. Generated clients should take
-    // an integer here and encode it, not expose a stringly typed page size.
-    schema: name === 'limit'
-      ? { type: 'integer', minimum: 1 }
-      : s,
-  }));
+  return Object.entries(props).map(([name, s]) => {
+    // The retired cursor spelling is documented the same way wherever it
+    // appears. Derived from the schema it still lives in, so the flag cannot be
+    // present on one route's copy of the parameter and absent on another's.
+    if (name === CURSOR_PARAM_ALIAS) return retiredCursorParam();
+    return {
+      name,
+      in: 'query',
+      // Query strings arrive at the server as text, but OpenAPI describes the
+      // caller-facing value before serialization. Generated clients should take
+      // an integer here and encode it, not expose a stringly typed page size.
+      schema: name === 'limit'
+        ? { type: 'integer', minimum: 1 }
+        : s,
+    };
+  });
 }
 
 const commitRecordListQuerySchema = commitRecordWhereSchema.safeExtend({
@@ -492,8 +536,8 @@ export function abloOpenApi(options: SchemaToOpenApiOptions = {}): Json {
         parameters: [modelParam(), ...queryParams(listQuerySchema)],
         responses: {
           '200': namedResp(
-            'A page of rows. `next_cursor` feeds `starting_after` on the next ' +
-              'call; `stamp` is the watermark the page was read at.',
+            'A page of rows. `next_cursor` feeds `cursor` on the next call; ' +
+              '`stamp` is the watermark the page was read at.',
             'ModelPage',
           ),
         },
@@ -599,6 +643,7 @@ export function abloOpenApi(options: SchemaToOpenApiOptions = {}): Json {
       get: {
         tags: ['branches'],
         summary: 'List transaction branches for the credential project',
+        parameters: collectionPageParams(),
         responses: {
           '200': jsonResp(
             'The root and every active child branch.',
@@ -611,6 +656,7 @@ export function abloOpenApi(options: SchemaToOpenApiOptions = {}): Json {
         summary: 'Create an isolated child branch',
         description:
           'The returned id is immutable; retain it for automation. The slug is a project-scoped human handle.',
+        parameters: [idempotencyKeyParam()],
         requestBody: jsonBody(derive(createBranchRequestSchema, 'input')),
         responses: {
           '201': jsonResp('The ready branch.', derive(branchResponseSchema, 'output')),
@@ -866,7 +912,7 @@ export function abloOpenApi(options: SchemaToOpenApiOptions = {}): Json {
       post: {
         tags: ['commits'],
         summary: 'Commit a batch of operations atomically, and/or register durable premises',
-        parameters: [{ name: 'Idempotency-Key', in: 'header', schema: { type: 'string' }, description: 'Replay-safe key; the server returns the cached receipt on retry.' }],
+        parameters: [idempotencyKeyParam()],
         requestBody: commitBody(),
         responses: { '200': commitReceipt() },
       },
@@ -993,7 +1039,7 @@ export function schemaToOpenApi<S extends SchemaRecord>(
     post: {
       tags: ['commits'],
       summary: 'Commit a batch of operations atomically, and/or register durable premises',
-      parameters: [{ name: 'Idempotency-Key', in: 'header', schema: { type: 'string' }, description: 'Replay-safe key; the server returns the cached receipt on retry.' }],
+      parameters: [idempotencyKeyParam()],
       requestBody: commitBody(),
       responses: { '200': commitReceipt() },
     },

package/src/schema/schema.ts

@@ -51,6 +51,9 @@ export {
   composeEntitySyncGroups,
   intersectRequestedWithAllowed,
   syncGroup,
+  identityAnchor,
+  IDENTITY_ANCHOR_KINDS,
+  type IdentityAnchorKind,
   syncGroupSchema,
   syncGroupRefSchema,
   syncGroupInputSchema,

package/src/server/adapter.ts

@@ -61,6 +61,8 @@ export type ReadResult =
   | {
       readonly kind: 'query';
       readonly rows: readonly Row[];
+      /** Opaque upstream cursor when a source-backed list has another page. */
+      readonly nextCursor?: string;
     };
 
 // ── sync ─────────────────────────────────────────────────────────────────────

package/src/server/index.ts

@@ -4,7 +4,8 @@
  * vocabulary ({@link Row}, {@link ReadRequest}, {@link ChangeSet}, and the rest),
  * the {@link CommitContext} and {@link CommitExecutionResult} commit types, the
  * {@link StorageMode} enumeration, and the per-model read configuration
- * ({@link BootstrapModel}, {@link ColumnOverride}). These are plain, driver-free
+ * ({@link ReadModelShape} and the {@link BootstrapModel} descriptor built on it,
+ * plus {@link ColumnOverride} and {@link ParentScope}). These are plain, driver-free
  * types; you supply the database code that fulfills them.
  */
 export type {
@@ -27,4 +28,9 @@ export {
   type CommitRecord,
 } from '../wire/commit.js';
 export { storageModeSchema, type StorageMode } from './storageMode.js';
-export type { ColumnOverride, BootstrapModel } from './readConfig.js';
+export type {
+  ColumnOverride,
+  ParentScope,
+  ReadModelShape,
+  BootstrapModel,
+} from './readConfig.js';

package/src/server/readConfig.ts

@@ -1,9 +1,23 @@
 /**
- * Canonical per-model read configuration consumed when a client bootstraps. Each
- * {@link BootstrapModel} maps a model to its physical table, its tenancy column, and
- * any parent scoping — plain data with no database driver. It feeds the read side of
- * the data adapter contract; your query builder reads it to load a model's initial
- * rows.
+ * Canonical per-model read configuration — how one model's rows are located,
+ * scoped to a tenant, and decoded back into the types the schema declared.
+ *
+ * {@link ReadModelShape} is the definition site for those facts. Every read seam
+ * needs the same set, and each one that restated the set drifted from the
+ * others: `json` decoding reached three of them, `number` decoding reached none,
+ * and the where-clause `boolean` list reached exactly one — so a `bigint`-backed
+ * field left one seam as a decimal string and its `int4` neighbour left the next
+ * as a number. Adding a declared type is now one edit here rather than a
+ * remembered sweep.
+ *
+ * The descriptors below carry that shape plus the facts only they need. They
+ * disagree on one thing, deliberately: the model's own name. A bootstrap
+ * descriptor spells it `name`, the server's read-model descriptor spells it
+ * `typename`. `name` is part of the published data-adapter contract, so the two
+ * spellings stay and the shape they share owns everything else.
+ *
+ * Plain data, no database driver — it feeds the read side of the data adapter
+ * contract, and your query builder reads it to load a model's initial rows.
  */
 
 /** A mapping from a declared field to a physical column, with the alias to apply after a `SELECT *`. */
@@ -13,70 +27,110 @@ export interface ColumnOverride {
   readonly alias: string;
 }
 
-/** Read configuration for one model: how to locate its rows and scope them to a tenant. */
-export interface BootstrapModel {
-  name: string;
+/**
+ * Parent-table tenancy scoping for rows that have no `organization_id` column
+ * of their own, mirroring the schema's `scopedVia` option. A read carrying this
+ * adds:
+ *
+ *   WHERE <table>.<localKey> IN
+ *     (SELECT <parentKey> FROM <parentTable> WHERE <parentOrgColumn> = $1)
+ *
+ * It applies on top of whatever `orgScoped` dictates, so a table can carry its
+ * own `organization_id` and still narrow through a parent. The common case is
+ * `orgScoped: false` together with this on a table that lacks the column —
+ * without it, such a table reads every tenant's rows.
+ */
+export interface ParentScope {
+  readonly localKey: string;
+  readonly parentTable: string;
+  readonly parentKey?: string;
+  readonly parentOrgColumn?: string;
+}
+
+/**
+ * Everything a read seam needs to know about one model except what it is called.
+ *
+ * Split from the descriptors that carry it because the two of them name the
+ * model differently and agree on all of this. A seam that only decodes, or only
+ * compiles SQL, projects the members it uses with `Pick` rather than declaring
+ * its own near-copy.
+ */
+export interface ReadModelShape {
   /**
    * Extra names accepted when a request looks up or filters this model. When the
-   * physical table name is canonical, `name` stays that table name and the aliases
-   * cover generated compatibility names such as `WeatherReports` or `weatherReports`.
+   * physical table name is canonical, the descriptor's own name stays that table
+   * name and the aliases cover generated compatibility names such as
+   * `WeatherReports` or `weatherReports`.
    */
-  aliases?: readonly string[];
+  readonly aliases?: readonly string[];
   /**
-   * The schema key used by source endpoints. `name` stays the wire and result model
-   * name (usually the typename), while source handlers are keyed by the developer's
-   * schema key, such as `files` or `blocks`.
+   * The schema key used by source endpoints. The descriptor's own name stays the
+   * wire and result model name (usually the typename), while source handlers are
+   * keyed by the developer's schema key, such as `files` or `blocks`.
    */
-  sourceModel?: string;
-  table: string;
-  syncGroups?: string[];
-  enabled?: boolean;
-  /** Max rows to return. Omit for unlimited. Maps to schema's bootstrapLimit. */
-  limit?: number;
-  /** SQL ORDER BY clause. Default: 'id'. Maps to schema's bootstrapOrderBy. */
-  orderBy?: string;
+  readonly sourceModel?: string;
+  readonly table: string;
   /** Whether the table has organization_id. Default: true. */
-  orgScoped?: boolean;
+  readonly orgScoped?: boolean;
   /**
    * The model derives its tenant from the connected data source (`policy:
-   * { by: 'source' }`) rather than a row column. It carries no tenant predicate on a
-   * log plane, so it is excluded from the bootstrap set entirely until the
-   * write-through connect path can resolve the org from the source registration —
-   * serving it now would return every row to every tenant. Kept on the type as a
-   * defense-in-depth marker so a source-scoped model that reaches `getBootstrapData`
-   * fails closed rather than bootstrapping unscoped.
+   * { by: 'source' }`) rather than a row column — the source registration is the
+   * tenant boundary. Distinct from `orgScoped: false` (a `none`/global model): a
+   * source-scoped model IS tenant-scoped, just not by a column. It carries no
+   * tenant predicate on a log plane, so every read and bootstrap site fails it
+   * closed with `source_tenancy_not_enforced` rather than treating it as global
+   * — serving it now would return every row to every tenant. When the
+   * write-through connect path can resolve the org from the source registration,
+   * this same flag routes to that resolution.
    */
-  sourceScoped?: boolean;
+  readonly sourceScoped?: boolean;
   /** Physical tenancy column (default `organization_id`, configurable per model). */
-  orgColumn?: string;
-  /**
-   * Parent-table scoping for rows that have no `organization_id` column, mirroring
-   * the schema's `scopedVia` option. When set, the bootstrap query adds:
-   *
-   *   WHERE <table>.<localKey> IN
-   *     (SELECT <parentKey> FROM <parentTable> WHERE <parentOrgColumn> = $1)
-   *
-   * This applies on top of whatever `orgScoped` dictates, so a table can carry its
-   * own `organization_id` and still narrow through a parent. The common case,
-   * though, is `orgScoped: false` together with `scopedVia` on a table that lacks the
-   * column.
-   */
-  scopedVia?: {
-    localKey: string;
-    parentTable: string;
-    parentKey?: string;
-    parentOrgColumn?: string;
-  };
+  readonly orgColumn?: string;
+  /** Parent-table scoping for rows with no tenancy column of their own. */
+  readonly scopedVia?: ParentScope;
   /** Client-facing field name → physical DB column for declared fields. */
-  fieldColumns?: Record<string, string>;
+  readonly fieldColumns?: Readonly<Record<string, string>>;
   /** Physical-column aliases needed after SELECT * for `.from(...)` fields. */
-  columnOverrides?: readonly ColumnOverride[];
+  readonly columnOverrides?: readonly ColumnOverride[];
   /**
-   * Physical columns the schema declares as JSON (via `field.json()`). A JSON field
-   * stored in a text column comes back from `row_to_json` as a serialized string, so
-   * the bootstrap reparses these columns to make the wire value the canonical object
-   * regardless of the physical column type. A `jsonb` column already returns an
-   * object, so reparsing it is a no-op.
+   * Physical columns the schema declares as JSON (via `field.json()`). A JSON
+   * field stored in a text column comes back serialized, so a read reparses these
+   * to make the wire value the canonical object regardless of the physical column
+   * type. A `jsonb` column already returns an object, so reparsing it is a no-op.
    */
-  jsonColumns?: readonly string[];
+  readonly jsonColumns?: readonly string[];
+  /**
+   * Physical columns the schema declares as a boolean (via `field.boolean()`).
+   * Two seams need the list. A where-clause parameter is coerced to a real JS
+   * boolean before binding, because the driver's bool encoder is a strict
+   * `=== true` and a string `'t'` would silently bind as `'f'` — an INVERTED
+   * filter, not an error. A row read back from the log is coerced the same way,
+   * because a value echoed from a customer's database arrives as PG's text
+   * literal rather than as `true`.
+   */
+  readonly boolColumns?: readonly string[];
+  /**
+   * Physical columns the schema declares as a number (via `field.number()`).
+   * Postgres has four integer widths where JavaScript has one, so a column too
+   * wide to always fit a JS number comes back as decimal text. A read decodes
+   * these so a `bigint`-backed field and an `int4`-backed one reach the client as
+   * the same JS type.
+   */
+  readonly numberColumns?: readonly string[];
+}
+
+/**
+ * Read configuration for one model at bootstrap: {@link ReadModelShape} plus the
+ * facts only the initial payload needs — which models are in it, how much of
+ * each, and in what order.
+ */
+export interface BootstrapModel extends ReadModelShape {
+  /** The wire and result model name. `ModelMeta.typename` is the same fact. */
+  readonly name: string;
+  readonly syncGroups?: readonly string[];
+  readonly enabled?: boolean;
+  /** Max rows to return. Omit for unlimited. Maps to schema's bootstrapLimit. */
+  readonly limit?: number;
+  /** SQL ORDER BY clause. Default: 'id'. Maps to schema's bootstrapOrderBy. */
+  readonly orderBy?: string;
 }

package/src/source/adapters/kysely.ts

@@ -120,6 +120,44 @@ function postgresLogicalMarkerQuery(payload: string): KyselyCompiledQuery {
   );
 }
 
+/**
+ * The two closing statements of a WAL-echo commit as ONE round trip.
+ *
+ * Neither result is read: the ledger update records the response, the marker
+ * lets the replication echo correlate itself. Sending them separately costs a
+ * second full round trip to the customer's database, which is ~6ms when Ablo
+ * and that database are neighbours and ~110ms when they are on different
+ * continents — paid on every write.
+ *
+ * A data-modifying `WITH` is the right shape rather than a coincidence: Postgres
+ * runs it exactly once and to completion whether or not the primary query reads
+ * its output, so the ledger update is not conditional on the marker. Ordering is
+ * preserved too — the CTE executes before the main query, the same order the two
+ * statements had — and both remain inside the caller's transaction, so the
+ * marker is still atomic with the write it describes.
+ */
+function completeLedgerWithMarkerQuery(
+  correlationId: string,
+  rows: readonly Row[],
+  payload: string,
+): KyselyCompiledQuery {
+  return rawQuery(
+    'ablo-idempotency-complete-with-marker',
+    `WITH complete AS (
+       UPDATE ablo_idempotency
+          SET response = $2::jsonb
+        WHERE client_tx_id = $1
+     )
+     SELECT pg_logical_emit_message(true, $3::text, $4::text)`,
+    [
+      correlationId,
+      JSON.stringify(rows),
+      ABLO_POSTGRES_COMMIT_ECHO_PREFIX,
+      payload,
+    ],
+  );
+}
+
 function parseCachedRows(response: unknown): Row[] {
   const parsed = typeof response === 'string' ? (JSON.parse(response) as unknown) : response;
   if (!Array.isArray(parsed)) {
@@ -288,12 +326,37 @@ export function createKyselyMutationAdapter(
           return { rows: parseCachedRows(cachedRow.response) };
         }
 
+        // Direct mode dispatches every operation before awaiting any of them, so
+        // the driver pipelines them into one trip instead of paying a full
+        // round trip per row. Postgres still executes them IN ORDER on the
+        // connection, so nothing about their semantics moves: a later operation
+        // still sees an earlier one's write, and two operations on the same row
+        // remain well-defined last-write-wins — which a multi-CTE batch would
+        // have made undefined. Each statement also keeps its own error, so
+        // "which operation failed" survives.
+        //
+        // Endpoint mode stays sequential: its outbox row is built FROM the
+        // returned row, so operation i+1's write cannot be dispatched before
+        // operation i has answered.
         const rows: Row[] = [];
-        for (const [index, operation] of request.operations.entries()) {
-          const row = await core.applyOperation(transaction, operation);
-          rows.push(row);
+        if (mode === 'direct') {
+          const dispatched = request.operations.map((operation) =>
+            core.applyOperation(transaction, operation),
+          );
+          // Settle every dispatch before inspecting, so a later rejection is
+          // never an unhandled rejection, then surface the FIRST failure in
+          // operation order — the one the caller's request actually tripped on.
+          const settled = await Promise.allSettled(dispatched);
+          const failure = settled.find((outcome) => outcome.status === 'rejected');
+          if (failure && failure.status === 'rejected') throw failure.reason;
+          for (const outcome of settled) {
+            if (outcome.status === 'fulfilled') rows.push(outcome.value);
+          }
+        } else {
+          for (const [index, operation] of request.operations.entries()) {
+            const row = await core.applyOperation(transaction, operation);
+            rows.push(row);
 
-          if (mode === 'endpoint') {
             const entityId = String(row.id ?? kyselyOperationRowId(operation));
             await transaction
               .insertInto('ablo_outbox')
@@ -311,15 +374,17 @@ export function createKyselyMutationAdapter(
           }
         }
 
-        await transaction.executeQuery(
-          completeLedgerQuery(request.correlationId, rows),
-        );
         if (request.echo?.kind === 'postgres-wal') {
           const payload = echoIntent
             ? JSON.stringify(resolveEchoMarker(echoIntent, rows))
             : request.echo.payload;
+          // One round trip, not two — see `completeLedgerWithMarkerQuery`.
+          await transaction.executeQuery(
+            completeLedgerWithMarkerQuery(request.correlationId, rows, payload),
+          );
+        } else {
           await transaction.executeQuery(
-            postgresLogicalMarkerQuery(payload),
+            completeLedgerQuery(request.correlationId, rows),
           );
         }
         return { rows };

package/src/source/contract.ts

@@ -165,6 +165,8 @@ export const outboxEventSchema = z.object({
   model: z.string().min(1),
   entityId: z.string().min(1),
   type: operationTypeSchema,
+  /** The changed row, in the key shape `SourceEvent.data` defines: the model's
+   *  declared schema fields, never the table's physical column names. */
   data: jsonObject.nullish(),
   organizationId: z.string().nullish(),
   /** Legacy source transaction id. Never use this field to settle a queued commit. */

package/src/source/types.ts

@@ -120,6 +120,7 @@ export interface SourceDelta {
   readonly model: string;
   readonly id: string;
   readonly type: SourceOperation['type'];
+  /** The changed row, in the key shape {@link SourceEvent.data} defines. */
   readonly data?: Record<string, unknown> | null;
   readonly transactionId?: string | null;
 }
@@ -144,6 +145,22 @@ export interface SourceEvent {
   readonly model: string;
   readonly entityId: string;
   readonly type: SourceOperation['type'];
+  /**
+   * The row after the change, keyed by the model's DECLARED SCHEMA FIELDS.
+   *
+   * A field named `reviewStatus` arrives as `reviewStatus`, even though the
+   * column it was read from is `review_status`. Ablo's own adapters rename the
+   * row before writing the outbox, so a source built on one of them is already
+   * in this shape; a hand-written `events` handler has to do the same. Pass
+   * `null` for a delete.
+   *
+   * Ablo reads exactly this spelling and never falls back to the physical one.
+   * Two namespaces that can collide have no safe merge: a model whose field `a`
+   * maps to column `b` while another field maps to column `a` would route the
+   * change into a different scope root's group. A key Ablo does not recognise
+   * costs a subscriber an update; a key it recognises as the wrong field crosses
+   * a tenant boundary.
+   */
   readonly data?: Record<string, unknown> | null;
   /**
    * The tenant this event belongs to. Populate it from the row's organization
@@ -183,9 +200,10 @@ export interface SourceEventForOperationOptions {
    */
   readonly entityId?: string;
   /**
-   * The row's payload after the write. Pass `null` for a delete. When omitted,
-   * the event carries no payload, which is valid but leaves less for clients to
-   * hydrate from in realtime.
+   * The row after the write, in the key shape {@link SourceEvent.data} defines:
+   * the model's declared schema fields, not your table's column names. Pass
+   * `null` for a delete. When omitted, the event carries no payload, which is
+   * valid but leaves less for clients to hydrate from in realtime.
    */
   readonly data?: Record<string, unknown> | null;
   /**