@abloatai/ablo 0.8.0 → 0.9.1

package/dist/server/adapter.d.ts

@@ -0,0 +1,156 @@
+/**
+ * `@abloatai/ablo/server` — the DataAdapter CONTRACT vocabulary.
+ *
+ * This is the Better-Auth-style seam: the package defines the storage
+ * interface and its value types; a host (today `apps/sync-server`, tomorrow a
+ * consumer's app) implements it against a real database. The reference Postgres
+ * implementation (`executeCommit` + `selectAdapter`) stays host-side — it
+ * carries a `postgres` driver and raw SQL, which must never enter this
+ * browser-shippable package.
+ *
+ * Scope note: this file holds the parts of the contract that are PURE — they
+ * depend only on primitives and {@link Row}. The full `DataAdapter` interface
+ * (and its `sync()` method) references `SyncDelta`, which currently has two
+ * definitions (server `db/deltas` vs package `core`) pending unification; the
+ * `commit`/`read` request envelopes reference server domain types
+ * (`CommitContext`, `BootstrapModel`). Those stay server-local and re-import
+ * these primitives until that canonicalization lands.
+ */
+import type { SourceListQuery, SourceOperation, SourceRequestContext } from '../source/index.js';
+import type { ServerSyncDelta } from '../schema/sync-delta-wire.js';
+import type { BootstrapModel } from './read-config.js';
+import type { CommitContext, CommitResult } from './commit.js';
+import type { StorageMode } from './storage-mode.js';
+/**
+ * A canonical row — one model record keyed by column name. The VALUE type is
+ * `unknown`, on purpose and as a best practice: a row's columns are JSONB /
+ * driver-dynamic, so `unknown` forces callers to narrow before use (the safe
+ * opposite of `any`). This is the single named domain type for "a row"; nothing
+ * in the spine uses a bare `unknown[]`. When the schema engine emits per-model
+ * types, `read<T>()` can narrow this to `T` without touching call sites.
+ */
+export type Row = Record<string, unknown>;
+/**
+ * The result of a {@link Row} read. Two shapes mirror the two request kinds:
+ *  - `bootstrap`: full-load — model name → its rows (empty models omitted).
+ *  - `query`: a single filtered model query.
+ */
+export type ReadResult = {
+    readonly kind: 'bootstrap';
+    /** model name → its rows. Empty models are omitted. */
+    readonly models: Record<string, Row[]>;
+    /** Models whose read failed (partial success), if any. */
+    readonly failedModels?: string[];
+} | {
+    readonly kind: 'query';
+    readonly rows: readonly Row[];
+};
+/**
+ * Resume position for `sync` — the client's last-seen `sync_deltas` watermark.
+ * Deliberately JUST the position: org / syncGroups / maxGap are server-derived
+ * and bound onto the adapter at resolve time (a trust boundary — the client
+ * never supplies the org it reads). `lastSyncId <= 0` means "no position yet",
+ * which `sync` reports as `needsFullRead`.
+ */
+export interface SyncCursor {
+    readonly lastSyncId: number;
+}
+export interface DataAdapterCapabilities {
+    /** The backend can dry-run a change without committing it. */
+    readonly propose?: boolean;
+    /** `commit` is atomic (all-or-nothing) across the change's operations. */
+    readonly transactions?: boolean;
+    /** Changes fan out in real time (vs poll-only). */
+    readonly realtime?: boolean;
+    /** The backend can be introspected for its schema. */
+    readonly schemaIntrospection?: boolean;
+}
+/** Result of a dry-run proposal (only adapters with `capabilities.propose`). */
+export interface ProposalResult {
+    readonly ok: boolean;
+    readonly conflicts?: readonly {
+        readonly model: string;
+        readonly id: string;
+        readonly reason: string;
+    }[];
+    readonly rows?: readonly Row[];
+}
+/**
+ * A request for canonical rows. Two shapes:
+ *  - `bootstrap`: the full-load reader — give me every (enabled) model's rows.
+ *  - `query`: a single filtered model query (the live `/sync/query` path).
+ *
+ * The `query` shape keeps the hosted SQL/tenant/RLS execution as a `runHosted`
+ * closure (same seam as a commit's `runHosted`): the adapter DISPATCHES — source
+ * → the customer's `list`, hosted/selfHosted → run the closure — but the query
+ * engine itself stays host-side rather than leaking into the adapter.
+ */
+export type ReadRequest = {
+    readonly kind: 'bootstrap';
+    readonly models: readonly BootstrapModel[];
+    readonly requestedModels?: readonly string[];
+    readonly scope?: SourceRequestContext;
+} | {
+    readonly kind: 'query';
+    readonly model: string;
+    /** Source-side model name, when it differs from `model`. */
+    readonly sourceModel?: string;
+    /** `__typename` stamped on each returned row. */
+    readonly typename: string;
+    readonly query: SourceListQuery;
+    readonly scope?: SourceRequestContext;
+    /** Hosted/self-hosted execution (compile + tenant pool + RLS + unpack). */
+    readonly runHosted: () => Promise<Row[]>;
+};
+/**
+ * A change to apply to the canonical store. `runHosted` is the pre-bound local
+ * mutator execution (the hosted/self-hosted write path lives in the mutator
+ * engine above the adapter); the hosted adapter simply runs it, while the source
+ * adapter ignores it and ships the operations to the customer endpoint. This is
+ * the seam that lets the adapter OWN the mode decision while the heavy mutator
+ * logic stays host-side.
+ */
+export interface ChangeSet {
+    readonly operations: readonly SourceOperation[];
+    readonly context: CommitContext;
+    readonly clientTxId: string;
+    readonly runHosted: () => Promise<CommitResult>;
+}
+export interface SyncResult {
+    /** Deltas in `(cursor.lastSyncId, nextCursor.lastSyncId]`, scoped to syncGroups. */
+    readonly changes: readonly ServerSyncDelta[];
+    readonly nextCursor: {
+        readonly lastSyncId: number;
+    };
+    /** True when the gap was too large to stream — caller must full-`read`. */
+    readonly needsFullRead: boolean;
+}
+/**
+ * The ONE interface every storage mode implements — the Better-Auth-style
+ * `Adapter` seam. The package owns this contract; a host (today
+ * `apps/sync-server`, tomorrow a consumer app) implements it against a real
+ * database. Design rule (load-bearing, = Zero's mutator principle): **adapters
+ * only guarantee reality access.** `read` fetches canonical rows, `commit`
+ * applies a change, `sync` reads the change log; orchestration (proposal,
+ * conflict policy) lives ABOVE the adapter. `propose` is a capability, never a
+ * required method.
+ */
+export interface DataAdapter {
+    /** Diagnostic discriminator (≈ Better Auth's `adapterId`). Routing decisions
+     *  go through the resolver/factory, not this. */
+    readonly mode: StorageMode;
+    readonly capabilities: DataAdapterCapabilities;
+    read(req: ReadRequest): Promise<ReadResult>;
+    commit(change: ChangeSet): Promise<CommitResult>;
+    sync(cursor: SyncCursor): Promise<SyncResult>;
+}
+/** An adapter whose backend can dry-run. Narrow to this only after checking the capability. */
+export interface ProposableDataAdapter extends DataAdapter {
+    propose(change: ChangeSet): Promise<ProposalResult>;
+}
+/** Resolves an authenticated scope to the adapter that serves it (≈ Better Auth's
+ *  `createAdapter` factory seam). */
+export type AdapterResolver = (scope: {
+    readonly projectId: string;
+    readonly accountScope?: string;
+}) => Promise<DataAdapter> | DataAdapter;

