@abloatai/ablo 0.25.0 → 0.27.0

package/dist/source/adapters/drizzle.js

@@ -1,32 +1,37 @@
 /**
- * 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.
+ * The Drizzle adapter for the data-source interface. It implements the same
+ * {@link DataSourceAdapter} contract as {@link prismaDataSource} and passes the
+ * same conformance suite, built against Drizzle's query API:
+ *   - `db.transaction(async (tx) => …)` runs an interactive transaction that
+ *     commits or rolls back as a unit.
+ *   - `db.execute(sql`…`)` runs parameterized raw SQL; `sql.identifier()` safely
+ *     quotes dynamic table and column names, and `sql`${value}`` parameterizes
+ *     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 and column names come from your schema, not from a hand-written Drizzle
+ * table. Because this adapter issues raw SQL, it would otherwise bypass any
+ * field-to-column translation, so it derives every name from the same rule the
+ * table provisioner uses:
  *   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.
+ *   column = `fieldMeta.column ?? camelToSnake(field)`   (plus the tenancy column)
+ * This keeps the tables `ablo migrate` creates (for example `operator_id`) and the
+ * columns this adapter reads and writes in agreement. You define the schema once
+ * and point the engine at your Postgres database. The adapter is the translation
+ * boundary: the rows it accepts and returns, and the outbox `data` it writes, are
+ * keyed by field name, while the physical columns it touches 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()`
+ * Two things to know about drivers:
+ *   1. Interactive `db.transaction` needs a driver that supports it. Neon's
+ *      `neon-http` driver is single-shot and does not, so use `neon-serverless`
+ *      (over WebSocket) or `pg`; under `neon-http` the commit path throws at
+ *      runtime.
+ *   2. The `db.execute` result shape is driver-specific — `postgres-js` returns an
+ *      array-like row list, while `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.
+ * Every write goes through `sql` and `db.execute` rather than the fluent builder,
+ * which keeps the adapter one small, fully typed unit with no per-driver builder
+ * generics.
  */
 import { AbloValidationError } from '../../errors.js';
 import { sql } from 'drizzle-orm';
@@ -82,14 +87,14 @@ export function drizzleDataSource(db, schema) {
     };
     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. */
+    /** Field-keyed row to column-keyed row, for INSERT and UPDATE values. */
     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. */
+    /** Column-keyed row (from `RETURNING *` or `SELECT *`) back to a field-keyed row, for reads and results. */
     const toFields = (mc, row) => {
         const out = {};
         for (const k of Object.keys(row))
@@ -144,8 +149,9 @@ export function drizzleDataSource(db, schema) {
         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 cachedRow = cached[0];
+                if (cachedRow)
+                    return { rows: cachedRow.response };
                 const rows = [];
                 for (const [index, op] of change.operations.entries()) {
                     const row = await applyOperation(tx, op);
@@ -180,7 +186,7 @@ export function drizzleDataSource(db, schema) {
                 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 };
+            return { events, nextCursor: events.at(-1)?.cursor ?? null };
         },
     };
 }

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

