@abloatai/ablo 0.9.0 → 0.9.1

package/dist/source/adapter.d.ts

@@ -1,24 +1,30 @@
 /**
- * The Data Source adapter spine — ONE interface every ORM backend implements,
- * and the bridge that wires it into the core `dataSource()` handler.
+ * The Data Source adapter — ONE interface every ORM backend implements, and the
+ * bridge that wires it into the core `dataSource()` handler.
  *
  * Pattern (Auth.js / Better Auth): one core interface, one package per ORM
  * (`prismaDataSource`, `drizzleDataSource`, `kyselyDataSource`), each provably
- * correct via the shared conformance suite. The adapter owns reality-access +
- * the transactional outbox/idempotency, so a customer never hand-writes them:
+ * correct via the shared conformance suite. The adapter owns reading and writing
+ * the database, plus the transactional outbox and idempotency, so a customer never
+ * hand-writes them:
  *
  *   export const POST = dataSource({
  *     schema, apiKey: process.env.ABLO_API_KEY!,
  *     ...sourceHandlersFromAdapter(prismaDataSource(prisma, schema), schema),
  *   });
  *
- * The bridge below is the spine connection: it turns ONE adapter into the core
- * handler's `commit` / `events` / per-model `load`+`list` — no per-ORM branching
- * anywhere above the adapter.
+ * The bridge below connects the adapter to the core: it turns ONE adapter into the
+ * core handler's `commit` / `events` / per-model `load`+`list` — no per-ORM
+ * branching anywhere above the adapter.
  */
 import type { SourceListQuery, SourceRequestContext } from './index.js';
 import type { AdapterCapabilities, ChangeSet, EventsPage, Migration } from './contract.js';
