@abloatai/ablo 0.26.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))

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))

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) {

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.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);
@@ -146,7 +143,7 @@ export function prismaDataSource(prisma, schema, options = {}) {
                     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());
                 }

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.

package/dist/source/conformance.js

@@ -1,26 +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.
+ * 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 assert from 'node:assert/strict';
 const change = (clientTxId, ops) => ({
     clientTxId,
     operations: ops,
 });
+/**
+ * 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 function dataSourceConformanceChecks(make) {
     return [
         {

package/dist/source/connector.d.ts

@@ -1,15 +1,13 @@
 /**
- * Customer-side Data Source reverse-channel connector.
+ * Opens the connector's side of the Data Source reverse channel. You run this
+ * process next to your database; it dials an outbound WebSocket to Ablo and serves
+ * the load, list, and commit requests over that socket, so a handler with no
+ * public URL never needs to receive inbound webhooks. It is the counterpart to
+ * `createPushQueue`, which gives the outbound events feed the same treatment, and
+ * it speaks the frames defined in `connectorProtocol.ts`.
  *
- * The dial-out half of the reverse channel (see `connector-protocol.ts`). The
- * customer runs this next to their database; it opens an OUTBOUND WebSocket to
- * Ablo Cloud and serves the `commit`/`load`/`list` leg over that socket instead
- * of receiving inbound webhooks. This is the symmetric primitive to
- * `createPushQueue` (which already gives the `events` leg an outbound transport)
- * and mirrors the Stripe CLI's `stripe listen`.
- *
- * The connector does NOT reimplement any handler logic. It wraps the SAME
- * `(request: Request) => Promise<Response>` the customer's deployed route uses:
+ * The connector reimplements none of the handler logic. It wraps the same
+ * `(request: Request) => Promise<Response>` your deployed route already uses:
  *
  *   import { dataSource, createSourceConnector } from '@abloatai/ablo';
  *   import { sourceOptions } from './ablo.source'; // shared with route.ts
@@ -20,23 +18,24 @@
  *   });
  *   await connector.run(controller.signal);
  *
- * Each drained `request` frame is replayed into a synthesized `Request` carrying
- * the original Standard Webhooks signature headers, so the handler verifies it
- * through the unchanged `verifyAbloSourceRequest` — identical to the webhook
- * path. The transport changes; the trust model does not.
+ * Each incoming `request` frame is replayed into a `Request` that carries the
+ * original signature headers, so the handler verifies it through the same
+ * `verifyAbloSourceRequest` it uses on the webhook path. The transport changes;
+ * the trust model does not.
  */
 /**
- * Reconnect backoff, in ms, indexed by consecutive failed connect attempts.
- * Unlike the (multi-day) Standard Webhooks delivery schedule, a long-lived
- * control socket should re-establish quickly and cap at a steady interval, so
- * this is a short capped curve. The last entry repeats for further attempts. A
- * clean `ready` resets the counter to 0.
+ * The reconnect backoff, in milliseconds, indexed by the number of consecutive
+ * failed connect attempts. A long-lived control socket should recover quickly and
+ * then settle at a steady interval, so this is a short curve that caps rather than
+ * growing without bound. The final entry repeats for any further attempts, and a
+ * connection that reaches `ready` resets the count to zero.
  */
 export declare const DEFAULT_RECONNECT_SCHEDULE: readonly number[];
 /**
- * Minimal structural WebSocket surface — the browser/`globalThis.WebSocket` API,
- * which Node 24+ implements natively. The `ws` package's default export also
- * satisfies this (it exposes `addEventListener`). Injectable for tests.
+ * The minimal WebSocket surface the connector needs, matching the standard
+ * `globalThis.WebSocket` API that browsers and current Node versions provide. The
+ * `ws` package's default export also satisfies it. Supply your own implementation
+ * to substitute a fake in tests.
  */
 export interface ConnectorWebSocket {
     send(data: string): void;
@@ -57,18 +56,18 @@ export type ConnectorWebSocketFactory = (url: string, protocols: readonly string
 export type ConnectorStatus = 'connecting' | 'ready' | 'disconnected';
 export interface SourceConnectorOptions {
     /**
-     * Ablo project API key. Defaults gate to `sk_test_*` (local-dev / sandbox);
-     * an `sk_live_*` key is only accepted when the source has opted into
-     * reverse-channel for production server-side.
+     * Your Ablo project API key. A test key (`sk_test_*`) works by default for local
+     * development and sandboxes; a live key (`sk_live_*`) is accepted only once the
+     * source has opted the reverse channel in for production use.
      */
     readonly apiKey: string;
     /**
-     * The unchanged Data Source handler — `dataSource(options)` /
-     * `abloSource(options)`. The connector feeds it synthesized `Request`s and
-     * relays the `Response`s back; it never inspects or alters them.
+     * The Data Source handler to serve, as returned by `dataSource(options)` or
+     * `abloSource(options)`. The connector feeds it each request and relays the
+     * response back untouched; it never inspects or alters either one.
      */
     readonly handler: (request: Request) => Promise<Response>;
-    /** Ablo Cloud base URL. Default `https://api.abloatai.com`. */
+    /** The Ablo base URL to dial. Defaults to `https://api.abloatai.com`. */
     readonly baseURL?: string;
     /** Inject a WebSocket implementation. Default `globalThis.WebSocket`. */
     readonly webSocket?: ConnectorWebSocketFactory;
@@ -87,9 +86,9 @@ export interface SourceConnectorOptions {
 }
 export interface SourceConnector {
     /**
-     * Run the connect → serve → reconnect loop until `signal` aborts. Resolves
-     * when aborted. Rejects only on a fatal, non-retryable condition (e.g. no
-     * WebSocket implementation available).
+     * Runs the connect, serve, and reconnect loop until `signal` aborts, then
+     * resolves. It rejects only on a fatal condition that cannot be retried, such as
+     * no WebSocket implementation being available.
      */
     run(signal: AbortSignal): Promise<void>;
 }