@abloatai/transaction 0.37.0

package/dist/source/connectorProtocol.js

@@ -0,0 +1,164 @@
+/**
+ * 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 { environmentSchema } from '../environment.js';
+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: environmentSchema.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);
+}
+//# sourceMappingURL=connectorProtocol.js.map

package/dist/source/connectorProtocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connectorProtocol.js","sourceRoot":"","sources":["../../src/source/connectorProtocol.ts"],"names":[],"mappings":"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"}

package/dist/source/contract.d.ts

@@ -0,0 +1,196 @@
+/**
+ * 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.
+ *
+ * These schemas describe the adapter's own contract: the change set it commits,
+ * the outbox row it stores, and the table migrations it ships. The operation
+ * vocabulary is not restated here — `operationSchema` is projected from the
+ * core's `commitOperationSchema`, so an action or field added to the commit
+ * contract reaches a data source by construction. The assertion at the end of
+ * this file then pins the published `SourceOperation` interface to that
+ * projection, which is what keeps the interface tied to the core rather than
+ * merely tied to a second local copy of it.
+ */
+import { z } from 'zod';
+/**
+ * Served, not mirrored. The commit vocabulary is declared once in the core; a
+ * data source speaks the same five actions, so it re-exports them rather than
+ * listing them again under a second name.
+ */
+export declare const operationTypeSchema: z.ZodEnum<{
+    CREATE: "CREATE";
+    UPDATE: "UPDATE";
+    DELETE: "DELETE";
+    ARCHIVE: "ARCHIVE";
+    UNARCHIVE: "UNARCHIVE";
+}>;
+export type OperationType = z.infer<typeof operationTypeSchema>;
+/**
+ * A single operation within a change set, and the runtime validator for it.
+ *
+ * The field set is projected from `commitOperationSchema` — an operation
+ * reaching a data source is a commit operation minus the two fields the core
+ * settles internally (`bypass`, `fenceToken`). The two `min(1)` overrides are
+ * deliberate and local: this is a customer-implemented boundary, so an empty
+ * model name or row id is rejected here rather than forwarded. Stating them as
+ * an extension keeps the tightening visible as a choice instead of hiding it
+ * inside a second copy of the shape.
+ */
+export declare const operationSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        CREATE: "CREATE";
+        UPDATE: "UPDATE";
+        DELETE: "DELETE";
+        ARCHIVE: "ARCHIVE";
+        UNARCHIVE: "UNARCHIVE";
+    }>;
+    readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        reject: "reject";
+        overwrite: "overwrite";
+        notify: "notify";
+    }>>>;
+    transactionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    model: z.ZodString;
+    id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    input: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, z.core.$strip>;
+export type Operation = z.infer<typeof operationSchema>;
+/** The supported customer-transaction echo mechanism. */
+export declare const sourceCommitEchoSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"postgres-wal">;
+    payload: z.ZodString;
+}, z.core.$strip>;
+export declare const sourceCommitEchoOperationSchema: z.ZodObject<{
+    model: z.ZodString;
+    id: z.ZodString;
+    action: z.ZodEnum<{
+        I: "I";
+        U: "U";
+        D: "D";
+    }>;
+    transactionId: z.ZodString;
+}, z.core.$strict>;
+export declare const sourceCommitEchoMarkerSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    correlationId: z.ZodString;
+    operations: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        model: z.ZodString;
+        id: z.ZodString;
+        action: z.ZodEnum<{
+            I: "I";
+            U: "U";
+            D: "D";
+        }>;
+        transactionId: z.ZodString;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type SourceCommitEchoMarkerWire = z.infer<typeof sourceCommitEchoMarkerSchema>;
+/**
+ * The unit a mutation wrapper commits atomically. `correlationId` is derived by
+ * Ablo from the authenticated plane, participant, and public idempotency key; it
+ * is the customer-ledger identity. It is intentionally not a raw caller-authored
+ * `clientTxId` or an operation transaction id.
+ */
+export declare const changeSetSchema: z.ZodObject<{
+    operations: z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            CREATE: "CREATE";
+            UPDATE: "UPDATE";
+            DELETE: "DELETE";
+            ARCHIVE: "ARCHIVE";
+            UNARCHIVE: "UNARCHIVE";
+        }>;
+        readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            reject: "reject";
+            overwrite: "overwrite";
+            notify: "notify";
+        }>>>;
+        transactionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        model: z.ZodString;
+        id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        input: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    }, z.core.$strip>>;
+    correlationId: z.ZodString;
+    intentHash: z.ZodOptional<z.ZodString>;
+    echo: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodLiteral<"postgres-wal">;
+        payload: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ChangeSet = z.infer<typeof changeSetSchema>;
+/**
+ * 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;
+    model: z.ZodString;
+    entityId: z.ZodString;
+    type: z.ZodEnum<{
+        CREATE: "CREATE";
+        UPDATE: "UPDATE";
+        DELETE: "DELETE";
+        ARCHIVE: "ARCHIVE";
+        UNARCHIVE: "UNARCHIVE";
+    }>;
+    data: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    organizationId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    clientTxId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    correlationId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    transactionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    occurredAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    cursor: z.ZodString;
+}, z.core.$strip>;
+export type OutboxEvent = z.infer<typeof outboxEventSchema>;
+/** A page of outbox events returned by `events()`. */
+export declare const eventsPageSchema: z.ZodObject<{
+    events: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        model: z.ZodString;
+        entityId: z.ZodString;
+        type: z.ZodEnum<{
+            CREATE: "CREATE";
+            UPDATE: "UPDATE";
+            DELETE: "DELETE";
+            ARCHIVE: "ARCHIVE";
+            UNARCHIVE: "UNARCHIVE";
+        }>;
+        data: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        organizationId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        clientTxId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        correlationId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        transactionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        occurredAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        cursor: z.ZodString;
+    }, z.core.$strip>>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type EventsPage = z.infer<typeof eventsPageSchema>;
+/**
+ * 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>;
+/** 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;
+    schemaIntrospection: z.ZodBoolean;
+    postgresWalEcho: z.ZodOptional<z.ZodBoolean>;
+    outboxEvents: z.ZodBoolean;
+}, z.core.$strip>;
+export type AdapterCapabilities = z.infer<typeof adapterCapabilitiesSchema>;
+//# sourceMappingURL=contract.d.ts.map

package/dist/source/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/source/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAiBxB;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;;;;EAA4B,CAAC;AAC7D,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;iBAMxB,CAAC;AACL,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,yDAAyD;AACzD,eAAO,MAAM,sBAAsB;;;iBASjC,CAAC;AAEH,eAAO,MAAM,+BAA+B;;;;;;;;;kBAK1C,CAAC;AAEH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;kBAsBrC,CAAC;AACL,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAEtF;;;;;GAKG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;iBAK1B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;iBAqB5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,sDAAsD;AACtD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;iBAG3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;;;GAIG;AACH,eAAO,MAAM,eAAe;;;iBAK1B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,sHAAsH;AACtH,eAAO,MAAM,yBAAyB;;;;;;iBAWpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC"}

package/dist/source/contract.js

@@ -0,0 +1,165 @@
+/**
+ * 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.
+ *
+ * These schemas describe the adapter's own contract: the change set it commits,
+ * the outbox row it stores, and the table migrations it ships. The operation
+ * vocabulary is not restated here — `operationSchema` is projected from the
+ * core's `commitOperationSchema`, so an action or field added to the commit
+ * contract reaches a data source by construction. The assertion at the end of
+ * this file then pins the published `SourceOperation` interface to that
+ * projection, which is what keeps the interface tied to the core rather than
+ * merely tied to a second local copy of it.
+ */
+import { z } from 'zod';
+import { correlationIdSchema } from '../wire/commit.js';
+import { commitOperationSchema, commitOperationTypeSchema, } from '../coordination/schema.js';
+import { ABLO_SOURCE_CLIENT_TX_ID_MAX_LENGTH, ABLO_SOURCE_ECHO_MAX_OPERATIONS, ABLO_SOURCE_ECHO_MAX_PAYLOAD_BYTES, } from './types.js';
+const jsonObject = z.record(z.string(), z.unknown());
+/**
+ * Served, not mirrored. The commit vocabulary is declared once in the core; a
+ * data source speaks the same five actions, so it re-exports them rather than
+ * listing them again under a second name.
+ */
+export const operationTypeSchema = commitOperationTypeSchema;
+/**
+ * A single operation within a change set, and the runtime validator for it.
+ *
+ * The field set is projected from `commitOperationSchema` — an operation
+ * reaching a data source is a commit operation minus the two fields the core
+ * settles internally (`bypass`, `fenceToken`). The two `min(1)` overrides are
+ * deliberate and local: this is a customer-implemented boundary, so an empty
+ * model name or row id is rejected here rather than forwarded. Stating them as
+ * an extension keeps the tightening visible as a choice instead of hiding it
+ * inside a second copy of the shape.
+ */
+export const operationSchema = commitOperationSchema
+    .omit({ bypass: true, fenceToken: true })
+    .extend({
+    model: z.string().min(1),
+    id: z.string().min(1).nullish(),
+    input: jsonObject.nullish(),
+});
+/** The supported customer-transaction echo mechanism. */
+export const sourceCommitEchoSchema = z.object({
+    kind: z.literal('postgres-wal'),
+    payload: z
+        .string()
+        .min(1)
+        .refine((value) => new TextEncoder().encode(value).byteLength <= ABLO_SOURCE_ECHO_MAX_PAYLOAD_BYTES, `WAL echo payload exceeds ${ABLO_SOURCE_ECHO_MAX_PAYLOAD_BYTES} UTF-8 bytes`),
+});
+export const sourceCommitEchoOperationSchema = z.strictObject({
+    model: z.string().min(1),
+    id: z.string().min(1),
+    action: z.enum(['I', 'U', 'D']),
+    transactionId: z.string().min(1).max(ABLO_SOURCE_CLIENT_TX_ID_MAX_LENGTH),
+});
+export const sourceCommitEchoMarkerSchema = z
+    .strictObject({
+    version: z.literal(1),
+    correlationId: correlationIdSchema,
+    operations: z
+        .array(sourceCommitEchoOperationSchema)
+        .min(1)
+        .max(ABLO_SOURCE_ECHO_MAX_OPERATIONS)
+        .readonly(),
+})
+    .superRefine(({ operations }, ctx) => {
+    const seen = new Set();
+    for (const [index, operation] of operations.entries()) {
+        if (seen.has(operation.transactionId)) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['operations', index, 'transactionId'],
+                message: 'WAL echo operation transactionIds must be unique',
+            });
+        }
+        seen.add(operation.transactionId);
+    }
+});
+/**
+ * The unit a mutation wrapper commits atomically. `correlationId` is derived by
+ * Ablo from the authenticated plane, participant, and public idempotency key; it
+ * is the customer-ledger identity. It is intentionally not a raw caller-authored
+ * `clientTxId` or an operation transaction id.
+ */
+export const changeSetSchema = z.object({
+    operations: z.array(operationSchema).min(1),
+    correlationId: correlationIdSchema,
+    intentHash: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+    echo: sourceCommitEchoSchema.optional(),
+});
+/**
+ * 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. */
+    id: z.string().min(1),
+    model: z.string().min(1),
+    entityId: z.string().min(1),
+    type: operationTypeSchema,
+    data: jsonObject.nullish(),
+    organizationId: z.string().nullish(),
+    /** Legacy source transaction id. Never use this field to settle a queued commit. */
+    clientTxId: z.string().nullish(),
+    /** Scoped server-authored identity that correlates this event to a queued commit. */
+    correlationId: correlationIdSchema.nullish(),
+    /** Stable identity of this operation within the correlated source commit. */
+    transactionId: z
+        .string()
+        .min(1)
+        .max(ABLO_SOURCE_CLIENT_TX_ID_MAX_LENGTH)
+        .nullish(),
+    occurredAt: z.number().nullish(),
+    /** Monotonic ordering key (bigint as string). `events()` pages by `cursor > ?`. */
+    cursor: z.string().min(1),
+});
+/** A page of outbox events returned by `events()`. */
+export const eventsPageSchema = z.object({
+    events: z.array(outboxEventSchema),
+    nextCursor: z.string().nullable(),
+});
+/**
+ * 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. */
+    name: z.string().min(1),
+    /** The forward SQL. */
+    up: z.string().min(1),
+});
+/** 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 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(),
+    /** The adapter can atomically emit the requested Postgres WAL marker. */
+    postgresWalEcho: z.boolean().optional(),
+    /** The wrapper atomically writes and serves an endpoint transactional outbox. */
+    outboxEvents: z.boolean(),
+});
+const _operationContractInSync = [
+    true,
+    true,
+];
+void _operationContractInSync;
+const _echoContractInSync = [
+    true,
+    true,
+];
+void _echoContractInSync;
+const _echoMarkerContractInSync = [true, true];
+void _echoMarkerContractInSync;
+//# sourceMappingURL=contract.js.map