package/dist/server/adapter.js

@@ -0,0 +1,19 @@
+/**
+ * `@abloatai/ablo/server` — the DataAdapter CONTRACT vocabulary.
+ *
+ * This is the Better-Auth-style seam: the package defines the storage
+ * interface and its value types; a host (today `apps/sync-server`, tomorrow a
+ * consumer's app) implements it against a real database. The reference Postgres
+ * implementation (`executeCommit` + `selectAdapter`) stays host-side — it
+ * carries a `postgres` driver and raw SQL, which must never enter this
+ * browser-shippable package.
+ *
+ * Scope note: this file holds the parts of the contract that are PURE — they
+ * depend only on primitives and {@link Row}. The full `DataAdapter` interface
+ * (and its `sync()` method) references `SyncDelta`, which currently has two
+ * definitions (server `db/deltas` vs package `core`) pending unification; the
+ * `commit`/`read` request envelopes reference server domain types
+ * (`CommitContext`, `BootstrapModel`). Those stay server-local and re-import
+ * these primitives until that canonicalization lands.
+ */
+export {};

package/dist/server/commit.d.ts

@@ -0,0 +1,82 @@
+/**
+ * `@abloatai/ablo/server` — the COMMIT contract types.
+ *
+ * `CommitContext` is the attribution/intent envelope the host's commit executor
+ * stamps onto every delta a batch produces; `CommitResult` is the receipt. Both
+ * are PURE descriptors (no `postgres`, no SQL, no functions), which is why they
+ * live in the portable package while the SQL engine that consumes them
+ * (`executeCommit`) stays host-side. They feed the `ChangeSet`/`DataAdapter`
+ * contract.
+ *
+ * The attribution fields reuse the canonical `ParticipantKind` /
+ * `ConfirmationState` / `ParticipantRef` so the commit-time shape and the
+ * stored/broadcast delta shape share ONE source of truth (these were previously
+ * a server-local interface "kept in sync by convention").
+ */
+import type { ParticipantKind, ConfirmationState } from '../schema/sync-delta-row.js';
+import type { ParticipantRef } from '../schema/sync-delta-wire.js';
+export interface CommitContext {
+    participantId: string;
+    /**
+     * Typed participant classification — required so every delta written through
+     * the commit executor carries structured attribution, not a string-prefix
+     * convention.
+     */
+    participantKind: ParticipantKind;
+    organizationId: string;
+    /**
+     * The participant's own subscribed sync groups (from the WS upgrade or
+     * capability token). Appended to every delta's `sync_groups` so writes fan
+     * out to agents scoped to entity-level groups (e.g. `deck:abc`), not only the
+     * default `org:X` / `user:Y` surface. Callers that omit this fall back to the
+     * legacy `[org, user]` broadcast behavior.
+     */
+    syncGroups?: readonly string[];
+    /**
+     * Sandbox keys should not stamp `org:<organizationId>` on deltas — otherwise
+     * live org subscribers would see test-environment writes.
+     */
+    omitOrgSyncGroup?: boolean;
+    /**
+     * On-behalf-of attribution — whose authority the actor acted under. For
+     * human-direct commits, equals the actor. For agent commits, the human at the
+     * root of the capability's delegation chain. Null for `system` principals.
+     */
+    onBehalfOf?: ParticipantRef | null;
+    /**
+     * FK to AgentCapabilityRoot.capabilityId. Non-null for agent / system commits
+     * authorized by a Biscuit; null for human-direct commits. Embedded in every
+     * delta so the audit chain "delta → capability → human" is one FK hop.
+     */
+    capabilityId?: string | null;
+    /**
+     * ApiKey row id when the caller authenticated with an API key. Used by the
+     * idempotency cache and usage attribution. Null for session / capability
+     * callers.
+     */
+    apiKeyId?: string | null;
+    /**
+     * Whether the human explicitly approved the change. Defaults to `auto` until
+     * the chat-side previewed/approved plumbing lands.
+     */
+    confirmationState?: ConfirmationState;
+    /**
+     * FK to AgentTurn.id. Pinned at turn open by `SyncAgent.beginTurn`, threaded
+     * through the wire frame's `causedByTaskId`, validated by the commit handler
+     * (turn must belong to the same agent and be open), and written onto every
+     * delta this batch produces. Absent for human-direct commits and SDKs that
+     * predate the turn protocol (→ `caused_by_task_id = NULL`).
+     */
+    causedByTaskId?: string | null;
+}
+/**
+ * The receipt of a commit. Pins the exact `sync_deltas` id range the batch
+ * produced, so a caller can broadcast just THIS batch's deltas
+ * (`getDeltasInRange(firstSyncId - 1, lastSyncId, …)`) without racing concurrent
+ * commits with adjacent ids. `firstSyncId` is 0 when the batch produced no
+ * deltas (empty ops / all no-ops).
+ */
+export interface CommitResult {
+    lastSyncId: number;
+    firstSyncId: number;
+}