-/** A canonical row — JSON object keyed by column. `unknown` leaf is narrowed by codegen later. */
+/**
+ * A canonical row keyed by schema FIELD name (e.g. `operatorId`) — the SDK shape,
+ * NOT physical column names. Each adapter is the translation boundary: Prisma maps
+ * via its `@map`, Drizzle via the schema's `camelToSnake`/`column` rule. `unknown`
+ * leaf is narrowed by codegen later.
+ */
 export type Row = Record<string, unknown>;
 /** A read against the canonical store — a single-row load or a filtered list. */
 export type AdapterReadRequest = {
@@ -37,13 +43,13 @@ export interface AdapterCommitResult {
     readonly rows: readonly Row[];
 }
 /**
- * The spine. An ORM adapter implements exactly these. `read`/`commit` are
- * reality-access; `events` reads the outbox; `migrations` ships the
- * `ablo_idempotency` + `ablo_outbox` DDL so the customer never writes it.
+ * The adapter interface. An ORM adapter implements exactly these. `read`/`commit`
+ * read and write the database; `events` reads the outbox; `migrations` ships the
+ * `ablo_idempotency` + `ablo_outbox` table-creation SQL so the customer never writes it.
  */
 export interface DataSourceAdapter {
     readonly capabilities: AdapterCapabilities;
-    /** DDL for the adapter-owned tables. `ablo init` emits these. */
+    /** The table-creation SQL the adapter ships for its own tables (`ablo_idempotency` + `ablo_outbox`). */
     migrations(): readonly Migration[];
     /** Canonical rows for a load/list. */
     read(req: AdapterReadRequest): Promise<readonly Row[]>;

package/dist/source/adapter.js

@@ -1,19 +1,20 @@
 /**
- * The Data Source adapter spine — ONE interface every ORM backend implements,
- * and the bridge that wires it into the core `dataSource()` handler.
+ * The Data Source adapter — ONE interface every ORM backend implements, and the
+ * bridge that wires it into the core `dataSource()` handler.
  *
  * Pattern (Auth.js / Better Auth): one core interface, one package per ORM
  * (`prismaDataSource`, `drizzleDataSource`, `kyselyDataSource`), each provably
- * correct via the shared conformance suite. The adapter owns reality-access +
- * the transactional outbox/idempotency, so a customer never hand-writes them:
+ * correct via the shared conformance suite. The adapter owns reading and writing
+ * the database, plus the transactional outbox and idempotency, so a customer never
+ * hand-writes them:
  *
  *   export const POST = dataSource({
  *     schema, apiKey: process.env.ABLO_API_KEY!,
  *     ...sourceHandlersFromAdapter(prismaDataSource(prisma, schema), schema),
  *   });
  *
- * The bridge below is the spine connection: it turns ONE adapter into the core
- * handler's `commit` / `events` / per-model `load`+`list` — no per-ORM branching
- * anywhere above the adapter.
+ * The bridge below connects the adapter to the core: it turns ONE adapter into the
+ * core handler's `commit` / `events` / per-model `load`+`list` — no per-ORM
+ * branching anywhere above the adapter.
  */
 export {};

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

@@ -1,12 +1,21 @@
 /**
- * Drizzle Data Source adapter. Same spine + conformance as `prismaDataSource`,
+ * 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 customer passes their Drizzle `tables` map (`{ task: pgTable(…) }`); a
- *     table object is resolved by name with NO reflection cast — unlike Prisma's
- *     nominal client, a `Record<string, PgTable>` is genuinely indexable.
+ *
+ * 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
@@ -20,8 +29,8 @@
  * adapter is one small, fully-typed unit with no per-driver builder generics.
  */
 import { type SQL } from 'drizzle-orm';
-import type { PgTable } from 'drizzle-orm/pg-core';
 import type { DataSourceAdapter, Row } from '../adapter.js';
+import type { Schema, SchemaRecord } from '../../schema/schema.js';
 /** The subset of a Drizzle database/transaction handle the adapter calls. */
 export interface DrizzleLike {
     execute(query: SQL): Promise<DrizzleExecuteResult>;
@@ -31,4 +40,4 @@ export interface DrizzleLike {
 export type DrizzleExecuteResult = readonly Row[] | {
     readonly rows: readonly Row[];
 };
-export declare function drizzleDataSource(db: DrizzleLike, tables: Record<string, PgTable>): DataSourceAdapter;
+export declare function drizzleDataSource<S extends SchemaRecord>(db: DrizzleLike, schema: Schema<S>): DataSourceAdapter;

package/dist/source/adapters/drizzle.js

@@ -1,12 +1,21 @@
 /**
- * Drizzle Data Source adapter. Same spine + conformance as `prismaDataSource`,
+ * 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 customer passes their Drizzle `tables` map (`{ task: pgTable(…) }`); a
- *     table object is resolved by name with NO reflection cast — unlike Prisma's
- *     nominal client, a `Record<string, PgTable>` is genuinely indexable.
+ *
+ * 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
@@ -19,8 +28,12 @@
  * 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, getTableName } from 'drizzle-orm';
+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;
 }
@@ -33,74 +46,99 @@ function rowId(op) {
 }
 /** `col1, col2` as a safely-quoted identifier list. */
 const identList = (cols) => sql.join(cols.map((c) => sql.identifier(c)), sql `, `);
-export function drizzleDataSource(db, tables) {
-    const tableNameFor = (model) => {
-        const table = tables[model];
-        if (!table)
-            throw new Error(`drizzleDataSource: no Drizzle table for model "${model}"`);
-        return getTableName(table);
+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 table = sql.identifier(tableNameFor(op.model));
+        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] ?? { id };
+            return deleted[0] ? toFields(mc, deleted[0]) : { id };
         }
         if (op.type === 'CREATE') {
-            const data = { id, ...input };
+            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] ?? data;
+            return inserted[0] ? toFields(mc, inserted[0]) : { id, ...input };
         }
-        // UPDATE / ARCHIVE / UNARCHIVE — a SET clause + the lifecycle column.
-        const patch = {
+        // 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' ? { archived_at: new Date() } : {}),
-            ...(op.type === 'UNARCHIVE' ? { archived_at: null } : {}),
-        };
+            ...(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] ?? { id, ...patch };
+        return updated[0] ? toFields(mc, updated[0]) : { id, ...input };
     };
     return {
         capabilities: { transactions: true, propose: false, schemaIntrospection: true },
         migrations() {
-            return [
-                {
-                    name: 'ablo_idempotency',
-                    up: `CREATE TABLE IF NOT EXISTS ablo_idempotency (
-  client_tx_id TEXT PRIMARY KEY,
-  response     JSONB NOT NULL,
-  created_at   TIMESTAMPTZ NOT NULL DEFAULT now()
-);`,
-                },
-                {
-                    name: 'ablo_outbox',
-                    up: `CREATE TABLE IF NOT EXISTS ablo_outbox (
-  cursor          BIGSERIAL PRIMARY KEY,
-  id              TEXT NOT NULL UNIQUE,
-  model           TEXT NOT NULL,
-  entity_id       TEXT NOT NULL,
-  type            TEXT NOT NULL,
-  data            JSONB,
-  organization_id TEXT,
-  client_tx_id    TEXT,
-  occurred_at     BIGINT,
-  created_at      TIMESTAMPTZ NOT NULL DEFAULT now()
-);`,
-                },
-            ];
+            return adapterTableMigrations();
         },
         async read(req) {
-            const table = sql.identifier(tableNameFor(req.model));
+            const mc = modelColumns(req.model);
+            const table = sql.identifier(mc.table);
             if (req.kind === 'load') {
-                return rowsOf(await db.execute(sql `SELECT * FROM ${table} WHERE id = ${req.id} LIMIT 1`));
+                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;
-            return rowsOf(await db.execute(sql `SELECT * FROM ${table} LIMIT ${limit}`));
+            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) => {

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

@@ -1,6 +1,6 @@
 /**
  * In-memory reference Data Source adapter — the canonical correct implementation
- * of the spine. It is the test double for the bridge/handler AND the thing the
+ * 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.

package/dist/source/adapters/memory.js

@@ -1,6 +1,6 @@
 /**
  * In-memory reference Data Source adapter — the canonical correct implementation
- * of the spine. It is the test double for the bridge/handler AND the thing the
+ * 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.
@@ -62,7 +62,7 @@ export function memoryDataSource() {
     return {
         capabilities: { transactions: true, propose: false, schemaIntrospection: false },
         migrations() {
-            // In-memory: no DDL. A real ORM adapter ships ablo_idempotency + ablo_outbox here.
+            // In-memory: no table-creation SQL. A real ORM adapter ships ablo_idempotency + ablo_outbox here.
             return [];
         },
         async read(req) {

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

@@ -1,12 +1,12 @@
 /**
  * Prisma Data Source adapter. The first real ORM adapter (Auth.js pattern: one
- * package per ORM, all behind the `DataSourceAdapter` spine, all proven by the
+ * 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 DDL for those two tables (`ablo init` emits it).
+ * 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
@@ -46,7 +46,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-tx client) — structural, no SDK dependency. */
+/** 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>;
 }

package/dist/source/adapters/prisma.js

@@ -1,18 +1,19 @@
 /**
  * Prisma Data Source adapter. The first real ORM adapter (Auth.js pattern: one
- * package per ORM, all behind the `DataSourceAdapter` spine, all proven by the
+ * 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 DDL for those two tables (`ablo init` emits it).
+ * 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
@@ -20,7 +21,7 @@ const lowerFirst = (s) => (s ? s[0].toLowerCase() + s.slice(1) : s);
  *
  *   - 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/tx is NOMINALLY keyed (`{ task: TaskDelegate; … }`), so a
+ *   - 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
@@ -122,31 +123,7 @@ export function prismaDataSource(prisma, schema, options = {}) {
     return {
         capabilities: { transactions: true, propose: false, schemaIntrospection: true },
         migrations() {
-            return [
-                {
-                    name: 'ablo_idempotency',
-                    up: `CREATE TABLE IF NOT EXISTS ablo_idempotency (
-  client_tx_id TEXT PRIMARY KEY,
-  response     JSONB NOT NULL,
-  created_at   TIMESTAMPTZ NOT NULL DEFAULT now()
-);`,
-                },
-                {
-                    name: 'ablo_outbox',
-                    up: `CREATE TABLE IF NOT EXISTS ablo_outbox (
-  cursor         BIGSERIAL PRIMARY KEY,
-  id             TEXT NOT NULL UNIQUE,
-  model          TEXT NOT NULL,
-  entity_id      TEXT NOT NULL,
-  type           TEXT NOT NULL,
-  data           JSONB,
-  organization_id TEXT,
-  client_tx_id   TEXT,
-  occurred_at    BIGINT,
-  created_at     TIMESTAMPTZ NOT NULL DEFAULT now()
-);`,
-                },
-            ];
+            return adapterTableMigrations();
         },
         async read(req) {
             const delegate = delegateFor(prisma, delegateName(req.model));
@@ -167,7 +144,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 tx.
+                    // 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());
                 }

package/dist/source/conformance.d.ts

@@ -2,7 +2,7 @@
  * 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"
+ * 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

package/dist/source/conformance.js

@@ -2,7 +2,7 @@
  * 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"
+ * 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
@@ -109,7 +109,7 @@ export function dataSourceConformanceChecks(make) {
             },
         },
         {
-            name: 'a later UPDATE under a new clientTxId is applied (idempotency is per-tx)',
+            name: 'a later UPDATE under a new clientTxId is applied (idempotency is per-transaction)',
             run: async () => {
                 const adapter = await make();
                 await adapter.commit(change('tx_c1', [{ type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } }]));

package/dist/source/contract.d.ts

@@ -126,8 +126,9 @@ export declare const eventsPageSchema: z.ZodObject<{
 }, 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.
+ * A table-creation migration an adapter ships so a customer never hand-writes the
+ * `ablo_idempotency` / `ablo_outbox` tables — the adapter returns them from
+ * `migrations()`.
  */
 export declare const migrationSchema: z.ZodObject<{
     name: z.ZodString;

package/dist/source/contract.js

@@ -73,8 +73,9 @@ export const eventsPageSchema = z.object({
     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.
+ * A table-creation migration an adapter ships so a customer never hand-writes the
+ * `ablo_idempotency` / `ablo_outbox` tables — the adapter returns them from
+ * `migrations()`.
  */
 export const migrationSchema = z.object({
     /** Stable name, used as the migration filename + applied-ledger key. */

package/dist/source/index.d.ts

@@ -466,3 +466,4 @@ export { createPushQueue, InMemoryPushQueueStorage, STANDARD_WEBHOOKS_RETRY_SCHE
 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';
+export { adapterTableMigrations } from './migrations.js';

package/dist/source/index.js

@@ -59,8 +59,8 @@ function json(data, status = 200) {
     });
 }
 /**
- * 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
+ * Serve a request from an ORM `adapter`. Routes the four operations to the adapter
+ * interface (`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) {
@@ -419,3 +419,4 @@ export function dataSource(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';
+export { adapterTableMigrations } from './migrations.js';

package/dist/source/migrations.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The table-creation SQL every ORM adapter ships for its OWN infrastructure tables —
+ * `ablo_idempotency` (dedupe by clientTxId) and `ablo_outbox` (transactional
+ * outbox the `events()` feed reads). Defined ONCE here so the Prisma adapter, the
+ * Drizzle adapter, and `ablo migrate` can never disagree on the shape (they used
+ * to inline their own copies, which had already drifted in whitespace).
+ *
+ * These are NOT model tables and are NOT emitted by the hosted provisioner
+ * (`generateProvisionPlan`) — the hosted path uses `sync_deltas` directly. They
+ * exist only on a customer's own database in Data Source mode.
+ */
+import type { Migration } from './contract.js';
+/** Canonical adapter-owned table-creation SQL. Idempotent (`IF NOT EXISTS`). */
+export declare function adapterTableMigrations(): readonly Migration[];

package/dist/source/migrations.js

@@ -0,0 +1,39 @@
+/**
+ * The table-creation SQL every ORM adapter ships for its OWN infrastructure tables —
+ * `ablo_idempotency` (dedupe by clientTxId) and `ablo_outbox` (transactional
+ * outbox the `events()` feed reads). Defined ONCE here so the Prisma adapter, the
+ * Drizzle adapter, and `ablo migrate` can never disagree on the shape (they used
+ * to inline their own copies, which had already drifted in whitespace).
+ *
+ * These are NOT model tables and are NOT emitted by the hosted provisioner
+ * (`generateProvisionPlan`) — the hosted path uses `sync_deltas` directly. They
+ * exist only on a customer's own database in Data Source mode.
+ */
+/** Canonical adapter-owned table-creation SQL. Idempotent (`IF NOT EXISTS`). */
+export function adapterTableMigrations() {
+    return [
+        {
+            name: 'ablo_idempotency',
+            up: `CREATE TABLE IF NOT EXISTS ablo_idempotency (
+  client_tx_id TEXT PRIMARY KEY,
+  response     JSONB NOT NULL,
+  created_at   TIMESTAMPTZ NOT NULL DEFAULT now()
+);`,
+        },
+        {
+            name: 'ablo_outbox',
+            up: `CREATE TABLE IF NOT EXISTS ablo_outbox (
+  cursor          BIGSERIAL PRIMARY KEY,
+  id              TEXT NOT NULL UNIQUE,
+  model           TEXT NOT NULL,
+  entity_id       TEXT NOT NULL,
+  type            TEXT NOT NULL,
+  data            JSONB,
+  organization_id TEXT,
+  client_tx_id    TEXT,
+  occurred_at     BIGINT,
+  created_at      TIMESTAMPTZ NOT NULL DEFAULT now()
+);`,
+        },
+    ];
+}

package/docs/cli.md

@@ -57,9 +57,9 @@ either mode) defines the same models test and live see; only the rows differ.
 | `ablo dev`                         | **Hosted** — push the schema to your test sandbox, then watch `ablo/schema.ts` and re-push on save.                                           | `--no-watch`, `--schema <path>`, `--export <name>`, `--url <url>`                                      |
 | `ablo logs`                        | Tail your scope's commit activity (`stripe logs tail`). Follows by default.                                                                   | `-n, --tail <N>`, `--since <dur\|ts>`, `--model`, `--op`, `--json`, `--no-follow`, `--mode test\|live` |
 | `ablo push`                        | **Hosted** — upload the schema to Ablo; the server diffs, migrates, and activates it.                                                         | `--force`, `--rename old:new`, `--backfill model.field=value`, `--schema`, `--export`, `--url`         |
-| `ablo migrate`                     | **Direct Postgres** — apply the schema to your own `DATABASE_URL` (you run the DDL).                                                          | `--dry-run`, `--output <file>`, `--schema`, `--export`                                                 |
+| `ablo migrate`                     | **Direct Postgres** — apply the schema to your own `DATABASE_URL` (you run the table-creation SQL).                                                          | `--dry-run`, `--output <file>`, `--schema`, `--export`                                                 |
 | `ablo pull`                        | **Direct Postgres** — generate `defineSchema(...)` from your existing tables (read-only, like `prisma db pull`).                              | `--out <path>`, `--app-schema <name>`, `--import <pkg>`, `--force`                                     |
-| `ablo check`                       | **Direct Postgres** — verify your _existing_ tables fit the schema (read-only, no DDL).                                                       | `--schema <path>`, `--export <name>`, `--app-schema <name>`                                            |
+| `ablo check`                       | **Direct Postgres** — verify your _existing_ tables fit the schema (read-only, no schema changes).                                                       | `--schema <path>`, `--export <name>`, `--app-schema <name>`                                            |
 | `ablo generate`                    | Emit TypeScript types from the schema.                                                                                                        | `--out <path>`, `--schema`, `--export`                                                                 |
 
 ## `ablo dev`
@@ -145,7 +145,7 @@ reshaping it. `ablo check` is read-only; it never proposes a migration.
 
 Same engine, two setups. If you use the **Direct Postgres connector**, use
 `ablo migrate` — it applies the schema to your own `DATABASE_URL`, and you run
-the DDL. If Ablo manages the sandbox/hosted store, use `ablo push` and
+the table-creation SQL. If Ablo manages the sandbox/hosted store, use `ablo push` and
 `ablo dev` — the server applies the change and version-gates connecting clients.
 
 ```bash

package/docs/index.md

@@ -42,7 +42,7 @@ Three things stay true no matter how you use Ablo:
 - [Quickstart](./quickstart.md) — Make your first schema-backed write.
 - [Schema Contract](./schema-contract.md) — One schema becomes typed model clients, React reads, agent writes, Data Source shape, and schema push.
 - [CLI & Migrations](./cli.md) — `init` / `migrate` / `push` / `generate`, the shared Zod→Postgres type map, and structured migration errors.
-- [Identity & Sync Groups](./identity.md) — Bring your own auth; tell Ablo who's connecting and how org / team / user map to sync-group scope.
+- [Identity & Sync Groups](./identity.md) — Use your own authentication; tell Ablo who's connecting and how org / team / user map to sync-group scope.
 - [Integration Guide](./integration-guide.md) — Choose Ablo-managed state, Data Source, React, multiplayer, and agent patterns.
 - [Guarantees](./guarantees.md) — What confirmed writes, stale checks, and claims guarantee.
 - [Interaction Model](./interaction-model.md) — The schema, claim, update, confirmation loop.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "State control API for AI agents and collaborative apps.",
   "license": "Apache-2.0",
   "type": "module",