@abloatai/ablo 0.29.3 → 0.30.0

package/dist/source/types.d.ts

@@ -60,6 +60,10 @@ export interface SourceRequestContext {
     readonly participantId?: string;
     readonly participantKind?: 'user' | 'agent' | 'system';
     readonly organizationId?: string;
+    /** Trusted project plane selected by the authenticating credential. */
+    readonly projectId?: string;
+    /** Trusted sandbox plane selected by the authenticating credential. */
+    readonly sandboxId?: string;
     readonly requiredSyncGroups?: readonly string[];
     /**
      * Whether this request runs in production or sandbox mode. Branch your
@@ -106,9 +110,9 @@ export interface SourceDelta {
  * through the SDK.
  *
  * Your handler can return the whole outbox unfiltered. Ablo deduplicates on
- * the stable `id` and uses `clientTxId` to drop echoes of changes the SDK
- * already committed. If that earlier commit never landed, the same outbox
- * event repairs the gap on the next poll or push.
+ * the stable `id`. A mediated endpoint write carries `correlationId` plus the
+ * operation's `transactionId`; those fields promote its queued receipt after
+ * the event is durably appended. External writes omit them.
  */
 export interface SourceEvent {
     /**
@@ -128,13 +132,14 @@ export interface SourceEvent {
      */
     readonly organizationId?: string;
     /**
-     * The originating SDK commit id, when you know it. If your outbox records the
-     * `clientTxId` that Ablo passed into the matching `commit` handler, echo it
-     * back here and Ablo will skip events whose commit already produced a change.
-     * Leave it unset for changes made outside the SDK, such as cron jobs, batch
-     * imports, or manual edits.
+     * @deprecated Legacy echo identity. It is not trusted for queued settlement;
+     * use `correlationId` and `transactionId` for mediated endpoint writes.
      */
     readonly clientTxId?: string;
+    /** Scoped server-authored identity of the queued mediated commit. */
+    readonly correlationId?: string;
+    /** Stable per-operation identity within the correlated commit. */
+    readonly transactionId?: string;
     /**
      * When the change occurred in your database. Optional and used only as an
      * ordering hint; Ablo trusts the order of your handler's response over this
@@ -162,11 +167,12 @@ export interface SourceEventForOperationOptions {
      */
     readonly data?: Record<string, unknown> | null;
     /**
-     * The commit request's idempotency key. Echoing it lets Ablo drop echoes of
-     * a change the SDK already committed, while still letting the outbox event
-     * repair that change if it never landed.
+     * @deprecated Legacy echo identity. Prefer the explicit correlation fields.
      */
     readonly clientTxId?: string;
+    readonly correlationId?: string;
+    /** Defaults to `operation.transactionId` when present. */
+    readonly transactionId?: string;
     readonly organizationId?: string;
     readonly occurredAt?: number | Date;
 }
@@ -192,10 +198,64 @@ export interface SourceCommitResult<Row = Record<string, unknown>> {
      */
     readonly deltas?: readonly SourceDelta[];
 }
+/**
+ * Requests a commit-correlated marker in the customer's Postgres WAL.
+ *
+ * This is opt-in because ordinary Data Source endpoints can be backed by
+ * stores other than Postgres. Connected Postgres planes request it for
+ * `wait: 'confirmed'`: the row changes and the logical message must be written
+ * by the same customer-side transaction, so a rollback publishes neither.
+ */
+export interface SourceCommitEcho {
+    readonly kind: 'postgres-wal';
+    /**
+     * Opaque, versioned marker payload authored by Ablo. A source handler must
+     * pass these exact bytes to `pg_logical_emit_message` inside the write
+     * transaction; it must not reconstruct or normalize the JSON.
+     */
+    readonly payload: string;
+}
+/** Prefix reserved for Ablo commit-correlation messages in pgoutput. */
+export declare const ABLO_POSTGRES_COMMIT_ECHO_PREFIX = "ablo";
+/**
+ * Maximum source commit-correlation key length. This matches the server's
+ * idempotency-key contract: a WAL marker longer than this can never name an
+ * accepted Ablo commit and must not be appended as an apparently correlatable
+ * echo.
+ */
+export declare const ABLO_SOURCE_CLIENT_TX_ID_MAX_LENGTH = 255;
+/** Connected-source batches are deliberately smaller than the generic wire cap. */
+export declare const ABLO_SOURCE_ECHO_MAX_OPERATIONS = 500;
+/** Maximum UTF-8 bytes accepted for one transactional WAL marker payload. */
+export declare const ABLO_SOURCE_ECHO_MAX_PAYLOAD_BYTES: number;
+export interface SourceCommitEchoOperation {
+    readonly model: string;
+    readonly id: string;
+    readonly action: 'I' | 'U' | 'D';
+    readonly transactionId: string;
+}
+/** Strict payload encoded into {@link SourceCommitEcho.payload}. */
+export interface SourceCommitEchoMarker {
+    readonly version: 1;
+    readonly correlationId: string;
+    readonly operations: readonly SourceCommitEchoOperation[];
+}
 /** The arguments passed to a top-level {@link SourceCommitHandler}. */
 export interface SourceCommitParams<TAuth = unknown> {
     readonly operations: readonly SourceOperation[];
+    /** Scoped, server-authored customer-ledger identity. */
+    readonly correlationId?: string;
+    /** @deprecated Legacy wire name for `correlationId`. */
     readonly clientTxId?: string;
+    /**
+     * Canonical hash of the complete caller intent (operations plus guarded
+     * context), authored and signed by Ablo. Persist it beside `correlationId` and
+     * reject a replay whose hash differs; this protects an ambiguous retry even
+     * if Ablo's local execution row rolled back after your commit succeeded.
+     */
+    readonly intentHash?: string;
+    /** Present when the caller requires a transaction-correlated WAL echo. */
+    readonly echo?: SourceCommitEcho;
     readonly context: SourceHandlerContext<TAuth>;
 }
 /**
@@ -245,7 +305,7 @@ export interface SourceHandlerContext<TAuth = unknown> {
      * The `webhook-id` from the signed request, globally unique per the
      * Standard Webhooks specification. Dedupe by this id to defend against
      * replay: Ablo does not deduplicate at the source-handler boundary.
-     * Commit idempotency keys on `clientTxId`, and event replay protection
+     * Commit idempotency keys on the scoped `correlationId`, and event replay protection
      * keys on the outbox event `id`.
      */
     readonly messageId?: string;
@@ -273,12 +333,19 @@ export interface SourceModelHandlers<Row, CreateInput, TAuth = unknown> {
     }): Promise<SourceListResult<Row>> | SourceListResult<Row>;
     /**
      * Apply one or more operations for this model within your own database
-     * transaction. Your handler must be idempotent on the operation and its
-     * `clientTxId`, so that a retried commit does not apply the change twice.
+     * transaction. Your handler must be idempotent on the scoped server
+     * `correlationId`, so that a retried commit does not apply the change twice.
      */
     commit?(params: {
         readonly operations: readonly SourceOperation[];
+        /** Scoped, server-authored customer-ledger identity. */
+        readonly correlationId?: string;
+        /** @deprecated Legacy wire name for `correlationId`. */
         readonly clientTxId?: string;
+        /** Persist and compare this hash as part of the idempotency ledger. */
+        readonly intentHash?: string;
+        /** Emit this marker inside the same transaction as the operations. */
+        readonly echo?: SourceCommitEcho;
         readonly context: SourceHandlerContext<TAuth>;
     }): Promise<SourceCommitResult<Row>> | SourceCommitResult<Row>;
 }
