@abloatai/ablo 0.8.0 → 0.9.1

package/dist/source/adapters/drizzle.js

@@ -0,0 +1,185 @@
+/**
+ * Drizzle Data Source adapter. Same adapter interface + conformance as `prismaDataSource`,
+ * built against Drizzle's REAL API (read from drizzle-orm's own source/docs):
+ *   - `db.transaction(async (tx) => …)` — interactive transaction (commit/rollback).
+ *   - `db.execute(sql`…`)` — parametrized raw SQL; `sql.identifier()` safely quotes
+ *     dynamic table/column names, `sql`${value}`` parametrizes values.
+ *
+ * SCHEMA-DRIVEN COLUMNS. Unlike Prisma — whose delegate applies the model's
+ * `@map` for free — this adapter writes raw SQL, so it would otherwise bypass any
+ * field→column translation. It therefore derives every table + column name from
+ * the SAME rule the provisioner uses (`generateProvisionPlan`):
+ *   table  = `model.tableName ?? key`
+ *   column = `fieldMeta.column ?? camelToSnake(field)`   (+ the model's tenancy column)
+ * so `ablo migrate` (which emits `operator_id`) and this adapter (which now writes
+ * `operator_id`) COMPOSE. Define the schema once, point Ablo at your Postgres —
+ * no hand-written parallel Drizzle table. The adapter is the translation boundary:
+ * its public surface (rows in/out, outbox `data`) is field-keyed (the SDK shape);
+ * the physical columns it reads/writes are snake_case.
+ *
+ * IMPORTANT GOTCHAS (from drizzle-orm docs):
+ *   1. Interactive `db.transaction` requires a driver that supports it. Neon's
+ *      `neon-http` driver does NOT (single-shot only) — use `neon-serverless`
+ *      (WebSocket) or `pg`. With neon-http the commit path throws at runtime.
+ *   2. `db.execute` result shape is driver-specific (postgres-js returns an
+ *      array-like RowList; node-postgres returns `{ rows }`). `rowsOf()`
+ *      normalizes both.
+ *
+ * We use `sql` + `db.execute` for ALL writes (not the fluent builder) so the
+ * adapter is one small, fully-typed unit with no per-driver builder generics.
+ */
+import { sql } from 'drizzle-orm';
+import { outboxEventSchema } from '../contract.js';
+import { adapterTableMigrations } from '../migrations.js';
+import { toSchemaJSON } from '../../schema/serialize.js';
+import { camelToSnake, snakeToCamel } from '../../schema/ddl.js';
+import { tenancyColumn } from '../../schema/tenancy.js';
+function rowsOf(result) {
+    return Array.isArray(result) ? result : result.rows;
+}
+function rowId(op) {
+    const id = op.id ?? op.input?.id;
+    if (typeof id !== 'string' || id.length === 0) {
+        throw new Error(`operation on "${op.model}" requires an id`);
+    }
+    return id;
+}
+/** `col1, col2` as a safely-quoted identifier list. */
+const identList = (cols) => sql.join(cols.map((c) => sql.identifier(c)), sql `, `);
+function buildColumnMaps(schema) {
+    const json = toSchemaJSON(schema);
+    const out = new Map();
+    for (const [key, model] of Object.entries(json.models)) {
+        const fieldToColumn = new Map();
+        const columnToField = new Map();
+        const register = (field, column) => {
+            // The default rule already covers `camelToSnake(field)`; only record real
+            // divergences so the reverse map never shadows a clean round-trip.
+            if (column === camelToSnake(field))
+                return;
+            fieldToColumn.set(field, column);
+            columnToField.set(column, field);
+        };
+        for (const [field, meta] of Object.entries(model.fields)) {
+            if (meta.column)
+                register(field, meta.column);
+        }
+        const orgColumn = tenancyColumn(model.tenancy);
+        if (orgColumn)
+            register('organizationId', orgColumn);
+        out.set(key, { table: model.tableName ?? key, fieldToColumn, columnToField });
+    }
+    return out;
+}
+export function drizzleDataSource(db, schema) {
+    const maps = buildColumnMaps(schema);
+    const modelColumns = (model) => {
+        const mc = maps.get(model);
+        if (!mc)
+            throw new Error(`drizzleDataSource: no model "${model}" in schema`);
+        return mc;
+    };
+    const columnFor = (mc, field) => mc.fieldToColumn.get(field) ?? camelToSnake(field);
+    const fieldFor = (mc, column) => mc.columnToField.get(column) ?? snakeToCamel(column);
+    /** Field-keyed (SDK shape) → column-keyed (physical), for INSERT/UPDATE. */
+    const toColumns = (mc, row) => {
+        const out = {};
+        for (const k of Object.keys(row))
+            out[columnFor(mc, k)] = row[k];
+        return out;
+    };
+    /** Column-keyed (RETURNING * / SELECT *) → field-keyed (SDK shape), for reads + results. */
+    const toFields = (mc, row) => {
+        const out = {};
+        for (const k of Object.keys(row))
+            out[fieldFor(mc, k)] = row[k];
+        return out;
+    };
+    const applyOperation = async (tx, op) => {
+        const mc = modelColumns(op.model);
+        const table = sql.identifier(mc.table);
+        const id = rowId(op);
+        const input = op.input ?? {};
+        if (op.type === 'DELETE') {
+            const deleted = rowsOf(await tx.execute(sql `DELETE FROM ${table} WHERE id = ${id} RETURNING *`));
+            return deleted[0] ? toFields(mc, deleted[0]) : { id };
+        }
+        if (op.type === 'CREATE') {
+            const data = toColumns(mc, { id, ...input });
+            const cols = Object.keys(data);
+            const values = sql.join(cols.map((c) => sql `${data[c]}`), sql `, `);
+            const inserted = rowsOf(await tx.execute(sql `INSERT INTO ${table} (${identList(cols)}) VALUES (${values}) RETURNING *`));
+            return inserted[0] ? toFields(mc, inserted[0]) : { id, ...input };
+        }
+        // UPDATE / ARCHIVE / UNARCHIVE — a SET clause + the lifecycle field. The
+        // lifecycle field is `archivedAt` (camelCase) and goes through `toColumns`
+        // like any other, so it lands in `archived_at` — same column the provisioner
+        // emits and the Prisma adapter writes (no per-adapter casing divergence).
+        const patch = toColumns(mc, {
+            ...input,
+            ...(op.type === 'ARCHIVE' ? { archivedAt: new Date() } : {}),
+            ...(op.type === 'UNARCHIVE' ? { archivedAt: null } : {}),
+        });
+        const assignments = sql.join(Object.keys(patch).map((c) => sql `${sql.identifier(c)} = ${patch[c]}`), sql `, `);
+        const updated = rowsOf(await tx.execute(sql `UPDATE ${table} SET ${assignments} WHERE id = ${id} RETURNING *`));
+        return updated[0] ? toFields(mc, updated[0]) : { id, ...input };
+    };
+    return {
+        capabilities: { transactions: true, propose: false, schemaIntrospection: true },
+        migrations() {
+            return adapterTableMigrations();
+        },
+        async read(req) {
+            const mc = modelColumns(req.model);
+            const table = sql.identifier(mc.table);
+            if (req.kind === 'load') {
+                const rows = rowsOf(await db.execute(sql `SELECT * FROM ${table} WHERE id = ${req.id} LIMIT 1`));
+                return rows.map((r) => toFields(mc, r));
+            }
+            const limit = req.query?.limit ?? 1000;
+            const rows = rowsOf(await db.execute(sql `SELECT * FROM ${table} LIMIT ${limit}`));
+            return rows.map((r) => toFields(mc, r));
+        },
+        async commit(change) {
+            return db.transaction(async (tx) => {
+                const cached = rowsOf(await tx.execute(sql `SELECT response FROM ablo_idempotency WHERE client_tx_id = ${change.clientTxId} LIMIT 1`));
+                if (cached.length > 0)
+                    return { rows: cached[0].response };
+                const rows = [];
+                for (const [index, op] of change.operations.entries()) {
+                    const row = await applyOperation(tx, op);
+                    rows.push(row);
+                    const entityId = String(row.id ?? rowId(op));
+                    await tx.execute(sql `
+            INSERT INTO ablo_outbox (id, model, entity_id, type, data, client_tx_id, occurred_at)
+            VALUES (
+              ${`${change.clientTxId}:${index}`}, ${op.model}, ${entityId}, ${op.type},
+              ${op.type === 'DELETE' ? null : JSON.stringify(row)}::jsonb, ${change.clientTxId}, ${Date.now()}
+            )`);
+                }
+                await tx.execute(sql `
+          INSERT INTO ablo_idempotency (client_tx_id, response)
+          VALUES (${change.clientTxId}, ${JSON.stringify(rows)}::jsonb)`);
+                return { rows };
+            });
+        },
+        async events(cursor, limit) {
+            const after = cursor ?? '0';
+            const rows = rowsOf(await db.execute(sql `
+          SELECT cursor, id, model, entity_id, type, data, organization_id, client_tx_id, occurred_at
+          FROM ablo_outbox WHERE cursor > ${after} ORDER BY cursor ASC LIMIT ${limit}`));
+            const events = rows.map((r) => outboxEventSchema.parse({
+                id: r.id,
+                model: r.model,
+                entityId: r.entity_id,
+                type: r.type,
+                data: r.data ?? null,
+                organizationId: r.organization_id ?? null,
+                clientTxId: r.client_tx_id ?? null,
+                occurredAt: r.occurred_at != null ? Number(r.occurred_at) : null,
+                cursor: String(r.cursor),
+            }));
+            return { events, nextCursor: events.length > 0 ? events[events.length - 1].cursor : null };
+        },
+    };
+}

