@abloatai/ablo 0.7.0 → 0.9.0

package/dist/source/conformance.js

@@ -0,0 +1,134 @@
+/**
+ * Data Source adapter conformance suite — the shared "is this adapter correct?"
+ * test set, in the Auth.js `@auth/adapter-test` mould. Every ORM adapter
+ * (Prisma/Drizzle/Kysely) and any hand-written handler runs THIS to prove,
+ * before production, the guarantees the spine promises. A new adapter is "done"
+ * when it passes — not when it compiles.
+ *
+ * Runner-agnostic: checks are plain async functions that throw (node:assert) on
+ * failure. `runDataSourceTests` registers them with whatever `it`/`test` you
+ * pass, so it works under vitest, jest, or node:test:
+ *
+ *   import { it } from 'vitest';
+ *   runDataSourceTests(memoryDataSource, it);
+ *
+ * Scope: this covers the ADAPTER contract (commit idempotency, read-after-write,
+ * the transactional outbox + cursor). Signature/scope rejection is a HANDLER
+ * concern (the adapter never sees a signature) and is tested separately.
+ */
+import assert from 'node:assert/strict';
+const change = (clientTxId, ops) => ({
+    clientTxId,
+    operations: ops,
+});
+export function dataSourceConformanceChecks(make) {
+    return [
+        {
+            name: 'commit applies a CREATE and returns the canonical row',
+            run: async () => {
+                const adapter = await make();
+                const result = await adapter.commit(change('tx_create', [{ type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } }]));
+                assert.equal(result.rows.length, 1, 'one row returned');
+                assert.equal(result.rows[0].id, 't1');
+                assert.equal(result.rows[0].title, 'A');
+            },
+        },
+        {
+            name: 'read load returns a committed row, and null-equivalent for an unknown id',
+            run: async () => {
+                const adapter = await make();
+                await adapter.commit(change('tx1', [{ type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } }]));
+                const found = await adapter.read({ kind: 'load', model: 'task', id: 't1' });
+                assert.equal(found.length, 1);
+                assert.equal(found[0].title, 'A');
+                const missing = await adapter.read({ kind: 'load', model: 'task', id: 'nope' });
+                assert.equal(missing.length, 0, 'unknown id reads empty');
+            },
+        },
+        {
+            name: 'read list returns committed rows',
+            run: async () => {
+                const adapter = await make();
+                await adapter.commit(change('tx_list', [
+                    { type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } },
+                    { type: 'CREATE', model: 'task', id: 't2', input: { title: 'B' } },
+                ]));
+                const rows = await adapter.read({ kind: 'list', model: 'task' });
+                const ids = rows.map((r) => r.id).sort();
+                assert.deepEqual(ids, ['t1', 't2']);
+            },
+        },
+        {
+            name: 'duplicate clientTxId is idempotent — same rows, applied once',
+            run: async () => {
+                const adapter = await make();
+                const cs = change('tx_dup', [{ type: 'CREATE', model: 'task', id: 't1', input: { title: 'A', n: 1 } }]);
+                const first = await adapter.commit(cs);
+                const second = await adapter.commit(cs);
+                assert.deepEqual(second.rows, first.rows, 'replay returns the original rows');
+                // Applied once: still exactly one row, and the outbox did not double up.
+                const rows = await adapter.read({ kind: 'list', model: 'task' });
+                assert.equal(rows.length, 1, 'no duplicate row');
+                const page = await adapter.events(null, 100);
+                const forTx = page.events.filter((e) => e.clientTxId === 'tx_dup');
+                assert.equal(forTx.length, 1, 'outbox not double-appended on replay');
+            },
+        },
+        {
+            name: 'commit appends outbox events with the originating clientTxId',
+            run: async () => {
+                const adapter = await make();
+                await adapter.commit(change('tx_evt', [{ type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } }]));
+                const page = await adapter.events(null, 100);
+                assert.ok(page.events.length >= 1, 'at least one event');
+                const evt = page.events.find((e) => e.entityId === 't1');
+                assert.ok(evt, 'event for the committed row');
+                assert.equal(evt?.model, 'task');
+                assert.equal(evt?.type, 'CREATE');
+                assert.equal(evt?.clientTxId, 'tx_evt');
+            },
+        },
+        {
+            name: 'events cursor advances and never re-delivers a page',
+            run: async () => {
+                const adapter = await make();
+                await adapter.commit(change('tx_a', [{ type: 'CREATE', model: 'task', id: 't1', input: {} }]));
+                await adapter.commit(change('tx_b', [{ type: 'CREATE', model: 'task', id: 't2', input: {} }]));
+                const first = await adapter.events(null, 1);
+                assert.equal(first.events.length, 1, 'respects limit');
+                assert.ok(first.nextCursor, 'returns a cursor');
+                const second = await adapter.events(first.nextCursor, 100);
+                // No overlap: the second page starts strictly after the first cursor.
+                const firstIds = new Set(first.events.map((e) => e.id));
+                for (const e of second.events) {
+                    assert.ok(!firstIds.has(e.id), `event ${e.id} re-delivered across cursor`);
+                }
+                // Draining to the end yields a stable terminal cursor.
+                const drained = await adapter.events(second.nextCursor ?? first.nextCursor, 100);
+                assert.equal(drained.events.length, 0, 'fully drained');
+            },
+        },
+        {
+            name: 'a later UPDATE under a new clientTxId is applied (idempotency is per-tx)',
+            run: async () => {
+                const adapter = await make();
+                await adapter.commit(change('tx_c1', [{ type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } }]));
+                await adapter.commit(change('tx_u1', [{ type: 'UPDATE', model: 'task', id: 't1', input: { title: 'B' } }]));
+                const found = await adapter.read({ kind: 'load', model: 'task', id: 't1' });
+                assert.equal(found[0].title, 'B', 'update applied');
+            },
+        },
+    ];
+}
+/**
+ * Register the conformance checks with a test runner's `it`/`test` function.
+ * `register(name, fn)` — pass vitest/jest `it` or `node:test` `test`.
+ */
+export function runDataSourceTests(make, register) {
+    for (const check of dataSourceConformanceChecks(make)) {
+        register(check.name, check.run);
+    }
+}
+// Re-export the reference adapter so `@abloatai/ablo/source/conformance`
+// exposes both the suite and the in-memory double in one import.
+export { memoryDataSource } from './adapters/memory.js';