package/dist/server/commit.js

@@ -0,0 +1 @@
+export {};

package/dist/server/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `@abloatai/ablo/server` — the host-side surface of the sync engine.
+ *
+ * Today this exposes the DataAdapter CONTRACT vocabulary (see {@link Row}).
+ * It will grow to hold the transport/storage-agnostic commit orchestration and
+ * the `Hub` core lifted out of `apps/sync-server` (see
+ * docs/plans/sync-engine-server-extraction-plan.md). The reference Postgres
+ * adapter (`executeCommit`/`selectAdapter`) and the WebSocket process lifecycle
+ * stay in the host — only the portable, driver-free pieces live here.
+ */
+export type { Row, ReadResult, SyncCursor, DataAdapterCapabilities, ProposalResult, ReadRequest, ChangeSet, SyncResult, DataAdapter, ProposableDataAdapter, AdapterResolver, } from './adapter.js';
+export type { CommitContext, CommitResult } from './commit.js';
+export { storageModeSchema, type StorageMode } from './storage-mode.js';
+export type { ColumnOverride, BootstrapModel } from './read-config.js';

package/dist/server/index.js

@@ -0,0 +1 @@
+export { storageModeSchema } from './storage-mode.js';

package/dist/server/next.d.ts

@@ -0,0 +1,51 @@
+/**
+ * `@abloatai/ablo/server/next` — mount Ablo's HTTP surface in a consumer's
+ * Next.js App Router, the Better-Auth `toNextJsHandler` way:
+ *
+ * ```ts
+ * // app/api/ablo/[...all]/route.ts
+ * import { toAbloHandler } from '@abloatai/ablo/server/next';
+ * import { ablo } from '@/lib/ablo';        // your configured Ablo HTTP app
+ * export const { GET, POST } = toAbloHandler(ablo);
+ * ```
+ *
+ * Ablo's HTTP endpoints (bootstrap / query / the commit fallback) are stateless
+ * request→response, so they drop straight into a route handler. The realtime
+ * WebSocket channel is deliberately NOT served here — it is a persistent
+ * connection a serverless route handler cannot host, and stays an Ablo-hosted
+ * (or long-running Node) service. That is the HTTP/WSS split the architecture
+ * draws on purpose (see docs/plans/sync-gateway-audit-log-architecture.md).
+ *
+ * The package owns this MOUNT PRIMITIVE; the host owns the infra-bound app it
+ * wraps (the Hono app holding the Hub + routes + auth). Mirrors Better Auth,
+ * where `betterAuth()` builds the `.handler` and `toNextJsHandler` just maps it
+ * onto the HTTP verbs.
+ */
+/**
+ * Anything that resolves a Web `Request` to a `Response` — e.g. a Hono app's
+ * `.fetch`, a Better-Auth-style `{ handler }`, or a bare function.
+ */
+export type AbloFetchHandler = (request: Request) => Response | Promise<Response>;
+/** The shapes `toAbloHandler` accepts: a Hono-style `{ fetch }`, a
+ *  `{ handler }`, or a bare `(Request) => Response`. */
+export type AbloHttpApp = {
+    readonly fetch: AbloFetchHandler;
+} | {
+    readonly handler: AbloFetchHandler;
+} | AbloFetchHandler;
+/** The route-handler object a Next.js App Router `route.ts` re-exports. One
+ *  handler bound to every method the `[...all]` catch-all may receive. */
+export interface AbloRouteHandlers {
+    readonly GET: AbloFetchHandler;
+    readonly POST: AbloFetchHandler;
+    readonly PATCH: AbloFetchHandler;
+    readonly PUT: AbloFetchHandler;
+    readonly DELETE: AbloFetchHandler;
+    readonly OPTIONS: AbloFetchHandler;
+}
+/**
+ * Wrap a configured Ablo HTTP app into Next.js App Router route handlers.
+ * Mirrors Better Auth's `toNextJsHandler` — accepts the app's `fetch`/`handler`
+ * (or a bare function) and returns one handler per verb.
+ */
+export declare function toAbloHandler(app: AbloHttpApp): AbloRouteHandlers;