package/dist/source/adapters/memory.d.ts

@@ -0,0 +1,12 @@
+/**
+ * In-memory reference Data Source adapter — the canonical correct implementation
+ * of the adapter interface. It is the test double for the bridge/handler AND the thing the
+ * conformance suite runs against to prove the suite itself is real (same role as
+ * the server's `memoryTenantDirectory`). A new ORM adapter is "done" when it
+ * passes the same suite this one passes.
+ *
+ * It models the real semantics minimally but faithfully: one canonical row store
+ * per model, an idempotency ledger keyed by `clientTxId`, and a monotonic outbox.
+ */
+import type { DataSourceAdapter } from '../adapter.js';
+export declare function memoryDataSource(): DataSourceAdapter;

package/dist/source/adapters/memory.js

@@ -0,0 +1,114 @@
+/**
+ * In-memory reference Data Source adapter — the canonical correct implementation
+ * of the adapter interface. It is the test double for the bridge/handler AND the thing the
+ * conformance suite runs against to prove the suite itself is real (same role as
+ * the server's `memoryTenantDirectory`). A new ORM adapter is "done" when it
+ * passes the same suite this one passes.
+ *
+ * It models the real semantics minimally but faithfully: one canonical row store
+ * per model, an idempotency ledger keyed by `clientTxId`, and a monotonic outbox.
+ */
+function rowId(op) {
+    const id = op.id ?? op.input?.id;
+    if (typeof id !== 'string' || id.length === 0) {
+        throw new Error(`operation on "${op.model}" requires an id`);
+    }
+    return id;
+}
+export function memoryDataSource() {
+    /** model → (id → row). */
+    const store = new Map();
+    /** clientTxId → the rows that commit returned (idempotency ledger). */
+    const idempotency = new Map();
+    /** Append-only outbox; `cursor` is the 1-based index as a string. */
+    const outbox = [];
+    const modelStore = (model) => {
+        let m = store.get(model);
+        if (!m) {
+            m = new Map();
+            store.set(model, m);
+        }
+        return m;
+    };
+    const applyOperation = (op) => {
+        const m = modelStore(op.model);
+        const id = rowId(op);
+        switch (op.type) {
+            case 'CREATE': {
+                const row = { id, ...(op.input ?? {}) };
+                m.set(id, row);
+                return row;
+            }
+            case 'UPDATE':
+            case 'ARCHIVE':
+            case 'UNARCHIVE': {
+                const prev = m.get(id) ?? { id };
+                const row = {
+                    ...prev,
+                    ...(op.input ?? {}),
+                    ...(op.type === 'ARCHIVE' ? { archivedAt: Date.now() } : {}),
+                    ...(op.type === 'UNARCHIVE' ? { archivedAt: null } : {}),
+                };
+                m.set(id, row);
+                return row;
+            }
+            case 'DELETE': {
+                const prev = m.get(id) ?? { id };
+                m.delete(id);
+                return prev;
+            }
+        }
+    };
+    return {
+        capabilities: { transactions: true, propose: false, schemaIntrospection: false },
+        migrations() {
+            // In-memory: no table-creation SQL. A real ORM adapter ships ablo_idempotency + ablo_outbox here.
+            return [];
+        },
+        async read(req) {
+            const m = store.get(req.model);
+            if (!m)
+                return [];
+            if (req.kind === 'load') {
+                const row = m.get(req.id);
+                return row ? [row] : [];
+            }
+            let rows = [...m.values()];
+            const limit = req.query?.limit;
+            if (typeof limit === 'number')
+                rows = rows.slice(0, limit);
+            return rows;
+        },
+        async commit(change) {
+            // Idempotency: a duplicate clientTxId returns the original rows, no re-apply.
+            const cached = idempotency.get(change.clientTxId);
+            if (cached)
+                return { rows: cached };
+            const rows = [];
+            for (const [index, op] of change.operations.entries()) {
+                const row = applyOperation(op);
+                rows.push(row);
+                // Transactional outbox: one event per op, monotonic cursor.
+                outbox.push({
+                    id: `${change.clientTxId}:${index}`,
+                    model: op.model,
+                    entityId: String(row.id ?? rowId(op)),
+                    type: op.type,
+                    data: op.type === 'DELETE' ? null : row,
+                    clientTxId: change.clientTxId,
+                    cursor: String(outbox.length + 1),
+                });
+            }
+            idempotency.set(change.clientTxId, rows);
+            return { rows };
+        },
+        async events(cursor, limit) {
+            const after = cursor ? Number(cursor) : 0;
+            const page = outbox.filter((e) => Number(e.cursor) > after).slice(0, limit);
+            return {
+                events: page,
+                nextCursor: page.length > 0 ? page[page.length - 1].cursor : null,
+            };
+        },
+    };
+}