package/dist/source/contract.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Data Source adapter contract — Zod-first.
+ *
+ * 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.
+ */
+import { z } from 'zod';
+/** Mirrors `SourceOperation['type']`. */
+export declare const operationTypeSchema: z.ZodEnum<{
+    CREATE: "CREATE";
+    UPDATE: "UPDATE";
+    DELETE: "DELETE";
+    ARCHIVE: "ARCHIVE";
+    UNARCHIVE: "UNARCHIVE";
+}>;
+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.
+ */
+export declare const operationSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        CREATE: "CREATE";
+        UPDATE: "UPDATE";
+        DELETE: "DELETE";
+        ARCHIVE: "ARCHIVE";
+        UNARCHIVE: "UNARCHIVE";
+    }>;
+    model: z.ZodString;
+    id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    input: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    transactionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        reject: "reject";
+        force: "force";
+        flag: "flag";
+        merge: "merge";
+    }>>>;
+}, 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.
+ */
+export declare const changeSetSchema: z.ZodObject<{
+    operations: z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            CREATE: "CREATE";
+            UPDATE: "UPDATE";
+            DELETE: "DELETE";
+            ARCHIVE: "ARCHIVE";
+            UNARCHIVE: "UNARCHIVE";
+        }>;
+        model: z.ZodString;
+        id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        input: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        transactionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            reject: "reject";
+            force: "force";
+            flag: "flag";
+            merge: "merge";
+        }>>>;
+    }, z.core.$strip>>;
+    clientTxId: z.ZodString;
+}, 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.
+ */
+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>>;
+    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>>;
+        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 DDL migration an adapter ships so a customer never hand-writes the
+ * `ablo_idempotency` / `ablo_outbox` tables — `ablo init` emits these.
+ */
+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). */
+export declare const adapterCapabilitiesSchema: z.ZodObject<{
+    transactions: z.ZodBoolean;
+    propose: z.ZodBoolean;
+    schemaIntrospection: z.ZodBoolean;
+}, z.core.$strip>;
+export type AdapterCapabilities = z.infer<typeof adapterCapabilitiesSchema>;

