@abloatai/ablo 0.29.3 → 0.30.0

package/dist/source/contract.js

@@ -13,6 +13,8 @@
  * at compile time so the schema and the interface cannot drift apart.
  */
 import { z } from 'zod';
+import { correlationIdSchema } from '../wire/commit.js';
+import { ABLO_SOURCE_CLIENT_TX_ID_MAX_LENGTH, ABLO_SOURCE_ECHO_MAX_OPERATIONS, ABLO_SOURCE_ECHO_MAX_PAYLOAD_BYTES, } from './types.js';
 const jsonObject = z.record(z.string(), z.unknown());
 /** Mirrors `SourceOperation['type']`. */
 export const operationTypeSchema = z.enum([
@@ -36,14 +38,54 @@ export const operationSchema = z.object({
     readAt: z.number().nullish(),
     onStale: z.enum(['reject', 'overwrite', 'notify']).nullish(),
 });
+/** The supported customer-transaction echo mechanism. */
+export const sourceCommitEchoSchema = z.object({
+    kind: z.literal('postgres-wal'),
+    payload: z
+        .string()
+        .min(1)
+        .refine((value) => new TextEncoder().encode(value).byteLength <= ABLO_SOURCE_ECHO_MAX_PAYLOAD_BYTES, `WAL echo payload exceeds ${ABLO_SOURCE_ECHO_MAX_PAYLOAD_BYTES} UTF-8 bytes`),
+});
+export const sourceCommitEchoOperationSchema = z.strictObject({
+    model: z.string().min(1),
+    id: z.string().min(1),
+    action: z.enum(['I', 'U', 'D']),
+    transactionId: z.string().min(1).max(ABLO_SOURCE_CLIENT_TX_ID_MAX_LENGTH),
+});
+export const sourceCommitEchoMarkerSchema = z
+    .strictObject({
+    version: z.literal(1),
+    correlationId: correlationIdSchema,
+    operations: z
+        .array(sourceCommitEchoOperationSchema)
+        .min(1)
+        .max(ABLO_SOURCE_ECHO_MAX_OPERATIONS)
+        .readonly(),
+})
+    .superRefine(({ operations }, ctx) => {
+    const seen = new Set();
+    for (const [index, operation] of operations.entries()) {
+        if (seen.has(operation.transactionId)) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['operations', index, 'transactionId'],
+                message: 'WAL echo operation transactionIds must be unique',
+            });
+        }
+        seen.add(operation.transactionId);
+    }
+});
 /**
- * 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 const changeSetSchema = z.object({
     operations: z.array(operationSchema).min(1),
-    clientTxId: z.string().min(1),
+    correlationId: correlationIdSchema,
+    intentHash: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+    echo: sourceCommitEchoSchema.optional(),
 });
 /**
  * A row in the adapter's `ablo_outbox` table. The adapter writes it in the same
@@ -60,8 +102,16 @@ export const outboxEventSchema = z.object({
     type: operationTypeSchema,
     data: jsonObject.nullish(),
     organizationId: z.string().nullish(),
-    /** The originating transaction id, carried so Ablo can drop echoes of changes the SDK itself wrote. */
+    /** Legacy source transaction id. Never use this field to settle a queued commit. */
     clientTxId: z.string().nullish(),
+    /** Scoped server-authored identity that correlates this event to a queued commit. */
+    correlationId: correlationIdSchema.nullish(),
+    /** Stable identity of this operation within the correlated source commit. */
+    transactionId: z
+        .string()
+        .min(1)
+        .max(ABLO_SOURCE_CLIENT_TX_ID_MAX_LENGTH)
+        .nullish(),
     occurredAt: z.number().nullish(),
     /** Monotonic ordering key (bigint as string). `events()` pages by `cursor > ?`. */
     cursor: z.string().min(1),
@@ -90,9 +140,20 @@ export const adapterCapabilitiesSchema = z.object({
     propose: z.boolean(),
     /** The backend can be introspected for its schema. */
     schemaIntrospection: z.boolean(),
+    /** The adapter can atomically emit the requested Postgres WAL marker. */
+    postgresWalEcho: z.boolean().optional(),
+    /** The wrapper atomically writes and serves an endpoint transactional outbox. */
+    outboxEvents: z.boolean(),
 });
 const _operationContractInSync = [
     true,
     true,
 ];
 void _operationContractInSync;
