@abloatai/ablo 0.26.0 → 0.27.0

package/dist/source/connector.js

@@ -1,15 +1,13 @@
 /**
- * Customer-side Data Source reverse-channel connector.
+ * Opens the connector's side of the Data Source reverse channel. You run this
+ * process next to your database; it dials an outbound WebSocket to Ablo and serves
+ * the load, list, and commit requests over that socket, so a handler with no
+ * public URL never needs to receive inbound webhooks. It is the counterpart to
+ * `createPushQueue`, which gives the outbound events feed the same treatment, and
+ * it speaks the frames defined in `connectorProtocol.ts`.
  *
- * The dial-out half of the reverse channel (see `connector-protocol.ts`). The
- * customer runs this next to their database; it opens an OUTBOUND WebSocket to
- * Ablo Cloud and serves the `commit`/`load`/`list` leg over that socket instead
- * of receiving inbound webhooks. This is the symmetric primitive to
- * `createPushQueue` (which already gives the `events` leg an outbound transport)
- * and mirrors the Stripe CLI's `stripe listen`.
- *
- * The connector does NOT reimplement any handler logic. It wraps the SAME
- * `(request: Request) => Promise<Response>` the customer's deployed route uses:
+ * The connector reimplements none of the handler logic. It wraps the same
+ * `(request: Request) => Promise<Response>` your deployed route already uses:
  *
  *   import { dataSource, createSourceConnector } from '@abloatai/ablo';
  *   import { sourceOptions } from './ablo.source'; // shared with route.ts
@@ -20,22 +18,24 @@
  *   });
  *   await connector.run(controller.signal);
  *
- * Each drained `request` frame is replayed into a synthesized `Request` carrying
- * the original Standard Webhooks signature headers, so the handler verifies it
- * through the unchanged `verifyAbloSourceRequest` — identical to the webhook
- * path. The transport changes; the trust model does not.
+ * Each incoming `request` frame is replayed into a `Request` that carries the
+ * original signature headers, so the handler verifies it through the same
+ * `verifyAbloSourceRequest` it uses on the webhook path. The transport changes;
+ * the trust model does not.
  */
-import { SOURCE_CONNECTOR_PROTOCOL_VERSION, SOURCE_CONNECTOR_WS_PATH, sourceConnectorSubprotocols, encodeFrame, decodeFrame, ConnectorProtocolError, } from './connector-protocol.js';
+import { SOURCE_CONNECTOR_PROTOCOL_VERSION, SOURCE_CONNECTOR_WS_PATH, sourceConnectorSubprotocols, encodeFrame, decodeFrame, ConnectorProtocolError, } from './connectorProtocol.js';
 import { ABLO_HOSTED_HTTP_BASE_URL } from '../client/hostedEndpoints.js';
