@korajs/server 1.0.0-beta.6 → 1.0.0-beta.9

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { Operation, HybridLogicalClock, SchemaDefinition, BlobRef, KoraEventEmitter, VersionVector, TimeSource } from '@korajs/core';
+import { Operation, HybridLogicalClock, SchemaDefinition, BlobRef, KoraEventEmitter, OperationTransform, VersionVector, TimeSource } from '@korajs/core';
 import * as _korajs_sync from '@korajs/sync';
 import { SyncStore, ApplyResult, MessageSerializer, SyncMessage, AwarenessUpdateMessage, YjsDocUpdateMessage, BlobChunkRequestMessage, BlobChunkResponseMessage } from '@korajs/sync';
 import { S as ServerTransport, a as ServerMessageHandler, b as ServerCloseHandler, c as ServerErrorHandler } from './server-transport-CU1BLWgr.cjs';
@@ -449,6 +449,7 @@ declare class KoraSyncServer {
     private readonly batchSize;
     private readonly schemaVersion;
     private readonly supportedSchemaVersions;
+    private readonly operationTransforms;
     private readonly port;
     private readonly host;
     private readonly path;
@@ -808,7 +809,10 @@ interface KoraSyncServerConfig {
     maxConnections?: number;
     /** Maximum operations per sync batch. Defaults to 100. */
     batchSize?: number;
-    /** Schema version the server expects. Defaults to 1. */
+    /**
+     * Schema version the server expects. Defaults to `store.getSchema()?.version`
+     * when the store has been configured with a schema, otherwise `1`.
+     */
     schemaVersion?: number;
     /**
      * Inclusive range of client schema versions accepted at handshake.
@@ -818,6 +822,13 @@ interface KoraSyncServerConfig {
         min: number;
         max: number;
     };
+    /**
+     * Transform accepted legacy client operations into the server schema version
+     * before validation and materialization. Required when
+     * `supportedSchemaVersions.min` is lower than `schemaVersion` and operation
+     * shapes changed across versions.
+     */
+    operationTransforms?: OperationTransform[];
     /** WebSocket path (standalone mode). Defaults to '/'. */
     path?: string;
     /** Structured logger. Defaults to pretty-print in dev, JSON lines in production. */
@@ -1062,6 +1073,8 @@ interface ClientSessionOptions {
         min: number;
         max: number;
     };
+    /** Transform accepted legacy operations into the server schema before validation. */
+    operationTransforms?: OperationTransform[];
     /** Called when this session has operations to relay to other sessions */
     onRelay?: RelayCallback;
     /** Called when this session receives an awareness update to broadcast */
@@ -1139,6 +1152,13 @@ declare class ClientSession {
      * client's reported watermark at handshake.
      */
     private lastAckedDeliverySeq;
+    /**
+     * Timestamp of the last delivery-stream send attempt. Periodic retransmission uses
+     * this as its stale window so a slow client does not receive duplicate full-stream
+     * batches every server tick while the first batch is still being applied.
+     */
+    private lastDeliveryPushAttemptAtMs;
+    private deliveryStallRepeatCount;
     /** Serializes incremental delivery pushes so their batches never interleave. */
     private deliveryPushChain;
     /**
@@ -1161,6 +1181,7 @@ declare class ClientSession {
     private readonly batchSize;
     private readonly schemaVersion;
     private readonly supportedSchemaVersions;
+    private readonly operationTransforms;
     private readonly onRelay;
     private readonly onAwarenessUpdate;
     private readonly onYjsDocUpdate;
@@ -1234,6 +1255,7 @@ declare class ClientSession {
     private handleMessageFailure;
     private handleHandshake;
     private handleOperationBatch;
+    private transformForServerSchema;
     private sendDelta;
     /**
      * Send the gap-free server->client delivery stream, resuming just after

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Operation, HybridLogicalClock, SchemaDefinition, BlobRef, KoraEventEmitter, VersionVector, TimeSource } from '@korajs/core';
+import { Operation, HybridLogicalClock, SchemaDefinition, BlobRef, KoraEventEmitter, OperationTransform, VersionVector, TimeSource } from '@korajs/core';
 import * as _korajs_sync from '@korajs/sync';
 import { SyncStore, ApplyResult, MessageSerializer, SyncMessage, AwarenessUpdateMessage, YjsDocUpdateMessage, BlobChunkRequestMessage, BlobChunkResponseMessage } from '@korajs/sync';
 import { S as ServerTransport, a as ServerMessageHandler, b as ServerCloseHandler, c as ServerErrorHandler } from './server-transport-CU1BLWgr.js';
@@ -449,6 +449,7 @@ declare class KoraSyncServer {
     private readonly batchSize;
     private readonly schemaVersion;
     private readonly supportedSchemaVersions;
+    private readonly operationTransforms;
     private readonly port;
     private readonly host;
     private readonly path;
@@ -808,7 +809,10 @@ interface KoraSyncServerConfig {
     maxConnections?: number;
     /** Maximum operations per sync batch. Defaults to 100. */
     batchSize?: number;
-    /** Schema version the server expects. Defaults to 1. */
+    /**
+     * Schema version the server expects. Defaults to `store.getSchema()?.version`
+     * when the store has been configured with a schema, otherwise `1`.
+     */
     schemaVersion?: number;
     /**
      * Inclusive range of client schema versions accepted at handshake.
@@ -818,6 +822,13 @@ interface KoraSyncServerConfig {
         min: number;
         max: number;
     };
+    /**
+     * Transform accepted legacy client operations into the server schema version
+     * before validation and materialization. Required when
+     * `supportedSchemaVersions.min` is lower than `schemaVersion` and operation
+     * shapes changed across versions.
+     */
+    operationTransforms?: OperationTransform[];
     /** WebSocket path (standalone mode). Defaults to '/'. */
     path?: string;
     /** Structured logger. Defaults to pretty-print in dev, JSON lines in production. */
@@ -1062,6 +1073,8 @@ interface ClientSessionOptions {
         min: number;
         max: number;
     };
+    /** Transform accepted legacy operations into the server schema before validation. */
+    operationTransforms?: OperationTransform[];
     /** Called when this session has operations to relay to other sessions */
     onRelay?: RelayCallback;
     /** Called when this session receives an awareness update to broadcast */
@@ -1139,6 +1152,13 @@ declare class ClientSession {
      * client's reported watermark at handshake.
      */
     private lastAckedDeliverySeq;
+    /**
+     * Timestamp of the last delivery-stream send attempt. Periodic retransmission uses
+     * this as its stale window so a slow client does not receive duplicate full-stream
+     * batches every server tick while the first batch is still being applied.
+     */
+    private lastDeliveryPushAttemptAtMs;
+    private deliveryStallRepeatCount;
     /** Serializes incremental delivery pushes so their batches never interleave. */
     private deliveryPushChain;
     /**
@@ -1161,6 +1181,7 @@ declare class ClientSession {
     private readonly batchSize;
     private readonly schemaVersion;
     private readonly supportedSchemaVersions;
+    private readonly operationTransforms;
     private readonly onRelay;
     private readonly onAwarenessUpdate;
     private readonly onYjsDocUpdate;
@@ -1234,6 +1255,7 @@ declare class ClientSession {
     private handleMessageFailure;
     private handleHandshake;
     private handleOperationBatch;
+    private transformForServerSchema;
     private sendDelta;
     /**
      * Send the gap-free server->client delivery stream, resuming just after

package/dist/index.js

@@ -2190,6 +2190,7 @@ var WsServerTransport = class {
 };
 
 // src/session/client-session.ts
+import { applyOperationTransforms } from "@korajs/core";
 import { generateUUIDv7 as generateUUIDv74, hashBlob } from "@korajs/core";
 import { topologicalSort } from "@korajs/core/internal";
 import { decodeBlobChunkBytes } from "@korajs/sync";
@@ -2323,6 +2324,18 @@ function nextServerSequenceNumber(store) {
 async function applyServerOperation(store, op, relationLookup) {
   const schema = store.getSchema();
   const lookup = relationLookup ?? (schema ? buildMergeRelationLookup(schema) : /* @__PURE__ */ new Map());
+  const shapeCheck = validateOperationShape(op, schema);
+  if (!shapeCheck.valid) {
+    return {
+      result: "skipped",
+      appliedOperations: [],
+      rejection: {
+        code: shapeCheck.code ?? "SCHEMA_VALIDATION_ERROR",
+        message: shapeCheck.message ?? `Operation "${op.id}" does not match the server schema`,
+        retriable: false
+      }
+    };
+  }
   const constraintCheck = await validateIncomingOperationConstraints(store, op, schema);
   if (!constraintCheck.valid) {
     const code = constraintCheck.code ?? "CONSTRAINT_VIOLATION";
@@ -2376,6 +2389,67 @@ async function applyServerOperation(store, op, relationLookup) {
     appliedOperations: result === "applied" ? [op] : []
   };
 }
+function validateOperationShape(op, schema) {
+  if (!schema) {
+    return { valid: true };
+  }
+  const collection = schema.collections[op.collection];
+  if (!collection) {
+    return {
+      valid: false,
+      code: "UNKNOWN_COLLECTION",
+      message: `Operation "${op.id}" targets unknown collection "${op.collection}".`
+    };
+  }
+  const declaredFields = new Set(Object.keys(collection.fields));
+  const systemPreviousFields = /* @__PURE__ */ new Set(["id", "_created_at", "_updated_at", "_deleted"]);
+  const invalidDataField = firstInvalidField(op.data, declaredFields);
+  if (invalidDataField) {
+    return {
+      valid: false,
+      code: "SCHEMA_VALIDATION_ERROR",
+      message: `Operation "${op.id}" contains undeclared field "${invalidDataField}" in data for collection "${op.collection}".`
+    };
+  }
+  const invalidPreviousField = firstInvalidField(
+    op.previousData,
+    declaredFields,
+    systemPreviousFields
+  );
+  if (invalidPreviousField) {
+    return {
+      valid: false,
+      code: "SCHEMA_VALIDATION_ERROR",
+      message: `Operation "${op.id}" contains undeclared field "${invalidPreviousField}" in previousData for collection "${op.collection}".`
+    };
+  }
+  if (op.atomicOps) {
+    for (const field of Object.keys(op.atomicOps)) {
+      if (!declaredFields.has(field)) {
+        return {
+          valid: false,
+          code: "SCHEMA_VALIDATION_ERROR",
+          message: `Operation "${op.id}" contains undeclared atomic field "${field}" for collection "${op.collection}".`
+        };
+      }
+    }
+  }
+  return { valid: true };
+}
+function firstInvalidField(value, declaredFields, extraAllowedFields) {
+  if (value === null || value === void 0) {
+    return null;
+  }
+  if (typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  for (const field of Object.keys(value)) {
+    if (!declaredFields.has(field) && !extraAllowedFields?.has(field)) {
+      return field;
+    }
+  }
+  return null;
+}
 
 // src/auth/no-auth.ts
 var NoAuthProvider = class {
@@ -2424,6 +2498,7 @@ function operationMatchesScopes(op, scopes, fullRecord) {
   if (!scopes) return true;
   const collectionScope = scopes[op.collection];
   if (!collectionScope) return false;
+  if (Object.keys(collectionScope).length === 0) return true;
   const snapshot = buildSnapshot(op, fullRecord);
   if (!snapshot) return false;
   for (const [field, expected] of Object.entries(collectionScope)) {
@@ -2437,6 +2512,7 @@ function missingScopeFields(op, scopes) {
   if (!scopes) return [];
   const collectionScope = scopes[op.collection];
   if (!collectionScope) return [];
+  if (Object.keys(collectionScope).length === 0) return [];
   const snapshot = buildSnapshot(op);
   return Object.keys(collectionScope).filter((field) => !snapshot || !(field in snapshot));
 }
@@ -2536,6 +2612,20 @@ function warnIfMultiTenantWithoutScopes(auth, resolvedScopes, schema) {
     "[kora] An authenticated session resolved to no sync scopes, so every user will sync every other user's data. Return per-user sync scopes from your auth provider (for example KoraAuthProvider's resolveScopes) to isolate tenants. Note: declaring sync rules in your schema is not enough on its own \u2014 the per-user values come from the auth provider. (This warning is expected for single-tenant apps where all authenticated users are meant to share the same data.)"
   );
 }
+function stableStringify(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+  }
+  if (value && typeof value === "object") {
+    const record = value;
+    const entries = Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`);
+    return `{${entries.join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+function sameScopeMap(a, b) {
+  return stableStringify(a ?? null) === stableStringify(b ?? null);
+}
 var ClientSession = class _ClientSession {
   state = "connected";
   clientNodeId = null;
@@ -2559,6 +2649,13 @@ var ClientSession = class _ClientSession {
    * client's reported watermark at handshake.
    */
   lastAckedDeliverySeq = 0;
+  /**
+   * Timestamp of the last delivery-stream send attempt. Periodic retransmission uses
+   * this as its stale window so a slow client does not receive duplicate full-stream
+   * batches every server tick while the first batch is still being applied.
+   */
+  lastDeliveryPushAttemptAtMs = 0;
+  deliveryStallRepeatCount = 0;
   /** Serializes incremental delivery pushes so their batches never interleave. */
   deliveryPushChain = Promise.resolve();
   /**
@@ -2581,6 +2678,7 @@ var ClientSession = class _ClientSession {
   batchSize;
   schemaVersion;
   supportedSchemaVersions;
+  operationTransforms;
   onRelay;
   onAwarenessUpdate;
   onYjsDocUpdate;
@@ -2610,6 +2708,7 @@ var ClientSession = class _ClientSession {
       min: this.schemaVersion,
       max: this.schemaVersion
     };
+    this.operationTransforms = options.operationTransforms ?? [];
     this.onRelay = options.onRelay ?? null;
     this.onAwarenessUpdate = options.onAwarenessUpdate ?? null;
     this.onYjsDocUpdate = options.onYjsDocUpdate ?? null;
@@ -2659,6 +2758,7 @@ var ClientSession = class _ClientSession {
     this.deliveryPushChain = this.deliveryPushChain.then(async () => {
       if (this.state !== "streaming" || !this.transport.isConnected()) return;
       try {
+        this.lastDeliveryPushAttemptAtMs = Date.now();
         await this.sendDeliveryStream(
           this.lastAckedDeliverySeq,
           false,
@@ -2706,6 +2806,18 @@ var ClientSession = class _ClientSession {
   retransmitPendingRelays(staleMs = 0) {
     if (this.state !== "streaming" || !this.transport.isConnected()) return;
     if (this.clientDeliveryWatermark !== null) {
+      if (staleMs > 0 && Date.now() - this.lastDeliveryPushAttemptAtMs < staleMs) {
+        return;
+      }
+      this.deliveryStallRepeatCount += 1;
+      if (this.deliveryStallRepeatCount >= 3) {
+        this.emitter?.emit({
+          type: "sync:delivery-stalled",
+          sessionId: this.sessionId,
+          watermark: this.lastAckedDeliverySeq,
+          repeatCount: this.deliveryStallRepeatCount
+        });
+      }
       this.pushDeliveryStream();
       return;
     }
@@ -2798,6 +2910,7 @@ var ClientSession = class _ClientSession {
         this.pendingRelays.delete(message.acknowledgedMessageId);
         if (message.deliverySequence !== void 0) {
           this.lastAckedDeliverySeq = Math.max(this.lastAckedDeliverySeq, message.deliverySequence);
+          this.deliveryStallRepeatCount = 0;
         }
         break;
       case "error":
@@ -2888,6 +3001,9 @@ var ClientSession = class _ClientSession {
     }
     this.resumeDeltaCursor = msg.deltaCursor ? decodeDeltaCursor(msg.deltaCursor) : null;
     this.clientDeliveryWatermark = msg.lastDeliverySequence ?? null;
+    if (this.clientDeliveryWatermark !== null && !sameScopeMap(msg.syncScope, this.authContext?.scopes)) {
+      this.clientDeliveryWatermark = 0;
+    }
     const clientUsesWatermark = this.clientDeliveryWatermark !== null;
     let serverMaxDelivery = 0;
     if (clientUsesWatermark) {
@@ -2901,6 +3017,14 @@ var ClientSession = class _ClientSession {
     this.setSerializerWireFormat(selectedWireFormat);
     if (!isClientSchemaVersionSupported(msg.schemaVersion, this.supportedSchemaVersions)) {
       const { min, max } = this.supportedSchemaVersions;
+      this.emitter?.emit({
+        type: "sync:schema-mismatch",
+        clientSchemaVersion: msg.schemaVersion,
+        serverSchemaVersion: this.schemaVersion,
+        supportedMin: min,
+        supportedMax: max,
+        reason: `${SCHEMA_MISMATCH_PREFIX}: client schema version ${msg.schemaVersion} not in supported range [${min}, ${max}]`
+      });
       const response2 = {
         type: "handshake-response",
         messageId: generateUUIDv74(),
@@ -2943,6 +3067,7 @@ var ClientSession = class _ClientSession {
     if (this.clientDeliveryWatermark !== null) {
       this.lastAckedDeliverySeq = this.clientDeliveryWatermark;
       const excludeOwn = this.clientDeliveryWatermark > 0 ? this.clientNodeId ?? void 0 : void 0;
+      this.lastDeliveryPushAttemptAtMs = Date.now();
       await this.sendDeliveryStream(this.clientDeliveryWatermark, true, excludeOwn);
     } else {
       const clientVector = wireToVersionVector(msg.versionVector);
@@ -2959,10 +3084,20 @@ var ClientSession = class _ClientSession {
   async handleOperationBatch(msg) {
     const operations2 = msg.operations.map((s) => this.serializer.decodeOperation(s));
     const applied = [];
-    const rejected = [];
+    let acknowledgedThrough = 0;
+    let canAdvanceAck = true;
     for (const op of operations2) {
+      if (!canAdvanceAck) {
+        continue;
+      }
       if (!await this.operationVisibleToClient(op)) {
-        rejected.push(op);
+        this.sendOperationRejected(
+          op,
+          "SCOPE_VIOLATION",
+          `Operation "${op.id}" in collection "${op.collection}" is outside the client's sync scope. Refresh sync scopes and retry.`,
+          true
+        );
+        canAdvanceAck = false;
         continue;
       }
       if (!isOperationTimestampValid(op)) {
@@ -2971,6 +3106,7 @@ var ClientSession = class _ClientSession {
           `Operation "${op.id}" timestamp is too far in the future`,
           false
         );
+        canAdvanceAck = false;
         continue;
       }
       if (!this.rateLimiter.allow(1)) {
@@ -2979,6 +3115,7 @@ var ClientSession = class _ClientSession {
           `Session exceeded operation rate limit (${String(this.maxOpsPerMinute)} ops/min)`,
           true
         );
+        canAdvanceAck = false;
         continue;
       }
       const sizeCheck = validateOperationSize(op, this.maxOperationBytes);
@@ -2988,53 +3125,73 @@ var ClientSession = class _ClientSession {
           sizeCheck.message ?? `Operation "${op.id}" is too large`,
           false
         );
+        canAdvanceAck = false;
+        continue;
+      }
+      const serverOp = this.transformForServerSchema(op);
+      if (serverOp === null) {
+        this.sendOperationRejected(
+          op,
+          "SCHEMA_TRANSFORM_UNAVAILABLE",
+          `Operation "${op.id}" cannot be transformed from schema v${op.schemaVersion} to server schema v${this.schemaVersion}.`,
+          false
+        );
+        acknowledgedThrough = op.sequenceNumber;
         continue;
       }
       if (this.validateOperation && this.koraContext) {
         let decision;
         try {
-          decision = await this.validateOperation(op, {
+          decision = await this.validateOperation(serverOp, {
             auth: this.authContext,
             kora: this.koraContext
           });
         } catch (error) {
           const message = error instanceof Error ? error.message : "validator error";
-          this.sendOperationRejected(op, "VALIDATION_ERROR", `Validator threw: ${message}`, true);
+          this.sendOperationRejected(
+            serverOp,
+            "VALIDATION_ERROR",
+            `Validator threw: ${message}`,
+            true
+          );
+          canAdvanceAck = false;
           continue;
         }
         if (decision.action === "reject") {
-          this.sendOperationRejected(
-            op,
-            decision.code,
-            decision.message,
-            decision.retriable ?? isRetriableRejection(decision.code)
-          );
+          const retriable = decision.retriable ?? isRetriableRejection(decision.code);
+          this.sendOperationRejected(serverOp, decision.code, decision.message, retriable);
+          if (retriable) {
+            canAdvanceAck = false;
+          } else {
+            acknowledgedThrough = op.sequenceNumber;
+          }
           continue;
         }
         if (decision.action === "ignore") {
+          acknowledgedThrough = op.sequenceNumber;
           continue;
         }
       }
-      const applyResult = await applyServerOperation(this.store, op);
+      const applyResult = await applyServerOperation(this.store, serverOp);
       if (applyResult.rejection) {
-        this.sendError(
+        this.sendOperationRejected(
+          serverOp,
           applyResult.rejection.code,
           applyResult.rejection.message,
           applyResult.rejection.retriable
         );
+        if (applyResult.rejection.retriable) {
+          canAdvanceAck = false;
+        } else {
+          acknowledgedThrough = op.sequenceNumber;
+        }
         continue;
       }
       if (applyResult.result === "applied") {
         applied.push(...applyResult.appliedOperations);
-      }
-    }
-    if (rejected.length > 0) {
-      for (const op of rejected) {
-        this.sendError(
-          "SCOPE_VIOLATION",
-          `Operation "${op.id}" in collection "${op.collection}" is outside the client's sync scope`,
-          false
-        );
+        acknowledgedThrough = op.sequenceNumber;
+      } else {
+        acknowledgedThrough = op.sequenceNumber;
       }
     }
     if (operations2.length > 0) {
@@ -3049,13 +3206,19 @@ var ClientSession = class _ClientSession {
       type: "acknowledgment",
       messageId: generateUUIDv74(),
       acknowledgedMessageId: msg.messageId,
-      lastSequenceNumber: lastOp ? lastOp.sequenceNumber : 0
+      lastSequenceNumber: lastOp ? Math.min(acknowledgedThrough, lastOp.sequenceNumber) : 0
     };
     this.sendToClient(ack);
     if (applied.length > 0) {
       this.onRelay?.(this.sessionId, applied);
     }
   }
+  transformForServerSchema(op) {
+    if (op.schemaVersion === this.schemaVersion) {
+      return op;
+    }
+    return applyOperationTransforms(op, this.schemaVersion, this.operationTransforms);
+  }
   async sendDelta(clientVector) {
     const serverVector = this.store.getVersionVector();
     const missing = [];
@@ -4044,6 +4207,7 @@ var KoraSyncServer = class _KoraSyncServer {
   batchSize;
   schemaVersion;
   supportedSchemaVersions;
+  operationTransforms;
   port;
   host;
   path;
@@ -4081,16 +4245,24 @@ var KoraSyncServer = class _KoraSyncServer {
   static ORPHANED_RELAY_TTL_MS = 5 * 6e4;
   constructor(config) {
     this.store = config.store;
+    const storeSchemaVersion = this.store.getSchema()?.version;
+    if (config.schemaVersion !== void 0 && storeSchemaVersion !== void 0 && config.schemaVersion !== storeSchemaVersion) {
+      throw new SyncError4("Sync schema version does not match the configured store schema.", {
+        syncSchemaVersion: config.schemaVersion,
+        storeSchemaVersion
+      });
+    }
     this.auth = config.auth ?? null;
     this.serializer = config.serializer ?? new JsonMessageSerializer2();
     this.emitter = config.emitter ?? null;
     this.maxConnections = config.maxConnections ?? DEFAULT_MAX_CONNECTIONS;
     this.batchSize = config.batchSize ?? DEFAULT_BATCH_SIZE2;
-    this.schemaVersion = config.schemaVersion ?? DEFAULT_SCHEMA_VERSION2;
+    this.schemaVersion = config.schemaVersion ?? storeSchemaVersion ?? DEFAULT_SCHEMA_VERSION2;
     this.supportedSchemaVersions = config.supportedSchemaVersions ?? {
       min: this.schemaVersion,
       max: this.schemaVersion
     };
+    this.operationTransforms = config.operationTransforms ?? [];
     this.port = config.port;
     this.host = config.host ?? DEFAULT_HOST;
     this.path = config.path ?? DEFAULT_PATH;
@@ -4214,6 +4386,21 @@ var KoraSyncServer = class _KoraSyncServer {
         details: { reason: event.reason }
       });
     });
+    sessionEmitter.on("sync:schema-mismatch", (event) => {
+      this.logger.log({
+        timestamp: Date.now(),
+        level: "warn",
+        event: "session.schema_mismatch",
+        sessionId,
+        details: {
+          clientSchemaVersion: event.clientSchemaVersion,
+          serverSchemaVersion: event.serverSchemaVersion,
+          supportedMin: event.supportedMin,
+          supportedMax: event.supportedMax,
+          reason: event.reason
+        }
+      });
+    });
   }
   /**
    * Get the metrics collector for external access (e.g., HTTP endpoints).
@@ -4416,6 +4603,33 @@ var KoraSyncServer = class _KoraSyncServer {
         sessionId
       });
     });
+    sessionEmitter.on("sync:schema-mismatch", (event) => {
+      this.logger.log({
+        timestamp: Date.now(),
+        level: "warn",
+        event: "session.schema_mismatch",
+        sessionId,
+        details: {
+          clientSchemaVersion: event.clientSchemaVersion,
+          serverSchemaVersion: event.serverSchemaVersion,
+          supportedMin: event.supportedMin,
+          supportedMax: event.supportedMax,
+          reason: event.reason
+        }
+      });
+    });
+    sessionEmitter.on("sync:delivery-stalled", (event) => {
+      this.logger.log({
+        timestamp: Date.now(),
+        level: "warn",
+        event: "session.delivery_stalled",
+        sessionId,
+        details: {
+          watermark: event.watermark,
+          repeatCount: event.repeatCount
+        }
+      });
+    });
     const session = new ClientSession({
       sessionId,
       transport,
@@ -4427,6 +4641,7 @@ var KoraSyncServer = class _KoraSyncServer {
       batchSize: this.batchSize,
       schemaVersion: this.schemaVersion,
       supportedSchemaVersions: this.supportedSchemaVersions,
+      operationTransforms: this.operationTransforms,
       onRelay: (sourceSessionId, operations2) => {
         this.handleRelay(sourceSessionId, operations2);
       },