package/dist/server/next.js

@@ -0,0 +1,47 @@
+/**
+ * `@abloatai/ablo/server/next` — mount Ablo's HTTP surface in a consumer's
+ * Next.js App Router, the Better-Auth `toNextJsHandler` way:
+ *
+ * ```ts
+ * // app/api/ablo/[...all]/route.ts
+ * import { toAbloHandler } from '@abloatai/ablo/server/next';
+ * import { ablo } from '@/lib/ablo';        // your configured Ablo HTTP app
+ * export const { GET, POST } = toAbloHandler(ablo);
+ * ```
+ *
+ * Ablo's HTTP endpoints (bootstrap / query / the commit fallback) are stateless
+ * request→response, so they drop straight into a route handler. The realtime
+ * WebSocket channel is deliberately NOT served here — it is a persistent
+ * connection a serverless route handler cannot host, and stays an Ablo-hosted
+ * (or long-running Node) service. That is the HTTP/WSS split the architecture
+ * draws on purpose (see docs/plans/sync-gateway-audit-log-architecture.md).
+ *
+ * The package owns this MOUNT PRIMITIVE; the host owns the infra-bound app it
+ * wraps (the Hono app holding the Hub + routes + auth). Mirrors Better Auth,
+ * where `betterAuth()` builds the `.handler` and `toNextJsHandler` just maps it
+ * onto the HTTP verbs.
+ */
+function resolveFetch(app) {
+    if (typeof app === 'function')
+        return app;
+    if ('fetch' in app)
+        return app.fetch;
+    return app.handler;
+}
+/**
+ * Wrap a configured Ablo HTTP app into Next.js App Router route handlers.
+ * Mirrors Better Auth's `toNextJsHandler` — accepts the app's `fetch`/`handler`
+ * (or a bare function) and returns one handler per verb.
+ */
+export function toAbloHandler(app) {
+    const fetch = resolveFetch(app);
+    const handler = (request) => fetch(request);
+    return {
+        GET: handler,
+        POST: handler,
+        PATCH: handler,
+        PUT: handler,
+        DELETE: handler,
+        OPTIONS: handler,
+    };
+}