@@ -1,36 +1,38 @@
 /**
- * Kysely Data Source adapter. Same adapter interface + conformance shape as
- * `prismaDataSource` / `drizzleDataSource`, built against Kysely's REAL
- * query-builder API:
- *   - `db.transaction().execute(async (trx) => …)` — interactive transaction.
- *   - `insertInto/updateTable/deleteFrom/selectFrom` + `returningAll()` —
- *     the fluent builder; table/column names are plain strings, so no raw
- *     SQL tag is needed and this module imports NOTHING from `kysely`
- *     (structural `KyselyLike`, mirroring the Prisma adapter's zero-dep
- *     `PrismaLike`).
+ * The Kysely adapter for the data-source interface. It implements the same
+ * {@link DataSourceAdapter} contract as {@link prismaDataSource} and
+ * {@link drizzleDataSource} and passes the same conformance suite, built against
+ * Kysely's query builder:
+ *   - `db.transaction().execute(async (trx) => …)` runs an interactive transaction.
+ *   - `insertInto` / `updateTable` / `deleteFrom` / `selectFrom` with
+ *     `returningAll()` form the fluent query. Table and column names are plain
+ *     strings, so the adapter needs no raw-SQL tag and imports nothing from
+ *     `kysely`; it depends only on the structural {@link KyselyLike} shape, the
+ *     same approach the Prisma adapter takes with {@link PrismaLike}.
  *
- * SCHEMA-DRIVEN COLUMNS. Kysely is SQL-near: it passes the column names you
- * give it through verbatim (no Prisma-style `@map`). Like the Drizzle
- * adapter, every table + column name is derived from the SAME rule the
- * provisioner uses (`generateProvisionPlan`):
+ * Table and column names come from your schema. Kysely passes the column names you
+ * give it straight through to SQL, so, like the Drizzle adapter, this one derives
+ * every name from the same rule the table provisioner uses:
  *   table  = `model.tableName ?? key`
- *   column = `fieldMeta.column ?? camelToSnake(field)`  (+ the tenancy column)
- * so `ablo migrate` (which emits `operator_id`) and this adapter COMPOSE.
- * The adapter is the translation boundary: rows in/out are field-keyed (the
- * SDK shape); the physical columns it reads/writes are snake_case.
+ *   column = `fieldMeta.column ?? camelToSnake(field)`  (plus the tenancy column)
+ * This keeps the tables `ablo migrate` creates (for example `operator_id`) and the
+ * columns this adapter uses in agreement. The adapter is the translation boundary:
+ * the rows it accepts and returns are keyed by field name, while the physical
+ * columns are snake_case.
  *
- * JSONB note: the outbox `data` / idempotency `response` values are passed
- * as JSON strings — Postgres infers the parameter type from the target
- * `jsonb` column, so the coercion is server-side and driver-agnostic (no
- * `::jsonb` cast available without raw SQL).
+ * A note on JSON columns: the outbox `data` and idempotency `response` values are
+ * passed as JSON strings. Postgres infers the parameter type from the target
+ * `jsonb` column, so the conversion happens on the server and works across drivers,
+ * without the `::jsonb` cast that only raw SQL allows.
  */
 import type { DataSourceAdapter, Row } from '../adapter.js';
 import type { Schema, SchemaRecord } from '../../schema/schema.js';
 /**
- * The subset of a Kysely instance (or transaction handle) the adapter calls.
- * Structural on purpose — declared with method shorthand so a real
- * `Kysely<DB>` (whose params are narrowed to `keyof DB`) stays assignable
- * under TypeScript's method bivariance, exactly like `PrismaLike`.
+ * The subset of a Kysely instance, or transaction handle, that the adapter calls.
+ * It is structural by design: declaring the members with method shorthand lets a
+ * real `Kysely<DB>` — whose parameters are narrowed to `keyof DB` — stay assignable
+ * under TypeScript's method-parameter bivariance, the same way {@link PrismaLike}
+ * accepts a real `PrismaClient`.
  */
 export interface KyselyLike {
     selectFrom(table: string): KyselySelectBuilder;

package/dist/source/adapters/kysely.js

@@ -1,28 +1,29 @@
 /**
- * Kysely Data Source adapter. Same adapter interface + conformance shape as
- * `prismaDataSource` / `drizzleDataSource`, built against Kysely's REAL
- * query-builder API:
- *   - `db.transaction().execute(async (trx) => …)` — interactive transaction.
- *   - `insertInto/updateTable/deleteFrom/selectFrom` + `returningAll()` —
- *     the fluent builder; table/column names are plain strings, so no raw
- *     SQL tag is needed and this module imports NOTHING from `kysely`
- *     (structural `KyselyLike`, mirroring the Prisma adapter's zero-dep
- *     `PrismaLike`).
+ * The Kysely adapter for the data-source interface. It implements the same
+ * {@link DataSourceAdapter} contract as {@link prismaDataSource} and
+ * {@link drizzleDataSource} and passes the same conformance suite, built against
+ * Kysely's query builder:
+ *   - `db.transaction().execute(async (trx) => …)` runs an interactive transaction.
+ *   - `insertInto` / `updateTable` / `deleteFrom` / `selectFrom` with
+ *     `returningAll()` form the fluent query. Table and column names are plain
+ *     strings, so the adapter needs no raw-SQL tag and imports nothing from
+ *     `kysely`; it depends only on the structural {@link KyselyLike} shape, the
+ *     same approach the Prisma adapter takes with {@link PrismaLike}.
  *
- * SCHEMA-DRIVEN COLUMNS. Kysely is SQL-near: it passes the column names you
- * give it through verbatim (no Prisma-style `@map`). Like the Drizzle
- * adapter, every table + column name is derived from the SAME rule the
- * provisioner uses (`generateProvisionPlan`):
+ * Table and column names come from your schema. Kysely passes the column names you
+ * give it straight through to SQL, so, like the Drizzle adapter, this one derives
+ * every name from the same rule the table provisioner uses:
  *   table  = `model.tableName ?? key`
- *   column = `fieldMeta.column ?? camelToSnake(field)`  (+ the tenancy column)
- * so `ablo migrate` (which emits `operator_id`) and this adapter COMPOSE.
- * The adapter is the translation boundary: rows in/out are field-keyed (the
- * SDK shape); the physical columns it reads/writes are snake_case.
+ *   column = `fieldMeta.column ?? camelToSnake(field)`  (plus the tenancy column)
+ * This keeps the tables `ablo migrate` creates (for example `operator_id`) and the
+ * columns this adapter uses in agreement. The adapter is the translation boundary:
+ * the rows it accepts and returns are keyed by field name, while the physical
+ * columns are snake_case.
  *
- * JSONB note: the outbox `data` / idempotency `response` values are passed
- * as JSON strings — Postgres infers the parameter type from the target
- * `jsonb` column, so the coercion is server-side and driver-agnostic (no
- * `::jsonb` cast available without raw SQL).
+ * A note on JSON columns: the outbox `data` and idempotency `response` values are
+ * passed as JSON strings. Postgres infers the parameter type from the target
+ * `jsonb` column, so the conversion happens on the server and works across drivers,
+ * without the `::jsonb` cast that only raw SQL allows.
  */
 import { AbloValidationError } from '../../errors.js';
 import { outboxEventSchema } from '../contract.js';
@@ -75,14 +76,14 @@ export function kyselyDataSource(db, schema) {
     };
     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. */
+    /** Field-keyed row to column-keyed row, for INSERT and UPDATE values. */
     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). */