-/** Default Ablo Cloud base. The connector appends `SOURCE_CONNECTOR_WS_PATH`.
- *  Single-sourced from the dependency-free hosted-endpoints leaf. */
+/**
+ * The default Ablo base URL the connector dials, to which it appends
+ * `SOURCE_CONNECTOR_WS_PATH`.
+ */
 const DEFAULT_BASE_URL = ABLO_HOSTED_HTTP_BASE_URL;
 /**
- * Reconnect backoff, in ms, indexed by consecutive failed connect attempts.
- * Unlike the (multi-day) Standard Webhooks delivery schedule, a long-lived
- * control socket should re-establish quickly and cap at a steady interval, so
- * this is a short capped curve. The last entry repeats for further attempts. A
- * clean `ready` resets the counter to 0.
+ * The reconnect backoff, in milliseconds, indexed by the number of consecutive
+ * failed connect attempts. A long-lived control socket should recover quickly and
+ * then settle at a steady interval, so this is a short curve that caps rather than
+ * growing without bound. The final entry repeats for any further attempts, and a
+ * connection that reaches `ready` resets the count to zero.
  */
 export const DEFAULT_RECONNECT_SCHEDULE = [
     0, // immediate first reconnect
@@ -79,10 +79,10 @@ export function createSourceConnector(options) {
     };
 }
 /**
- * One connection lifecycle: open → register → serve drained requests until the
- * socket closes or `signal` aborts. Resolves to whether the connection reached
- * the `ready` state (used to reset reconnect backoff). Never rejects — transport
- * failures are normal and drive a reconnect.
+ * Runs one connection: open the socket, register, then serve requests until the
+ * socket closes or `signal` aborts. Resolves to whether the connection reached the
+ * `ready` state, which the caller uses to reset the reconnect backoff. It never
+ * rejects, because a dropped transport is expected and simply drives a reconnect.
  */
 function connectOnce(params) {
     return new Promise((resolve) => {
@@ -199,8 +199,8 @@ function connectOnce(params) {
             }
             catch (err) {
                 params.onError?.(err);
-                // Surface as a 500 so the server-side SourceClient treats it as a
-                // retryable failure, exactly like a webhook endpoint throwing.
+                // Surface this as a 500 so Ablo treats it as a retryable failure, exactly
+                // as it would a webhook endpoint that threw.
                 return {
                     type: 'response',
                     id: frame.id,

package/dist/source/connectorProtocol.d.ts

@@ -0,0 +1,160 @@
+/**
+ * The wire protocol for the Data Source reverse channel — the frames that travel
+ * over the WebSocket a connector opens to Ablo.
+ *
+ * The load, list, and commit leg of a Data Source normally arrives as an inbound
+ * webhook that Ablo posts to your HTTPS endpoint. That needs a public URL, so it
+ * cannot reach a handler running on localhost or inside a private network with no
+ * inbound path. The reverse channel flips the direction: the connector dials out
+ * to Ablo over a WebSocket and serves those same requests back over the open
+ * socket. This module defines the frames exchanged on that socket.
+ *
+ * The trust model does not change. A `request` frame carries the same signature
+ * headers (`webhook-id`, `webhook-timestamp`, `webhook-signature`) and the same
+ * raw body Ablo would have posted, so the connector verifies it through
+ * `verifyAbloSourceRequest` exactly as it would a webhook. Only the transport
+ * differs.
+ *
+ * Frames are validated with Zod as they arrive, the same discipline `contract.ts`
+ * applies to change sets: a malformed frame is rejected at the boundary, and both
+ * sides infer every wire type from one schema so they cannot silently drift.
+ */
+import { z } from 'zod';
+/**
+ * The wire-protocol version. It increases on any breaking change to a frame's
+ * shape, so a connector and server on mismatched versions fail fast during
+ * `register` rather than misparsing a frame later in the stream.
+ */
+export declare const SOURCE_CONNECTOR_PROTOCOL_VERSION = 1;
+/** The WebSocket path the connector dials, appended to its configured base URL. */
+export declare const SOURCE_CONNECTOR_WS_PATH = "/v1/source/listen";
+/**
+ * The WebSocket subprotocol that identifies a reverse-channel source connector,
+ * as opposed to the SDK's sync client, which uses `ablo.sync.v1`. During the
+ * handshake the server echoes back only this value and never the subprotocol that
+ * carries the credential, keeping the API key out of proxy and load-balancer logs.
+ */
+export declare const WS_SOURCE_SUBPROTOCOL = "ablo.source.v1";
+/**
+ * Builds the `Sec-WebSocket-Protocol` list a connector offers during the
+ * handshake: the source subprotocol followed by the bearer credential, encoded as
+ * `ablo.bearer.<apiKey>`. A WebSocket handshake cannot carry an `Authorization`
+ * header, so the API key rides as a subprotocol instead — the same mechanism the
+ * SDK's sync client uses, which the server reads back with `extractBearer`.
+ */
+export declare function sourceConnectorSubprotocols(apiKey: string): string[];
+/**
+ * The first frame the connector sends, right after the socket opens. The server
+ * has already authenticated the connection and resolved which source it serves
+ * from the API key in the handshake, so this frame only negotiates the protocol
+ * version and carries advisory metadata.
+ */
+export declare const registerFrameSchema: z.ZodObject<{
+    type: z.ZodLiteral<"register">;
+    protocolVersion: z.ZodNumber;
+    client: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type RegisterFrame = z.infer<typeof registerFrameSchema>;
+/**
+ * The server's acknowledgement of a successful `register`. It echoes the resolved
+ * source identity so the connector can confirm and log which source it is serving.
+ */
+export declare const readyFrameSchema: z.ZodObject<{
+    type: z.ZodLiteral<"ready">;
+    protocolVersion: z.ZodNumber;
+    sourceId: z.ZodOptional<z.ZodString>;
+    organizationId: z.ZodOptional<z.ZodString>;
+    environment: z.ZodOptional<z.ZodEnum<{
+        production: "production";
+        sandbox: "sandbox";
+    }>>;
+}, z.core.$strip>;
+export type ReadyFrame = z.infer<typeof readyFrameSchema>;
+/**
+ * A single load, list, or commit request the server forwards to the connector.
+ * Its `headers` and `body` are byte-for-byte what the inbound webhook path would
+ * have sent, so the connector can replay them into a `Request` and let the same
+ * handler verify the signature exactly as it would for a webhook.
+ */
+export declare const requestFrameSchema: z.ZodObject<{
+    type: z.ZodLiteral<"request">;
+    id: z.ZodString;
+    method: z.ZodLiteral<"POST">;
+    url: z.ZodString;
+    headers: z.ZodRecord<z.ZodString, z.ZodString>;
+    body: z.ZodString;
+}, z.core.$strip>;
+export type RequestFrame = z.infer<typeof requestFrameSchema>;
+/**
+ * The handler's response to one `request` frame, sent back by the connector. The
+ * server matches it to the pending request by `id` and treats its `status` and
+ * `body` as though an HTTP response had returned.
+ */
+export declare const responseFrameSchema: z.ZodObject<{
+    type: z.ZodLiteral<"response">;
+    id: z.ZodString;
+    status: z.ZodNumber;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    body: z.ZodString;
+}, z.core.$strip>;
+export type ResponseFrame = z.infer<typeof responseFrameSchema>;
+/**
+ * An error either side can send for a failure that is not a normal request
+ * result, such as a rejected credential, an unsupported protocol version, or a
+ * malformed frame. When `id` is set the error belongs to that pending request and
+ * fails it; without an `id` it is a connection-level error.
+ */
+export declare const errorFrameSchema: z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    id: z.ZodOptional<z.ZodString>;
+    code: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>;
+export type ErrorFrame = z.infer<typeof errorFrameSchema>;
+export declare const connectorFrameSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"register">;
+    protocolVersion: z.ZodNumber;
+    client: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ready">;
+    protocolVersion: z.ZodNumber;
+    sourceId: z.ZodOptional<z.ZodString>;
+    organizationId: z.ZodOptional<z.ZodString>;
+    environment: z.ZodOptional<z.ZodEnum<{
+        production: "production";
+        sandbox: "sandbox";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"request">;
+    id: z.ZodString;
+    method: z.ZodLiteral<"POST">;
+    url: z.ZodString;
+    headers: z.ZodRecord<z.ZodString, z.ZodString>;
+    body: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"response">;
+    id: z.ZodString;
+    status: z.ZodNumber;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    body: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    id: z.ZodOptional<z.ZodString>;
+    code: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>], "type">;
+export type ConnectorFrame = z.infer<typeof connectorFrameSchema>;
+/** Thrown when an incoming frame fails to parse or validate. */
+export declare class ConnectorProtocolError extends Error {
+    readonly code = "source_connector_protocol_error";
+    constructor(message: string);
+}
+/** Serialize a frame for transmission. */
+export declare function encodeFrame(frame: ConnectorFrame): string;
+/**
+ * Parses and validates one incoming frame. It accepts either the string or the
+ * binary payloads a WebSocket `message` event can deliver, and throws
+ * {@link ConnectorProtocolError} on any malformed or unrecognized frame so the
+ * caller can reject the connection instead of acting on bad data.
+ */
+export declare function decodeFrame(raw: string | ArrayBuffer | Uint8Array): ConnectorFrame;

package/dist/source/connectorProtocol.js

@@ -0,0 +1,162 @@
+/**
+ * The wire protocol for the Data Source reverse channel — the frames that travel
+ * over the WebSocket a connector opens to Ablo.
+ *
+ * The load, list, and commit leg of a Data Source normally arrives as an inbound
+ * webhook that Ablo posts to your HTTPS endpoint. That needs a public URL, so it
+ * cannot reach a handler running on localhost or inside a private network with no
+ * inbound path. The reverse channel flips the direction: the connector dials out
+ * to Ablo over a WebSocket and serves those same requests back over the open
+ * socket. This module defines the frames exchanged on that socket.
+ *
+ * The trust model does not change. A `request` frame carries the same signature
+ * headers (`webhook-id`, `webhook-timestamp`, `webhook-signature`) and the same
+ * raw body Ablo would have posted, so the connector verifies it through
+ * `verifyAbloSourceRequest` exactly as it would a webhook. Only the transport
+ * differs.
+ *
+ * Frames are validated with Zod as they arrive, the same discipline `contract.ts`
+ * applies to change sets: a malformed frame is rejected at the boundary, and both
+ * sides infer every wire type from one schema so they cannot silently drift.
+ */
+import { z } from 'zod';
+import { WS_BEARER_SUBPROTOCOL_PREFIX } from '../auth/credentialSource.js';
+/**
+ * The wire-protocol version. It increases on any breaking change to a frame's
+ * shape, so a connector and server on mismatched versions fail fast during
+ * `register` rather than misparsing a frame later in the stream.
+ */
+export const SOURCE_CONNECTOR_PROTOCOL_VERSION = 1;
+/** The WebSocket path the connector dials, appended to its configured base URL. */
+export const SOURCE_CONNECTOR_WS_PATH = '/v1/source/listen';
+/**
+ * The WebSocket subprotocol that identifies a reverse-channel source connector,
+ * as opposed to the SDK's sync client, which uses `ablo.sync.v1`. During the
+ * handshake the server echoes back only this value and never the subprotocol that
+ * carries the credential, keeping the API key out of proxy and load-balancer logs.
+ */
+export const WS_SOURCE_SUBPROTOCOL = 'ablo.source.v1';
+/**
+ * Builds the `Sec-WebSocket-Protocol` list a connector offers during the
+ * handshake: the source subprotocol followed by the bearer credential, encoded as
+ * `ablo.bearer.<apiKey>`. A WebSocket handshake cannot carry an `Authorization`
+ * header, so the API key rides as a subprotocol instead — the same mechanism the
+ * SDK's sync client uses, which the server reads back with `extractBearer`.
+ */
+export function sourceConnectorSubprotocols(apiKey) {
+    return [WS_SOURCE_SUBPROTOCOL, `${WS_BEARER_SUBPROTOCOL_PREFIX}${apiKey}`];
+}
+const headerRecord = z.record(z.string(), z.string());
+/**
+ * The first frame the connector sends, right after the socket opens. The server
+ * has already authenticated the connection and resolved which source it serves
+ * from the API key in the handshake, so this frame only negotiates the protocol
+ * version and carries advisory metadata.
+ */
+export const registerFrameSchema = z.object({
+    type: z.literal('register'),
+    protocolVersion: z.number().int(),
+    /**
+     * An optional client identifier, such as `@abloatai/ablo@0.12.0`, recorded in
+     * the server's logs. It is advisory only and never affects a decision.
+     */
+    client: z.string().optional(),
+});
+/**
+ * The server's acknowledgement of a successful `register`. It echoes the resolved
+ * source identity so the connector can confirm and log which source it is serving.
+ */
+export const readyFrameSchema = z.object({
+    type: z.literal('ready'),
+    protocolVersion: z.number().int(),
+    sourceId: z.string().optional(),
+    organizationId: z.string().optional(),
+    environment: z.enum(['production', 'sandbox']).optional(),
+});
+/**
+ * A single load, list, or commit request the server forwards to the connector.
+ * Its `headers` and `body` are byte-for-byte what the inbound webhook path would
+ * have sent, so the connector can replay them into a `Request` and let the same
+ * handler verify the signature exactly as it would for a webhook.
+ */
+export const requestFrameSchema = z.object({
+    type: z.literal('request'),
+    /** Correlation id; the matching `response` frame carries the same value. */
+    id: z.string().min(1),
+    method: z.literal('POST'),
+    /** Synthetic absolute URL used only to construct the `Request` object. */
+    url: z.string().min(1),
+    /** The signed webhook signature headers, plus `Content-Type`. */
+    headers: headerRecord,
+    /** Raw JSON request body — exactly the bytes that were signed. */
+    body: z.string(),
+});
+/**
+ * The handler's response to one `request` frame, sent back by the connector. The
+ * server matches it to the pending request by `id` and treats its `status` and
+ * `body` as though an HTTP response had returned.
+ */
+export const responseFrameSchema = z.object({
+    type: z.literal('response'),
+    id: z.string().min(1),
+    status: z.number().int(),
+    headers: headerRecord.optional(),
+    /** Raw JSON response body. */
+    body: z.string(),
+});
+/**
+ * An error either side can send for a failure that is not a normal request
+ * result, such as a rejected credential, an unsupported protocol version, or a
+ * malformed frame. When `id` is set the error belongs to that pending request and
+ * fails it; without an `id` it is a connection-level error.
+ */
+export const errorFrameSchema = z.object({
+    type: z.literal('error'),
+    id: z.string().min(1).optional(),
+    code: z.string().min(1),
+    message: z.string(),
+});
+export const connectorFrameSchema = z.discriminatedUnion('type', [
+    registerFrameSchema,
+    readyFrameSchema,
+    requestFrameSchema,
+    responseFrameSchema,
+    errorFrameSchema,
+]);
+/** Thrown when an incoming frame fails to parse or validate. */
+export class ConnectorProtocolError extends Error {
+    code = 'source_connector_protocol_error';
+    constructor(message) {
+        super(message);
+        this.name = 'ConnectorProtocolError';
+    }
+}
+/** Serialize a frame for transmission. */
+export function encodeFrame(frame) {
+    return JSON.stringify(frame);
+}
+/**
+ * Parses and validates one incoming frame. It accepts either the string or the
+ * binary payloads a WebSocket `message` event can deliver, and throws
+ * {@link ConnectorProtocolError} on any malformed or unrecognized frame so the
+ * caller can reject the connection instead of acting on bad data.
+ */
+export function decodeFrame(raw) {
+    const text = typeof raw === 'string' ? raw : decodeBinary(raw);
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new ConnectorProtocolError('Frame is not valid JSON');
+    }
+    const result = connectorFrameSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new ConnectorProtocolError(`Invalid connector frame: ${result.error.message}`);
+    }
+    return result.data;
+}
+function decodeBinary(raw) {
+    const bytes = raw instanceof Uint8Array ? raw : new Uint8Array(raw);
+    return new TextDecoder().decode(bytes);
+}

package/dist/source/contract.d.ts

@@ -1,19 +1,16 @@
 /**
- * Data Source adapter contract — Zod-first.
+ * Defines the data an ORM adapter exchanges with Ablo, expressed as Zod schemas
+ * rather than plain interfaces so every value is validated where it crosses the
+ * boundary. A malformed operation or outbox row is rejected at the edge instead of
+ * failing deep inside a transaction, and each TypeScript type is inferred from the
+ * one schema that validates it.
  *
- * The wire shapes an ORM adapter (Prisma/Drizzle/Kysely) consumes and produces
- * are defined here as Zod schemas, not hand-typed interfaces, so they are
- * VALIDATED at the boundary (a malformed op / outbox row is rejected at the
- * edge, not deep inside a transaction) and every inferred type flows from one
- * source. This mirrors the server's `tenant-connection.schema.ts` convention:
- * schema-validate what crosses a trust boundary, infer the TS types from it.
- *
- * Scope note: the existing `SourceOperation` / `SourceEvent` interfaces in
- * `index.ts` are the established cross-package wire types — this module does NOT
- * redefine them. It owns the ADAPTER-level contract (the change envelope the
- * adapter commits, the outbox row it persists, the migration it ships) and keeps
- * `operationSchema` structurally compatible with `SourceOperation` (asserted at
- * the bottom of the file) so the two never drift.
+ * These schemas describe the adapter's own contract: the change set it commits,
+ * the outbox row it stores, and the table migrations it ships. They do not
+ * redefine the shared `SourceOperation` and `SourceEvent` wire types, which live
+ * in `types.ts`; instead `operationSchema` is kept structurally compatible with
+ * `SourceOperation`, a compatibility the assertion at the end of this file proves
+ * at compile time so the schema and the interface cannot drift apart.
  */
 import { z } from 'zod';
 /** Mirrors `SourceOperation['type']`. */
@@ -26,8 +23,9 @@ export declare const operationTypeSchema: z.ZodEnum<{
 }>;
 export type OperationType = z.infer<typeof operationTypeSchema>;
 /**
- * One operation in a change set. Structurally compatible with `SourceOperation`
- * (see the assertion below) — this is its runtime validator.
+ * A single operation within a change set, and the runtime validator for it. It is
+ * structurally compatible with the shared `SourceOperation` type, as the assertion
+ * at the end of this file confirms.
  */
 export declare const operationSchema: z.ZodObject<{
     type: z.ZodEnum<{
@@ -50,9 +48,9 @@ export declare const operationSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type Operation = z.infer<typeof operationSchema>;
 /**
- * The atomic unit an adapter commits: one or more operations under a single
- * `clientTxId`. The `clientTxId` is the idempotency key — committing the same
- * change set twice must produce the same result exactly once.
+ * The unit an adapter commits atomically: one or more operations grouped under a
+ * single `clientTxId`. That `clientTxId` is the idempotency key, so committing the
+ * same change set twice applies it once and returns the same result.
  */
 export declare const changeSetSchema: z.ZodObject<{
     operations: z.ZodArray<z.ZodObject<{
@@ -78,10 +76,11 @@ export declare const changeSetSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type ChangeSet = z.infer<typeof changeSetSchema>;
 /**
- * A row in the adapter-owned `ablo_outbox` table. Written in the SAME
- * transaction as the app-row mutation (transactional outbox), then read back by
- * `events()` and handed to Ablo. `cursor` is the monotonic ordering key Ablo
- * round-trips to resume.
+ * A row in the adapter's `ablo_outbox` table. The adapter writes it in the same
+ * transaction as the underlying row change — the transactional-outbox pattern — so
+ * a change and its event commit together or not at all. The `events()` feed later
+ * reads these rows back and hands them to Ablo, and `cursor` is the monotonic
+ * ordering key Ablo round-trips to resume where it left off.
  */
 export declare const outboxEventSchema: z.ZodObject<{
     id: z.ZodString;
@@ -124,16 +123,16 @@ export declare const eventsPageSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type EventsPage = z.infer<typeof eventsPageSchema>;
 /**
- * A table-creation migration an adapter ships so a customer never hand-writes the
- * `ablo_idempotency` / `ablo_outbox` tables — the adapter returns them from
- * `migrations()`.
+ * A table-creation migration an adapter ships, so you never hand-write the
+ * `ablo_idempotency` and `ablo_outbox` tables yourself. An adapter returns these
+ * from its `migrations()` method.
  */
 export declare const migrationSchema: z.ZodObject<{
     name: z.ZodString;
     up: z.ZodString;
 }, z.core.$strip>;
 export type Migration = z.infer<typeof migrationSchema>;
-/** What an adapter's backend can do — a capability profile (no behavior inference). */
+/** Describes what an adapter's backend supports, so callers check a capability rather than infer it from behavior. */
 export declare const adapterCapabilitiesSchema: z.ZodObject<{
     transactions: z.ZodBoolean;
     propose: z.ZodBoolean;

package/dist/source/contract.js

@@ -1,19 +1,16 @@
 /**
- * Data Source adapter contract — Zod-first.
+ * Defines the data an ORM adapter exchanges with Ablo, expressed as Zod schemas
+ * rather than plain interfaces so every value is validated where it crosses the
+ * boundary. A malformed operation or outbox row is rejected at the edge instead of
+ * failing deep inside a transaction, and each TypeScript type is inferred from the
+ * one schema that validates it.
  *
- * The wire shapes an ORM adapter (Prisma/Drizzle/Kysely) consumes and produces
- * are defined here as Zod schemas, not hand-typed interfaces, so they are
- * VALIDATED at the boundary (a malformed op / outbox row is rejected at the
- * edge, not deep inside a transaction) and every inferred type flows from one
- * source. This mirrors the server's `tenant-connection.schema.ts` convention:
- * schema-validate what crosses a trust boundary, infer the TS types from it.
- *
- * Scope note: the existing `SourceOperation` / `SourceEvent` interfaces in
- * `index.ts` are the established cross-package wire types — this module does NOT
- * redefine them. It owns the ADAPTER-level contract (the change envelope the
- * adapter commits, the outbox row it persists, the migration it ships) and keeps
- * `operationSchema` structurally compatible with `SourceOperation` (asserted at
- * the bottom of the file) so the two never drift.
+ * These schemas describe the adapter's own contract: the change set it commits,
+ * the outbox row it stores, and the table migrations it ships. They do not
+ * redefine the shared `SourceOperation` and `SourceEvent` wire types, which live
+ * in `types.ts`; instead `operationSchema` is kept structurally compatible with
+ * `SourceOperation`, a compatibility the assertion at the end of this file proves
+ * at compile time so the schema and the interface cannot drift apart.
  */
 import { z } from 'zod';
 const jsonObject = z.record(z.string(), z.unknown());
@@ -26,8 +23,9 @@ export const operationTypeSchema = z.enum([
     'UNARCHIVE',
 ]);
 /**
- * One operation in a change set. Structurally compatible with `SourceOperation`
- * (see the assertion below) — this is its runtime validator.
+ * A single operation within a change set, and the runtime validator for it. It is
+ * structurally compatible with the shared `SourceOperation` type, as the assertion
+ * at the end of this file confirms.
  */
 export const operationSchema = z.object({
     type: operationTypeSchema,
@@ -39,19 +37,20 @@ export const operationSchema = z.object({
     onStale: z.enum(['reject', 'overwrite', 'notify']).nullish(),
 });
 /**
- * The atomic unit an adapter commits: one or more operations under a single
- * `clientTxId`. The `clientTxId` is the idempotency key — committing the same
- * change set twice must produce the same result exactly once.
+ * The unit an adapter commits atomically: one or more operations grouped under a
+ * single `clientTxId`. That `clientTxId` is the idempotency key, so committing the
+ * same change set twice applies it once and returns the same result.
  */
 export const changeSetSchema = z.object({
     operations: z.array(operationSchema).min(1),
     clientTxId: z.string().min(1),
 });
 /**
- * A row in the adapter-owned `ablo_outbox` table. Written in the SAME
- * transaction as the app-row mutation (transactional outbox), then read back by
- * `events()` and handed to Ablo. `cursor` is the monotonic ordering key Ablo
- * round-trips to resume.
+ * A row in the adapter's `ablo_outbox` table. The adapter writes it in the same
+ * transaction as the underlying row change — the transactional-outbox pattern — so
+ * a change and its event commit together or not at all. The `events()` feed later
+ * reads these rows back and hands them to Ablo, and `cursor` is the monotonic
+ * ordering key Ablo round-trips to resume where it left off.
  */
 export const outboxEventSchema = z.object({
     /** Stable, globally-unique id — Ablo's replay-protection key. */
@@ -61,7 +60,7 @@ export const outboxEventSchema = z.object({
     type: operationTypeSchema,
     data: jsonObject.nullish(),
     organizationId: z.string().nullish(),
-    /** Round-tripped so Ablo can filter SDK-origin echoes after a direct append. */
+    /** The originating transaction id, carried so Ablo can drop echoes of changes the SDK itself wrote. */
     clientTxId: z.string().nullish(),
     occurredAt: z.number().nullish(),
     /** Monotonic ordering key (bigint as string). `events()` pages by `cursor > ?`. */
@@ -73,9 +72,9 @@ export const eventsPageSchema = z.object({
     nextCursor: z.string().nullable(),
 });
 /**
- * A table-creation migration an adapter ships so a customer never hand-writes the
- * `ablo_idempotency` / `ablo_outbox` tables — the adapter returns them from
- * `migrations()`.
+ * A table-creation migration an adapter ships, so you never hand-write the
+ * `ablo_idempotency` and `ablo_outbox` tables yourself. An adapter returns these
+ * from its `migrations()` method.
  */
 export const migrationSchema = z.object({
     /** Stable name, used as the migration filename + applied-ledger key. */
@@ -83,11 +82,11 @@ export const migrationSchema = z.object({
     /** The forward SQL. */
     up: z.string().min(1),
 });
-/** What an adapter's backend can do — a capability profile (no behavior inference). */
+/** Describes what an adapter's backend supports, so callers check a capability rather than infer it from behavior. */
 export const adapterCapabilitiesSchema = z.object({
     /** `commit` is atomic across all operations in the change set. */
     transactions: z.boolean(),
-    /** A dry-run `propose` is supported (else proposal lives above the adapter). */
+    /** A dry-run `propose` is available; when false, proposing a change happens before the adapter is called. */
     propose: z.boolean(),
     /** The backend can be introspected for its schema. */
     schemaIntrospection: z.boolean(),