package/dist/server/read-config.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `@abloatai/ablo/server` — per-model READ configuration the bootstrap
+ * reader consumes. Host-side type config (physical table, tenancy column,
+ * parent-scoping) — pure data, no `postgres` — so it lives in the server
+ * subpath and feeds the `DataAdapter` read contract. The SQL that consumes it
+ * (the bootstrap query builder) stays host-side.
+ */
+/** A field→column mapping with an explicit post-`SELECT *` alias. */
+export interface ColumnOverride {
+    readonly field: string;
+    readonly column: string;
+    readonly alias: string;
+}
+export interface BootstrapModel {
+    name: string;
+    /**
+     * Additional names accepted for request-side lookup/filtering. In DB-canonical
+     * mode `name` stays the physical table name, while aliases cover generated
+     * compatibility names such as `WeatherReports` / `weatherReports`.
+     */
+    aliases?: readonly string[];
+    /**
+     * Schema key used by source endpoints. `name` remains the wire/result model
+     * name, usually the typename; source handlers are keyed by the developer's
+     * schema object (`files`, `slideLayers`, ...).
+     */
+    sourceModel?: string;
+    table: string;
+    syncGroups?: string[];
+    enabled?: boolean;
+    /** Max rows to return. Omit for unlimited. Maps to schema's bootstrapLimit. */
+    limit?: number;
+    /** SQL ORDER BY clause. Default: 'id'. Maps to schema's bootstrapOrderBy. */
+    orderBy?: string;
+    /** Whether the table has organization_id. Default: true. */
+    orgScoped?: boolean;
+    /** Physical tenancy column (default `organization_id`, configurable per model). */
+    orgColumn?: string;
+    /**
+     * Parent-table scoping for rows with no `organization_id` column. Mirrors the
+     * schema's `scopedVia` option. When set, the bootstrap query emits:
+     *
+     *   WHERE <table>.<localKey> IN
+     *     (SELECT <parentKey> FROM <parentTable> WHERE <parentOrgColumn> = $1)
+     *
+     * Applied IN ADDITION TO whatever `orgScoped` dictates — so a table can have
+     * its own `organization_id` AND further narrow via a parent, though the common
+     * use is `orgScoped: false` + `scopedVia` on tables that lack the column.
+     */
+    scopedVia?: {
+        localKey: string;
+        parentTable: string;
+        parentKey?: string;
+        parentOrgColumn?: string;
+    };
+    /** Client-facing field name → physical DB column for declared fields. */
+    fieldColumns?: Record<string, string>;
+    /** Physical-column aliases needed after SELECT * for `.from(...)` fields. */
+    columnOverrides?: readonly ColumnOverride[];
+}

