@abloatai/transaction 0.51.0 → 0.53.0

package/src/schema/schema.ts

@@ -8,20 +8,20 @@
  *   import { defineSchema, model, relation } from '@abloatai/transaction/schema';
  *
  *   const schema = defineSchema({
- *     tasks: model({
+ *     items: model({
  *       title: z.string(),
  *       status: z.enum(['todo', 'doing', 'done']).default('todo'),
- *       projectId: z.string().optional(),
+ *       workspaceId: z.string().optional(),
  *     }, {
- *       project: relation.belongsTo('projects', 'projectId'),
+ *       workspace: relation.belongsTo('workspaces', 'workspaceId'),
  *     }),
  *   });
  *
- *   type Task = InferModel<typeof schema, 'tasks'>;
+ *   type Item = InferModel<typeof schema, 'items'>;
  */
 
 import { z } from 'zod';
-import type { ModelDef, RelationRecord } from './model.js';
+import type { ComputedRecord, ModelDef, RelationRecord } from './model.js';
 import type { RelationDef } from './relation.js';
 import { AbloValidationError } from '../errors.js';
 import type { IdentityRole } from './roles.js';
@@ -210,7 +210,7 @@ export interface DefineSchemaOptions {
 export type SchemaRecord = Record<string, ModelDef>;
 
 /**
- * Base fields every synced model gets automatically.
+ * The logical identity every model gets automatically.
  *
  * Exported (internal) so `parseSchema` can rebuild a model's validator the
  * same way `defineSchema` does — `baseFieldsSchema.merge(modelSchema)` — when
@@ -218,26 +218,14 @@ export type SchemaRecord = Record<string, ModelDef>;
  */
 export const baseFieldsSchema = z.object({
   id: z.string(),
-  createdAt: z.date(),
-  updatedAt: z.date(),
-  organizationId: z.string().optional(),
-  createdBy: z.string().optional(),
 });
 
 /**
- * The base-column names every model carries automatically — the keys of
- * {@link baseFieldsSchema}, kept here as the single source of truth. Code
- * generation reads it to avoid emitting a base column twice, and
- * {@link defineSchema} uses it to reject a model that redeclares one, since
- * merging the user's field over the base field would produce a `string & Date`
- * type and break the build.
+ * The universal model field names. Audit and application metadata is declared
+ * by the application or carried by the commit record, never injected here.
  */
 export const BASE_FIELDS = [
   'id',
-  'createdAt',
-  'updatedAt',
-  'organizationId',
-  'createdBy',
 ] as const;
 
 /** The base fields type — pure data columns. */
@@ -262,15 +250,15 @@ export interface Schema<S extends SchemaRecord = SchemaRecord> {
 
   /**
    * Every declared field as a {@link FieldRef} — the field as a value rather
-   * than a quoted name: `schema.fields.tasks.status`.
+   * than a quoted name: `schema.fields.items.status`.
    *
    * A surface that names a field takes one of these instead of a string, so a
    * name that does not exist stops compiling and a rename is a compile error at
    * every use. Claims are the first caller; anything else that has to say
    * "which field" should take a reference for the same reason.
    *
-   * Base fields (`id`, `createdAt`, …) are not here: the schema does not
-   * declare them, and a caller naming one means the row, not a part of it.
+   * Automatically supplied `id` is not here. Every application-declared field
+   * does appear here.
    */
   readonly fields: {
     readonly [K in keyof S & string]: S[K] extends ModelDef<infer Shape>
@@ -281,7 +269,7 @@ export interface Schema<S extends SchemaRecord = SchemaRecord> {
       : never;
   };
 
-  /** Zod schemas with base fields merged in */
+  /** Zod schemas with logical identity merged into each declared model shape. */
   readonly validators: {
     readonly [K in keyof S]: S[K] extends ModelDef<infer Shape>
       ? z.ZodObject<Shape & typeof baseFieldsSchema.shape>
@@ -339,7 +327,7 @@ export interface Schema<S extends SchemaRecord = SchemaRecord> {
  * Includes base fields (id, createdAt, updatedAt, etc.)
  *
  * ```ts
- * type Task = InferModel<typeof schema, 'tasks'>;
+ * type Item = InferModel<typeof schema, 'items'>;
  * ```
  */
 /** The schema bound via `declare module … interface Register { Schema: … }`
@@ -351,15 +339,15 @@ type RegisteredSchema = import('../types/global.js').Register extends {
   : never;
 
 /**
- * The primary model-type helper. Once your project's `ablo/register.ts`
+ * The primary model-type helper. Once your workspace's `ablo/register.ts`
  * registers the schema, a single argument is all it takes:
  *
  * ```ts
- * type Task = Model<'tasks'>;
+ * type Item = Model<'items'>;
  * ```
  *
  * Without that registration, or for a second schema, pass the schema
- * explicitly: `Model<typeof schema, 'tasks'>`.
+ * explicitly: `Model<typeof schema, 'items'>`.
  */
 export type Model<A, B = never> = [B] extends [never]
   ? A extends keyof RegisteredSchema['models']
@@ -371,21 +359,14 @@ export type Model<A, B = never> = [B] extends [never]
 
 /**
  * The row type {@link Model} resolves to. Internal: `Model<typeof schema,
- * 'tasks'>` is the published spelling, because it reads as the domain rather
+ * 'items'>` is the published spelling, because it reads as the domain rather
  * than the machinery. This one is no longer exported from any subpath — it
  * stays because `Model` is defined in terms of it, not as a second name for
  * the same idea.
  */
 export type InferModel<S extends Schema, ModelName extends keyof S['models']> =
   S['models'][ModelName] extends ModelDef<infer Shape, infer R, infer C>
-    ? // `Omit<…, keyof BaseModelFields>` so a model that (wrongly) redeclares a
-      // reserved field degrades to "framework field wins" (e.g. `createdAt: Date`)
-      // instead of intersecting to `never` (`string & Date`, which then surfaces
-      // as a baffling "missing field" error three layers away). defineSchema also
-      // throws on such a redeclaration at runtime (code `schema_reserved_field`);
-      // this is the type-level belt to that runtime suspenders. No-op for correct
-      // schemas — they never carry a base-field key, so nothing is omitted.
-      Omit<z.infer<z.ZodObject<Shape>>, keyof BaseModelFields>
+    ? Omit<z.infer<z.ZodObject<Shape>>, 'id'>
         & BaseModelFields
         & BaseModelMethods
         & InferComputed<C>
@@ -452,14 +433,13 @@ export type InferRelations<S extends Schema, R extends RelationRecord> =
  */
 export type InferRow<S extends Schema, ModelName extends keyof S['models']> =
   S['models'][ModelName] extends ModelDef<infer Shape, RelationRecord, infer C>
-    ? // Same reserved-field guard as InferModel — see the comment there.
-      Omit<z.infer<z.ZodObject<Shape>>, keyof BaseModelFields>
+    ? Omit<z.infer<z.ZodObject<Shape>>, 'id'>
         & BaseModelFields
         & InferComputed<C>
     : never;
 
 /**
- * The reactive-row companion to {@link Model}. Once your project's
+ * The reactive-row companion to {@link Model}. Once your workspace's
  * `ablo/register.ts` registers the schema, a single argument is all it takes:
  *
  * ```ts
@@ -500,26 +480,22 @@ export type InferComputed<C> =
     : { readonly [K in keyof C]: C[K] extends (...args: any[]) => infer R ? R : never };
 
 /**
- * Infer the create input type. Only schema-defined fields are accepted —
- * base fields (id, createdAt, updatedAt) are auto-generated by the SDK
- * and cannot be passed by the consumer.
+ * Infer the create input type. Application fields retain their declared input
+ * requirements and types.
  *
  * The only exception is `id`: consumers can optionally provide one for
  * client-generated IDs (useful for optimistic UI that needs to reference
  * the entity before the server confirms).
  *
  * ```ts
- * type CreateTask = InferCreate<typeof schema, 'tasks'>;
+ * type CreateItem = InferCreate<typeof schema, 'items'>;
  * // { title: string; status?: 'todo' | 'doing' | 'done'; id?: string }
- * // createdAt, updatedAt are NOT accepted — they're auto-generated
  * ```
  */
 export type InferCreate<S extends Schema, ModelName extends keyof S['models']> =
   S['models'][ModelName] extends ModelDef<infer Shape>
-    ? // Same reserved-field guard as InferModel: drop any (wrongly) redeclared
-      // base field so the input degrades to "framework field wins" rather than
-      // collapsing to `never`. No-op for correct schemas.
-      Omit<z.input<z.ZodObject<Shape>>, keyof BaseModelFields> & Partial<BaseModelFields>
+    ? Omit<z.input<z.ZodObject<Shape>>, 'id'>
+        & Partial<Pick<BaseModelFields, 'id'>>
     : never;
 
 /**
@@ -570,8 +546,8 @@ export interface DeleteId<S extends Schema, ModelName extends keyof S['models']>
  *
  * ```ts
  * const schema = defineSchema({
- *   tasks: model({ title: z.string(), status: z.string().default('todo') }),
- *   projects: model({ name: z.string() }),
+ *   items: model({ title: z.string(), status: z.string().default('todo') }),
+ *   workspaces: model({ name: z.string() }),
  * });
  * ```
  */
@@ -682,16 +658,15 @@ export function defineSchema<const S extends SchemaRecord>(
     // failure immediate and unambiguous.
     for (const fieldName of Object.keys(def.shape)) {
       assertRoundTrippableCamelCase(name, fieldName);
-      // Reserved base columns are merged in below via `baseFieldsSchema.merge`,
-      // and Zod `.merge` silently OVERWRITES the base field with the user's —
-      // e.g. a model declaring `createdAt: z.string()` ends up with a field
-      // typed `string & Date`, which breaks the build. Reject the collision at
-      // definition time so the author sees an unambiguous error instead.
-      if ((BASE_FIELDS as readonly string[]).includes(fieldName)) {
+      // Logical identity is the only universal model field. Application
+      // timestamps, tenancy columns and attribution columns are ordinary
+      // fields when an application declares them.
+      const reservedFields = ['id'];
+      if ((reservedFields as readonly string[]).includes(fieldName)) {
         throw new AbloValidationError(
           `[defineSchema] ${name}.${fieldName}: field \`${fieldName}\` collides with a ` +
             `reserved field that the SDK provides automatically ` +
-            `(${BASE_FIELDS.join(', ')}). Remove it from your model — redeclaring it ` +
+            `(${reservedFields.join(', ')}). Remove it from your model — redeclaring it ` +
             `produces a \`string & Date\` type and breaks the build.`,
           { code: 'schema_reserved_field', param: `${name}.${fieldName}` },
         );

package/src/schema/sugar.ts

@@ -15,10 +15,10 @@
  *
  * @example
  * ```ts
- * tasks: mutable.lazy({ title: z.string() }, {
- *   typename: 'Task', tableName: 'tasks',
+ * items: mutable.lazy({ title: z.string() }, {
+ *   typename: 'Item', tableName: 'items',
  *   relations: { ... },
- *   computed: tasksComputed,
+ *   computed: itemsComputed,
  * }),
  * ```
  */
@@ -47,13 +47,13 @@ export interface SugarOptions<
   /** Computed getters installed on the model class prototype. */
   computed?: C;
   /**
-   * Wire `__typename` (PascalCase, e.g. `'Task'`). Defaults to the schema
+   * Wire `__typename` (PascalCase, e.g. `'Item'`). Defaults to the schema
    * key via `defineSchema` — override when the wire shape differs from
    * the camelCase schema key.
    */
   typename?: string;
   /**
-   * The physical table name. Override it when the table name differs from the
+   * The database table name. Override it when the table name differs from the
    * snake_case of the typename — for example, a `Member` type stored in a table
    * named `'member'` rather than `'members'`.
    */
@@ -112,9 +112,9 @@ function build<
  * `{ mutable: true, load: X }` on `model()`.
  *
  * Pick the load suffix by data-access pattern:
- *   - `.instant`  — small, always-needed (Theme, Layout, StatusGroup)
+ *   - `.instant`  — small, always-needed control rows
  *   - `.lazy`     — large collections fetched on first query
- *     (Block, Message, Task)
+ *     (Block, Message, Item)
  */
 export const mutable = {
   instant: <

package/src/server/adapter.ts

@@ -61,6 +61,8 @@ export type ReadResult =
   | {
       readonly kind: 'query';
       readonly rows: readonly Row[];
+      /** Opaque upstream cursor when a source-backed list has another page. */
+      readonly nextCursor?: string;
     };
 
 // ── sync ─────────────────────────────────────────────────────────────────────

package/src/server/commit.ts

@@ -16,6 +16,7 @@
 import type { ParticipantKind, ConfirmationState } from '../log/syncDeltaRow.js';
 import type { ParticipantRef } from '../wire/delta.js';
 import type { CommitExecutionResultInput } from '../wire/commit.js';
+import type { CommitOperationResult } from '../wire/commit.js';
 import type { ReadDependency, TrackDependency } from '../coordination/schema.js';
 import type { EffectiveAuthority } from '../auth/capability.js';
 
@@ -99,4 +100,7 @@ export interface CommitContext {
  * lives with the HTTP/WS confirmation contract so queued correlation cannot drift
  * between cache, transport, and client.
  */
-export type CommitExecutionResult = CommitExecutionResultInput;
+export type CommitExecutionResult = CommitExecutionResultInput & {
+  /** Response-time projection from the exact writing transaction. Never persisted. */
+  readonly operationResults?: readonly CommitOperationResult[];
+};

package/src/server/index.ts

@@ -4,7 +4,8 @@
  * vocabulary ({@link Row}, {@link ReadRequest}, {@link ChangeSet}, and the rest),
  * the {@link CommitContext} and {@link CommitExecutionResult} commit types, the
  * {@link StorageMode} enumeration, and the per-model read configuration
- * ({@link BootstrapModel}, {@link ColumnOverride}). These are plain, driver-free
+ * ({@link ReadModelShape} and the {@link BootstrapModel} descriptor built on it,
+ * plus {@link ColumnOverride} and {@link ParentScope}). These are plain, driver-free
  * types; you supply the database code that fulfills them.
  */
 export type {
@@ -27,4 +28,9 @@ export {
   type CommitRecord,
 } from '../wire/commit.js';
 export { storageModeSchema, type StorageMode } from './storageMode.js';
-export type { ColumnOverride, BootstrapModel } from './readConfig.js';
+export type {
+  ColumnOverride,
+  ParentScope,
+  ReadModelShape,
+  BootstrapModel,
+} from './readConfig.js';

package/src/server/readConfig.ts

@@ -1,9 +1,23 @@
 /**
- * Canonical per-model read configuration consumed when a client bootstraps. Each
- * {@link BootstrapModel} maps a model to its physical table, its tenancy column, and
- * any parent scoping — plain data with no database driver. It feeds the read side of
- * the data adapter contract; your query builder reads it to load a model's initial
- * rows.
+ * Canonical per-model read configuration — how one model's rows are located,
+ * scoped to a tenant, and decoded back into the types the schema declared.
+ *
+ * {@link ReadModelShape} is the definition site for those facts. Every read seam
+ * needs the same set, and each one that restated the set drifted from the
+ * others: `json` decoding reached three of them, `number` decoding reached none,
+ * and the where-clause `boolean` list reached exactly one — so a `bigint`-backed
+ * field left one seam as a decimal string and its `int4` neighbour left the next
+ * as a number. Adding a declared type is now one edit here rather than a
+ * remembered sweep.
+ *
+ * The descriptors below carry that shape plus the facts only they need. They
+ * disagree on one thing, deliberately: the model's own name. A bootstrap
+ * descriptor spells it `name`, the server's read-model descriptor spells it
+ * `typename`. `name` is part of the published data-adapter contract, so the two
+ * spellings stay and the shape they share owns everything else.
+ *
+ * Plain data, no database driver — it feeds the read side of the data adapter
+ * contract, and your query builder reads it to load a model's initial rows.
  */
 
 /** A mapping from a declared field to a physical column, with the alias to apply after a `SELECT *`. */
@@ -13,70 +27,110 @@ export interface ColumnOverride {
   readonly alias: string;
 }
 
-/** Read configuration for one model: how to locate its rows and scope them to a tenant. */
-export interface BootstrapModel {
-  name: string;
+/**
+ * Parent-table tenancy scoping for rows that have no `organization_id` column
+ * of their own, mirroring the schema's `scopedVia` option. A read carrying this
+ * adds:
+ *
+ *   WHERE <table>.<localKey> IN
+ *     (SELECT <parentKey> FROM <parentTable> WHERE <parentOrgColumn> = $1)
+ *
+ * It applies on top of whatever `orgScoped` dictates, so a table can carry its
+ * own `organization_id` and still narrow through a parent. The common case is
+ * `orgScoped: false` together with this on a table that lacks the column —
+ * without it, such a table reads every tenant's rows.
+ */
+export interface ParentScope {
+  readonly localKey: string;
+  readonly parentTable: string;
+  readonly parentKey?: string;
+  readonly parentOrgColumn?: string;
+}
+
+/**
+ * Everything a read seam needs to know about one model except what it is called.
+ *
+ * Split from the descriptors that carry it because the two of them name the
+ * model differently and agree on all of this. A seam that only decodes, or only
+ * compiles SQL, projects the members it uses with `Pick` rather than declaring
+ * its own near-copy.
+ */
+export interface ReadModelShape {
   /**
    * Extra names accepted when a request looks up or filters this model. When the
-   * physical table name is canonical, `name` stays that table name and the aliases
-   * cover generated compatibility names such as `WeatherReports` or `weatherReports`.
+   * physical table name is canonical, the descriptor's own name stays that table
+   * name and the aliases cover generated compatibility names such as
+   * `WeatherReports` or `weatherReports`.
    */
-  aliases?: readonly string[];
+  readonly aliases?: readonly string[];
   /**
-   * The schema key used by source endpoints. `name` stays the wire and result model
-   * name (usually the typename), while source handlers are keyed by the developer's
-   * schema key, such as `files` or `blocks`.
+   * The schema key used by source endpoints. The descriptor's own name stays the
+   * wire and result model name (usually the typename), while source handlers are
+   * keyed by the developer's schema key, such as `files` or `blocks`.
    */
-  sourceModel?: string;
-  table: string;
-  syncGroups?: string[];
-  enabled?: boolean;
-  /** Max rows to return. Omit for unlimited. Maps to schema's bootstrapLimit. */
-  limit?: number;
-  /** SQL ORDER BY clause. Default: 'id'. Maps to schema's bootstrapOrderBy. */
-  orderBy?: string;
+  readonly sourceModel?: string;
+  readonly table: string;
   /** Whether the table has organization_id. Default: true. */
-  orgScoped?: boolean;
+  readonly 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.
+   * { by: 'source' }`) rather than a row column — the source registration is the
+   * tenant boundary. Distinct from `orgScoped: false` (a `none`/global model): a
+   * source-scoped model IS tenant-scoped, just not by a column. It carries no
+   * tenant predicate on a log plane, so every read and bootstrap site fails it
+   * closed with `source_tenancy_not_enforced` rather than treating it as global
+   * — serving it now would return every row to every tenant. When the
+   * write-through connect path can resolve the org from the source registration,
+   * this same flag routes to that resolution.
    */
-  sourceScoped?: boolean;
+  readonly sourceScoped?: boolean;
   /** Physical tenancy column (default `organization_id`, configurable per model). */
-  orgColumn?: string;
-  /**
-   * Parent-table scoping for rows that have no `organization_id` column, mirroring
-   * the schema's `scopedVia` option. When set, the bootstrap query adds:
-   *
-   *   WHERE <table>.<localKey> IN
-   *     (SELECT <parentKey> FROM <parentTable> WHERE <parentOrgColumn> = $1)
-   *
-   * This applies on top of whatever `orgScoped` dictates, so a table can carry its
-   * own `organization_id` and still narrow through a parent. The common case,
-   * though, is `orgScoped: false` together with `scopedVia` on a table that lacks the
-   * column.
-   */
-  scopedVia?: {
-    localKey: string;
-    parentTable: string;
-    parentKey?: string;
-    parentOrgColumn?: string;
-  };
+  readonly orgColumn?: string;
+  /** Parent-table scoping for rows with no tenancy column of their own. */
+  readonly scopedVia?: ParentScope;
   /** Client-facing field name → physical DB column for declared fields. */
-  fieldColumns?: Record<string, string>;
+  readonly fieldColumns?: Readonly<Record<string, string>>;
   /** Physical-column aliases needed after SELECT * for `.from(...)` fields. */
-  columnOverrides?: readonly ColumnOverride[];
+  readonly columnOverrides?: readonly ColumnOverride[];
   /**
-   * Physical columns the schema declares as JSON (via `field.json()`). A JSON field
-   * stored in a text column comes back from `row_to_json` as a serialized string, so
-   * the bootstrap reparses these columns to make the wire value the canonical object
-   * regardless of the physical column type. A `jsonb` column already returns an
-   * object, so reparsing it is a no-op.
+   * Physical columns the schema declares as JSON (via `field.json()`). A JSON
+   * field stored in a text column comes back serialized, so a read reparses these
+   * to make the wire value the canonical object regardless of the physical column
+   * type. A `jsonb` column already returns an object, so reparsing it is a no-op.
    */
-  jsonColumns?: readonly string[];
+  readonly jsonColumns?: readonly string[];
+  /**
+   * Physical columns the schema declares as a boolean (via `field.boolean()`).
+   * Two seams need the list. A where-clause parameter is coerced to a real JS
+   * boolean before binding, because the driver's bool encoder is a strict
+   * `=== true` and a string `'t'` would silently bind as `'f'` — an INVERTED
+   * filter, not an error. A row read back from the log is coerced the same way,
+   * because a value echoed from a customer's database arrives as PG's text
+   * literal rather than as `true`.
+   */
+  readonly boolColumns?: readonly string[];
+  /**
+   * Physical columns the schema declares as a number (via `field.number()`).
+   * Postgres has four integer widths where JavaScript has one, so a column too
+   * wide to always fit a JS number comes back as decimal text. A read decodes
+   * these so a `bigint`-backed field and an `int4`-backed one reach the client as
+   * the same JS type.
+   */
+  readonly numberColumns?: readonly string[];
+}
+
+/**
+ * Read configuration for one model at bootstrap: {@link ReadModelShape} plus the
+ * facts only the initial payload needs — which models are in it, how much of
+ * each, and in what order.
+ */
+export interface BootstrapModel extends ReadModelShape {
+  /** The wire and result model name. `ModelMeta.typename` is the same fact. */
+  readonly name: string;
+  readonly syncGroups?: readonly string[];
+  readonly enabled?: boolean;
+  /** Max rows to return. Omit for unlimited. Maps to schema's bootstrapLimit. */
+  readonly limit?: number;
+  /** SQL ORDER BY clause. Default: 'id'. Maps to schema's bootstrapOrderBy. */
+  readonly orderBy?: string;
 }

package/src/source/adapters/drizzle.ts

@@ -151,6 +151,11 @@ export function drizzleDataSource<S extends SchemaRecord>(
   };
 
   const applyOperation = async (tx: DrizzleLike, op: Operation): Promise<Row> => {
+    if (op.where) {
+      throw new AbloValidationError('The Drizzle adapter does not support conditional operations', {
+        code: 'source_adapter_misconfigured',
+      });
+    }
     const mc = modelColumns(op.model);
     const table = sql.identifier(mc.table);
     const id = rowId(op);

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 };