@abloatai/transaction 0.50.0 → 0.52.0

package/src/source/adapters/kysely.ts

@@ -32,6 +32,8 @@ import {
   changeSetSchema,
   outboxEventSchema,
   sourceCommitEchoMarkerSchema,
+  sourceCommitEchoIntentSchema,
+  type SourceCommitEchoIntent,
 } from '../contract.js';
 import {
   assertSourceIdempotencyIntent,
@@ -135,19 +137,17 @@ function markerAction(type: ChangeSet['operations'][number]['type']): 'I' | 'U'
   return 'U';
 }
 
-function assertDirectLogicalMarker(
+function parseEchoIntent(
   change: ChangeSet,
   markerModelFor: (operationModel: string) => string,
-): void {
+  required: boolean,
+): SourceCommitEchoIntent | undefined {
   const payload = change.echo?.payload;
   if (!payload) {
-    throw new AbloValidationError(
-      'A direct Kysely mutation requires a transactional Postgres logical marker',
-      { code: 'source_adapter_misconfigured' },
-    );
+    return undefined;
   }
   try {
-    const marker = sourceCommitEchoMarkerSchema.parse(JSON.parse(payload) as unknown);
+    const marker = sourceCommitEchoIntentSchema.parse(JSON.parse(payload) as unknown);
     if (marker.correlationId !== change.correlationId) {
       throw new Error('marker correlation does not match the ledger key');
     }
@@ -163,15 +163,18 @@ function assertDirectLogicalMarker(
       if (
         !markerOperation ||
         markerOperation.model !== markerModelFor(operation.model) ||
-        markerOperation.id !== kyselyOperationRowId(operation) ||
+        (markerOperation.id != null && markerOperation.id !== kyselyOperationRowId(operation)) ||
+        (markerOperation.id == null && operation.type !== 'CREATE') ||
         markerOperation.action !== markerAction(operation.type) ||
         markerOperation.transactionId !== operation.transactionId
       ) {
         throw new Error(`marker operation ${index} does not match the mutation`);
       }
     }
+    return marker;
   } catch (error) {
     if (error instanceof AbloValidationError) throw error;
+    if (!required) return undefined;
     throw new AbloValidationError(
       `The direct Postgres logical marker is invalid: ${error instanceof Error ? error.message : 'unknown marker error'}`,
       { code: 'source_adapter_misconfigured' },
@@ -179,6 +182,32 @@ function assertDirectLogicalMarker(
   }
 }
 
+function resolveEchoMarker(
+  intent: SourceCommitEchoIntent,
+  rows: readonly Row[],
+) {
+  return sourceCommitEchoMarkerSchema.parse({
+    ...intent,
+    operations: intent.operations.map((operation, index) => {
+      const returnedId = rows[index]?.id;
+      const id = operation.id ?? returnedId;
+      if (typeof id !== 'string' || id.length === 0) {
+        throw new AbloValidationError(
+          `source operation ${index} did not return a canonical id for WAL correlation`,
+          { code: 'source_adapter_misconfigured' },
+        );
+      }
+      if (returnedId != null && String(returnedId) !== id) {
+        throw new AbloValidationError(
+          `source operation ${index} returned an id that does not match its WAL correlation`,
+          { code: 'source_adapter_misconfigured' },
+        );
+      }
+      return { ...operation, id };
+    }),
+  });
+}
+
 /**
  * Build the shared transaction policy around one Kysely mutation core. Exported
  * for engine integrations that need to inject a prebuilt core while retaining
@@ -226,7 +255,13 @@ export function createKyselyMutationAdapter(
 
     async commit(change: ChangeSet): Promise<AdapterCommitResult> {
       const request = changeSetSchema.parse(change);
-      if (mode === 'direct') assertDirectLogicalMarker(request, markerModelFor);
+      if (mode === 'direct' && !request.echo) {
+        throw new AbloValidationError(
+          'A direct Kysely mutation requires a transactional Postgres logical marker',
+          { code: 'source_adapter_misconfigured' },
+        );
+      }
+      const echoIntent = parseEchoIntent(request, markerModelFor, mode === 'direct');
 
       const requestHash = sourceChangeIntentHash(request);
       return db.transaction().execute(async (transaction) => {
@@ -280,8 +315,11 @@ export function createKyselyMutationAdapter(
           completeLedgerQuery(request.correlationId, rows),
         );
         if (request.echo?.kind === 'postgres-wal') {
+          const payload = echoIntent
+            ? JSON.stringify(resolveEchoMarker(echoIntent, rows))
+            : request.echo.payload;
           await transaction.executeQuery(
-            postgresLogicalMarkerQuery(request.echo.payload),
+            postgresLogicalMarkerQuery(payload),
           );
         }
         return { rows };

package/src/source/adapters/kyselyMutationCore.ts

@@ -1,7 +1,7 @@
 /**
  * Reusable Kysely row-mutation core.
  *
- * This is the single schema-field ↔ physical-column translation used by both
+ * This is the single schema-field ↔ database-column translation used by both
  * Kysely transports. It deliberately knows nothing about outboxes, logical
  * markers, or idempotency: wrappers compose those transaction policies around
  * the same `applyOperation` implementation, so direct and endpoint DML cannot
@@ -133,6 +133,11 @@ export function kyselyOperationRowId(operation: Operation): string {
   return id;
 }
 
+function suppliedOperationRowId(operation: Operation): string | undefined {
+  const id = operation.id ?? operation.input?.id;
+  return typeof id === 'string' && id.length > 0 ? id : undefined;
+}
+
 /** The transport-independent Kysely field/column mutation boundary. */
 export interface KyselyMutationCore {
   read(request: AdapterReadRequest): Promise<readonly Row[]>;
@@ -159,16 +164,23 @@ export function createKyselyMutationCore<S extends SchemaRecord>(
     columns.fieldToColumn.get(field) ?? camelToSnake(field);
   const fieldFor = (columns: ModelColumns, column: string): string =>
     columns.columnToField.get(column) ?? snakeToCamel(column);
-
   const toColumns = (columns: ModelColumns, row: Row): Row => {
     const out: Row = {};
-    for (const key of Object.keys(row)) out[columnFor(columns, key)] = row[key];
+    for (const key of Object.keys(row)) {
+      out[columnFor(columns, key)] = row[key];
+    }
     return out;
   };
 
   const toFields = (columns: ModelColumns, row: Row): Row => {
     const out: Row = {};
-    for (const key of Object.keys(row)) out[fieldFor(columns, key)] = row[key];
+    for (const key of Object.keys(row)) {
+      const field = fieldFor(columns, key);
+      const value = row[key];
+      out[field] = field === 'id' && value !== null && value !== undefined
+        ? String(value)
+        : value;
+    }
     return out;
   };
 
@@ -179,7 +191,7 @@ export function createKyselyMutationCore<S extends SchemaRecord>(
         const rows = await db
           .selectFrom(columns.table)
           .selectAll()
-          .where('id', '=', request.id)
+          .where(columnFor(columns, 'id'), '=', request.id)
           .limit(1)
           .execute();
         return rows.map((row) => toFields(columns, row));
@@ -194,13 +206,53 @@ export function createKyselyMutationCore<S extends SchemaRecord>(
 
     async applyOperation(transaction, operation): Promise<Row> {
       const columns = modelColumns(operation.model);
-      const id = kyselyOperationRowId(operation);
       const input = operation.input ?? {};
+      if (operation.where && operation.type !== 'UPDATE') {
+        throw new AbloValidationError('where is supported only for UPDATE operations', {
+          code: 'commit_operation_invalid',
+          param: 'where',
+        });
+      }
+
+      if (operation.type === 'CREATE') {
+        const suppliedId = suppliedOperationRowId(operation);
+        const createInput = operation.id == null
+          ? Object.fromEntries(Object.entries(input).filter(([field]) => field !== 'id'))
+          : input;
+        const inserted = await transaction
+          .insertInto(columns.table)
+          .values(toColumns(columns, {
+            ...createInput,
+            ...(operation.id == null
+              ? {}
+              : suppliedId
+                ? { id: suppliedId }
+                : {}),
+          }))
+          .returningAll()
+          .execute();
+        if (!inserted[0]) {
+          throw new AbloValidationError(
+            `${operation.type} on "${operation.model}" returned no source row`,
+            { code: 'source_adapter_misconfigured' },
+          );
+        }
+        const row = toFields(columns, inserted[0]);
+        if (typeof row.id !== 'string' || row.id.length === 0) {
+          throw new AbloValidationError(
+            `${operation.type} on "${operation.model}" did not return a canonical id`,
+            { code: 'source_adapter_misconfigured' },
+          );
+        }
+        return row;
+      }
+
+      const id = kyselyOperationRowId(operation);
 
       if (operation.type === 'DELETE') {
         const deleted = await transaction
           .deleteFrom(columns.table)
-          .where('id', '=', id)
+          .where(columnFor(columns, 'id'), '=', id)
           .returningAll()
           .execute();
         if (!deleted[0]) {
@@ -212,30 +264,25 @@ export function createKyselyMutationCore<S extends SchemaRecord>(
         return toFields(columns, deleted[0]);
       }
 
-      if (operation.type === 'CREATE') {
-        const inserted = await transaction
-          .insertInto(columns.table)
-          .values(toColumns(columns, { id, ...input }))
-          .returningAll()
-          .execute();
-        return inserted[0] ? toFields(columns, inserted[0]) : { id, ...input };
-      }
-
       const patch = toColumns(columns, {
         ...input,
         ...(operation.type === 'ARCHIVE' ? { archivedAt: new Date() } : {}),
         ...(operation.type === 'UNARCHIVE' ? { archivedAt: null } : {}),
       });
-      const updated = await transaction
+      let update = transaction
         .updateTable(columns.table)
         .set(patch)
-        .where('id', '=', id)
-        .returningAll()
-        .execute();
+        .where(columnFor(columns, 'id'), '=', id);
+      for (const [column, value] of Object.entries(toColumns(columns, operation.where ?? {}))) {
+        update = update.where(column, '=', value);
+      }
+      const updated = await update.returningAll().execute();
       if (!updated[0]) {
         throw new AbloValidationError(
-          `${operation.type} on "${operation.model}/${id}" matched no source row`,
-          { code: 'mutate_update_entity_not_found' },
+          operation.where
+            ? `The conditional ${operation.type} on "${operation.model}/${id}" did not match`
+            : `${operation.type} on "${operation.model}/${id}" matched no source row`,
+          { code: operation.where ? 'precondition_failed' : 'mutate_update_entity_not_found' },
         );
       }
       return toFields(columns, updated[0]);

package/src/source/adapters/memory.ts

@@ -54,6 +54,11 @@ export function memoryDataSource(): DataSourceAdapter {
   };
 
   const applyOperation = (op: Operation): Row => {
+    if (op.where) {
+      throw new AbloValidationError('The memory adapter does not support conditional operations', {
+        code: 'source_adapter_misconfigured',
+      });
+    }
     const m = modelStore(op.model);
     const id = rowId(op);
     switch (op.type) {

package/src/source/adapters/prisma.ts

@@ -80,7 +80,7 @@ const lowerFirst = (s: string): string => (s ? s.charAt(0).toLowerCase() + s.sli
  * the adapter, and it reflects a real limit of the type system rather than a
  * shortcut. Writes inside `prisma.$transaction(tx => …)` must go through the
  * transactional client `tx`, and the model is known only as a runtime string.
- * Prisma keys its client by fixed property names (`{ task: TaskDelegate; … }`), so
+ * Prisma keys its client by fixed property names (`{ item: ItemDelegate; … }`), so
  * a dynamic `tx[name]` lookup is `unknown` to the compiler: there is no static key
  * to infer from a string. The cast is checked at runtime immediately afterward by
  * confirming that `findMany` is a function on the resolved delegate.
@@ -149,6 +149,11 @@ export function prismaDataSource<S extends SchemaRecord>(
   void schema; // held for typed reads and model validation
 
   const applyOperation = async (tx: PrismaRaw, op: Operation): Promise<Row> => {
+    if (op.where) {
+      throw new AbloValidationError('The Prisma adapter does not support conditional operations', {
+        code: 'source_adapter_misconfigured',
+      });
+    }
     const delegate = delegateFor(tx, delegateName(op.model));
     const id = rowId(op);
     switch (op.type) {

package/src/source/conformance.ts

@@ -75,7 +75,7 @@ export function mutationConformanceChecks(
         const adapter = await make();
         const result = await adapter.commit(
           request('corr_create', [
-            { type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } },
+            { type: 'CREATE', model: 'item', id: 't1', input: { title: 'A' } },
           ]),
         );
         assert.equal(result.rows.length, 1, 'one row returned');
@@ -90,12 +90,12 @@ export function mutationConformanceChecks(
       run: async () => {
         const adapter = await make();
         await adapter.commit(request('corr_load', [
-          { type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } },
+          { type: 'CREATE', model: 'item', id: 't1', input: { title: 'A' } },
         ]));
-        const found = await adapter.read({ kind: 'load', model: 'task', id: 't1' });
+        const found = await adapter.read({ kind: 'load', model: 'item', id: 't1' });
         assert.equal(found.length, 1);
         assert.equal(found[0]?.title, 'A');
-        const missing = await adapter.read({ kind: 'load', model: 'task', id: 'nope' });
+        const missing = await adapter.read({ kind: 'load', model: 'item', id: 'nope' });
         assert.equal(missing.length, 0, 'unknown id reads empty');
       },
     },
@@ -104,10 +104,10 @@ export function mutationConformanceChecks(
       run: async () => {
         const adapter = await make();
         await adapter.commit(request('corr_list', [
-          { type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } },
-          { type: 'CREATE', model: 'task', id: 't2', input: { title: 'B' } },
+          { type: 'CREATE', model: 'item', id: 't1', input: { title: 'A' } },
+          { type: 'CREATE', model: 'item', id: 't2', input: { title: 'B' } },
         ]));
-        const rows = await adapter.read({ kind: 'list', model: 'task' });
+        const rows = await adapter.read({ kind: 'list', model: 'item' });
         assert.deepEqual(rows.map((row) => row.id).sort(), ['t1', 't2']);
       },
     },
@@ -116,12 +116,12 @@ export function mutationConformanceChecks(
       run: async () => {
         const adapter = await make();
         const commitRequest = request('corr_replay', [
-          { type: 'CREATE', model: 'task', id: 't1', input: { title: 'A', n: 1 } },
+          { type: 'CREATE', model: 'item', 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');
-        const rows = await adapter.read({ kind: 'list', model: 'task' });
+        const rows = await adapter.read({ kind: 'list', model: 'item' });
         assert.equal(rows.length, 1, 'no duplicate row');
       },
     },
@@ -131,13 +131,13 @@ export function mutationConformanceChecks(
         const adapter = await make();
         await adapter.commit(request(
           'corr_conflict',
-          [{ type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } }],
+          [{ type: 'CREATE', model: 'item', 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' } }],
+            [{ type: 'UPDATE', model: 'item', id: 't1', input: { title: 'B' } }],
             'b'.repeat(64),
           )),
           (error: unknown) =>
@@ -153,14 +153,14 @@ export function mutationConformanceChecks(
       run: async () => {
         const adapter = await make();
         const commitRequest = request('corr_concurrent', [
-          { type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } },
+          { type: 'CREATE', model: 'item', 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' });
+        const rows = await adapter.read({ kind: 'list', model: 'item' });
         assert.equal(rows.length, 1, 'concurrent retries produced one row');
       },
     },
@@ -169,12 +169,12 @@ export function mutationConformanceChecks(
       run: async () => {
         const adapter = await make();
         await adapter.commit(request('corr_create_2', [
-          { type: 'CREATE', model: 'task', id: 't1', input: { title: 'A' } },
+          { type: 'CREATE', model: 'item', id: 't1', input: { title: 'A' } },
         ]));
         await adapter.commit(request('corr_update_2', [
-          { type: 'UPDATE', model: 'task', id: 't1', input: { title: 'B' } },
+          { type: 'UPDATE', model: 'item', id: 't1', input: { title: 'B' } },
         ]));
-        const found = await adapter.read({ kind: 'load', model: 'task', id: 't1' });
+        const found = await adapter.read({ kind: 'load', model: 'item', id: 't1' });
         assert.equal(found[0]?.title, 'B', 'update applied');
       },
     },
@@ -200,7 +200,7 @@ export function endpointConformanceChecks(make: MakeAdapter): ConformanceCheck[]
         const request = change('corr_outbox_replay', [
           {
             type: 'CREATE',
-            model: 'task',
+            model: 'item',
             id: 't1',
             input: { title: 'A' },
             transactionId: 'op_outbox_replay',
@@ -223,7 +223,7 @@ export function endpointConformanceChecks(make: MakeAdapter): ConformanceCheck[]
         await adapter.commit(change('corr_event', [
           {
             type: 'CREATE',
-            model: 'task',
+            model: 'item',
             id: 't1',
             input: { title: 'A' },
             transactionId: 'op_event',
@@ -232,7 +232,7 @@ export function endpointConformanceChecks(make: MakeAdapter): ConformanceCheck[]
         const page = await adapter.events(null, 100);
         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.model, 'item');
         assert.equal(event.type, 'CREATE');
         assert.equal(event.correlationId, 'corr_event');
         assert.equal(event.transactionId, 'op_event');
@@ -244,10 +244,10 @@ export function endpointConformanceChecks(make: MakeAdapter): ConformanceCheck[]
       run: async () => {
         const adapter = await make();
         await adapter.commit(change('corr_page_a', [
-          { type: 'CREATE', model: 'task', id: 't1', input: {} },
+          { type: 'CREATE', model: 'item', id: 't1', input: {} },
         ]));
         await adapter.commit(change('corr_page_b', [
-          { type: 'CREATE', model: 'task', id: 't2', input: {} },
+          { type: 'CREATE', model: 'item', id: 't2', input: {} },
         ]));
 
         const first = await adapter.events(null, 1);

package/src/source/contract.ts

@@ -79,6 +79,40 @@ export const sourceCommitEchoOperationSchema = z.strictObject({
   transactionId: z.string().min(1).max(ABLO_SOURCE_CLIENT_TX_ID_MAX_LENGTH),
 });
 
+/**
+ * Pre-write correlation evidence. A database-generated CREATE has no row id
+ * until its INSERT returns, so the adapter receives the same operation shape
+ * with that one value absent and finalizes it inside the writing transaction.
+ */
+const sourceCommitEchoIntentOperationSchema = sourceCommitEchoOperationSchema.extend({
+  id: z.string().min(1).nullish(),
+});
+
+export const sourceCommitEchoIntentSchema = z
+  .strictObject({
+    version: z.literal(1),
+    correlationId: correlationIdSchema,
+    operations: z
+      .array(sourceCommitEchoIntentOperationSchema)
+      .min(1)
+      .max(ABLO_SOURCE_ECHO_MAX_OPERATIONS)
+      .readonly(),
+  })
+  .superRefine(({ operations }, ctx) => {
+    const seen = new Set<string>();
+    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);
+    }
+  });
+export type SourceCommitEchoIntent = z.infer<typeof sourceCommitEchoIntentSchema>;
+
 export const sourceCommitEchoMarkerSchema = z
   .strictObject({
     version: z.literal(1),

package/src/source/index.ts

@@ -129,6 +129,7 @@ export {
   sourceCommitEchoSchema,
   sourceCommitEchoOperationSchema,
   sourceCommitEchoMarkerSchema,
+  sourceCommitEchoIntentSchema,
   changeSetSchema,
   outboxEventSchema,
   eventsPageSchema,
@@ -141,6 +142,7 @@ export {
   type Migration,
   type AdapterCapabilities,
   type SourceCommitEchoMarkerWire,
+  type SourceCommitEchoIntent,
 } from './contract.js';
 export { prismaDataSource, type PrismaLike, type PrismaDataSourceOptions } from './adapters/prisma.js';
 export {

package/src/source/types.ts

@@ -105,6 +105,7 @@ export interface SourceOperation {
   readonly model: string;
   readonly id?: string | null;
   readonly input?: Record<string, unknown> | null;
+  readonly where?: Record<string, unknown> | null;
   readonly transactionId?: string | null;
   readonly readAt?: number | null;
   readonly onStale?: OnStaleMode | null;

package/src/transactionLayer.ts

@@ -17,9 +17,9 @@
  * over a socket, and it joins the seam when its core carrier type exists —
  * see docs/plans/transaction-core-language.md, Tier 3.
  *
- * This is the contract, not a runtime: nothing in this package implements it
- * yet. The first explicit implementation (a headless client, a test harness)
- * gains a compile-time conformance pin against this interface.
+ * This is the contract, not a runtime. The headless HTTP client implements it
+ * as a proxy to the hosted authority; other compositions gain the same
+ * compile-time conformance pin against this interface.
  */
 
 import type { CommitMessage } from './wire/frames.js';

package/src/transport/httpClient.ts

@@ -166,10 +166,10 @@ export interface HttpModelClient<T, C = T> {
    * duplicated.
    *
    * ```ts
-   * await ablo.tasks.track({ id: 'task_42' });
+   * await ablo.items.track({ id: 'item_42' });
    * // …minutes of other work later, on the next write…
    * const res = await ablo.commits.create({ operations: [ … ] });
-   * res.notifications; // populated if task_42 moved in the meantime
+   * res.notifications; // populated if item_42 moved in the meantime
    * ```
    *
    * The returned `notifications` are only the tracks that had ALREADY fired at
@@ -209,6 +209,10 @@ export type AbloHttpClient<S extends SchemaRecord> = {
   readonly logs: HttpLogsResource;
   /** Server-confirmed authority of the credential, populated by `ready()`. */
   readonly identity: EffectiveAuthority | null;
+  /**
+   * Waits for requests already using this client and commits already scheduled
+   * on its commit lane. Stop accepting application work before calling it.
+   */
   dispose(): Promise<void>;
   /** Resolves the bearer credential this client authenticates with, or `null` if none is set. */
   getAuthToken(): Promise<string | null>;