@abloatai/ablo 0.29.2 → 0.30.0

package/dist/source/adapters/memory.js

@@ -6,10 +6,11 @@
  * mapper is complete when it passes the same suite this one passes.
  *
  * 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
+ * idempotency ledger keyed by scoped correlation, and an append-only outbox with a
  * monotonic cursor.
  */
 import { AbloValidationError } from '../../errors.js';
+import { assertSourceIdempotencyIntent, sourceChangeIntentHash, } from '../idempotency.js';
 function rowId(op) {
     const id = op.id ?? op.input?.id;
     if (typeof id !== 'string' || id.length === 0) {
@@ -20,7 +21,7 @@ function rowId(op) {
 export function memoryDataSource() {
     /** model → (id → row). */
     const store = new Map();
-    /** clientTxId → the rows that commit returned (idempotency ledger). */
+    /** Permanent correlationId → intent hash + original response ledger. */
     const idempotency = new Map();
     /** Append-only outbox; `cursor` is the 1-based index as a string. */
     const outbox = [];
@@ -62,7 +63,13 @@ export function memoryDataSource() {
         }
     };
     return {
-        capabilities: { transactions: true, propose: false, schemaIntrospection: false },
+        capabilities: {
+            transactions: true,
+            propose: false,
+            schemaIntrospection: false,
+            postgresWalEcho: false,
+            outboxEvents: true,
+        },
         migrations() {
             // Nothing to create in memory. A database-backed adapter returns the SQL for its ablo_idempotency and ablo_outbox tables here.
             return [];
@@ -82,26 +89,33 @@ export function memoryDataSource() {
             return rows;
         },
         async commit(change) {
-            // Idempotency: a duplicate clientTxId returns the original rows, no re-apply.
-            const cached = idempotency.get(change.clientTxId);
-            if (cached)
-                return { rows: cached };
+            if (change.echo) {
+                throw new AbloValidationError('memoryDataSource cannot emit a Postgres WAL commit echo');
+            }
+            // Idempotency: a duplicate scoped correlation returns the original rows.
+            const requestHash = sourceChangeIntentHash(change);
+            const cached = idempotency.get(change.correlationId);
+            if (cached) {
+                assertSourceIdempotencyIntent(cached.requestHash, requestHash);
+                return { rows: cached.rows };
+            }
             const rows = [];
             for (const [index, op] of change.operations.entries()) {
                 const row = applyOperation(op);
                 rows.push(row);
                 // Transactional outbox: one event per op, monotonic cursor.
                 outbox.push({
-                    id: `${change.clientTxId}:${index}`,
+                    id: `${change.correlationId}:${index}`,
                     model: op.model,
                     entityId: String(row.id ?? rowId(op)),
                     type: op.type,
                     data: op.type === 'DELETE' ? null : row,
-                    clientTxId: change.clientTxId,
+                    correlationId: change.correlationId,
+                    ...(op.transactionId ? { transactionId: op.transactionId } : {}),
                     cursor: String(outbox.length + 1),
                 });
             }
-            idempotency.set(change.clientTxId, rows);
+            idempotency.set(change.correlationId, { requestHash, rows });
             return { rows };
         },
         async events(cursor, limit) {

package/dist/source/adapters/prisma.js

@@ -16,6 +16,8 @@
 import { AbloValidationError } from '../../errors.js';
 import { outboxEventSchema } from '../contract.js';
 import { adapterTableMigrations } from '../migrations.js';
+import { assertSourceIdempotencyIntent, assertSourceIdempotencyRetention, sourceChangeIntentHash, } from '../idempotency.js';
+import { ABLO_POSTGRES_COMMIT_ECHO_PREFIX, } from '../types.js';
 const lowerFirst = (s) => (s ? s.charAt(0).toLowerCase() + s.slice(1) : s);
 /**
  * Resolves a model's Prisma delegate by name. This is the one unavoidable cast in
@@ -119,7 +121,13 @@ export function prismaDataSource(prisma, schema, options = {}) {
         }
     };
     return {
-        capabilities: { transactions: true, propose: false, schemaIntrospection: true },
+        capabilities: {
+            transactions: true,
+            propose: false,
+            schemaIntrospection: true,
+            postgresWalEcho: true,
+            outboxEvents: true,
+        },
         migrations() {
             return adapterTableMigrations();
         },
@@ -132,28 +140,45 @@ export function prismaDataSource(prisma, schema, options = {}) {
             return delegate.findMany(findManyArgs(req.query));
         },
         async commit(change) {
+            const requestHash = sourceChangeIntentHash(change);
             return prisma.$transaction(async (tx) => {
-                // Idempotency: a duplicate clientTxId returns the original rows, no re-apply.
-                const cached = await tx.$queryRawUnsafe(`SELECT response FROM ablo_idempotency WHERE client_tx_id = $1 LIMIT 1`, change.clientTxId);
+                // Idempotency: a duplicate scoped correlation returns the original rows.
+                const cached = await tx.$queryRawUnsafe(`SELECT response, request_hash AS "requestHash", expires_at AS "expiresAt"
+             FROM ablo_idempotency WHERE client_tx_id = $1 LIMIT 1`, change.correlationId);
                 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));
                     // 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());
+                    await tx.$executeRawUnsafe(`INSERT INTO ablo_outbox (
+               id, model, entity_id, type, data,
+               correlation_id, transaction_id, occurred_at
+             ) VALUES ($1, $2, $3, $4, $5::jsonb, $6, $7, $8)`, `${change.correlationId}:${index}`, op.model, entityId, op.type, JSON.stringify(op.type === 'DELETE' ? null : row), change.correlationId, op.transactionId ?? null, Date.now());
+                }
+                await tx.$executeRawUnsafe(`INSERT INTO ablo_idempotency (client_tx_id, response, request_hash)
+           VALUES ($1, $2::jsonb, $3)`, change.correlationId, JSON.stringify(rows), requestHash);
+                if (change.echo?.kind === 'postgres-wal') {
+                    // Cast the returned LSN to text. `pg_logical_emit_message` yields a
+                    // `pg_lsn`, and Prisma's driver adapter can't deserialize that OID
+                    // ("Failed to deserialize column of type 'pg_lsn'"); the value is
+                    // discarded anyway, so text is the safe carrier. (postgres.js-backed
+                    // adapters read pg_lsn as a string and don't need this.)
+                    await tx.$queryRawUnsafe(`SELECT pg_logical_emit_message(true, $1::text, $2::text)::text`, ABLO_POSTGRES_COMMIT_ECHO_PREFIX, change.echo.payload);
                 }
-                await tx.$executeRawUnsafe(`INSERT INTO ablo_idempotency (client_tx_id, response) VALUES ($1, $2::jsonb)`, change.clientTxId, JSON.stringify(rows));
                 return { rows };
             });
         },
         async events(cursor, limit) {
             const after = cursor ? cursor : '0';
-            const rows = await prisma.$queryRawUnsafe(`SELECT cursor, id, model, entity_id, type, data, organization_id, client_tx_id, occurred_at
+            const rows = await prisma.$queryRawUnsafe(`SELECT cursor, id, model, entity_id, type, data, organization_id,
+                client_tx_id, correlation_id, transaction_id, occurred_at
          FROM ablo_outbox WHERE cursor > $1 ORDER BY cursor ASC LIMIT $2`, after, limit);
             const events = rows.map((r) => outboxEventSchema.parse({
                 id: r.id,
@@ -163,6 +188,8 @@ export function prismaDataSource(prisma, schema, options = {}) {
                 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/conformance.d.ts

@@ -1,39 +1,37 @@
 /**
- * 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.
+ * Capability-split conformance for customer-database mutation wrappers.
  *
- * 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);
- *
- * 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.
+ * `mutationConformanceChecks` covers only guarantees shared by direct and
+ * endpoint: schema-mapped DML, reads, permanent scoped idempotency, canonical
+ * request-hash conflicts, and concurrent replay. `endpointConformanceChecks`
+ * covers the endpoint-only transactional outbox and events cursor. Direct
+ * wrappers must not run (or claim) those outbox guarantees because WAL is their
+ * sole source feed.
  */
-import type { DataSourceAdapter } from './adapter.js';
-/** A factory that returns a fresh adapter. Each check calls it to start from clean state. */
+import type { DataSourceAdapter, MutationAdapter } from './adapter.js';
+import type { ChangeSet } from './contract.js';
+export type MakeMutationAdapter = () => MutationAdapter | Promise<MutationAdapter>;
 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 interface MutationConformanceOptions {
+    /**
+     * Add transport-required evidence without changing the shared checks. Direct
+     * wrappers use this to attach their logical marker; endpoint wrappers need no
+     * decoration.
+     */
+    readonly prepareChange?: (change: ChangeSet) => ChangeSet;
+}
+/** Guarantees shared by direct and endpoint mutation wrappers. */
+export declare function mutationConformanceChecks(make: MakeMutationAdapter, options?: MutationConformanceOptions): ConformanceCheck[];
+/** Guarantees that apply only to endpoint wrappers with an outbox/events feed. */
+export declare function endpointConformanceChecks(make: MakeAdapter): ConformanceCheck[];
+/** Compatibility name for the complete endpoint adapter suite. */
 export declare function dataSourceConformanceChecks(make: MakeAdapter): ConformanceCheck[];
-/**
- * Register the conformance checks with a test runner's `it`/`test` function.
- * `register(name, fn)` — pass vitest/jest `it` or `node:test` `test`.
- */
+export declare function runMutationTests(make: MakeMutationAdapter, register: (name: string, fn: () => Promise<void>) => void, options?: MutationConformanceOptions): void;
+export declare function runEndpointDataSourceTests(make: MakeAdapter, register: (name: string, fn: () => Promise<void>) => void): void;
+/** Backward-compatible complete endpoint suite. */
 export declare function runDataSourceTests(make: MakeAdapter, register: (name: string, fn: () => Promise<void>) => void): void;
 export { memoryDataSource } from './adapters/memory.js';

package/dist/source/conformance.js

@@ -1,39 +1,33 @@
 /**
- * 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.
+ * Capability-split conformance for customer-database mutation wrappers.
  *
- * 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);
- *
- * 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.
+ * `mutationConformanceChecks` covers only guarantees shared by direct and
+ * endpoint: schema-mapped DML, reads, permanent scoped idempotency, canonical
+ * request-hash conflicts, and concurrent replay. `endpointConformanceChecks`
+ * covers the endpoint-only transactional outbox and events cursor. Direct
+ * wrappers must not run (or claim) those outbox guarantees because WAL is their
+ * sole source feed.
  */
 import assert from 'node:assert/strict';
-const change = (clientTxId, ops) => ({
-    clientTxId,
-    operations: ops,
+const change = (correlationId, operations, intentHash) => ({
+    correlationId,
+    operations,
+    ...(intentHash ? { intentHash } : {}),
 });
-/**
- * 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) {
+/** Guarantees shared by direct and endpoint mutation wrappers. */
+export function mutationConformanceChecks(make, options = {}) {
+    const request = (correlationId, operations, intentHash) => {
+        const value = change(correlationId, operations, intentHash);
+        return options.prepareChange?.(value) ?? value;
+    };
     return [
         {
             name: 'commit applies a CREATE and returns the canonical row',
             run: async () => {
                 const adapter = await make();
-                const result = await adapter.commit(change('tx_create', [{ type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } }]));
+                const result = await adapter.commit(request('corr_create', [
+                    { type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } },
+                ]));
                 assert.equal(result.rows.length, 1, 'one row returned');
                 const created = result.rows[0];
                 assert.ok(created, 'one row returned');
@@ -45,7 +39,9 @@ export function dataSourceConformanceChecks(make) {
             name: 'read load returns a committed row, and null-equivalent for an unknown id',
             run: async () => {
                 const adapter = await make();
-                await adapter.commit(change('tx1', [{ type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } }]));
+                await adapter.commit(request('corr_load', [
+                    { type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } },
+                ]));
                 const found = await adapter.read({ kind: 'load', model: 'task', id: 't1' });
                 assert.equal(found.length, 1);
                 assert.equal(found[0]?.title, 'A');
@@ -57,86 +53,163 @@ export function dataSourceConformanceChecks(make) {
             name: 'read list returns committed rows',
             run: async () => {
                 const adapter = await make();
-                await adapter.commit(change('tx_list', [
+                await adapter.commit(request('corr_list', [
                     { type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } },
                     { type: 'CREATE', model: 'task', id: 't2', input: { title: 'B' } },
                 ]));
                 const rows = await adapter.read({ kind: 'list', model: 'task' });
-                const ids = rows.map((r) => (r).id).sort();
-                assert.deepEqual(ids, ['t1', 't2']);
+                assert.deepEqual(rows.map((row) => row.id).sort(), ['t1', 't2']);
             },
         },
         {
-            name: 'duplicate clientTxId is idempotent — same rows, applied once',
+            name: 'same scoped correlation and intent replays the original response without DML',
             run: async () => {
                 const adapter = await make();
-                const cs = change('tx_dup', [{ type: 'CREATE', model: 'task', id: 't1', input: { title: 'A', n: 1 } }]);
-                const first = await adapter.commit(cs);
-                const second = await adapter.commit(cs);
+                const commitRequest = request('corr_replay', [
+                    { type: 'CREATE', model: 'task', id: 't1', input: { title: 'A', n: 1 } },
+                ]);
+                const first = await adapter.commit(commitRequest);
+                const second = await adapter.commit(commitRequest);
                 assert.deepEqual(second.rows, first.rows, 'replay returns the original rows');
-                // Applied once: still exactly one row, and the outbox did not double up.
                 const rows = await adapter.read({ kind: 'list', model: 'task' });
                 assert.equal(rows.length, 1, 'no duplicate row');
+            },
+        },
+        {
+            name: 'same scoped correlation with a different canonical intent rejects',
+            run: async () => {
+                const adapter = await make();
+                await adapter.commit(request('corr_conflict', [{ type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } }], 'a'.repeat(64)));
+                await assert.rejects(adapter.commit(request('corr_conflict', [{ type: 'UPDATE', model: 'task', id: 't1', input: { title: 'B' } }], 'b'.repeat(64))), (error) => typeof error === 'object' &&
+                    error !== null &&
+                    'code' in error &&
+                    error.code === 'idempotency_conflict');
+            },
+        },
+        {
+            name: 'concurrent identical requests apply once and replay one response',
+            run: async () => {
+                const adapter = await make();
+                const commitRequest = request('corr_concurrent', [
+                    { type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } },
+                ]);
+                const [first, second] = await Promise.all([
+                    adapter.commit(commitRequest),
+                    adapter.commit(commitRequest),
+                ]);
+                assert.deepEqual(second.rows, first.rows);
+                const rows = await adapter.read({ kind: 'list', model: 'task' });
+                assert.equal(rows.length, 1, 'concurrent retries produced one row');
+            },
+        },
+        {
+            name: 'a later mutation under a new scoped correlation is applied',
+            run: async () => {
+                const adapter = await make();
+                await adapter.commit(request('corr_create_2', [
+                    { type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } },
+                ]));
+                await adapter.commit(request('corr_update_2', [
+                    { type: 'UPDATE', model: 'task', id: 't1', input: { title: 'B' } },
+                ]));
+                const found = await adapter.read({ kind: 'load', model: 'task', id: 't1' });
+                assert.equal(found[0]?.title, 'B', 'update applied');
+            },
+        },
+    ];
+}
+/** Guarantees that apply only to endpoint wrappers with an outbox/events feed. */
+export function endpointConformanceChecks(make) {
+    return [
+        {
+            name: 'endpoint replay does not append its correlated outbox event twice',
+            run: async () => {
+                const adapter = await make();
+                assert.equal(adapter.capabilities.outboxEvents, true);
+                const request = change('corr_outbox_replay', [
+                    {
+                        type: 'CREATE',
+                        model: 'task',
+                        id: 't1',
+                        input: { title: 'A' },
+                        transactionId: 'op_outbox_replay',
+                    },
+                ]);
+                await adapter.commit(request);
+                await adapter.commit(request);
                 const page = await adapter.events(null, 100);
-                const forTx = page.events.filter((e) => e.clientTxId === 'tx_dup');
-                assert.equal(forTx.length, 1, 'outbox not double-appended on replay');
+                assert.equal(page.events.filter((event) => event.correlationId === 'corr_outbox_replay').length, 1);
             },
         },
         {
-            name: 'commit appends outbox events with the originating clientTxId',
+            name: 'endpoint outbox exposes explicit correlation and operation identity',
             run: async () => {
                 const adapter = await make();
-                await adapter.commit(change('tx_evt', [{ type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } }]));
+                assert.equal(adapter.capabilities.outboxEvents, true);
+                await adapter.commit(change('corr_event', [
+                    {
+                        type: 'CREATE',
+                        model: 'task',
+                        id: 't1',
+                        input: { title: 'A' },
+                        transactionId: 'op_event',
+                    },
+                ]));
                 const page = await adapter.events(null, 100);
-                assert.ok(page.events.length >= 1, 'at least one event');
-                const evt = page.events.find((e) => e.entityId === 't1');
-                assert.ok(evt, 'event for the committed row');
-                assert.equal(evt.model, 'task');
-                assert.equal(evt.type, 'CREATE');
-                assert.equal(evt.clientTxId, 'tx_evt');
+                const event = page.events.find((candidate) => candidate.entityId === 't1');
+                assert.ok(event, 'event for the committed row');
+                assert.equal(event.model, 'task');
+                assert.equal(event.type, 'CREATE');
+                assert.equal(event.correlationId, 'corr_event');
+                assert.equal(event.transactionId, 'op_event');
+                assert.equal(event.clientTxId ?? null, null, 'legacy echo identity stays empty');
             },
         },
         {
-            name: 'events cursor advances and never re-delivers a page',
+            name: 'endpoint events cursor advances and never re-delivers a page',
             run: async () => {
                 const adapter = await make();
-                await adapter.commit(change('tx_a', [{ type: 'CREATE', model: 'task', id: 't1', input: {} }]));
-                await adapter.commit(change('tx_b', [{ type: 'CREATE', model: 'task', id: 't2', input: {} }]));
+                await adapter.commit(change('corr_page_a', [
+                    { type: 'CREATE', model: 'task', id: 't1', input: {} },
+                ]));
+                await adapter.commit(change('corr_page_b', [
+                    { type: 'CREATE', model: 'task', id: 't2', input: {} },
+                ]));
                 const first = await adapter.events(null, 1);
                 assert.equal(first.events.length, 1, 'respects limit');
                 assert.ok(first.nextCursor, 'returns a cursor');
                 const second = await adapter.events(first.nextCursor, 100);
-                // No overlap: the second page starts strictly after the first cursor.
-                const firstIds = new Set(first.events.map((e) => e.id));
-                for (const e of second.events) {
-                    assert.ok(!firstIds.has(e.id), `event ${e.id} re-delivered across cursor`);
+                const firstIds = new Set(first.events.map((event) => event.id));
+                for (const event of second.events) {
+                    assert.ok(!firstIds.has(event.id), `event ${event.id} re-delivered across cursor`);
                 }
-                // Draining to the end yields a stable terminal cursor.
                 const drained = await adapter.events(second.nextCursor ?? first.nextCursor, 100);
                 assert.equal(drained.events.length, 0, 'fully drained');
             },
         },
-        {
-            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' } }]));
-                await adapter.commit(change('tx_u1', [{ type: 'UPDATE', model: 'task', id: 't1', input: { title: 'B' } }]));
-                const found = await adapter.read({ kind: 'load', model: 'task', id: 't1' });
-                assert.equal(found[0]?.title, 'B', 'update applied');
-            },
-        },
     ];
 }
-/**
- * Register the conformance checks with a test runner's `it`/`test` function.
- * `register(name, fn)` — pass vitest/jest `it` or `node:test` `test`.
- */
+/** Compatibility name for the complete endpoint adapter suite. */
+export function dataSourceConformanceChecks(make) {
+    return [
+        ...mutationConformanceChecks(make),
+        ...endpointConformanceChecks(make),
+    ];
+}
+export function runMutationTests(make, register, options = {}) {
+    for (const check of mutationConformanceChecks(make, options)) {
+        register(check.name, check.run);
+    }
+}
+export function runEndpointDataSourceTests(make, register) {
+    for (const check of endpointConformanceChecks(make)) {
+        register(check.name, check.run);
+    }
+}
+/** Backward-compatible complete endpoint suite. */
 export function runDataSourceTests(make, register) {
     for (const check of dataSourceConformanceChecks(make)) {
         register(check.name, check.run);
     }
 }
-// Re-export the reference adapter so `@abloatai/ablo/source/conformance`
-// exposes both the suite and the in-memory double in one import.
 export { memoryDataSource } from './adapters/memory.js';

package/dist/source/contract.d.ts

@@ -47,10 +47,41 @@ export declare const operationSchema: z.ZodObject<{
     }>>>;
 }, z.core.$strip>;
 export type Operation = z.infer<typeof operationSchema>;
+/** The supported customer-transaction echo mechanism. */
+export declare const sourceCommitEchoSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"postgres-wal">;
+    payload: z.ZodString;
+}, z.core.$strip>;
+export declare const sourceCommitEchoOperationSchema: z.ZodObject<{
+    model: z.ZodString;
+    id: z.ZodString;
+    action: z.ZodEnum<{
+        I: "I";
+        U: "U";
+        D: "D";
+    }>;
+    transactionId: z.ZodString;
+}, z.core.$strict>;
+export declare const sourceCommitEchoMarkerSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    correlationId: z.ZodString;
+    operations: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        model: z.ZodString;
+        id: z.ZodString;
+        action: z.ZodEnum<{
+            I: "I";
+            U: "U";
+            D: "D";
+        }>;
+        transactionId: z.ZodString;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type SourceCommitEchoMarkerWire = z.infer<typeof sourceCommitEchoMarkerSchema>;
 /**
- * The unit an adapter commits atomically: one or more operations grouped under a
- * single `clientTxId`. That `clientTxId` is the idempotency key, so committing the
- * same change set twice applies it once and returns the same result.
+ * The unit a mutation wrapper commits atomically. `correlationId` is derived by
+ * Ablo from the authenticated plane, participant, and public idempotency key; it
+ * is the customer-ledger identity. It is intentionally not a raw caller-authored
+ * `clientTxId` or an operation transaction id.
  */
 export declare const changeSetSchema: z.ZodObject<{
     operations: z.ZodArray<z.ZodObject<{
@@ -72,7 +103,12 @@ export declare const changeSetSchema: z.ZodObject<{
             notify: "notify";
         }>>>;
     }, z.core.$strip>>;
-    clientTxId: z.ZodString;
+    correlationId: z.ZodString;
+    intentHash: z.ZodOptional<z.ZodString>;
+    echo: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodLiteral<"postgres-wal">;
+        payload: z.ZodString;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type ChangeSet = z.infer<typeof changeSetSchema>;
 /**
@@ -96,6 +132,8 @@ export declare const outboxEventSchema: z.ZodObject<{
     data: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
     organizationId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     clientTxId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    correlationId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    transactionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     occurredAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     cursor: z.ZodString;
 }, z.core.$strip>;
@@ -116,6 +154,8 @@ export declare const eventsPageSchema: z.ZodObject<{
         data: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
         organizationId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         clientTxId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        correlationId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        transactionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         occurredAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         cursor: z.ZodString;
     }, z.core.$strip>>;
@@ -137,5 +177,7 @@ export declare const adapterCapabilitiesSchema: z.ZodObject<{
     transactions: z.ZodBoolean;
     propose: z.ZodBoolean;
     schemaIntrospection: z.ZodBoolean;
+    postgresWalEcho: z.ZodOptional<z.ZodBoolean>;
+    outboxEvents: z.ZodBoolean;
 }, z.core.$strip>;
 export type AdapterCapabilities = z.infer<typeof adapterCapabilitiesSchema>;