package/dist/source/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/source/contract.ts"],"names":[],"mappings":"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"}

package/dist/source/drizzle.d.ts

@@ -0,0 +1,2 @@
+export * from './adapters/drizzle.js';
+//# sourceMappingURL=drizzle.d.ts.map

package/dist/source/drizzle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drizzle.d.ts","sourceRoot":"","sources":["../../src/source/drizzle.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC"}

package/dist/source/drizzle.js

@@ -0,0 +1,2 @@
+export * from './adapters/drizzle.js';
+//# sourceMappingURL=drizzle.js.map

package/dist/source/drizzle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"drizzle.js","sourceRoot":"","sources":["../../src/source/drizzle.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC"}

package/dist/source/factory.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Builds the request handler returned by `dataSource()`. Given your options —
+ * the schema, the API key, and either
+ * per-model handlers or an ORM adapter — the handler verifies each signed request,
+ * enforces the per-key scopes, and routes the four wire operations (`load`,
+ * `list`, `commit`, and `events`) to whichever handlers you configured.
+ */
+import type { Schema, SchemaRecord, InferCreate } from '../schema/schema.js';
+import type { DataSourceAdapter } from './adapter.js';
+import type { SourceApiKey, SourceAuthorizeContext, SourceCommitHandler, SourceEventsHandler, SourceModelHandlers, SourceRequest, SourceScope } from './types.js';
+type SourceModels<S extends SchemaRecord, TAuth> = Partial<{
+    readonly [K in keyof S & string]: SourceModelHandlers<InferCreate<Schema<S>, K> & {
+        readonly id: string;
+    } & Record<string, unknown>, InferCreate<Schema<S>, K>, TAuth>;
+}>;
+export type DataSourceOptions<S extends SchemaRecord, TAuth = unknown> = {
+    readonly schema: Schema<S>;
+    /**
+     * Your Ablo project credential. Ablo signs each Data Source call with the same
+     * project API key your server-side SDK already uses, so your environment holds a
+     * single Ablo credential and every request is signature-verified before any
+     * handler runs.
+     */
+    readonly apiKey: SourceApiKey;
+    /**
+     * How much clock skew to tolerate when verifying a request's signed timestamp.
+     * Defaults to five minutes.
+     */
+    readonly signatureToleranceMs?: number;
+    /**
+     * Attaches your own context to a verified request and returns it — for example a
+     * database handle, an account scope, or the current actor. Keep database
+     * credentials inside this function's environment and never send them to Ablo. The
+     * signature has already been checked against `apiKey` by the time this runs, so
+     * `authorize` only needs to supply business context, not re-verify the caller.
+     */
+    readonly authorize?: (context: SourceAuthorizeContext) => Promise<TAuth> | TAuth;
+    /**
+     * Resolves the set of operations a request's key may perform. When you provide
+     * it, the handler checks the operation the request is asking for (`load`, `list`,
+     * `commit`, or `events`) against the returned set and responds 403
+     * `source_forbidden` if it is not allowed, before any model handler runs. A
+     * typical implementation reads a key id from the request — a `webhook-id` prefix,
+     * a custom header, or the API key itself — and looks that key's scopes up in your
+     * store. Omit it to allow every operation; return an empty set to deny them all.
+     */
+    readonly resolveScopes?: (params: {
+        readonly auth: TAuth;
+        readonly request: Request;
+        readonly body: SourceRequest;
+    }) => Promise<ReadonlySet<SourceScope> | readonly SourceScope[]> | ReadonlySet<SourceScope> | readonly SourceScope[];
+    /**
+     * Handles a commit atomically across every model it touches. Prefer this in real
+     * applications: a single user action can change several models at once and should
+     * run inside one transaction you control.
+     */
+    readonly commit?: SourceCommitHandler<TAuth>;
+    /**
+     * Reports changes that happened outside the SDK — cron jobs, dashboard edits,
+     * batch imports — which Ablo polls for. Each event you return becomes a delta and
+     * fans out to connected clients. You can return your outbox rows directly: Ablo
+     * dedupes on stable `event.id`, appends the authoritative event, and uses a
+     * server-authored `correlationId` plus per-operation `transactionId` to settle
+     * the matching queued write. Store both fields for mediated endpoint commits.
+     */
+    readonly events?: SourceEventsHandler<TAuth>;
+    /**
+     * Groups per-model handlers under a `models` key. The spread form below is
+     * usually shorter — `dataSource({ schema, files: { load, list, commit } })` —
+     * but this explicit form is available when you prefer it.
+     */
+    readonly models?: SourceModels<S, TAuth>;
+    /**
+     * An ORM adapter, such as `prismaDataSource(prisma, schema)`. When set, it serves
+     * all four operations on its own — reads for `load` and `list`, an idempotent
+     * `commit` backed by the outbox, and `events` — so you write no handlers by hand.
+     * Because rows travel as JSON, the adapter is applied at a single generic
+     * dispatch point and needs no per-model types. Use either an adapter or
+     * hand-written handlers, not both.
+     */
+    readonly adapter?: DataSourceAdapter;
+} & SourceModels<S, TAuth>;
+/**
+ * Creates a Data Source endpoint you host in front of your own database.
+ *
+ * Your application code still reads and writes through Ablo, as in
+ * `ablo.files.load`, `.list`, and `.update`. This helper is for keeping the
+ * canonical rows in your database: Ablo calls a narrow, signed endpoint you
+ * control rather than holding your database credentials.
+ */
+export declare function dataSource<const S extends SchemaRecord, TAuth = unknown>(options: DataSourceOptions<S, TAuth>): (request: Request) => Promise<Response>;
+export {};
+//# sourceMappingURL=factory.d.ts.map