@@ -304,7 +371,14 @@ export interface SourceCommitRequest {
      */
     readonly model?: string;
     readonly operations: readonly SourceOperation[];
+    /** Scoped, server-authored customer-ledger identity. */
+    readonly correlationId?: string;
+    /** @deprecated Legacy wire name for `correlationId`. */
     readonly clientTxId?: string;
+    /** Signed canonical hash of the complete server-side commit intent. */
+    readonly intentHash?: string;
+    /** Commit-confirmation marker requested by a connected Postgres plane. */
+    readonly echo?: SourceCommitEcho;
     readonly scope?: SourceRequestContext;
 }
 export interface SourceEventsRequest {

package/dist/source/types.js

@@ -24,6 +24,7 @@ export function sourceEventForOperation(options) {
         throw new AbloValidationError('sourceEventForOperation requires operation.id or an explicit entityId', { code: 'source_event_invalid' });
     }
     const occurredAt = normalizeEventOccurredAt(options.occurredAt);
+    const transactionId = options.transactionId ?? options.operation.transactionId ?? undefined;
     return {
         id: options.eventId,
         model: options.operation.model,
@@ -32,6 +33,8 @@ export function sourceEventForOperation(options) {
         ...(options.data !== undefined ? { data: options.data } : {}),
         ...(options.organizationId ? { organizationId: options.organizationId } : {}),
         ...(options.clientTxId ? { clientTxId: options.clientTxId } : {}),
+        ...(options.correlationId ? { correlationId: options.correlationId } : {}),
+        ...(transactionId ? { transactionId } : {}),
         ...(occurredAt !== undefined ? { occurredAt } : {}),
     };
 }
@@ -41,3 +44,16 @@ function normalizeEventOccurredAt(value) {
     const timestamp = value instanceof Date ? value.getTime() : value;
     return Number.isFinite(timestamp) ? timestamp : undefined;
 }
+/** Prefix reserved for Ablo commit-correlation messages in pgoutput. */
+export const ABLO_POSTGRES_COMMIT_ECHO_PREFIX = 'ablo';
+/**
+ * Maximum source commit-correlation key length. This matches the server's
+ * idempotency-key contract: a WAL marker longer than this can never name an
+ * accepted Ablo commit and must not be appended as an apparently correlatable
+ * echo.
+ */
+export const ABLO_SOURCE_CLIENT_TX_ID_MAX_LENGTH = 255;
+/** Connected-source batches are deliberately smaller than the generic wire cap. */
+export const ABLO_SOURCE_ECHO_MAX_OPERATIONS = 500;
+/** Maximum UTF-8 bytes accepted for one transactional WAL marker payload. */
+export const ABLO_SOURCE_ECHO_MAX_PAYLOAD_BYTES = 256 * 1024;

package/dist/surface.d.ts

@@ -30,7 +30,7 @@ export declare const PUBLIC_LIST_OPTION_KEYS: readonly ["where", "filter", "orde
  * The keys of the client constructor options, {@link AbloOptions}. Only
  * `schema` is required; every other key is optional.
  */
-export declare const PUBLIC_ABLO_OPTION_KEYS: readonly ["schema", "apiKey", "authEndpoint", "databaseUrl", "persistence", "durableWrites", "commitOutbox", "commitOutboxScope", "transport", "debug", "logLevel", "authToken", "baseURL", "fetch", "defaultHeaders", "defaultQuery", "dangerouslyAllowBrowser"];
+export declare const PUBLIC_ABLO_OPTION_KEYS: readonly ["schema", "apiKey", "authEndpoint", "persistence", "durableWrites", "commitOutbox", "commitOutboxScope", "transport", "debug", "logLevel", "authToken", "baseURL", "fetch", "defaultHeaders", "defaultQuery", "dangerouslyAllowBrowser"];
 export type ModelVerb = (typeof PUBLIC_MODEL_VERBS)[number];
 export type ListOptionKey = (typeof PUBLIC_LIST_OPTION_KEYS)[number];
 export type AbloOptionKey = (typeof PUBLIC_ABLO_OPTION_KEYS)[number];

package/dist/surface.js

@@ -56,7 +56,6 @@ export const PUBLIC_ABLO_OPTION_KEYS = [
     'schema',
     'apiKey',
     'authEndpoint',
-    'databaseUrl',
     'persistence',
     'durableWrites',
     'commitOutbox',

package/dist/sync/BootstrapFetcher.js

@@ -42,6 +42,13 @@ export class BootstrapFetcher {
         const clientHash = getContext().config.expectedSchemaHash;
         if (!clientHash || clientHash === serverHash)
             return;
+        // A projection (`selectModels`/`omitModels`) hashes its subset, which never
+        // equals the full schema a server runs — so it also carries the source
+        // schema's hash. Matching that means the client is a faithful subset of the
+        // deployed schema: current, not drifted. Only warn when neither matches.
+        const sourceHash = getContext().config.expectedSourceSchemaHash;
+        if (sourceHash && sourceHash === serverHash)
+            return;
         this.schemaDriftWarned = true;
         const org = this.options.organizationId;
         const where = org ? `${this.baseUrl} (org ${org})` : this.baseUrl;

package/dist/sync/SyncWebSocket.d.ts

@@ -10,7 +10,7 @@ import { EventEmitter } from 'events';
 import type { MutationOperation } from '../interfaces/index.js';
 import { type ClientSyncDelta } from '../wire/delta.js';
 import type { BootstrapReason } from '../wire/bootstrapReason.js';
-import type { ClaimError, ClaimRejection, StaleNotification, ReadDependency } from '../coordination/schema.js';
+import type { ClaimRejection, StaleNotification, ReadDependency, WireClaim } from '../coordination/schema.js';
 import { type CommitAck } from './commitFrames.js';
 export type { CommitAck } from './commitFrames.js';
 import { type AuthTokenGetter } from '../auth/credentialSource.js';
@@ -153,32 +153,10 @@ export interface PresenceUpdateEvent {
     participantKind?: string;
     timestamp?: number;
     /** Every presence frame carries this participant's open claims, stamped by
-     *  the server, so peers see them without a separate channel. */
-    activeClaims?: {
-        claimId: string;
-        entityType: string;
-        entityId: string;
-        path?: string;
-        range?: {
-            startLine: number;
-            endLine: number;
-            startColumn?: number;
-            endColumn?: number;
-        };
-        reason: string;
-        field?: string;
-        meta?: Record<string, unknown>;
-        declaredAt: number;
-        expiresAt: number;
-        /**
-         * The claim's lifecycle state. When absent, the reader treats it as
-         * `'active'`. A terminal state (`committed`, `expired`, or `canceled`) rides
-         * one final frame as the claim ends, so peers learn how it resolved before
-         * it drops from the active set.
-         */
-        status?: 'active' | 'committed' | 'expired' | 'canceled';
-        error?: ClaimError;
-    }[];
+     *  the server, so peers see them without a separate channel. The claim shape
+     *  is the canonical {@link WireClaim} — one declaration in
+     *  `coordination/schema.ts`, not a hand-kept copy. */
+    activeClaims?: WireClaim[];
     localTime?: string;
     type?: string;
     timezone?: string;

package/dist/sync/awaitClaimGrant.d.ts

@@ -28,6 +28,12 @@ export interface ClaimGrantInfo {
      * The grant frame itself is the authoritative signal.
      */
     readonly waited: boolean;
+    /**
+     * The fencing token the server minted for this grant (Option B), read off the
+     * grant frame — the authoritative source, since the token is server-stamped.
+     * `undefined` when the server does not fence (no minter wired).
+     */
+    readonly fenceToken?: number;
 }
 export declare function awaitClaimGrant(transport: GrantTransport, claimId: string, options?: {
     timeoutMs?: number;

package/dist/sync/awaitClaimGrant.js

@@ -14,6 +14,10 @@
  */
 import { AbloClaimedError, formatClaimedErrorMessage, claimTargetLabel, } from '../errors.js';
 import { getContext } from '../context.js';
+/** Read the server-stamped fencing token off a grant frame, if present. */
+function readFenceToken(p) {
+    return typeof p.fenceToken === 'number' ? p.fenceToken : undefined;
+}
 export function awaitClaimGrant(transport, claimId, options) {
     return new Promise((resolve, reject) => {
         const unsubs = [];
@@ -31,7 +35,10 @@ export function awaitClaimGrant(transport, claimId, options) {
         unsubs.push(transport.subscribe('claim_acquired', (p) => {
             if (p?.claimId === claimId) {
                 getContext().logger.debug(`claim: acquired ${claimId} (target was free)`);
-                settle(() => { resolve({ waited: false }); });
+                const fenceToken = readFenceToken(p);
+                settle(() => {
+                    resolve({ waited: false, ...(fenceToken !== undefined ? { fenceToken } : {}) });
+                });
             }
         }));
         unsubs.push(transport.subscribe('claim_granted', (p) => {
@@ -39,7 +46,10 @@ export function awaitClaimGrant(transport, claimId, options) {
                 // Promoted to the head of the line — the creator's "it's the agent's
                 // turn now" moment after waiting behind a holder.
                 getContext().logger.info(`claim: granted ${claimId} — your turn (waited in queue)`);
-                settle(() => { resolve({ waited: true }); });
+                const fenceToken = readFenceToken(p);
+                settle(() => {
+                    resolve({ waited: true, ...(fenceToken !== undefined ? { fenceToken } : {}) });
+                });
             }
         }));
         if (options?.maxQueueDepth !== undefined) {

package/dist/sync/commitFrames.d.ts

@@ -5,6 +5,7 @@
  * dispatch can share them.
  */
 import type { CommitMessage } from '../wire/index.js';
+import type { CommitAck as CanonicalCommitAck } from '../wire/commit.js';
 import type { MutationOperation, ClaimEvent } from '../interfaces/index.js';
 import type { StaleNotification, ReadDependency } from '../coordination/schema.js';
 /**
@@ -13,10 +14,7 @@ import type { StaleNotification, ReadDependency } from '../coordination/schema.j
  * carries the advisory signal that lets the writer self-heal, and the same
  * signal also arrives on the `conflict:notified` event.
  */
-export interface CommitAck {
-    lastSyncId: number;
-    notifications?: StaleNotification[];
-}
+export type CommitAck = CanonicalCommitAck;
 /**
  * Converts the client's list of {@link MutationOperation} values into the wire
  * {@link CommitMessage} the server accepts. This is the one place the loosely

package/dist/sync/commitFrames.js

@@ -26,6 +26,7 @@ export function buildCommitFrame(operations, clientTxId, causedByTaskId, reads)
             transactionId: op.transactionId,
             readAt: op.readAt,
             onStale: op.onStale,
+            fenceToken: op.fenceToken,
         })),
         clientTxId,
     };

package/dist/sync/createClaimStream.d.ts

@@ -13,7 +13,7 @@
  *
  * Wire frames:
  *   • Outbound `claim_begin` — announce a claim: `{ claimId, entityType,
- *       entityId, reason, field?, estimatedMs? }`.
+ *       entityId, description, field?, estimatedMs? }`.
  *   • Outbound `claim_abandon` — release it: `{ claimId, entityType?,
  *       entityId? }`.
  *   • Inbound, via presence — `event.activeClaims`, each stamped with

package/dist/sync/createClaimStream.js

@@ -13,7 +13,7 @@
  *
  * Wire frames:
  *   • Outbound `claim_begin` — announce a claim: `{ claimId, entityType,
- *       entityId, reason, field?, estimatedMs? }`.
+ *       entityId, description, field?, estimatedMs? }`.
  *   • Outbound `claim_abandon` — release it: `{ claimId, entityType?,
  *       entityId? }`.
  *   • Inbound, via presence — `event.activeClaims`, each stamped with
@@ -120,7 +120,11 @@ export function createClaimStream(config, transport = null) {
                 // `settled()`. Absent status means active (wire back-compat).
                 if (claim.status && claim.status !== 'active')
                     continue;
-                const description = descriptionFromMeta(claim.meta);
+                // Resolve the always-present public field, tolerating a frame that
+                // carries the value in `meta` rather than as an explicit description.
+                const description = claim.description ??
+                    descriptionFromMeta(claim.meta) ??
+                    'editing';
                 activeByClaimId.set(claim.claimId, {
                     object: 'claim',
                     id: claim.claimId,
@@ -135,8 +139,7 @@ export function createClaimStream(config, transport = null) {
                         field: claim.field,
                         meta: claim.meta,
                     },
-                    reason: claim.reason,
-                    ...(description ? { description } : {}),
+                    description,
                     ttlSeconds: Math.max(0, Math.floor((claim.expiresAt - Date.now()) / 1000)),
                     createdAt: claim.declaredAt,
                     expiresAt: claim.expiresAt,
@@ -267,7 +270,7 @@ export function createClaimStream(config, transport = null) {
                 entityId: claim.entityId,
                 path: claim.path,
                 range: claim.range,
-                reason: claim.reason,
+                description: claim.description,
                 field: claim.field,
                 meta: claim.meta,
                 estimatedMs: claim.estimatedMs,
@@ -337,11 +340,6 @@ export function createClaimStream(config, transport = null) {
             },
         });
     }
-    function withDescription(meta, description) {
-        if (!description)
-            return meta;
-        return { ...(meta ?? {}), description };
-    }
     function mintHandle(args) {
         const claimId = crypto.randomUUID();
         const estimatedMs = args.ttl !== undefined ? toMs(args.ttl) : undefined;
@@ -352,14 +350,14 @@ export function createClaimStream(config, transport = null) {
             range: args.range,
             field: args.field,
             meta: args.meta,
-            reason: args.reason,
+            description: args.description,
             estimatedMs,
             queue: args.queue,
         };
         ownClaims.set(claimId, claim);
         sendBegin(claimId, claim);
         // Coordination trace (info): the creator can see their human/agent claims.
-        getContext().logger.info(`claim: requesting ${claimLabel(claim.entityType, claim.entityId, claim.field)} for "${claim.reason}"` +
+        getContext().logger.info(`claim: requesting ${claimLabel(claim.entityType, claim.entityId, claim.field)} for "${claim.description}"` +
             (claim.queue ? ' (will queue if contended)' : ''), { claimId });
         let revoked = false;
         const revoke = () => {
@@ -374,7 +372,7 @@ export function createClaimStream(config, transport = null) {
             object: 'claim',
             id: claimId,
             status: 'active',
-            reason: args.reason,
+            description: args.description,
             target: {
                 type: args.entityType,
                 id: args.entityId,
@@ -407,8 +405,8 @@ export function createClaimStream(config, transport = null) {
                 path: resolved.path,
                 range: resolved.range,
                 field: resolved.field,
-                meta: withDescription(resolved.meta, opts?.description),
-                reason: opts?.reason ?? 'editing',
+                meta: resolved.meta,
+                description: opts?.description ?? 'editing',
                 ttl: opts?.ttl,
                 queue: opts?.queue,
             });

package/dist/sync/deltaPipeline.d.ts

@@ -41,7 +41,7 @@ export interface DeltaPipelineContext {
     readonly highestProcessedSyncId: number;
     /** Resume/ack cursor (`syncClient.position.persisted`). */
     readonly lastAckedId: number;
-    onDeltaReceived(syncId: number): void;
+    onDeltaReceived(syncId: number, transactionId?: string, correlationId?: string): void;
     advanceApplied(syncId: number): void;
     advancePersisted(syncId: number): void;
     processDeltaBatch(deltas: {

package/dist/sync/deltaPipeline.js

@@ -125,7 +125,7 @@ export function enqueueDelta(ctx, delta, options = {}) {
         return false;
     }
     // Confirm awaiting transactions via sync ID threshold (before batching)
-    ctx.onDeltaReceived(delta.id);
+    ctx.onDeltaReceived(delta.id, delta.transactionId, delta.correlationId);
     // Queue during active bootstrap
     if (ctx.bootstrapDeltaQueue !== null) {
         ctx.bootstrapDeltaQueue.push(delta);

package/dist/sync/participants.d.ts

@@ -61,9 +61,8 @@ export interface ScopedPresence {
 export interface ScopedClaimOptions {
     /** Override the participant's focus target for this one claim. */
     readonly target?: PresenceTarget;
-    /** Free-form reason. Defaults to `'editing'`. Common: `'editing'`,
-     *  `'writing'`, `'reviewing'`, app-specific phases. */
-    readonly reason?: string;
+    /** Peer-visible description of the work. Defaults to `'editing'`. */
+    readonly description?: string;
     /** How long the claim lives; the server expires it automatically after this. */
     readonly ttl?: import('../types/streams.js').Duration;
 }

package/dist/sync/participants.js

@@ -221,7 +221,7 @@ function createJoinedParticipant(args) {
         return {
             object: 'claim',
             id: handle.id,
-            reason: handle.reason,
+            description: handle.description,
             target: handle.target,
             async release() {
                 ownHandles.delete(handle);
@@ -246,7 +246,7 @@ function createJoinedParticipant(args) {
         },
         claim(opts) {
             return track(args.claims.claim(requireTarget(opts?.target), {
-                reason: opts?.reason,
+                description: opts?.description,
                 ttl: opts?.ttl,
             }));
         },

package/dist/sync/wsFrameHandlers.js

@@ -7,7 +7,8 @@
  * point; every parsed frame then passes through {@link dispatchWsFrame}.
  */
 import { getContext } from '../context.js';
-import { CapabilityError, errorFromWire, } from '../errors.js';
+import { AbloConnectionError, CapabilityError, errorFromWire, } from '../errors.js';
+import { commitAckSchema, legacyCompatibleCommitReceiptSchema, } from '../wire/commit.js';
 import { subscriptionAckPayloadSchema } from '../coordination/schema.js';
 import { formatConflict } from '../coordination/trace.js';
 import { parseNotifications, recordClaim } from './commitFrames.js';
@@ -35,10 +36,15 @@ export function isWsInboundFrame(value) {
  */
 const handleMutationResult = (session, message) => {
     const p = (message.payload ?? message);
-    const { clientTxId, success, lastSyncId, error } = p ?? {};
+    const { clientTxId, success, error } = p;
     // Defensive: validate notifications against the canonical schema —
     // untrusted wire data from a possibly-older/newer server.
     const notifications = parseNotifications(p?.notifications);
+    const missingIds = Array.isArray(p.missingIds)
+        ? [
+            ...new Set(p.missingIds.filter((id) => typeof id === 'string' && id.length > 0)),
+        ]
+        : undefined;
     const pending = typeof clientTxId === 'string'
         ? session.pendingMutations.get(clientTxId)
         : undefined;
@@ -48,21 +54,28 @@ const handleMutationResult = (session, message) => {
     // `pending` exists ⇒ clientTxId was a string key (the guard above).
     session.pendingMutations.delete(clientTxId);
     if (success) {
-        // Coerce defensively — bigint columns serialize as strings
-        // from older servers (see normalizeWireDelta).
-        const ackedSyncId = Number(lastSyncId);
+        const parsedReceipt = legacyCompatibleCommitReceiptSchema.safeParse({
+            ...p,
+            notifications,
+            missingIds,
+        });
+        if (!parsedReceipt.success) {
+            pending.reject(new AbloConnectionError('The sync server returned an invalid commit receipt; its outcome remains pending and is safe to retry.', { code: 'commit_no_result', cause: parsedReceipt.error }));
+            return;
+        }
+        const receipt = parsedReceipt.data;
         // The write succeeded, but a guarded premise shifted underneath it.
         // Emit the advisory signal so a caller can react, and still resolve
         // the receipt, since the commit itself went through.
-        if (notifications && notifications.length > 0) {
-            const txId = typeof clientTxId === 'string' ? clientTxId : '';
+        if (receipt.notifications && receipt.notifications.length > 0) {
+            const txId = receipt.clientTxId;
             const event = {
                 clientTxId: txId,
-                rows: notifications.map((n) => ({
+                rows: receipt.notifications.map((n) => ({
                     model: n.model,
                     id: n.id,
                     fields: n.conflictingFields,
-                    writtenBy: n.writtenBy?.kind,
+                    writtenBy: n.writtenBy.kind,
                 })),
             };
             const message = formatConflict(event);
@@ -72,15 +85,22 @@ const handleMutationResult = (session, message) => {
             ctx.observability.captureConflict(event);
             session.emit('conflict:notified', {
                 clientTxId: txId,
-                notifications,
+                notifications: receipt.notifications,
             });
         }
-        pending.resolve({
-            lastSyncId: Number.isFinite(ackedSyncId) ? ackedSyncId : 0,
-            ...(notifications && notifications.length > 0
-                ? { notifications }
+        pending.resolve(commitAckSchema.parse({
+            status: receipt.status,
+            ...(receipt.correlationId
+                ? { correlationId: receipt.correlationId }
                 : {}),
-        });
+            lastSyncId: receipt.lastSyncId,
+            ...(receipt.notifications && receipt.notifications.length > 0
+                ? { notifications: receipt.notifications }
+                : {}),
+            ...(receipt.missingIds && receipt.missingIds.length > 0
+                ? { missingIds: receipt.missingIds }
+                : {}),
+        }));
     }
     else {
         // Capture the full server error so the caller can see what actually