package/dist/source/adapters/prisma.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Prisma Data Source adapter. The first real ORM adapter (Auth.js pattern: one
+ * package per ORM, all behind the `DataSourceAdapter` interface, all proven by the
+ * same conformance suite the in-memory reference passes).
+ *
+ * It owns the transactional outbox + idempotency so the customer never writes
+ * them: `commit` runs the app-row mutations, the `ablo_outbox` append, and the
+ * `ablo_idempotency` record in ONE `prisma.$transaction`. `migrations()` ships
+ * the table-creation SQL for those two tables.
+ *
+ * No `@prisma/client` dependency: the client is accepted structurally
+ * (`PrismaLike`), so this compiles in the SDK package and is unit-testable with
+ * a fake, while a real `PrismaClient` satisfies it at the call site.
+ */
+import type { DataSourceAdapter, Row } from '../adapter.js';
+import type { SchemaRecord, Schema } from '../../schema/schema.js';
+/** A Prisma model delegate (the subset we call). */
+export interface PrismaDelegate {
+    findUnique(args: {
+        where: {
+            id: string;
+        };
+    }): Promise<Row | null>;
+    findMany(args: {
+        where?: Record<string, unknown>;
+        take?: number;
+        orderBy?: Record<string, 'asc' | 'desc'>;
+    }): Promise<Row[]>;
+    create(args: {
+        data: Row;
+    }): Promise<Row>;
+    update(args: {
+        where: {
+            id: string;
+        };
+        data: Row;
+    }): Promise<Row>;
+    delete(args: {
+        where: {
+            id: string;
+        };
+    }): Promise<Row>;
+}
+/** The raw-SQL surface used for the adapter-owned tables. */
+export interface PrismaRaw {
+    $executeRawUnsafe(query: string, ...values: unknown[]): Promise<number>;
+    $queryRawUnsafe<T = unknown>(query: string, ...values: unknown[]): Promise<T>;
+}
+/** A Prisma client (or interactive-transaction client) — structural, no SDK dependency. */
+export interface PrismaLike extends PrismaRaw {
+    $transaction<T>(fn: (tx: PrismaLike & PrismaRaw) => Promise<T>): Promise<T>;
+}
+export interface PrismaDataSourceOptions {
+    /** Map a schema model name → its Prisma delegate name. Default: lower-first-letter. */
+    readonly delegateName?: (model: string) => string;
+}
+export declare function prismaDataSource<S extends SchemaRecord>(prisma: PrismaLike, schema: Schema<S>, options?: PrismaDataSourceOptions): DataSourceAdapter;