package/dist/source/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/source/factory.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,MAAM,EACN,YAAY,EACZ,WAAW,EACZ,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAOtD,OAAO,KAAK,EACV,YAAY,EACZ,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EAInB,mBAAmB,EAEnB,aAAa,EAEb,WAAW,EACZ,MAAM,YAAY,CAAC;AAEpB,KAAK,YAAY,CAAC,CAAC,SAAS,YAAY,EAAE,KAAK,IAAI,OAAO,CAAC;IACzD,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM,GAAG,mBAAmB,CACnD,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7E,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EACzB,KAAK,CACN;CACF,CAAC,CAAC;AAEH,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,YAAY,EAAE,KAAK,GAAG,OAAO,IAAI;IACvE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CACnB,OAAO,EAAE,sBAAsB,KAC5B,OAAO,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC;IAC5B;;;;;;;;OAQG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE;QAChC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;QACrB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;QAC1B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;KAC9B,KAAK,OAAO,CAAC,WAAW,CAAC,WAAW,CAAC,GAAG,SAAS,WAAW,EAAE,CAAC,GAC9D,WAAW,CAAC,WAAW,CAAC,GAAG,SAAS,WAAW,EAAE,CAAC;IACpD;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAC7C;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAC7C;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IACzC;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,iBAAiB,CAAC;CACtC,GAAG,YAAY,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;AAuK3B;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,CAAC,CAAC,SAAS,YAAY,EAAE,KAAK,GAAG,OAAO,EACtE,OAAO,EAAE,iBAAiB,CAAC,CAAC,EAAE,KAAK,CAAC,GACnC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CA0JzC"}