package/dist/server/read-config.js

@@ -0,0 +1,8 @@
+/**
+ * `@abloatai/ablo/server` — per-model READ configuration the bootstrap
+ * reader consumes. Host-side type config (physical table, tenancy column,
+ * parent-scoping) — pure data, no `postgres` — so it lives in the server
+ * subpath and feeds the `DataAdapter` read contract. The SQL that consumes it
+ * (the bootstrap query builder) stays host-side.
+ */
+export {};

package/dist/server/storage-mode.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `@abloatai/ablo/server` — the storage-mode vocabulary the `DataAdapter`
+ * contract supports. Analogous to Better Auth's adapter `id`/`adapterId`: a
+ * diagnostic discriminator on the adapter, NOT a routing switch (routing goes
+ * through the resolver/factory). The package owns this enum so the contract and
+ * every host adapter agree on the closed set:
+ *   - `hosted`     — Ablo's control-plane database.
+ *   - `selfHosted` — the customer's database, same execution path as hosted.
+ *   - `source`     — a customer-owned endpoint (credentialless ingestion).
+ */
+import { z } from 'zod';
+export declare const storageModeSchema: z.ZodEnum<{
+    source: "source";
+    hosted: "hosted";
+    selfHosted: "selfHosted";
+}>;
+export type StorageMode = z.infer<typeof storageModeSchema>;

package/dist/server/storage-mode.js

@@ -0,0 +1,12 @@
+/**
+ * `@abloatai/ablo/server` — the storage-mode vocabulary the `DataAdapter`
+ * contract supports. Analogous to Better Auth's adapter `id`/`adapterId`: a
+ * diagnostic discriminator on the adapter, NOT a routing switch (routing goes
+ * through the resolver/factory). The package owns this enum so the contract and
+ * every host adapter agree on the closed set:
+ *   - `hosted`     — Ablo's control-plane database.
+ *   - `selfHosted` — the customer's database, same execution path as hosted.
+ *   - `source`     — a customer-owned endpoint (credentialless ingestion).
+ */
+import { z } from 'zod';
+export const storageModeSchema = z.enum(['hosted', 'source', 'selfHosted']);