package/dist/source/contract.js

@@ -0,0 +1,98 @@
+/**
+ * Data Source adapter contract — Zod-first.
+ *
+ * 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.
+ */
+import { z } from 'zod';
+const jsonObject = z.record(z.string(), z.unknown());
+/** Mirrors `SourceOperation['type']`. */
+export const operationTypeSchema = z.enum([
+    'CREATE',
+    'UPDATE',
+    'DELETE',
+    'ARCHIVE',
+    'UNARCHIVE',
+]);
+/**
+ * One operation in a change set. Structurally compatible with `SourceOperation`
+ * (see the assertion below) — this is its runtime validator.
+ */
+export const operationSchema = z.object({
+    type: operationTypeSchema,
+    model: z.string().min(1),
+    id: z.string().min(1).nullish(),
+    input: jsonObject.nullish(),
+    transactionId: z.string().nullish(),
+    readAt: z.number().nullish(),
+    onStale: z.enum(['reject', 'force', 'flag', 'merge']).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.
+ */
+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.
+ */
+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(),
+    /** Round-tripped so Ablo can filter SDK-origin echoes after a direct append. */
+    clientTxId: z.string().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 DDL migration an adapter ships so a customer never hand-writes the
+ * `ablo_idempotency` / `ablo_outbox` tables — `ablo init` emits these.
+ */
+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),
+});
+/** What an adapter's backend can do — a capability profile (no behavior inference). */
+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). */
+    propose: z.boolean(),
+    /** The backend can be introspected for its schema. */
+    schemaIntrospection: z.boolean(),
+});
+const _operationContractInSync = [
+    true,
+    true,
+];
+void _operationContractInSync;

package/dist/source/index.d.ts

@@ -1,4 +1,5 @@
 import type { Schema, SchemaRecord, InferCreate } from '../schema/schema.js';