+const _echoContractInSync = [
+    true,
+    true,
+];
+void _echoContractInSync;
+const _echoMarkerContractInSync = [true, true];
+void _echoMarkerContractInSync;

package/dist/source/factory.d.ts

@@ -59,9 +59,9 @@ export type DataSourceOptions<S extends SchemaRecord, TAuth = unknown> = {
      * Reports changes that happened outside the SDK — cron jobs, dashboard edits,
      * batch imports — which Ablo polls for. Each event you return becomes a delta and
      * fans out to connected clients. You can return your outbox rows directly: Ablo
-     * dedupes on the stable `event.id` and drops echoes of the SDK's own writes when a
-     * row carries the originating `clientTxId`, so store both fields in your outbox
-     * table.
+     * dedupes on stable `event.id`, appends the authoritative event, and uses a
+     * server-authored `correlationId` plus per-operation `transactionId` to settle
+     * the matching queued write. Store both fields for mediated endpoint commits.
      */
     readonly events?: SourceEventsHandler<TAuth>;
     /**

package/dist/source/factory.js

@@ -38,16 +38,29 @@ async function handleViaAdapter(adapter, body, scope) {
         return json({ rows });
     }
     if (body.type === 'commit') {
-        if (!body.clientTxId) {
-            return json({ error: 'source_commit_requires_client_tx_id', message: 'commit requires a clientTxId for idempotency' }, 400);
+        const correlationId = body.correlationId ?? body.clientTxId;
+        if (!correlationId) {
+            return json({
+                error: 'source_commit_requires_correlation_id',
+                message: 'commit requires a scoped correlationId for idempotency',
+            }, 400);
         }
         const parsed = changeSetSchema.safeParse({
             operations: body.operations,
-            clientTxId: body.clientTxId,
+            correlationId,
+            intentHash: body.intentHash,
+            echo: body.echo,
         });
         if (!parsed.success) {
             return json({ error: 'source_commit_invalid', message: parsed.error.message }, 400);
         }
+        if (parsed.data.echo?.kind === 'postgres-wal' &&
+            adapter.capabilities.postgresWalEcho !== true) {
+            return json({
+                error: 'source_commit_echo_not_supported',
+                message: 'This adapter cannot emit the required Postgres WAL commit echo',
+            }, 409);
+        }
         const result = await adapter.commit(parsed.data);
         return json({ rows: result.rows });
     }
@@ -62,6 +75,8 @@ async function handleViaAdapter(adapter, body, scope) {
                 ...(event.data !== undefined && event.data !== null ? { data: event.data } : {}),
                 ...(event.organizationId ? { organizationId: event.organizationId } : {}),
                 ...(event.clientTxId ? { clientTxId: event.clientTxId } : {}),
+                ...(event.correlationId ? { correlationId: event.correlationId } : {}),
+                ...(event.transactionId ? { transactionId: event.transactionId } : {}),
                 ...(event.occurredAt !== undefined && event.occurredAt !== null
                     ? { occurredAt: event.occurredAt }
                     : {}),
@@ -224,7 +239,10 @@ export function dataSource(options) {
             if (options.commit) {
                 const result = await options.commit({
                     operations: body.operations,
+                    correlationId: body.correlationId ?? body.clientTxId,
                     clientTxId: body.clientTxId,
+                    intentHash: body.intentHash,
+                    echo: body.echo,
                     context,
                 });
                 return json(result);
@@ -239,7 +257,10 @@ export function dataSource(options) {
             }
             const result = await handlers.commit({
                 operations: body.operations,
+                correlationId: body.correlationId ?? body.clientTxId,
                 clientTxId: body.clientTxId,
+                intentHash: body.intentHash,
+                echo: body.echo,
                 context,
             });
             return json(result);

package/dist/source/idempotency.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Customer-side source idempotency helpers.
+ *
+ * Connected writes use a permanent, server-derived correlation key at the
+ * customer boundary. The matching intent hash must therefore also be
+ * permanent: replaying the key with a different request is a conflict, never a
+ * fresh execution. Ablo supplies the hash for signed source requests because
+ * it covers context/read guards that an adapter cannot reconstruct from the
+ * effective operation list alone. Direct adapter users get a canonical
+ * operations-only fallback.
+ */
+import { z } from 'zod';
+import type { ChangeSet, Operation } from './contract.js';
+/** Runtime shape recovered from the internal storage envelope. */
+export declare const sourceEchoTransactionIdSchema: z.ZodObject<{
+    correlationId: z.ZodString;
+    transactionId: z.ZodString;
+}, z.core.$strict>;
+export type SourceEchoTransactionId = z.infer<typeof sourceEchoTransactionIdSchema>;
+/**
+ * Store both source-batch identity and the originating optimistic-write id in
+ * the existing `sync_deltas.transaction_id` column. The database value is an
+ * internal envelope: the server unwraps it before broadcasting, so clients
+ * still receive the exact operation transaction id they authored.
+ *
+ * Keeping the opaque, authenticated-scope correlation in the stored value is
+ * load-bearing for crash recovery. A raw caller may choose or reuse an
+ * operation transaction id; that value alone must never be able to satisfy a
+ * different participant's queued receipt.
+ */
+export declare function encodeSourceEchoTransactionId(correlationId: string, transactionId: string): string;
+/** Decode a source-WAL transaction envelope, or return null for normal rows. */
+export declare function decodeSourceEchoTransactionId(value: string | null): SourceEchoTransactionId | null;
+/** Canonical operations-only fallback for direct adapter use. */
+export declare function sourceOperationsIntentHash(operations: readonly Operation[]): string;
+/** Resolve the hash every newly-written customer ledger row must persist. */
+export declare function sourceChangeIntentHash(change: ChangeSet): string;
+/** Fail closed for changed intent and legacy rows that lack hash evidence. */
+export declare function assertSourceIdempotencyIntent(cachedHash: unknown, requestHash: string): void;
+/**
+ * Enforce the initial permanent-retention contract. New rows use Postgres
+ * `infinity`; this check also fails explicitly if a future bounded-retention
+ * policy leaves an expired tombstone. Missing expiry evidence is accepted only
+ * for adapters reading rows written before the column existed.
+ */
+export declare function assertSourceIdempotencyRetention(expiresAt: unknown, now?: number): void;

package/dist/source/idempotency.js

@@ -0,0 +1,129 @@
+/**
+ * Customer-side source idempotency helpers.
+ *
+ * Connected writes use a permanent, server-derived correlation key at the
+ * customer boundary. The matching intent hash must therefore also be
+ * permanent: replaying the key with a different request is a conflict, never a
+ * fresh execution. Ablo supplies the hash for signed source requests because
+ * it covers context/read guards that an adapter cannot reconstruct from the
+ * effective operation list alone. Direct adapter users get a canonical
+ * operations-only fallback.
+ */
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { AbloValidationError } from '../errors.js';
+import { COMMIT_CORRELATION_ID_MAX_LENGTH, correlationIdSchema, } from '../wire/commit.js';
+const SOURCE_ECHO_TRANSACTION_ID_PREFIX = 'ablo_echo_tx_v1:';
+const sourceOperationTransactionIdSchema = z
+    .string()
+    .min(1)
+    .max(COMMIT_CORRELATION_ID_MAX_LENGTH);
+/** Runtime shape recovered from the internal storage envelope. */
+export const sourceEchoTransactionIdSchema = z.strictObject({
+    correlationId: correlationIdSchema,
+    transactionId: sourceOperationTransactionIdSchema,
+});
+const sourceEchoTransactionIdTupleSchema = z.tuple([
+    correlationIdSchema,
+    sourceOperationTransactionIdSchema,
+]);
+/**
+ * Store both source-batch identity and the originating optimistic-write id in
+ * the existing `sync_deltas.transaction_id` column. The database value is an
+ * internal envelope: the server unwraps it before broadcasting, so clients
+ * still receive the exact operation transaction id they authored.
+ *
+ * Keeping the opaque, authenticated-scope correlation in the stored value is
+ * load-bearing for crash recovery. A raw caller may choose or reuse an
+ * operation transaction id; that value alone must never be able to satisfy a
+ * different participant's queued receipt.
+ */
+export function encodeSourceEchoTransactionId(correlationId, transactionId) {
+    const tuple = sourceEchoTransactionIdTupleSchema.parse([
+        correlationId,
+        transactionId,
+    ]);
+    return `${SOURCE_ECHO_TRANSACTION_ID_PREFIX}${JSON.stringify(tuple)}`;
+}
+/** Decode a source-WAL transaction envelope, or return null for normal rows. */
+export function decodeSourceEchoTransactionId(value) {
+    if (!value?.startsWith(SOURCE_ECHO_TRANSACTION_ID_PREFIX))
+        return null;
+    try {
+        const parsed = JSON.parse(value.slice(SOURCE_ECHO_TRANSACTION_ID_PREFIX.length));
+        const tuple = sourceEchoTransactionIdTupleSchema.safeParse(parsed);
+        if (!tuple.success)
+            return null;
+        return sourceEchoTransactionIdSchema.parse({
+            correlationId: tuple.data[0],
+            transactionId: tuple.data[1],
+        });
+    }
+    catch {
+        return null;
+    }
+}
+function canonicalJson(value) {
+    if (value === null || typeof value !== 'object') {
+        const encoded = JSON.stringify(value);
+        return encoded ?? 'null';
+    }
+    if (Array.isArray(value)) {
+        return `[${value
+            .map((entry) => canonicalJson(entry === undefined ? null : entry))
+            .join(',')}]`;
+    }
+    const record = value;
+    return `{${Object.keys(record)
+        .filter((key) => record[key] !== undefined)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
+        .join(',')}}`;
+}
+/** Canonical operations-only fallback for direct adapter use. */
+export function sourceOperationsIntentHash(operations) {
+    return createHash('sha256')
+        .update(canonicalJson(operations))
+        .digest('hex');
+}
+/** Resolve the hash every newly-written customer ledger row must persist. */
+export function sourceChangeIntentHash(change) {
+    if (change.echo && !change.intentHash) {
+        throw new AbloValidationError('A WAL-correlated source commit requires Ablo intentHash evidence', { code: 'idempotency_conflict' });
+    }
+    return change.intentHash ?? sourceOperationsIntentHash(change.operations);
+}
+/** Fail closed for changed intent and legacy rows that lack hash evidence. */
+export function assertSourceIdempotencyIntent(cachedHash, requestHash) {
+    if (cachedHash !== requestHash) {
+        throw new AbloValidationError(cachedHash == null
+            ? 'The source idempotency row predates intent hashing and cannot be replayed safely'
+            : 'The source idempotency key was already used with a different request intent', { code: 'idempotency_conflict' });
+    }
+}
+/**
+ * Enforce the initial permanent-retention contract. New rows use Postgres
+ * `infinity`; this check also fails explicitly if a future bounded-retention
+ * policy leaves an expired tombstone. Missing expiry evidence is accepted only
+ * for adapters reading rows written before the column existed.
+ */
+export function assertSourceIdempotencyRetention(expiresAt, now = Date.now()) {
+    if (expiresAt == null ||
+        expiresAt === 'infinity' ||
+        expiresAt === Infinity) {
+        return;
+    }
+    const timestamp = expiresAt instanceof Date
+        ? expiresAt.getTime()
+        : typeof expiresAt === 'number'
+            ? expiresAt
+            : typeof expiresAt === 'string'
+                ? Date.parse(expiresAt)
+                : Number.NaN;
+    if (!Number.isFinite(timestamp)) {
+        throw new AbloValidationError('The source idempotency retention evidence is invalid', { code: 'idempotency_conflict' });
+    }
+    if (timestamp <= now) {
+        throw new AbloValidationError('The source idempotency key has expired and cannot be executed again safely', { code: 'idempotency_key_expired' });
+    }
+}

package/dist/source/index.d.ts

@@ -8,13 +8,15 @@
  *
  * Import from here; the sibling modules import one another directly.
  */
-export { sourceEventForOperation, type SourcePrimitive, type SourceWhere, type SourceListQuery, type SourceListPage, type SourceListResult, type SourceRequestContext, type SourceOperation, type SourceDelta, type SourceEvent, type SourceEventForOperationOptions, type SourceCommitResult, type SourceCommitParams, type SourceScope, type SourceEventsResult, type SourceEventsHandler, type SourceAuthorizeContext, type SourceHandlerContext, type SourceModelHandlers, type SourceCommitHandler, type SourceApiKey, type SourceLoadRequest, type SourceListRequest, type SourceCommitRequest, type SourceEventsRequest, type SourceRequest, type SourceResponse, } from './types.js';
+export { sourceEventForOperation, ABLO_POSTGRES_COMMIT_ECHO_PREFIX, ABLO_SOURCE_CLIENT_TX_ID_MAX_LENGTH, ABLO_SOURCE_ECHO_MAX_OPERATIONS, ABLO_SOURCE_ECHO_MAX_PAYLOAD_BYTES, type SourcePrimitive, type SourceWhere, type SourceListQuery, type SourceListPage, type SourceListResult, type SourceRequestContext, type SourceOperation, type SourceDelta, type SourceEvent, type SourceEventForOperationOptions, type SourceCommitResult, type SourceCommitEcho, type SourceCommitEchoOperation, type SourceCommitEchoMarker, type SourceCommitParams, type SourceScope, type SourceEventsResult, type SourceEventsHandler, type SourceAuthorizeContext, type SourceHandlerContext, type SourceModelHandlers, type SourceCommitHandler, type SourceApiKey, type SourceLoadRequest, type SourceListRequest, type SourceCommitRequest, type SourceEventsRequest, type SourceRequest, type SourceResponse, } from './types.js';
 export { ABLO_SOURCE_HEADERS, SourceSignatureError, signAbloSourceRequest, verifyAbloSourceRequest, type SourceSignatureOptions, type SourceSignatureVerificationOptions, type SourceSignatureVerificationResult, } from './signing.js';
 export { dataSource, type DataSourceOptions, } from './factory.js';
 export { createPushQueue, InMemoryPushQueueStorage, STANDARD_WEBHOOKS_RETRY_SCHEDULE, type PushQueue, type PushQueueItem, type PushQueueOptions, type PushQueueStorage, } from './pushQueue.js';
 export { createSourceConnector, DEFAULT_RECONNECT_SCHEDULE, type SourceConnector, type SourceConnectorOptions, type ConnectorWebSocket, type ConnectorWebSocketFactory, type ConnectorStatus, } from './connector.js';
 export { SOURCE_CONNECTOR_PROTOCOL_VERSION, SOURCE_CONNECTOR_WS_PATH, WS_SOURCE_SUBPROTOCOL, sourceConnectorSubprotocols, encodeFrame, decodeFrame, ConnectorProtocolError, connectorFrameSchema, type ConnectorFrame, type RegisterFrame, type ReadyFrame, type RequestFrame, type ResponseFrame, type ErrorFrame, } from './connectorProtocol.js';
-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 { type DataSourceAdapter, type MutationAdapter, type AdapterReadRequest, type AdapterCommitResult, type Row as AdapterRow, } from './adapter.js';
+export { operationSchema, operationTypeSchema, sourceCommitEchoSchema, sourceCommitEchoOperationSchema, sourceCommitEchoMarkerSchema, changeSetSchema, outboxEventSchema, eventsPageSchema, migrationSchema, adapterCapabilitiesSchema, type Operation, type ChangeSet, type OutboxEvent, type EventsPage, type Migration, type AdapterCapabilities, type SourceCommitEchoMarkerWire, } from './contract.js';
 export { prismaDataSource, type PrismaLike, type PrismaDataSourceOptions } from './adapters/prisma.js';
-export { adapterTableMigrations } from './migrations.js';
+export { adapterTableMigrations, endpointOutboxMigrations, idempotencyLedgerMigrations, } from './migrations.js';
+export { createKyselyMutationAdapter, createKyselyMutationCore, kyselyDataSource, kyselyDirectMutation, kyselyOperationRowId, type KyselyCompiledQuery, type KyselyDeleteBuilder, type KyselyInsertBuilder, type KyselyInsertValuesBuilder, type KyselyLike, type KyselyMutationCore, type KyselyReturningExecutable, type KyselySelectBuilder, type KyselyTransactionBuilder, type KyselyUpdateBuilder, type KyselyUpdateSetBuilder, } from './adapters/kysely.js';
+export { sourceOperationsIntentHash, sourceChangeIntentHash, assertSourceIdempotencyIntent, assertSourceIdempotencyRetention, sourceEchoTransactionIdSchema, encodeSourceEchoTransactionId, decodeSourceEchoTransactionId, type SourceEchoTransactionId, } from './idempotency.js';

package/dist/source/index.js

@@ -8,7 +8,7 @@
  *
  * Import from here; the sibling modules import one another directly.
  */
-export { sourceEventForOperation, } from './types.js';
+export { sourceEventForOperation, ABLO_POSTGRES_COMMIT_ECHO_PREFIX, ABLO_SOURCE_CLIENT_TX_ID_MAX_LENGTH, ABLO_SOURCE_ECHO_MAX_OPERATIONS, ABLO_SOURCE_ECHO_MAX_PAYLOAD_BYTES, } from './types.js';
 export { ABLO_SOURCE_HEADERS, SourceSignatureError, signAbloSourceRequest, verifyAbloSourceRequest, } from './signing.js';
 export { dataSource, } from './factory.js';
 export { createPushQueue, InMemoryPushQueueStorage, STANDARD_WEBHOOKS_RETRY_SCHEDULE, } from './pushQueue.js';
@@ -20,6 +20,8 @@ export { createSourceConnector, DEFAULT_RECONNECT_SCHEDULE, } from './connector.
 export { SOURCE_CONNECTOR_PROTOCOL_VERSION, SOURCE_CONNECTOR_WS_PATH, WS_SOURCE_SUBPROTOCOL, sourceConnectorSubprotocols, encodeFrame, decodeFrame, ConnectorProtocolError, connectorFrameSchema, } from './connectorProtocol.js';
 // The Data Source adapter interface and its Zod contract, with per-ORM implementations.
 export {} from './adapter.js';
-export { operationSchema, operationTypeSchema, changeSetSchema, outboxEventSchema, eventsPageSchema, migrationSchema, adapterCapabilitiesSchema, } from './contract.js';
+export { operationSchema, operationTypeSchema, sourceCommitEchoSchema, sourceCommitEchoOperationSchema, sourceCommitEchoMarkerSchema, changeSetSchema, outboxEventSchema, eventsPageSchema, migrationSchema, adapterCapabilitiesSchema, } from './contract.js';
 export { prismaDataSource } from './adapters/prisma.js';
-export { adapterTableMigrations } from './migrations.js';
+export { adapterTableMigrations, endpointOutboxMigrations, idempotencyLedgerMigrations, } from './migrations.js';
+export { createKyselyMutationAdapter, createKyselyMutationCore, kyselyDataSource, kyselyDirectMutation, kyselyOperationRowId, } from './adapters/kysely.js';
+export { sourceOperationsIntentHash, sourceChangeIntentHash, assertSourceIdempotencyIntent, assertSourceIdempotencyRetention, sourceEchoTransactionIdSchema, encodeSourceEchoTransactionId, decodeSourceEchoTransactionId, } from './idempotency.js';

package/dist/source/migrations.d.ts

@@ -1,14 +1,18 @@
 /**
  * The table-creation SQL every ORM adapter ships for its own infrastructure
- * tables: `ablo_idempotency`, which dedupes commits by `clientTxId`, and
- * `ablo_outbox`, the transactional outbox the `events()` feed reads. Defining it in
- * one place keeps the Prisma adapter, the Drizzle adapter, and `ablo migrate` in
- * agreement on the exact shape.
+ * tables: `ablo_idempotency`, whose legacy-named `client_tx_id` column stores the
+ * scoped server correlation, and (for endpoint wrappers only) `ablo_outbox`, the
+ * transactional outbox the `events()` feed reads. Direct wrappers install only
+ * the ledger migration because WAL is their authoritative feed.
  *
  * These are infrastructure tables, not model tables, and they exist only on your
  * own database when you run a Data Source. Ablo's hosted storage does not use them;
  * it records changes in its own `sync_deltas` log instead.
  */
 import type { Migration } from './contract.js';
-/** Returns the adapter's table-creation migrations. The SQL is idempotent, guarded by `IF NOT EXISTS`. */
+/** The permanent ledger shared by direct and endpoint mutation wrappers. */
+export declare function idempotencyLedgerMigrations(): readonly Migration[];
+/** Endpoint-only transactional outbox and its correlation columns. */
+export declare function endpointOutboxMigrations(): readonly Migration[];
+/** Full endpoint adapter migrations (ledger + outbox). */
 export declare function adapterTableMigrations(): readonly Migration[];

package/dist/source/migrations.js

@@ -1,25 +1,45 @@
 /**
  * The table-creation SQL every ORM adapter ships for its own infrastructure
- * tables: `ablo_idempotency`, which dedupes commits by `clientTxId`, and
- * `ablo_outbox`, the transactional outbox the `events()` feed reads. Defining it in
- * one place keeps the Prisma adapter, the Drizzle adapter, and `ablo migrate` in
- * agreement on the exact shape.
+ * tables: `ablo_idempotency`, whose legacy-named `client_tx_id` column stores the
+ * scoped server correlation, and (for endpoint wrappers only) `ablo_outbox`, the
+ * transactional outbox the `events()` feed reads. Direct wrappers install only
+ * the ledger migration because WAL is their authoritative feed.
  *
  * These are infrastructure tables, not model tables, and they exist only on your
  * own database when you run a Data Source. Ablo's hosted storage does not use them;
  * it records changes in its own `sync_deltas` log instead.
  */
-/** Returns the adapter's table-creation migrations. The SQL is idempotent, guarded by `IF NOT EXISTS`. */
-export function adapterTableMigrations() {
+/** The permanent ledger shared by direct and endpoint mutation wrappers. */
+export function idempotencyLedgerMigrations() {
     return [
         {
             name: 'ablo_idempotency',
             up: `CREATE TABLE IF NOT EXISTS ablo_idempotency (
   client_tx_id TEXT PRIMARY KEY,
   response     JSONB NOT NULL,
+  request_hash TEXT,
+  expires_at   TIMESTAMPTZ NOT NULL DEFAULT 'infinity',
   created_at   TIMESTAMPTZ NOT NULL DEFAULT now()
 );`,
         },
+        {
+            name: 'ablo_idempotency_request_hash',
+            // Nullable only for rows created by older adapter versions. New writes
+            // always populate it; replaying a legacy NULL row fails closed because
+            // the adapter cannot prove that the intent matches.
+            up: `ALTER TABLE ablo_idempotency
+  ADD COLUMN IF NOT EXISTS request_hash TEXT;`,
+        },
+        {
+            name: 'ablo_idempotency_permanent_retention',
+            up: `ALTER TABLE ablo_idempotency
+  ADD COLUMN IF NOT EXISTS expires_at TIMESTAMPTZ NOT NULL DEFAULT 'infinity';`,
+        },
+    ];
+}
+/** Endpoint-only transactional outbox and its correlation columns. */
+export function endpointOutboxMigrations() {
+    return [
         {
             name: 'ablo_outbox',
             up: `CREATE TABLE IF NOT EXISTS ablo_outbox (
@@ -31,9 +51,22 @@ export function adapterTableMigrations() {
   data            JSONB,
   organization_id TEXT,
   client_tx_id    TEXT,
+  correlation_id  TEXT,
+  transaction_id  TEXT,
   occurred_at     BIGINT,
   created_at      TIMESTAMPTZ NOT NULL DEFAULT now()
 );`,
         },
+        {
+            name: 'ablo_outbox_correlation',
+            up: `ALTER TABLE ablo_outbox
+  ADD COLUMN IF NOT EXISTS correlation_id TEXT;
+ALTER TABLE ablo_outbox
+  ADD COLUMN IF NOT EXISTS transaction_id TEXT;`,
+        },
     ];
 }
+/** Full endpoint adapter migrations (ledger + outbox). */
+export function adapterTableMigrations() {
+    return [...idempotencyLedgerMigrations(), ...endpointOutboxMigrations()];
+}