package/dist/source/adapter.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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 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 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 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 = {
+    readonly kind: 'load';
+    readonly model: string;
+    readonly id: string;
+    readonly scope?: SourceRequestContext;
+} | {
+    readonly kind: 'list';
+    readonly model: string;
+    readonly query?: SourceListQuery;
+    readonly scope?: SourceRequestContext;
+};
+export interface AdapterCommitResult {
+    /** Canonical rows after the write — Ablo derives deltas from these. */
+    readonly rows: readonly Row[];
+}
+/**
+ * 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;
+    /** 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[]>;
+    /**
+     * Apply a change set transactionally and idempotently by `clientTxId`:
+     * a duplicate `clientTxId` returns the original rows without re-applying.
+     * Writes the `ablo_outbox` rows in the SAME transaction as the app rows.
+     */
+    commit(change: ChangeSet): Promise<AdapterCommitResult>;
+    /** Read outbox events after `cursor` (null = from the beginning), up to `limit`. */
+    events(cursor: string | null, limit: number): Promise<EventsPage>;
+}
+export type { AdapterCapabilities, ChangeSet, Migration, OutboxEvent, EventsPage } from './contract.js';

package/dist/source/adapter.js

@@ -0,0 +1,20 @@
+/**
+ * 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 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 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

@@ -0,0 +1,43 @@
+/**
+ * Drizzle Data Source adapter. Same adapter interface + conformance as `prismaDataSource`,
+ * built against Drizzle's REAL API (read from drizzle-orm's own source/docs):
+ *   - `db.transaction(async (tx) => …)` — interactive transaction (commit/rollback).
+ *   - `db.execute(sql`…`)` — parametrized raw SQL; `sql.identifier()` safely quotes
+ *     dynamic table/column names, `sql`${value}`` parametrizes values.
+ *
+ * SCHEMA-DRIVEN COLUMNS. Unlike Prisma — whose delegate applies the model's
+ * `@map` for free — this adapter writes raw SQL, so it would otherwise bypass any
+ * field→column translation. It therefore derives every table + column name from
+ * the SAME rule the provisioner uses (`generateProvisionPlan`):
+ *   table  = `model.tableName ?? key`
+ *   column = `fieldMeta.column ?? camelToSnake(field)`   (+ the model's tenancy column)
+ * so `ablo migrate` (which emits `operator_id`) and this adapter (which now writes
+ * `operator_id`) COMPOSE. Define the schema once, point Ablo at your Postgres —
+ * no hand-written parallel Drizzle table. The adapter is the translation boundary:
+ * its public surface (rows in/out, outbox `data`) is field-keyed (the SDK shape);
+ * the physical columns it reads/writes are snake_case.
+ *
+ * IMPORTANT GOTCHAS (from drizzle-orm docs):
+ *   1. Interactive `db.transaction` requires a driver that supports it. Neon's
+ *      `neon-http` driver does NOT (single-shot only) — use `neon-serverless`
+ *      (WebSocket) or `pg`. With neon-http the commit path throws at runtime.
+ *   2. `db.execute` result shape is driver-specific (postgres-js returns an
+ *      array-like RowList; node-postgres returns `{ rows }`). `rowsOf()`
+ *      normalizes both.
+ *
+ * We use `sql` + `db.execute` for ALL writes (not the fluent builder) so the
+ * adapter is one small, fully-typed unit with no per-driver builder generics.
+ */
+import { type SQL } from 'drizzle-orm';
+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>;
+    transaction<T>(fn: (tx: DrizzleLike) => Promise<T>): Promise<T>;
+}
+/** `db.execute` is array-like (postgres-js) or `{ rows }` (node-postgres). */
+export type DrizzleExecuteResult = readonly Row[] | {
+    readonly rows: readonly Row[];
+};
+export declare function drizzleDataSource<S extends SchemaRecord>(db: DrizzleLike, schema: Schema<S>): DataSourceAdapter;