package/dist/source/adapters/prisma.js

@@ -0,0 +1,176 @@
+/**
+ * Prisma Data Source adapter. The first real ORM adapter (Auth.js pattern: one
+ * package per ORM, all behind the `DataSourceAdapter` interface, all proven by the
+ * same conformance suite the in-memory reference passes).
+ *
+ * It owns the transactional outbox + idempotency so the customer never writes
+ * them: `commit` runs the app-row mutations, the `ablo_outbox` append, and the
+ * `ablo_idempotency` record in ONE `prisma.$transaction`. `migrations()` ships
+ * the table-creation SQL for those two tables.
+ *
+ * No `@prisma/client` dependency: the client is accepted structurally
+ * (`PrismaLike`), so this compiles in the SDK package and is unit-testable with
+ * a fake, while a real `PrismaClient` satisfies it at the call site.
+ */
+import { outboxEventSchema } from '../contract.js';
+import { adapterTableMigrations } from '../migrations.js';
+const lowerFirst = (s) => (s ? s[0].toLowerCase() + s.slice(1) : s);
+/**
+ * Resolve a model's Prisma delegate by name. This is the ONE irreducible cast in
+ * the adapter layer, and it's a genuine type-system limit, not laziness:
+ *
+ *   - Inside `prisma.$transaction(tx => …)` the writes MUST go through the
+ *     transactional client `tx`, and the model is only known as a runtime string.
+ *   - Prisma's client (and transaction handle) is NOMINALLY keyed (`{ task: TaskDelegate; … }`), so a
+ *     dynamic `tx[name]` is `unknown` to the compiler — there is no key to infer.
+ *
+ * Dynamic property access on a statically-keyed type cannot be typed without an
+ * assertion; this is the reflection boundary, validated at runtime (`findMany` is
+ * a function) right after. `ablo generate` removes even this by emitting a typed
+ * `model → delegate` map, at which point this helper is replaced by a lookup.
+ */
+function delegateFor(client, name) {
+    const delegate = client[name];
+    if (!delegate || typeof delegate.findMany !== 'function') {
+        throw new Error(`prismaDataSource: no Prisma delegate "${name}" on the client`);
+    }
+    return delegate;
+}
+/** Translate a Source `where` tuple set into a Prisma `where` object. */
+function toPrismaWhere(where) {
+    const out = {};
+    for (const clause of where ?? []) {
+        const [field] = clause;
+        if (clause.length === 2) {
+            out[field] = clause[1];
+            continue;
+        }
+        const [, op, value] = clause;
+        switch (op) {
+            case '=':
+                out[field] = value;
+                break;
+            case '!=':
+                out[field] = { not: value };
+                break;
+            case '<':
+                out[field] = { lt: value };
+                break;
+            case '<=':
+                out[field] = { lte: value };
+                break;
+            case '>':
+                out[field] = { gt: value };
+                break;
+            case '>=':
+                out[field] = { gte: value };
+                break;
+            case 'IN':
+                out[field] = { in: value };
+                break;
+            case 'NOT IN':
+                out[field] = { notIn: value };
+                break;
+            case 'LIKE':
+            case 'ILIKE':
+                out[field] = { contains: value, mode: op === 'ILIKE' ? 'insensitive' : 'default' };
+                break;
+            case 'NOT LIKE':
+            case 'NOT ILIKE':
+                out[field] = { not: { contains: value } };
+                break;
+            case 'IS':
+            case 'IS NOT':
+                out[field] = op === 'IS' ? value : { not: value };
+                break;
+        }
+    }
+    return out;
+}
+function findManyArgs(query) {
+    return {
+        where: toPrismaWhere(query?.where),
+        ...(typeof query?.limit === 'number' ? { take: query.limit } : {}),
+        ...(query?.orderBy ? { orderBy: { [query.orderBy]: query.order ?? 'asc' } } : {}),
+    };
+}
+function rowId(op) {
+    const id = op.id ?? op.input?.id;
+    if (typeof id !== 'string' || id.length === 0) {
+        throw new Error(`operation on "${op.model}" requires an id`);
+    }
+    return id;
+}
+export function prismaDataSource(prisma, schema, options = {}) {
+    const delegateName = options.delegateName ?? lowerFirst;
+    void schema; // reserved for codegen-typed reads / model validation
+    const applyOperation = async (tx, op) => {
+        const delegate = delegateFor(tx, delegateName(op.model));
+        const id = rowId(op);
+        switch (op.type) {
+            case 'CREATE':
+                return delegate.create({ data: { id, ...(op.input ?? {}) } });
+            case 'UPDATE':
+                return delegate.update({ where: { id }, data: { ...(op.input ?? {}) } });
+            case 'ARCHIVE':
+                return delegate.update({ where: { id }, data: { ...(op.input ?? {}), archivedAt: new Date() } });
+            case 'UNARCHIVE':
+                return delegate.update({ where: { id }, data: { ...(op.input ?? {}), archivedAt: null } });
+            case 'DELETE':
+                return delegate.delete({ where: { id } });
+        }
+    };
+    return {
+        capabilities: { transactions: true, propose: false, schemaIntrospection: true },
+        migrations() {
+            return adapterTableMigrations();
+        },
+        async read(req) {
+            const delegate = delegateFor(prisma, delegateName(req.model));
+            if (req.kind === 'load') {
+                const row = await delegate.findUnique({ where: { id: req.id } });
+                return row ? [row] : [];
+            }
+            return delegate.findMany(findManyArgs(req.query));
+        },
+        async commit(change) {
+            return prisma.$transaction(async (tx) => {
+                // Idempotency: a duplicate clientTxId returns the original rows, no re-apply.
+                const cached = await tx.$queryRawUnsafe(`SELECT response FROM ablo_idempotency WHERE client_tx_id = $1 LIMIT 1`, change.clientTxId);
+                if (cached.length > 0)
+                    return { rows: cached[0].response };
+                const rows = [];
+                for (const [index, op] of change.operations.entries()) {
+                    const row = await applyOperation(tx, op);
+                    rows.push(row);
+                    const entityId = String(row.id ?? rowId(op));
+                    // Transactional outbox: one event per op, written in THIS transaction.
+                    await tx.$executeRawUnsafe(`INSERT INTO ablo_outbox (id, model, entity_id, type, data, client_tx_id, occurred_at)
+             VALUES ($1, $2, $3, $4, $5::jsonb, $6, $7)`, `${change.clientTxId}:${index}`, op.model, entityId, op.type, JSON.stringify(op.type === 'DELETE' ? null : row), change.clientTxId, Date.now());
+                }
+                await tx.$executeRawUnsafe(`INSERT INTO ablo_idempotency (client_tx_id, response) VALUES ($1, $2::jsonb)`, change.clientTxId, JSON.stringify(rows));
+                return { rows };
+            });
+        },
+        async events(cursor, limit) {
+            const after = cursor ? cursor : '0';
+            const rows = await prisma.$queryRawUnsafe(`SELECT cursor, id, model, entity_id, type, data, organization_id, client_tx_id, occurred_at
+         FROM ablo_outbox WHERE cursor > $1 ORDER BY cursor ASC LIMIT $2`, after, limit);
+            const events = rows.map((r) => outboxEventSchema.parse({
+                id: r.id,
+                model: r.model,
+                entityId: r.entity_id,
+                type: r.type,
+                data: r.data ?? null,
+                organizationId: r.organization_id ?? null,
+                clientTxId: r.client_tx_id ?? null,
+                occurredAt: r.occurred_at != null ? Number(r.occurred_at) : null,
+                cursor: String(r.cursor),
+            }));
+            return {
+                events,
+                nextCursor: events.length > 0 ? events[events.length - 1].cursor : null,
+            };
+        },
+    };
+}

package/dist/source/conformance.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 adapter interface 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 type { DataSourceAdapter } from './adapter.js';
+export type MakeAdapter = () => DataSourceAdapter | Promise<DataSourceAdapter>;
+/** A single conformance check. `run` throws on failure. */
+export interface ConformanceCheck {
+    readonly name: string;
+    run(): Promise<void>;
+}
+export declare function dataSourceConformanceChecks(make: MakeAdapter): ConformanceCheck[];
+/**
+ * Register the conformance checks with a test runner's `it`/`test` function.
+ * `register(name, fn)` — pass vitest/jest `it` or `node:test` `test`.
+ */
+export declare function runDataSourceTests(make: MakeAdapter, register: (name: string, fn: () => Promise<void>) => void): void;
+export { memoryDataSource } from './adapters/memory.js';