+    /** Column-keyed row (from `RETURNING *` or `SELECT *`) back to a field-keyed row. */
     const toFields = (mc, row) => {
         const out = {};
         for (const k of Object.keys(row))
@@ -153,8 +154,9 @@ export function kyselyDataSource(db, schema) {
                     .where('client_tx_id', '=', change.clientTxId)
                     .limit(1)
                     .execute();
-                if (cached.length > 0) {
-                    const response = cached[0].response;
+                const cachedRow = cached[0];
+                if (cachedRow) {
+                    const response = cachedRow.response;
                     return {
                         rows: (typeof response === 'string' ? JSON.parse(response) : response),
                     };
@@ -204,7 +206,7 @@ export function kyselyDataSource(db, schema) {
                 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 };
+            return { events, nextCursor: events.at(-1)?.cursor ?? null };
         },
     };
 }

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

@@ -1,12 +1,13 @@
 /**
- * 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.
+ * The in-memory reference implementation of {@link DataSourceAdapter}. It is the
+ * simplest correct adapter: a stand-in you can commit to and read from in tests
+ * without a database, and the fixture the conformance suite runs against to confirm
+ * the suite exercises real behavior. An adapter for a given object-relational
+ * mapper is complete 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.
+ * It models the semantics minimally but faithfully: one row store per model, an
+ * idempotency ledger keyed by `clientTxId`, and an append-only outbox with a
+ * monotonic cursor.
  */
 import type { DataSourceAdapter } from '../adapter.js';
 export declare function memoryDataSource(): DataSourceAdapter;

package/dist/source/adapters/memory.js

@@ -1,12 +1,13 @@
 /**
- * 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.
+ * The in-memory reference implementation of {@link DataSourceAdapter}. It is the
+ * simplest correct adapter: a stand-in you can commit to and read from in tests
+ * without a database, and the fixture the conformance suite runs against to confirm
+ * the suite exercises real behavior. An adapter for a given object-relational
+ * mapper is complete 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.
+ * It models the semantics minimally but faithfully: one row store per model, an
+ * idempotency ledger keyed by `clientTxId`, and an append-only outbox with a
+ * monotonic cursor.
  */
 import { AbloValidationError } from '../../errors.js';
 function rowId(op) {
@@ -63,7 +64,7 @@ export function memoryDataSource() {
     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.
+            // Nothing to create in memory. A database-backed adapter returns the SQL for its ablo_idempotency and ablo_outbox tables here.
             return [];
         },
         async read(req) {
@@ -108,7 +109,7 @@ export function memoryDataSource() {
             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,
+                nextCursor: page.at(-1)?.cursor ?? null,
             };
         },
     };

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

@@ -1,20 +1,21 @@
 /**
- * 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).
+ * The Prisma adapter for the data-source interface. It implements
+ * {@link DataSourceAdapter} against a Prisma client and passes the same conformance
+ * suite as the in-memory reference and the other adapters.
  *
- * 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.
+ * The adapter owns the transactional outbox and idempotency bookkeeping, so you
+ * never write them: `commit` runs the row mutations, the `ablo_outbox` append, and
+ * the `ablo_idempotency` record inside a single `prisma.$transaction`, and
+ * `migrations` returns the SQL that creates 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.
+ * It takes no dependency on `@prisma/client`. The client is accepted structurally
+ * as {@link PrismaLike}, so this module compiles without Prisma installed and can
+ * be tested with a fake, while a real `PrismaClient` satisfies the shape 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). */
+/** A Prisma model delegate — the subset of its methods the adapter calls. */
 export interface PrismaDelegate {
     findUnique(args: {
         where: {
@@ -46,7 +47,7 @@ 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. */
+/** A Prisma client, or its interactive-transaction client, as a structural shape that needs no `@prisma/client` import. */
 export interface PrismaLike extends PrismaRaw {
     $transaction<T>(fn: (tx: PrismaLike & PrismaRaw) => Promise<T>): Promise<T>;
 }

package/dist/source/adapters/prisma.js

@@ -1,34 +1,31 @@
 /**
- * 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).
+ * The Prisma adapter for the data-source interface. It implements
+ * {@link DataSourceAdapter} against a Prisma client and passes the same conformance
+ * suite as the in-memory reference and the other adapters.
  *
- * 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.
+ * The adapter owns the transactional outbox and idempotency bookkeeping, so you
+ * never write them: `commit` runs the row mutations, the `ablo_outbox` append, and
+ * the `ablo_idempotency` record inside a single `prisma.$transaction`, and
+ * `migrations` returns the SQL that creates 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.
+ * It takes no dependency on `@prisma/client`. The client is accepted structurally
+ * as {@link PrismaLike}, so this module compiles without Prisma installed and can
+ * be tested with a fake, while a real `PrismaClient` satisfies the shape at the
+ * call site.
  */
 import { AbloValidationError } from '../../errors.js';
 import { outboxEventSchema } from '../contract.js';
 import { adapterTableMigrations } from '../migrations.js';
-const lowerFirst = (s) => (s ? s[0].toLowerCase() + s.slice(1) : s);
+const lowerFirst = (s) => (s ? s.charAt(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.
+ * Resolves a model's Prisma delegate by name. This is the one unavoidable cast in
+ * the adapter, and it reflects a real limit of the type system rather than a
+ * shortcut. Writes inside `prisma.$transaction(tx => …)` must go through the
+ * transactional client `tx`, and the model is known only as a runtime string.
+ * Prisma keys its client by fixed property names (`{ task: TaskDelegate; … }`), so
+ * a dynamic `tx[name]` lookup is `unknown` to the compiler: there is no static key
+ * to infer from a string. The cast is checked at runtime immediately afterward by
+ * confirming that `findMany` is a function on the resolved delegate.
  */
 function delegateFor(client, name) {
     const delegate = client[name];
@@ -37,7 +34,7 @@ function delegateFor(client, name) {
     }
     return delegate;
 }
-/** Translate a Source `where` tuple set into a Prisma `where` object. */
+/** Translates a source-query `where` tuple set into a Prisma `where` object. */
 function toPrismaWhere(where) {
     const out = {};
     for (const clause of where ?? []) {
@@ -104,7 +101,7 @@ function rowId(op) {
 }
 export function prismaDataSource(prisma, schema, options = {}) {
     const delegateName = options.delegateName ?? lowerFirst;
-    void schema; // reserved for codegen-typed reads / model validation
+    void schema; // held for typed reads and model validation
     const applyOperation = async (tx, op) => {
         const delegate = delegateFor(tx, delegateName(op.model));
         const id = rowId(op);
@@ -138,14 +135,15 @@ export function prismaDataSource(prisma, schema, options = {}) {
             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 cachedRow = cached[0];
+                if (cachedRow)
+                    return { rows: cachedRow.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.
+                    // Transactional outbox: one event per operation, written in this same 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());
                 }
@@ -170,7 +168,7 @@ export function prismaDataSource(prisma, schema, options = {}) {
             }));
             return {
                 events,
-                nextCursor: events.length > 0 ? events[events.length - 1].cursor : null,
+                nextCursor: events.at(-1)?.cursor ?? null,
             };
         },
     };

package/dist/source/conformance.d.ts

@@ -1,28 +1,35 @@
 /**
- * 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.
+ * The conformance suite for data-source adapters: a shared set of tests that checks
+ * whether an adapter is correct. Every adapter in this package (Prisma, Drizzle,
+ * Kysely) and any adapter you write yourself runs this suite to confirm it upholds
+ * the guarantees {@link DataSourceAdapter} promises. An adapter is complete when it
+ * passes, not merely 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:
+ * The suite is runner-agnostic: each check is a plain async function that throws,
+ * via `node:assert`, on failure. {@link runDataSourceTests} registers the checks
+ * with whichever `it` or `test` function you pass, so it runs 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.
+ * The checks cover the adapter contract: commit idempotency, read-after-write, and
+ * the transactional outbox with its cursor. They do not cover request-signature or
+ * scope rejection, which the HTTP handler enforces before the adapter is ever
+ * called and which is tested separately.
  */
 import type { DataSourceAdapter } from './adapter.js';
+/** A factory that returns a fresh adapter. Each check calls it to start from clean state. */
 export type MakeAdapter = () => DataSourceAdapter | Promise<DataSourceAdapter>;
 /** A single conformance check. `run` throws on failure. */
 export interface ConformanceCheck {
     readonly name: string;
     run(): Promise<void>;
 }
+/**
+ * Builds the list of conformance checks for an adapter. Call this to run the checks
+ * yourself, or use {@link runDataSourceTests} to register them with a test runner.
+ */
 export declare function dataSourceConformanceChecks(make: MakeAdapter): ConformanceCheck[];
 /**
  * Register the conformance checks with a test runner's `it`/`test` function.