+import type { DataSourceAdapter } from './adapter.js';
 export type SourcePrimitive = string | number | boolean | null;
 export type SourceWhere = readonly [field: string, value: SourcePrimitive] | readonly [
     field: string,
@@ -84,10 +85,11 @@ export interface SourceDelta {
  * `sync_deltas` and fan them out to connected clients exactly like
  * SDK-originated commits.
  *
- * The events handler can return everything from the outbox unfiltered;
- * Ablo dedupes against `mutation_log` server-side using `clientTxId`.
- * Events with no `clientTxId` are treated as external (cron jobs,
- * dashboard edits, batch imports) and always fan out.
+ * The events handler can return everything from the outbox unfiltered. Ablo
+ * dedupes stable `event.id` values and uses `clientTxId` to filter SDK-origin
+ * echoes after the direct append has already succeeded. If the direct append
+ * failed, the same outbox event repairs it on poll/push because no matching
+ * `mutation_log` row exists yet.
  */
 export interface SourceEvent {
     /**
@@ -122,6 +124,42 @@ export interface SourceEvent {
      */
     readonly occurredAt?: number;
 }
+export interface SourceEventForOperationOptions {
+    /**
+     * Stable id from the customer's outbox table. This is Ablo's replay-
+     * protection key; retries must return the same id.
+     */
+    readonly eventId: string;
+    readonly operation: SourceOperation;
+    /**
+     * Committed row id. Defaults to `operation.id`; pass this for generated-id
+     * CREATEs where the database assigns the id inside the transaction.
+     */
+    readonly entityId?: string;
+    /**
+     * Canonical row payload after the write. Pass `null` for DELETE. When omitted
+     * the event carries no row payload, which is valid but less useful for
+     * realtime hydration.
+     */
+    readonly data?: Record<string, unknown> | null;
+    /**
+     * Batch idempotency key from the Data Source commit request. Round-tripping it
+     * lets Ablo filter SDK-origin echoes after the direct append succeeds, while
+     * still using the outbox event to repair a failed direct append.
+     */
+    readonly clientTxId?: string;
+    readonly organizationId?: string;
+    readonly occurredAt?: number | Date;
+}
+/**
+ * Build the source-event marker customers should write to their outbox table in
+ * the SAME transaction as their app-row mutation.
+ *
+ * This helper does not persist anything. It only standardizes the marker shape
+ * so Prisma/Drizzle/Kysely/raw-SQL adapters all emit the fields Ablo's
+ * reconciler expects.
+ */
+export declare function sourceEventForOperation(options: SourceEventForOperationOptions): SourceEvent;
 export interface SourceCommitResult<Row = Record<string, unknown>> {
     /**
      * Canonical rows after the write. Ablo uses these to update hosted
@@ -181,7 +219,8 @@ export interface SourceHandlerContext<TAuth = unknown> {
      * `webhook-id` from the signed request — globally unique per the
      * Standard Webhooks spec. Customers should dedupe by this id to
      * defend against replay (Ablo doesn't dedupe at the source-handler
-     * boundary; it does at the delta-append boundary via `clientTxId`).
+     * boundary; commit idempotency is `clientTxId`, and event replay
+     * protection is the outbox event `id`).
      */
     readonly messageId?: string;
     readonly signedAt?: number;
@@ -317,11 +356,10 @@ export type AbloSourceOptions<S extends SchemaRecord, TAuth = unknown> = {
      * imports). Each returned event becomes a delta and fans out to
      * connected clients.
      *
-     * MUST exclude events that originated from Ablo SDK commits — those
-     * already produced deltas via the `commit` path. Returning them here
-     * would surface as duplicate updates on every connected client.
-     * Customers typically tag outbox rows with the originating
-     * `clientTxId` and skip rows whose tag is non-null.
+     * Handlers may return the raw outbox feed. Ablo dedupes stable
+     * `event.id` values and filters SDK-origin echoes when rows carry
+     * the originating `clientTxId`; customers should persist both fields
+     * in their outbox table.
      */
     readonly events?: SourceEventsHandler<TAuth>;
     /**
@@ -329,6 +367,15 @@ export type AbloSourceOptions<S extends SchemaRecord, TAuth = unknown> = {
      * `abloSource({ schema, files: { load, list, commit } })`.
      */
     readonly models?: SourceModels<S, TAuth>;
+    /**
+     * An ORM adapter (`prismaDataSource(prisma, schema)`, …). When set, it serves
+     * ALL four operations — read (load/list), commit (idempotent + outbox), and
+     * events — so no hand-written `commit`/`events`/model handlers are needed. The
+     * adapter is consumed at the generic dispatch layer (rows are JSON on the wire),
+     * which is why it carries no per-model types and needs no cast at the call site.
+     * Mutually exclusive with hand-written handlers.
+     */
+    readonly adapter?: DataSourceAdapter;
 } & SourceModels<S, TAuth>;
 export type SourceLoadRequest = {
     readonly type: 'load';
@@ -392,6 +439,7 @@ export type DataSourceRequestContext = SourceRequestContext;
 export type DataSourceOperation = SourceOperation;
 export type DataSourceDelta = SourceDelta;
 export type DataSourceEvent = SourceEvent;
+export type DataSourceEventForOperationOptions = SourceEventForOperationOptions;
 export type DataSourceCommitResult<Row = Record<string, unknown>> = SourceCommitResult<Row>;
 export type DataSourceCommitParams<TAuth = unknown> = SourceCommitParams<TAuth>;
 export type DataSourceScope = SourceScope;
@@ -415,3 +463,6 @@ export type DataSourceResponse<Row = Record<string, unknown>> = SourceResponse<R
 export declare function abloSource<const S extends SchemaRecord, TAuth = unknown>(options: AbloSourceOptions<S, TAuth>): (request: Request) => Promise<Response>;
 export declare function dataSource<const S extends SchemaRecord, TAuth = unknown>(options: DataSourceOptions<S, TAuth>): (request: Request) => Promise<Response>;
 export { createPushQueue, InMemoryPushQueueStorage, STANDARD_WEBHOOKS_RETRY_SCHEDULE, type PushQueue, type PushQueueItem, type PushQueueOptions, type PushQueueStorage, } from './pushQueue.js';
+export { type DataSourceAdapter, type AdapterReadRequest, type AdapterCommitResult, type Row as AdapterRow, } from './adapter.js';
+export { operationSchema, operationTypeSchema, changeSetSchema, outboxEventSchema, eventsPageSchema, migrationSchema, adapterCapabilitiesSchema, type Operation, type ChangeSet, type OutboxEvent, type EventsPage, type Migration, type AdapterCapabilities, } from './contract.js';
+export { prismaDataSource, type PrismaLike, type PrismaDataSourceOptions } from './adapters/prisma.js';

package/dist/source/index.js

@@ -1,3 +1,35 @@
+import { changeSetSchema } from './contract.js';
+/**
+ * Build the source-event marker customers should write to their outbox table in
+ * the SAME transaction as their app-row mutation.
+ *
+ * This helper does not persist anything. It only standardizes the marker shape
+ * so Prisma/Drizzle/Kysely/raw-SQL adapters all emit the fields Ablo's
+ * reconciler expects.
+ */
+export function sourceEventForOperation(options) {
+    const entityId = options.entityId ?? options.operation.id;
+    if (typeof entityId !== 'string' || entityId.length === 0) {
+        throw new Error('sourceEventForOperation requires operation.id or an explicit entityId');
+    }
+    const occurredAt = normalizeEventOccurredAt(options.occurredAt);
+    return {
+        id: options.eventId,
+        model: options.operation.model,
+        entityId,
+        type: options.operation.type,
+        ...(options.data !== undefined ? { data: options.data } : {}),
+        ...(options.organizationId ? { organizationId: options.organizationId } : {}),
+        ...(options.clientTxId ? { clientTxId: options.clientTxId } : {}),
+        ...(occurredAt !== undefined ? { occurredAt } : {}),
+    };
+}
+function normalizeEventOccurredAt(value) {
+    if (value === undefined)
+        return undefined;
+    const timestamp = value instanceof Date ? value.getTime() : value;
+    return Number.isFinite(timestamp) ? timestamp : undefined;
+}
 /**
  * HTTP headers used on signed source requests. Conforms to the
  * Standard Webhooks specification (https://www.standardwebhooks.com/)
@@ -26,6 +58,64 @@ function json(data, status = 200) {
         headers: { 'Content-Type': 'application/json' },
     });
 }
+/**
+ * Serve a request from an ORM `adapter`. Routes the four operations to the spine
+ * (`read`/`commit`/`events`) and shapes the wire response. The adapter is the
+ * single point of dispatch — no per-model branching here.
+ */
+async function handleViaAdapter(adapter, body, scope) {
+    if (body.type === 'load') {
+        const rows = await adapter.read({
+            kind: 'load',
+            model: body.model,
+            id: body.id,
+            ...(scope ? { scope } : {}),
+        });
+        return json({ row: rows[0] ?? null });
+    }
+    if (body.type === 'list') {
+        const rows = await adapter.read({
+            kind: 'list',
+            model: body.model,
+            ...(body.query ? { query: body.query } : {}),
+            ...(scope ? { scope } : {}),
+        });
+        return json({ rows });
+    }
+    if (body.type === 'commit') {
+        if (!body.clientTxId) {
+            return json({ error: 'source_commit_requires_client_tx_id', message: 'commit requires a clientTxId for idempotency' }, 400);
+        }
+        const parsed = changeSetSchema.safeParse({
+            operations: body.operations,
+            clientTxId: body.clientTxId,
+        });
+        if (!parsed.success) {
+            return json({ error: 'source_commit_invalid', message: parsed.error.message }, 400);
+        }
+        const result = await adapter.commit(parsed.data);
+        return json({ rows: result.rows });
+    }
+    if (body.type === 'events') {
+        const page = await adapter.events(body.cursor ?? null, body.limit ?? 100);
+        return json({
+            events: page.events.map((event) => ({
+                id: event.id,
+                model: event.model,
+                entityId: event.entityId,
+                type: event.type,
+                ...(event.data !== undefined && event.data !== null ? { data: event.data } : {}),
+                ...(event.organizationId ? { organizationId: event.organizationId } : {}),
+                ...(event.clientTxId ? { clientTxId: event.clientTxId } : {}),
+                ...(event.occurredAt !== undefined && event.occurredAt !== null
+                    ? { occurredAt: event.occurredAt }
+                    : {}),
+            })),
+            ...(page.nextCursor !== null ? { nextCursor: page.nextCursor } : {}),
+        });
+    }
+    return json({ error: 'unknown_source_request' }, 400);
+}
 async function readBody(request) {
     if (typeof request.text === 'function') {
         const rawBody = await request.text();
@@ -257,6 +347,12 @@ export function abloSource(options) {
             signedAt: signature?.signedAt,
             ...(body.scope ? { scope: body.scope } : {}),
         };
+        // Adapter path: when an ORM adapter is configured it serves every operation,
+        // consumed at this generic layer (rows are JSON on the wire), so no per-model
+        // handler lookup and no typed↔generic boundary.
+        if (options.adapter) {
+            return handleViaAdapter(options.adapter, body, context.scope);
+        }
         if (body.type === 'load') {
             const handlers = getModelHandlers(options, body.model);
             if (!handlers?.load) {
@@ -321,3 +417,5 @@ export function dataSource(options) {
     return abloSource(options);
 }
 export { createPushQueue, InMemoryPushQueueStorage, STANDARD_WEBHOOKS_RETRY_SCHEDULE, } from './pushQueue.js';
+export { operationSchema, operationTypeSchema, changeSetSchema, outboxEventSchema, eventsPageSchema, migrationSchema, adapterCapabilitiesSchema, } from './contract.js';
+export { prismaDataSource } from './adapters/prisma.js';

package/dist/source/next.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Next.js App Router adapter for Data Source. The core `dataSource()` already
+ * returns a Web-standard `(Request) => Promise<Response>`, which Next App Router
+ * accepts directly — so this is pure ergonomics: wire an ORM `adapter` in via the
+ * bridge and hand back a named `POST` so the customer's route file is the minimum:
+ *
+ *   // app/api/ablo/source/route.ts
+ *   import { dataSourceNext } from '@abloatai/ablo/source/next';
+ *   import { prismaDataSource } from '@abloatai/ablo/source';
+ *   import { schema } from '@/ablo/schema';
+ *   import { prisma } from '@/lib/prisma';
+ *
+ *   export const { POST } = dataSourceNext({
+ *     schema,
+ *     apiKey: process.env.ABLO_API_KEY!,
+ *     adapter: prismaDataSource(prisma, schema),
+ *   });
+ *
+ * Day-one scope: Next + the adapter form only. Hand-written handlers use the core
+ * `dataSource()` directly; Hono/Express are the same one-liner and land on demand
+ * — not pre-built.
+ */
+import type { SchemaRecord } from '../schema/schema.js';
+import { type DataSourceOptions } from './index.js';
+/**
+ * Next options ARE the core options — the `adapter` field lives on the core
+ * handler now, so there is no bridging, no cast, and no per-model-typed boundary
+ * at the call site. Pass `{ schema, apiKey, adapter }`.
+ */
+export type DataSourceNextOptions<S extends SchemaRecord, TAuth = unknown> = DataSourceOptions<S, TAuth>;
+export declare function dataSourceNext<const S extends SchemaRecord, TAuth = unknown>(options: DataSourceNextOptions<S, TAuth>): {
+    readonly POST: (request: Request) => Promise<Response>;
+};