@abloatai/ablo 0.29.3 → 0.30.0

package/dist/server/index.d.ts

@@ -9,5 +9,6 @@
  */
 export type { Row, ReadResult, SyncCursor, DataAdapterCapabilities, ProposalResult, ReadRequest, ChangeSet, SyncResult, DataAdapter, ProposableDataAdapter, AdapterResolver, } from './adapter.js';
 export type { CommitContext, CommitResult } from './commit.js';
+export { commitExecutionResultSchema } from '../wire/commit.js';
 export { storageModeSchema, type StorageMode } from './storageMode.js';
 export type { ColumnOverride, BootstrapModel } from './readConfig.js';

package/dist/server/index.js

@@ -1 +1,2 @@
+export { commitExecutionResultSchema } from '../wire/commit.js';
 export { storageModeSchema } from './storageMode.js';

package/dist/server/readConfig.d.ts

@@ -35,6 +35,16 @@ export interface BootstrapModel {
     orderBy?: string;
     /** Whether the table has organization_id. Default: true. */
     orgScoped?: boolean;
+    /**
+     * The model derives its tenant from the connected data source (`policy:
+     * { by: 'source' }`) rather than a row column. It carries no tenant predicate on a
+     * log plane, so it is excluded from the bootstrap set entirely until the
+     * write-through connect path can resolve the org from the source registration —
+     * serving it now would return every row to every tenant. Kept on the type as a
+     * defense-in-depth marker so a source-scoped model that reaches `getBootstrapData`
+     * fails closed rather than bootstrapping unscoped.
+     */
+    sourceScoped?: boolean;
     /** Physical tenancy column (default `organization_id`, configurable per model). */
     orgColumn?: string;
     /**

package/dist/source/adapter.d.ts

@@ -3,10 +3,12 @@
  * that wires an implementation into the `dataSource()` HTTP handler. This package
  * defines the contract and ships adapters for three object-relational mappers —
  * {@link prismaDataSource}, {@link drizzleDataSource}, and {@link kyselyDataSource} —
- * each verified by the shared conformance suite. You can also write your own.
+ * each verified by shared mutation checks plus endpoint-only outbox checks. The
+ * direct Kysely wrapper runs only the shared mutation contract. You can also
+ * write your own.
  *
- * An adapter reads and writes your database, and it owns the transactional outbox
- * and idempotency bookkeeping as well, so you never write those by hand:
+ * An endpoint adapter reads and writes your database, and it owns the transactional
+ * outbox and idempotency bookkeeping as well, so you never write those by hand:
  *
  *   export const POST = dataSource({
  *     schema, apiKey: process.env.ABLO_API_KEY!,
@@ -39,31 +41,40 @@ export type AdapterReadRequest = {
     readonly query?: SourceListQuery;
     readonly scope?: SourceRequestContext;
 };
-/** What {@link DataSourceAdapter.commit} returns: the rows as they stand after the write. */
+/** What {@link MutationAdapter.commit} returns: the rows as they stand after the write. */
 export interface AdapterCommitResult {
     /** The affected rows after the write. The change log is derived from these. */
     readonly rows: readonly Row[];
 }
 /**
- * The interface an adapter implements to serve one data source. `read` and
- * `commit` read from and write to your database, `events` reads the outbox that
- * `commit` appends to, and `migrations` supplies the SQL that creates the adapter's
- * own two tables. `capabilities` advertises which optional features the adapter
- * supports.
+ * Guarantees shared by direct and endpoint mutation wrappers. Both apply row DML
+ * and write the permanent idempotency ledger in one transaction. The scoped,
+ * server-authored `correlationId` is the ledger key; a caller-authored operation
+ * transaction id is never used as that namespace.
  */
-export interface DataSourceAdapter {
+export interface MutationAdapter {
     readonly capabilities: AdapterCapabilities;
-    /** The table-creation SQL the adapter needs for its own tables, `ablo_idempotency` and `ablo_outbox`. */
+    /** Infrastructure migrations required by this wrapper's advertised capabilities. */
     migrations(): readonly Migration[];
     /** The rows matching a load or list request. */
     read(req: AdapterReadRequest): Promise<readonly Row[]>;
     /**
-     * Applies a change set in one transaction, keyed for idempotency by `clientTxId`.
-     * Replaying the same `clientTxId` returns the original rows without applying the
-     * change again. The matching `ablo_outbox` rows are written in the same
-     * transaction as the data rows, so the outbox can never drift from the data.
+     * Applies a change set in one transaction, keyed by its scoped `correlationId`.
+     * Replaying the same correlation and canonical request hash returns the original
+     * rows without applying DML again; a different hash fails closed.
      */
     commit(change: ChangeSet): Promise<AdapterCommitResult>;
+}
+/**
+ * Endpoint-only extension of {@link MutationAdapter}. Its commit writes one
+ * correlated outbox event per operation in the same transaction as the DML and
+ * ledger. Direct wrappers deliberately do not implement this interface: WAL is
+ * their authoritative source feed and they must never write `ablo_outbox`.
+ */
+export interface DataSourceAdapter extends MutationAdapter {
+    readonly capabilities: AdapterCapabilities & {
+        readonly outboxEvents: true;
+    };
     /** Reads outbox events after `cursor` (`null` starts from the beginning), up to `limit` events. */
     events(cursor: string | null, limit: number): Promise<EventsPage>;
 }

package/dist/source/adapter.js

@@ -3,10 +3,12 @@
  * that wires an implementation into the `dataSource()` HTTP handler. This package
  * defines the contract and ships adapters for three object-relational mappers —
  * {@link prismaDataSource}, {@link drizzleDataSource}, and {@link kyselyDataSource} —
- * each verified by the shared conformance suite. You can also write your own.
+ * each verified by shared mutation checks plus endpoint-only outbox checks. The
+ * direct Kysely wrapper runs only the shared mutation contract. You can also
+ * write your own.
  *
- * An adapter reads and writes your database, and it owns the transactional outbox
- * and idempotency bookkeeping as well, so you never write those by hand:
+ * An endpoint adapter reads and writes your database, and it owns the transactional
+ * outbox and idempotency bookkeeping as well, so you never write those by hand:
  *
  *   export const POST = dataSource({
  *     schema, apiKey: process.env.ABLO_API_KEY!,

package/dist/source/adapters/drizzle.js

@@ -37,9 +37,11 @@ import { AbloValidationError } from '../../errors.js';
 import { sql } from 'drizzle-orm';
 import { outboxEventSchema } from '../contract.js';
 import { adapterTableMigrations } from '../migrations.js';
+import { assertSourceIdempotencyIntent, assertSourceIdempotencyRetention, sourceChangeIntentHash, } from '../idempotency.js';
 import { toSchemaJSON } from '../../schema/serialize.js';
 import { camelToSnake, snakeToCamel } from '../../schema/ddl.js';
 import { tenancyColumn } from '../../schema/tenancy.js';
+import { ABLO_POSTGRES_COMMIT_ECHO_PREFIX } from '../types.js';
 function rowsOf(result) {
     return Array.isArray(result) ? result : result.rows;
 }
@@ -131,7 +133,13 @@ export function drizzleDataSource(db, schema) {
         return updated[0] ? toFields(mc, updated[0]) : { id, ...input };
     };
     return {
-        capabilities: { transactions: true, propose: false, schemaIntrospection: true },
+        capabilities: {
+            transactions: true,
+            propose: false,
+            schemaIntrospection: true,
+            postgresWalEcho: true,
+            outboxEvents: true,
+        },
         migrations() {
             return adapterTableMigrations();
         },
@@ -147,33 +155,49 @@ export function drizzleDataSource(db, schema) {
             return rows.map((r) => toFields(mc, r));
         },
         async commit(change) {
+            const requestHash = sourceChangeIntentHash(change);
             return db.transaction(async (tx) => {
-                const cached = rowsOf(await tx.execute(sql `SELECT response FROM ablo_idempotency WHERE client_tx_id = ${change.clientTxId} LIMIT 1`));
+                const cached = rowsOf(await tx.execute(sql `SELECT response, request_hash AS "requestHash", expires_at AS "expiresAt"
+                FROM ablo_idempotency
+                WHERE client_tx_id = ${change.correlationId} LIMIT 1`));
                 const cachedRow = cached[0];
-                if (cachedRow)
+                if (cachedRow) {
+                    assertSourceIdempotencyIntent(cachedRow.requestHash, requestHash);
+                    assertSourceIdempotencyRetention(cachedRow.expiresAt);
                     return { rows: cachedRow.response };
+                }
                 const rows = [];
                 for (const [index, op] of change.operations.entries()) {
                     const row = await applyOperation(tx, op);
                     rows.push(row);
                     const entityId = String(row.id ?? rowId(op));
                     await tx.execute(sql `
-            INSERT INTO ablo_outbox (id, model, entity_id, type, data, client_tx_id, occurred_at)
+            INSERT INTO ablo_outbox (
+              id, model, entity_id, type, data,
+              correlation_id, transaction_id, occurred_at
+            )
             VALUES (
-              ${`${change.clientTxId}:${index}`}, ${op.model}, ${entityId}, ${op.type},
-              ${op.type === 'DELETE' ? null : JSON.stringify(row)}::jsonb, ${change.clientTxId}, ${Date.now()}
+              ${`${change.correlationId}:${index}`}, ${op.model}, ${entityId}, ${op.type},
+              ${op.type === 'DELETE' ? null : JSON.stringify(row)}::jsonb,
+              ${change.correlationId}, ${op.transactionId ?? null}, ${Date.now()}
             )`);
                 }
                 await tx.execute(sql `
-          INSERT INTO ablo_idempotency (client_tx_id, response)
-          VALUES (${change.clientTxId}, ${JSON.stringify(rows)}::jsonb)`);
+          INSERT INTO ablo_idempotency (client_tx_id, response, request_hash)
+          VALUES (
+            ${change.correlationId}, ${JSON.stringify(rows)}::jsonb, ${requestHash}
+          )`);
+                if (change.echo?.kind === 'postgres-wal') {
+                    await tx.execute(sql `SELECT pg_logical_emit_message(true, ${ABLO_POSTGRES_COMMIT_ECHO_PREFIX}, ${change.echo.payload})`);
+                }
                 return { rows };
             });
         },
         async events(cursor, limit) {
             const after = cursor ?? '0';
             const rows = rowsOf(await db.execute(sql `
-          SELECT cursor, id, model, entity_id, type, data, organization_id, client_tx_id, occurred_at
+          SELECT cursor, id, model, entity_id, type, data, organization_id,
+                 client_tx_id, correlation_id, transaction_id, occurred_at
           FROM ablo_outbox WHERE cursor > ${after} ORDER BY cursor ASC LIMIT ${limit}`));
             const events = rows.map((r) => outboxEventSchema.parse({
                 id: r.id,
@@ -183,6 +207,8 @@ export function drizzleDataSource(db, schema) {
                 data: r.data ?? null,
                 organizationId: r.organization_id ?? null,
                 clientTxId: r.client_tx_id ?? null,
+                correlationId: r.correlation_id ?? null,
+                transactionId: r.transaction_id ?? null,
                 occurredAt: r.occurred_at != null ? Number(r.occurred_at) : null,
                 cursor: String(r.cursor),
             }));

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

@@ -1,70 +1,42 @@
 /**
- * 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}.
+ * Kysely wrappers for Ablo's two customer-database write transports.
  *
- * 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)`  (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.
+ * Both wrappers compose the same exported {@link createKyselyMutationCore}:
  *
- * 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.
+ * - {@link kyselyDataSource} is the endpoint adapter. Its transaction contains
+ *   row DML, the permanent idempotency ledger, and correlated outbox events. A
+ *   Postgres logical marker remains optional for compatibility.
+ * - {@link kyselyDirectMutation} is the engine-side direct wrapper. Its
+ *   transaction contains row DML, the same ledger, and a required logical
+ *   marker. It never creates, writes, or serves `ablo_outbox`.
+ *
+ * The ledger reservation happens before DML via `INSERT ... ON CONFLICT DO
+ * NOTHING`. Postgres waits on a concurrent uncommitted owner of the same key;
+ * after that owner commits, the loser reads and hash-checks its durable response.
+ * If the owner rolls back, the waiter acquires the reservation and performs the
+ * mutation. This gives same-key concurrency one database arbiter and one effect.
  */
-import type { DataSourceAdapter, Row } from '../adapter.js';
 import type { Schema, SchemaRecord } from '../../schema/schema.js';
+import type { DataSourceAdapter, MutationAdapter } from '../adapter.js';
+import { type KyselyLike, type KyselyMutationCore } from './kyselyMutationCore.js';
+export { createKyselyMutationCore, kyselyOperationRowId, type KyselyCompiledQuery, type KyselyDeleteBuilder, type KyselyInsertBuilder, type KyselyInsertValuesBuilder, type KyselyLike, type KyselyMutationCore, type KyselyReturningExecutable, type KyselySelectBuilder, type KyselyTransactionBuilder, type KyselyUpdateBuilder, type KyselyUpdateSetBuilder, } from './kyselyMutationCore.js';
+type KyselyMutationMode = 'endpoint' | 'direct';
 /**
- * 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`.
+ * Build the shared transaction policy around one Kysely mutation core. Exported
+ * for engine integrations that need to inject a prebuilt core while retaining
+ * the exact same ledger and mapping semantics as the endpoint adapter.
  */
-export interface KyselyLike {
-    selectFrom(table: string): KyselySelectBuilder;
-    insertInto(table: string): KyselyInsertBuilder;
-    updateTable(table: string): KyselyUpdateBuilder;
-    deleteFrom(table: string): KyselyDeleteBuilder;
-    transaction(): KyselyTransactionBuilder;
-}
-export interface KyselyTransactionBuilder {
-    execute<T>(fn: (trx: KyselyLike) => Promise<T>): Promise<T>;
-}
-export interface KyselySelectBuilder {
-    selectAll(): KyselySelectBuilder;
-    where(column: string, operator: string, value: unknown): KyselySelectBuilder;
-    orderBy(column: string, direction: 'asc' | 'desc'): KyselySelectBuilder;
-    limit(limit: number): KyselySelectBuilder;
-    execute(): Promise<readonly Row[]>;
-}
-export interface KyselyInsertBuilder {
-    values(row: Row): KyselyInsertBuilder;
-    returningAll(): KyselyInsertBuilder;
-    execute(): Promise<readonly Row[]>;
-}
-export interface KyselyUpdateBuilder {
-    set(patch: Row): KyselyUpdateBuilder;
-    where(column: string, operator: string, value: unknown): KyselyUpdateBuilder;
-    returningAll(): KyselyUpdateBuilder;
-    execute(): Promise<readonly Row[]>;
-}
-export interface KyselyDeleteBuilder {
-    where(column: string, operator: string, value: unknown): KyselyDeleteBuilder;
-    returningAll(): KyselyDeleteBuilder;
-    execute(): Promise<readonly Row[]>;
+export interface KyselyMutationAdapterOptions {
+    /**
+     * Translate a mutation operation's authoring model key into the canonical
+     * marker vocabulary (the schema typename). Direct wrappers must supply the
+     * schema-backed translation; identity is only correct when a schema's
+     * typenames equal its keys.
+     */
+    readonly markerModelFor?: (operationModel: string) => string;
 }
+export declare function createKyselyMutationAdapter(db: KyselyLike, core: KyselyMutationCore, mode: KyselyMutationMode, options?: KyselyMutationAdapterOptions): MutationAdapter;
+/** Endpoint wrapper: mutation + ledger + outbox, with an optional marker. */
 export declare function kyselyDataSource<S extends SchemaRecord>(db: KyselyLike, schema: Schema<S>): DataSourceAdapter;
+/** Direct wrapper: mutation + ledger + required logical marker, never outbox. */
+export declare function kyselyDirectMutation<S extends SchemaRecord>(db: KyselyLike, schema: Schema<S>): MutationAdapter;