@abloatai/transaction 0.53.0 → 0.55.0

package/src/schema/openapi.ts

@@ -56,6 +56,7 @@ import { errorEnvelopeSchema } from '../wire/errorEnvelope.js';
 import { modelReadResponseSchema, modelListResponseSchema } from '../wire/modelResponses.js';
 import { modelMutationRequestSchema } from '../wire/modelMutations.js';
 import { logListResponseSchema, logQuerySchema } from '../wire/feedEvent.js';
+import { logDeliveryResponseSchema } from '../wire/deltaDelivery.js';
 import { schemaReadResponseSchema } from '../wire/accountResponses.js';
 import {
   ephemeralKeyRequestSchema,
@@ -161,6 +162,7 @@ const ABLO_OPERATION_IDS: Readonly<Record<string, string>> = {
   'POST /v1/capabilities/{id}/rotate': 'rotateCapability',
   'GET /v1/schema': 'getSchema',
   'GET /v1/logs': 'listLogEntries',
+  'GET /v1/logs/delivery': 'getLogDelivery',
   'GET /v1/commits': 'listCommits',
   'POST /v1/commits': 'commit',
   'GET /v1/commits/{id}': 'getCommit',
@@ -902,6 +904,25 @@ export function abloOpenApi(options: SchemaToOpenApiOptions = {}): Json {
         },
       },
     },
+    '/v1/logs/delivery': {
+      get: {
+        tags: ['logs'],
+        summary: 'How much of what was recorded could reach anyone',
+        description:
+          'The fan-out verdict for your plane over a recent window. `recorded` ' +
+          'counts the changes the log accepted; `unroutable` counts the ones ' +
+          'excluded from delivery because they carried no sync group, which is ' +
+          'the state a row reaches when it was written into your database ' +
+          'outside Ablo and so carries no tenancy value. Any number above zero ' +
+          'means writes are landing that no subscriber is told about.',
+        responses: {
+          '200': jsonResp(
+            'The counts, plus the most recent undeliverable change when there is one.',
+            derive(logDeliveryResponseSchema, 'output'),
+          ),
+        },
+      },
+    },
     '/v1/commits': {
       get: {
         tags: ['commits'],

package/src/schema/schema.ts

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

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;
   /**

package/src/wire/auth.ts

@@ -27,7 +27,7 @@ export type EphemeralKeyUser = z.infer<typeof ephemeralKeyUserSchema>;
  * Only a secret key (`sk_`) may call this: a session cannot mint itself. By
  * default the key mints into the caller's own organization; naming a different
  * `organizationId` is the multi-tenant case and requires the
- * `ephemeral:mint-any-org` scope, which is the same privilege that allows
+ * `organization:act-as` scope, which is the same privilege that allows
  * binding the session's schema to another organization's project.
  */
 export const ephemeralKeyRequestSchema = z.object({
@@ -35,7 +35,7 @@ export const ephemeralKeyRequestSchema = z.object({
   user: ephemeralKeyUserSchema,
   /**
    * Mint into this organization instead of the caller's own. Requires the
-   * `ephemeral:mint-any-org` scope — without it a secret key can never mint a
+   * `organization:act-as` scope — without it a secret key can never mint a
    * session into another tenant.
    */
   organizationId: z.string().min(1).optional(),
@@ -43,7 +43,7 @@ export const ephemeralKeyRequestSchema = z.object({
    * Override the shared project used to resolve this session's schema while
    * its data stays scoped to the target organization. A cross-organization
    * mint defaults both coordinates to the caller key's own project. Both
-   * fields are set together, and both require `ephemeral:mint-any-org`.
+   * fields are set together, and both require `organization:act-as`.
    */
   schemaProjectId: z.string().min(1).optional(),
   schemaOwnerOrgId: z.string().min(1).optional(),

package/src/wire/deltaDelivery.ts

@@ -0,0 +1,47 @@
+/**
+ * What `GET /v1/logs/delivery` answers: of the changes this plane recorded,
+ * how many could reach anyone.
+ *
+ * The engine already knows. A delta whose `sync_groups` is empty is an upstream
+ * invariant violation — `buildDeltaSyncGroups` guarantees at least one group —
+ * so the fan-out excludes it from delivery, counts it, and warns. All three land
+ * on Ablo's side of the boundary. The row is in the customer's database, the
+ * commit confirmed, every configuration check green, and nobody is told. This
+ * response moves that fact to the side the person debugging it is standing on.
+ *
+ * Counts and one sample, never row data: `model` and `id` are what the warning
+ * already names, and they are what turns "realtime is broken" into a row to look
+ * at.
+ */
+
+import { z } from 'zod';
+
+/** The model and row of one undeliverable change — enough to find it, no more. */
+export const deliverySampleSchema = z.object({
+  model: z.string(),
+  id: z.string(),
+  at: z.string(),
+});
+export type DeliverySample = z.infer<typeof deliverySampleSchema>;
+
+/**
+ * `GET /v1/logs/delivery` — the plane's fan-out verdict over a fixed recent
+ * window.
+ *
+ * `recorded` and `unroutable` are the verdict and always present. `sample` is
+ * optional in the reader's stance the rest of this surface takes: a deployment
+ * that omits it must still be readable, because refusing to parse would refuse
+ * the diagnosis along with it.
+ */
+export const logDeliveryResponseSchema = z.object({
+  object: z.literal('log_delivery').optional(),
+  /** The window the counts cover, so a reader never hardcodes it. */
+  window_seconds: z.number(),
+  /** Deltas this plane recorded in the window. */
+  recorded: z.number(),
+  /** Of those, the ones excluded from delivery for having no sync group. */
+  unroutable: z.number(),
+  /** The most recent undeliverable change, when there is one. */
+  sample: deliverySampleSchema.nullable().optional(),
+});
+export type LogDeliveryResponse = z.infer<typeof logDeliveryResponseSchema>;

package/src/wire/index.ts

@@ -41,6 +41,11 @@ export {
   logQuerySchema,
 } from './feedEvent.js';
 export type { FeedEvent, LogListResponse, LogQuery } from './feedEvent.js';
+
+// The same feed's delivery verdict — how much of what it recorded could reach
+// anyone. Read by `ablo doctor`.
+export { logDeliveryResponseSchema, deliverySampleSchema } from './deltaDelivery.js';
+export type { LogDeliveryResponse, DeliverySample } from './deltaDelivery.js';
 export {
   feedCursorSchema,
   parseFeedCursor,