@korajs/sync 0.3.1 → 0.4.0

package/dist/index.js

@@ -3,6 +3,7 @@ import {
 } from "./chunk-TU345YUC.js";
 
 // src/types.ts
+import { KoraError } from "@korajs/core";
 var SYNC_STATES = [
   "disconnected",
   "connecting",
@@ -12,6 +13,63 @@ var SYNC_STATES = [
   "error"
 ];
 var SYNC_STATUSES = ["connected", "syncing", "synced", "offline", "error"];
+var ScopeViolationError = class extends KoraError {
+  constructor(operationId, collection, scope, message) {
+    super(
+      message ?? `Operation "${operationId}" in collection "${collection}" violates sync scope`,
+      "SCOPE_VIOLATION",
+      { operationId, collection, scope }
+    );
+    this.operationId = operationId;
+    this.collection = collection;
+    this.scope = scope;
+    this.name = "ScopeViolationError";
+  }
+  operationId;
+  collection;
+  scope;
+};
+var InvalidScopeError = class extends KoraError {
+  constructor(message, context) {
+    super(message, "INVALID_SCOPE", context);
+    this.name = "InvalidScopeError";
+  }
+};
+
+// src/scopes/scope-filter.ts
+function operationMatchesScope(op, scopeMap) {
+  if (!scopeMap) return true;
+  const collectionScope = scopeMap[op.collection];
+  if (!collectionScope) return false;
+  if (Object.keys(collectionScope).length === 0) return true;
+  const snapshot = buildSnapshot(op);
+  if (!snapshot) return false;
+  for (const [field, expected] of Object.entries(collectionScope)) {
+    if (snapshot[field] !== expected) {
+      return false;
+    }
+  }
+  return true;
+}
+function filterOperationsByScope(operations, scopeMap) {
+  if (!scopeMap) return operations;
+  return operations.filter((op) => operationMatchesScope(op, scopeMap));
+}
+function buildSnapshot(op) {
+  const previous = asRecord(op.previousData);
+  const next = asRecord(op.data);
+  if (!previous && !next) return null;
+  return {
+    ...previous ?? {},
+    ...next ?? {}
+  };
+}
+function asRecord(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return null;
+  }
+  return value;
+}
 
 // src/protocol/messages.ts
 function isSyncMessage(value) {
@@ -29,6 +87,8 @@ function isSyncMessage(value) {
       return isAcknowledgmentMessage(value);
     case "error":
       return isErrorMessage(value);
+    case "awareness-update":
+      return isAwarenessUpdateMessage(value);
     default:
       return false;
   }
@@ -58,6 +118,11 @@ function isErrorMessage(value) {
   const msg = value;
   return msg.type === "error" && typeof msg.messageId === "string" && typeof msg.code === "string" && typeof msg.message === "string" && typeof msg.retriable === "boolean";
 }
+function isAwarenessUpdateMessage(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const msg = value;
+  return msg.type === "awareness-update" && typeof msg.messageId === "string" && typeof msg.clientId === "number" && typeof msg.states === "object" && msg.states !== null && !Array.isArray(msg.states);
+}
 
 // src/protocol/serializer.ts
 import { SyncError } from "@korajs/core";
@@ -110,7 +175,10 @@ var JsonMessageSerializer = class {
       },
       sequenceNumber: op.sequenceNumber,
       causalDeps: [...op.causalDeps],
-      schemaVersion: op.schemaVersion
+      schemaVersion: op.schemaVersion,
+      ...op.atomicOps !== void 0 ? { atomicOps: op.atomicOps } : {},
+      ...op.transactionId !== void 0 ? { transactionId: op.transactionId } : {},
+      ...op.mutationName !== void 0 ? { mutationName: op.mutationName } : {}
     };
   }
   decodeOperation(serialized) {
@@ -129,7 +197,10 @@ var JsonMessageSerializer = class {
       },
       sequenceNumber: serialized.sequenceNumber,
       causalDeps: [...serialized.causalDeps],
-      schemaVersion: serialized.schemaVersion
+      schemaVersion: serialized.schemaVersion,
+      ...serialized.atomicOps !== void 0 ? { atomicOps: serialized.atomicOps } : {},
+      ...serialized.transactionId !== void 0 ? { transactionId: serialized.transactionId } : {},
+      ...serialized.mutationName !== void 0 ? { mutationName: serialized.mutationName } : {}
     };
   }
 };
@@ -193,7 +264,10 @@ function toProtoEnvelope(message) {
         type: message.type,
         messageId: message.messageId,
         nodeId: message.nodeId,
-        versionVector: Object.entries(message.versionVector).map(([key, value]) => ({ key, value })),
+        versionVector: Object.entries(message.versionVector).map(([key, value]) => ({
+          key,
+          value
+        })),
         schemaVersion: message.schemaVersion,
         authToken: message.authToken,
         supportedWireFormats: message.supportedWireFormats
@@ -203,7 +277,10 @@ function toProtoEnvelope(message) {
         type: message.type,
         messageId: message.messageId,
         nodeId: message.nodeId,
-        versionVector: Object.entries(message.versionVector).map(([key, value]) => ({ key, value })),
+        versionVector: Object.entries(message.versionVector).map(([key, value]) => ({
+          key,
+          value
+        })),
         schemaVersion: message.schemaVersion,
         accepted: message.accepted,
         rejectReason: message.rejectReason,
@@ -232,6 +309,11 @@ function toProtoEnvelope(message) {
         errorMessage: message.message,
         retriable: message.retriable
       };
+    case "awareness-update":
+      return {
+        type: message.type,
+        messageId: message.messageId
+      };
   }
 }
 function fromProtoEnvelope(envelope) {
@@ -241,7 +323,9 @@ function fromProtoEnvelope(envelope) {
         type: "handshake",
         messageId: envelope.messageId,
         nodeId: envelope.nodeId ?? "",
-        versionVector: Object.fromEntries((envelope.versionVector ?? []).map((entry) => [entry.key, entry.value])),
+        versionVector: Object.fromEntries(
+          (envelope.versionVector ?? []).map((entry) => [entry.key, entry.value])
+        ),
         schemaVersion: envelope.schemaVersion ?? 0,
         authToken: envelope.authToken,
         supportedWireFormats: envelope.supportedWireFormats?.filter(
@@ -253,7 +337,9 @@ function fromProtoEnvelope(envelope) {
         type: "handshake-response",
         messageId: envelope.messageId,
         nodeId: envelope.nodeId ?? "",
-        versionVector: Object.fromEntries((envelope.versionVector ?? []).map((entry) => [entry.key, entry.value])),
+        versionVector: Object.fromEntries(
+          (envelope.versionVector ?? []).map((entry) => [entry.key, entry.value])
+        ),
         schemaVersion: envelope.schemaVersion ?? 0,
         accepted: envelope.accepted ?? false,
         rejectReason: envelope.rejectReason,
@@ -289,13 +375,33 @@ function fromProtoEnvelope(envelope) {
   }
 }
 function serializeProtoOperation(operation) {
+  const hasMetadata = operation.transactionId !== void 0 || operation.mutationName !== void 0;
+  let dataJson = "";
+  if (operation.data !== null) {
+    const dataPayload = { ...operation.data };
+    if (operation.atomicOps !== void 0 && Object.keys(operation.atomicOps).length > 0) {
+      dataPayload.__kora_atomic_ops__ = operation.atomicOps;
+    }
+    if (operation.transactionId !== void 0) {
+      dataPayload.__kora_tx_id__ = operation.transactionId;
+    }
+    if (operation.mutationName !== void 0) {
+      dataPayload.__kora_mutation__ = operation.mutationName;
+    }
+    dataJson = JSON.stringify(dataPayload);
+  } else if (hasMetadata) {
+    const meta = {};
+    if (operation.transactionId !== void 0) meta.__kora_tx_id__ = operation.transactionId;
+    if (operation.mutationName !== void 0) meta.__kora_mutation__ = operation.mutationName;
+    dataJson = JSON.stringify(meta);
+  }
   return {
     id: operation.id,
     nodeId: operation.nodeId,
     type: operation.type,
     collection: operation.collection,
     recordId: operation.recordId,
-    dataJson: operation.data === null ? "" : JSON.stringify(operation.data),
+    dataJson,
     previousDataJson: operation.previousData === null ? "" : JSON.stringify(operation.previousData),
     timestamp: {
       wallTime: operation.timestamp.wallTime,
@@ -310,13 +416,31 @@ function serializeProtoOperation(operation) {
   };
 }
 function deserializeProtoOperation(operation) {
+  let data = null;
+  let atomicOps;
+  let transactionId;
+  let mutationName;
+  if (operation.hasData || operation.dataJson.length > 0) {
+    const parsed = JSON.parse(operation.dataJson);
+    if ("__kora_atomic_ops__" in parsed) {
+      atomicOps = parsed.__kora_atomic_ops__;
+    }
+    if ("__kora_tx_id__" in parsed) {
+      transactionId = parsed.__kora_tx_id__;
+    }
+    if ("__kora_mutation__" in parsed) {
+      mutationName = parsed.__kora_mutation__;
+    }
+    const { __kora_atomic_ops__: _a, __kora_tx_id__: _t, __kora_mutation__: _m, ...rest } = parsed;
+    data = operation.hasData && Object.keys(rest).length > 0 ? rest : null;
+  }
   return {
     id: operation.id,
     nodeId: operation.nodeId,
     type: operation.type,
     collection: operation.collection,
     recordId: operation.recordId,
-    data: operation.hasData ? JSON.parse(operation.dataJson) : null,
+    data,
     previousData: operation.hasPreviousData ? JSON.parse(operation.previousDataJson) : null,
     timestamp: {
       wallTime: operation.timestamp.wallTime,
@@ -325,7 +449,10 @@ function deserializeProtoOperation(operation) {
     },
     sequenceNumber: operation.sequenceNumber,
     causalDeps: [...operation.causalDeps],
-    schemaVersion: operation.schemaVersion
+    schemaVersion: operation.schemaVersion,
+    ...atomicOps !== void 0 ? { atomicOps } : {},
+    ...transactionId !== void 0 ? { transactionId } : {},
+    ...mutationName !== void 0 ? { mutationName } : {}
   };
 }
 function decodeTextPayload(data) {
@@ -356,12 +483,14 @@ function encodeEnvelope(envelope) {
     writer.ldelim();
   }
   if (envelope.schemaVersion !== void 0) writer.uint32(40).int32(envelope.schemaVersion);
-  if (envelope.authToken && envelope.authToken.length > 0) writer.uint32(50).string(envelope.authToken);
+  if (envelope.authToken && envelope.authToken.length > 0)
+    writer.uint32(50).string(envelope.authToken);
   for (const format of envelope.supportedWireFormats ?? []) {
     writer.uint32(58).string(format);
   }
   if (envelope.accepted !== void 0) writer.uint32(64).bool(envelope.accepted);
-  if (envelope.rejectReason && envelope.rejectReason.length > 0) writer.uint32(74).string(envelope.rejectReason);
+  if (envelope.rejectReason && envelope.rejectReason.length > 0)
+    writer.uint32(74).string(envelope.rejectReason);
   if (envelope.selectedWireFormat && envelope.selectedWireFormat.length > 0) {
     writer.uint32(82).string(envelope.selectedWireFormat);
   }
@@ -375,8 +504,10 @@ function encodeEnvelope(envelope) {
   if (envelope.acknowledgedMessageId && envelope.acknowledgedMessageId.length > 0) {
     writer.uint32(114).string(envelope.acknowledgedMessageId);
   }
-  if (envelope.lastSequenceNumber !== void 0) writer.uint32(120).int64(envelope.lastSequenceNumber);
-  if (envelope.errorCode && envelope.errorCode.length > 0) writer.uint32(130).string(envelope.errorCode);
+  if (envelope.lastSequenceNumber !== void 0)
+    writer.uint32(120).int64(envelope.lastSequenceNumber);
+  if (envelope.errorCode && envelope.errorCode.length > 0)
+    writer.uint32(130).string(envelope.errorCode);
   if (envelope.errorMessage && envelope.errorMessage.length > 0) {
     writer.uint32(138).string(envelope.errorMessage);
   }
@@ -399,7 +530,10 @@ function decodeEnvelope(bytes) {
         envelope.nodeId = reader.string();
         break;
       case 4:
-        envelope.versionVector = [...envelope.versionVector ?? [], decodeVectorEntry(reader, reader.uint32())];
+        envelope.versionVector = [
+          ...envelope.versionVector ?? [],
+          decodeVectorEntry(reader, reader.uint32())
+        ];
         break;
       case 5:
         envelope.schemaVersion = reader.int32();
@@ -420,7 +554,10 @@ function decodeEnvelope(bytes) {
         envelope.selectedWireFormat = reader.string();
         break;
       case 11:
-        envelope.operations = [...envelope.operations ?? [], decodeProtoOperation(reader, reader.uint32())];
+        envelope.operations = [
+          ...envelope.operations ?? [],
+          decodeProtoOperation(reader, reader.uint32())
+        ];
         break;
       case 12:
         envelope.isFinal = reader.bool();
@@ -1032,6 +1169,653 @@ var ChaosTransport = class {
 import { SyncError as SyncError4 } from "@korajs/core";
 import { topologicalSort as topologicalSort2 } from "@korajs/core/internal";
 
+// src/diagnostics/bandwidth-estimator.ts
+var BandwidthEstimator = class {
+  maxSamples;
+  timeSource;
+  samples = [];
+  /**
+   * @param maxSamples - Maximum number of samples to retain. Defaults to 20.
+   * @param timeSource - Injectable time source for deterministic testing.
+   */
+  constructor(maxSamples = 20, timeSource) {
+    this.maxSamples = maxSamples;
+    this.timeSource = timeSource ?? { now: () => Date.now() };
+  }
+  /**
+   * Record a transfer of `bytes` that took `durationMs` to complete.
+   * Samples with zero or negative duration are ignored to avoid division errors.
+   */
+  recordTransfer(bytes, durationMs) {
+    if (durationMs <= 0 || bytes <= 0) return;
+    this.samples.push({
+      bytes,
+      durationMs,
+      timestamp: this.timeSource.now()
+    });
+    while (this.samples.length > this.maxSamples) {
+      this.samples.shift();
+    }
+  }
+  /**
+   * Estimate current effective bandwidth in bytes per second.
+   *
+   * Uses exponential weighting so recent samples have more influence.
+   * Returns null if fewer than 2 samples exist (not enough data).
+   */
+  estimate() {
+    if (this.samples.length < 2) return null;
+    let weightedSum = 0;
+    let totalWeight = 0;
+    const decayFactor = 0.9;
+    for (let i = this.samples.length - 1; i >= 0; i--) {
+      const sample = this.samples[i];
+      const bytesPerSec = sample.bytes / sample.durationMs * 1e3;
+      const age = this.samples.length - 1 - i;
+      const weight = decayFactor ** age;
+      weightedSum += bytesPerSec * weight;
+      totalWeight += weight;
+    }
+    if (totalWeight === 0) return null;
+    return Math.round(weightedSum / totalWeight);
+  }
+  /**
+   * Reset all recorded samples.
+   */
+  reset() {
+    this.samples.length = 0;
+  }
+  /**
+   * Get the number of samples currently stored.
+   */
+  sampleCount() {
+    return this.samples.length;
+  }
+};
+
+// src/diagnostics/percentile.ts
+var SlidingWindowPercentile = class {
+  samples;
+  maxSize;
+  writeIndex = 0;
+  count = 0;
+  /**
+   * @param maxSize - Maximum number of samples in the sliding window.
+   *                  Older samples are overwritten when the buffer is full.
+   */
+  constructor(maxSize) {
+    if (maxSize < 1) {
+      throw new Error(`SlidingWindowPercentile maxSize must be >= 1, got ${maxSize}`);
+    }
+    this.maxSize = maxSize;
+    this.samples = new Array(maxSize);
+  }
+  /**
+   * Add a sample to the sliding window.
+   * If the window is full, the oldest sample is overwritten.
+   */
+  addSample(value) {
+    this.samples[this.writeIndex] = value;
+    this.writeIndex = (this.writeIndex + 1) % this.maxSize;
+    if (this.count < this.maxSize) {
+      this.count++;
+    }
+  }
+  /**
+   * Compute a percentile value from the current window.
+   *
+   * Uses the nearest-rank method: the percentile value is the smallest
+   * value in the dataset such that at least p% of the data is <= that value.
+   *
+   * @param p - Percentile to compute (0-100). E.g., 50 for median, 95 for p95.
+   * @returns The percentile value, or 0 if no samples have been recorded.
+   */
+  percentile(p) {
+    if (this.count === 0) return 0;
+    const sorted = this.samples.slice(0, this.count).sort((a, b) => a - b);
+    const rank = Math.ceil(p / 100 * sorted.length) - 1;
+    const index = Math.max(0, Math.min(rank, sorted.length - 1));
+    return sorted[index];
+  }
+  /**
+   * Get the most recently added sample, or 0 if no samples exist.
+   */
+  latest() {
+    if (this.count === 0) return 0;
+    const lastIndex = (this.writeIndex - 1 + this.maxSize) % this.maxSize;
+    return this.samples[lastIndex];
+  }
+  /**
+   * Get the number of samples currently in the window.
+   */
+  size() {
+    return this.count;
+  }
+  /**
+   * Reset the sliding window, clearing all samples.
+   */
+  reset() {
+    this.writeIndex = 0;
+    this.count = 0;
+  }
+};
+
+// src/diagnostics/metrics-collector.ts
+var SyncMetricsCollector = class {
+  rttWindow;
+  inboundBandwidth;
+  outboundBandwidth;
+  timeSource;
+  diagnosticsInterval;
+  // Connection
+  connectedAt = null;
+  disconnectedAt = null;
+  reconnectAttempts = 0;
+  // Throughput
+  operationsSent = 0;
+  operationsReceived = 0;
+  bytesSent = 0;
+  bytesReceived = 0;
+  // Queue
+  pendingOperations = 0;
+  outboundQueueSize = 0;
+  // Sync progress
+  lastSyncedAt = null;
+  syncStartTime = null;
+  syncDuration = null;
+  initialSyncComplete = false;
+  initialSyncTotalBatches = 0;
+  initialSyncReceivedBatches = 0;
+  // Errors
+  lastError = null;
+  errorCount = 0;
+  // Status
+  currentStatus = "offline";
+  currentQuality = "offline";
+  // Periodic emission
+  emitter = null;
+  periodicTimer = null;
+  constructor(config) {
+    this.rttWindow = new SlidingWindowPercentile(config?.rttWindowSize ?? 100);
+    this.inboundBandwidth = new BandwidthEstimator(
+      config?.bandwidthWindowSize ?? 20,
+      config?.timeSource
+    );
+    this.outboundBandwidth = new BandwidthEstimator(
+      config?.bandwidthWindowSize ?? 20,
+      config?.timeSource
+    );
+    this.timeSource = config?.timeSource ?? { now: () => Date.now() };
+    this.diagnosticsInterval = config?.diagnosticsInterval ?? 5e3;
+  }
+  /**
+   * Attach an event emitter for periodic diagnostics emission.
+   * Starts emitting `sync:diagnostics` events at the configured interval
+   * while connected.
+   */
+  attachEmitter(emitter) {
+    this.emitter = emitter;
+  }
+  /**
+   * Record that a connection has been established.
+   */
+  recordConnected() {
+    this.connectedAt = this.timeSource.now();
+    this.reconnectAttempts = 0;
+    this.startPeriodicEmission();
+  }
+  /**
+   * Record that the connection has been lost.
+   */
+  recordDisconnected() {
+    this.disconnectedAt = this.timeSource.now();
+    this.stopPeriodicEmission();
+  }
+  /**
+   * Record a reconnection attempt.
+   */
+  recordReconnectAttempt() {
+    this.reconnectAttempts++;
+  }
+  /**
+   * Record a round-trip time measurement.
+   */
+  recordRtt(ms) {
+    this.rttWindow.addSample(ms);
+  }
+  /**
+   * Record operations sent with their serialized byte size.
+   */
+  recordSent(operationCount, byteSize, durationMs) {
+    this.operationsSent += operationCount;
+    this.bytesSent += byteSize;
+    if (durationMs > 0 && byteSize > 0) {
+      this.outboundBandwidth.recordTransfer(byteSize, durationMs);
+      this.emitBandwidthEvent("out");
+    }
+  }
+  /**
+   * Record operations received with their serialized byte size.
+   */
+  recordReceived(operationCount, byteSize, durationMs) {
+    this.operationsReceived += operationCount;
+    this.bytesReceived += byteSize;
+    if (durationMs > 0 && byteSize > 0) {
+      this.inboundBandwidth.recordTransfer(byteSize, durationMs);
+      this.emitBandwidthEvent("in");
+    }
+  }
+  /**
+   * Update the pending operations count and estimated outbound queue size.
+   */
+  updateQueue(pendingOps, estimatedBytes) {
+    this.pendingOperations = pendingOps;
+    this.outboundQueueSize = estimatedBytes;
+  }
+  /**
+   * Record that sync has started (for measuring sync duration).
+   */
+  recordSyncStarted() {
+    this.syncStartTime = this.timeSource.now();
+  }
+  /**
+   * Record that a sync cycle has completed.
+   */
+  recordSyncCompleted() {
+    if (this.syncStartTime !== null) {
+      this.syncDuration = this.timeSource.now() - this.syncStartTime;
+      this.syncStartTime = null;
+    }
+    this.lastSyncedAt = this.timeSource.now();
+    if (!this.initialSyncComplete) {
+      this.initialSyncComplete = true;
+    }
+  }
+  /**
+   * Update initial sync progress.
+   * @param receivedBatches - Number of delta batches received so far.
+   * @param totalBatches - Estimated total batches (0 if unknown).
+   */
+  updateInitialSyncProgress(receivedBatches, totalBatches) {
+    this.initialSyncReceivedBatches = receivedBatches;
+    this.initialSyncTotalBatches = totalBatches;
+    const progress = totalBatches > 0 ? Math.min(1, receivedBatches / totalBatches) : receivedBatches > 0 ? 0.5 : 0;
+    this.emitter?.emit({
+      type: "sync:initial-sync-progress",
+      progress,
+      totalBatches,
+      receivedBatches
+    });
+  }
+  /**
+   * Record an error.
+   */
+  recordError(message) {
+    this.lastError = message;
+    this.errorCount++;
+  }
+  /**
+   * Update the current developer-facing status.
+   */
+  updateStatus(status) {
+    this.currentStatus = status;
+  }
+  /**
+   * Update the connection quality.
+   */
+  updateQuality(quality) {
+    this.currentQuality = quality;
+  }
+  /**
+   * Compute and return a full diagnostics snapshot.
+   */
+  getSnapshot() {
+    return {
+      // Connection
+      status: this.currentStatus,
+      connectedAt: this.connectedAt,
+      disconnectedAt: this.disconnectedAt,
+      reconnectAttempts: this.reconnectAttempts,
+      // Latency
+      rttMs: this.rttWindow.latest(),
+      rttP50Ms: this.rttWindow.percentile(50),
+      rttP95Ms: this.rttWindow.percentile(95),
+      rttP99Ms: this.rttWindow.percentile(99),
+      // Throughput
+      operationsSent: this.operationsSent,
+      operationsReceived: this.operationsReceived,
+      bytesSent: this.bytesSent,
+      bytesReceived: this.bytesReceived,
+      // Queue
+      pendingOperations: this.pendingOperations,
+      outboundQueueSize: this.outboundQueueSize,
+      // Sync Progress
+      lastSyncedAt: this.lastSyncedAt,
+      syncDuration: this.syncDuration,
+      initialSyncComplete: this.initialSyncComplete,
+      initialSyncProgress: this.computeInitialSyncProgress(),
+      // Errors
+      lastError: this.lastError,
+      errorCount: this.errorCount,
+      // Connection Quality
+      quality: this.currentQuality,
+      effectiveBandwidth: this.computeEffectiveBandwidth()
+    };
+  }
+  /**
+   * Assess connection quality from current metrics.
+   *
+   * Quality is derived from RTT percentiles, error rate, and bandwidth:
+   * - excellent: p95 < 100ms, no errors
+   * - good: p95 < 300ms, errorCount <= 1
+   * - fair: p95 < 1000ms, errorCount <= 3
+   * - poor: p95 >= 1000ms or errorCount > 3
+   * - offline: no connection
+   */
+  assessQuality() {
+    if (this.currentStatus === "offline") return "offline";
+    const p95 = this.rttWindow.percentile(95);
+    const hasSamples = this.rttWindow.size() > 0;
+    if (!hasSamples) {
+      if (this.errorCount > 3) return "poor";
+      if (this.errorCount > 0) return "fair";
+      return "good";
+    }
+    if (this.errorCount > 3) return "poor";
+    if (p95 < 100 && this.errorCount === 0) return "excellent";
+    if (p95 < 300 && this.errorCount <= 1) return "good";
+    if (p95 < 1e3 && this.errorCount <= 3) return "fair";
+    return "poor";
+  }
+  /**
+   * Reset all collected metrics. Call when starting a new session.
+   */
+  reset() {
+    this.rttWindow.reset();
+    this.inboundBandwidth.reset();
+    this.outboundBandwidth.reset();
+    this.connectedAt = null;
+    this.disconnectedAt = null;
+    this.reconnectAttempts = 0;
+    this.operationsSent = 0;
+    this.operationsReceived = 0;
+    this.bytesSent = 0;
+    this.bytesReceived = 0;
+    this.pendingOperations = 0;
+    this.outboundQueueSize = 0;
+    this.lastSyncedAt = null;
+    this.syncStartTime = null;
+    this.syncDuration = null;
+    this.initialSyncComplete = false;
+    this.initialSyncTotalBatches = 0;
+    this.initialSyncReceivedBatches = 0;
+    this.lastError = null;
+    this.errorCount = 0;
+    this.currentStatus = "offline";
+    this.currentQuality = "offline";
+    this.stopPeriodicEmission();
+  }
+  /**
+   * Stop periodic emission and clean up resources.
+   */
+  dispose() {
+    this.stopPeriodicEmission();
+    this.emitter = null;
+  }
+  // --- Private helpers ---
+  computeInitialSyncProgress() {
+    if (this.initialSyncComplete) return 1;
+    if (this.initialSyncTotalBatches > 0) {
+      return Math.min(1, this.initialSyncReceivedBatches / this.initialSyncTotalBatches);
+    }
+    return this.initialSyncReceivedBatches > 0 ? 0.5 : 0;
+  }
+  computeEffectiveBandwidth() {
+    const inbound = this.inboundBandwidth.estimate();
+    const outbound = this.outboundBandwidth.estimate();
+    if (inbound === null && outbound === null) return null;
+    if (inbound === null) return outbound;
+    if (outbound === null) return inbound;
+    return Math.min(inbound, outbound);
+  }
+  startPeriodicEmission() {
+    if (this.periodicTimer !== null) return;
+    if (!this.emitter) return;
+    this.periodicTimer = setInterval(() => {
+      this.emitDiagnostics();
+    }, this.diagnosticsInterval);
+  }
+  stopPeriodicEmission() {
+    if (this.periodicTimer !== null) {
+      clearInterval(this.periodicTimer);
+      this.periodicTimer = null;
+    }
+  }
+  emitDiagnostics() {
+    this.emitter?.emit({
+      type: "sync:diagnostics",
+      diagnostics: this.getSnapshot()
+    });
+  }
+  emitBandwidthEvent(direction) {
+    const estimator = direction === "in" ? this.inboundBandwidth : this.outboundBandwidth;
+    const bps = estimator.estimate();
+    if (bps !== null) {
+      this.emitter?.emit({
+        type: "sync:bandwidth",
+        bytesPerSecond: bps,
+        direction
+      });
+    }
+  }
+};
+
+// src/awareness/awareness-manager.ts
+var DEFAULT_TIMEOUT_MS = 3e4;
+var nextLocalClientId = 1;
+var AwarenessManager = class {
+  /** Unique client ID for this instance */
+  clientId;
+  localState = null;
+  remoteStates = /* @__PURE__ */ new Map();
+  listeners = /* @__PURE__ */ new Set();
+  emitter;
+  timeoutMs;
+  // Track when we last received an update from each remote client.
+  // Used for timeout-based cleanup as a safety net in case the server
+  // does not send an explicit removal on disconnect.
+  lastUpdated = /* @__PURE__ */ new Map();
+  cleanupTimer = null;
+  sendHandler = null;
+  destroyed = false;
+  constructor(options) {
+    this.clientId = options?.clientId ?? nextLocalClientId++;
+    this.emitter = options?.emitter ?? null;
+    this.timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  }
+  /**
+   * Set the local user's awareness state and broadcast to peers.
+   *
+   * @param state - The awareness state to share. Pass null to clear presence.
+   */
+  setLocalState(state) {
+    if (this.destroyed) return;
+    this.localState = state;
+    const message = {
+      type: "awareness",
+      clientId: this.clientId,
+      states: { [this.clientId]: state }
+    };
+    this.sendHandler?.(message);
+    this.emitAwarenessEvent();
+  }
+  /**
+   * Get the local awareness state.
+   */
+  getLocalState() {
+    return this.localState;
+  }
+  /**
+   * Get all known awareness states (local + remote).
+   * Returns a new Map on each call.
+   */
+  getStates() {
+    const result = /* @__PURE__ */ new Map();
+    if (this.localState) {
+      result.set(this.clientId, this.localState);
+    }
+    for (const [id, state] of this.remoteStates) {
+      result.set(id, state);
+    }
+    return result;
+  }
+  /**
+   * Handle an incoming awareness message from the transport.
+   * This processes remote state updates and notifies listeners.
+   */
+  handleRemoteMessage(message) {
+    if (this.destroyed) return;
+    const added = [];
+    const updated = [];
+    const removed = [];
+    const now = Date.now();
+    for (const [clientIdStr, state] of Object.entries(message.states)) {
+      const clientId = Number(clientIdStr);
+      if (clientId === this.clientId) continue;
+      if (state === null) {
+        if (this.remoteStates.has(clientId)) {
+          this.remoteStates.delete(clientId);
+          this.lastUpdated.delete(clientId);
+          removed.push(clientId);
+        }
+      } else {
+        if (this.remoteStates.has(clientId)) {
+          this.remoteStates.set(clientId, state);
+          this.lastUpdated.set(clientId, now);
+          updated.push(clientId);
+        } else {
+          this.remoteStates.set(clientId, state);
+          this.lastUpdated.set(clientId, now);
+          added.push(clientId);
+        }
+      }
+    }
+    if (added.length > 0 || updated.length > 0 || removed.length > 0) {
+      const change = { added, updated, removed };
+      this.notifyListeners(change);
+      this.emitAwarenessEvent();
+    }
+  }
+  /**
+   * Remove a specific remote client's awareness state.
+   * Called when the server notifies that a client has disconnected.
+   */
+  removeClient(clientId) {
+    if (this.destroyed) return;
+    if (!this.remoteStates.has(clientId)) return;
+    this.remoteStates.delete(clientId);
+    this.lastUpdated.delete(clientId);
+    const change = {
+      added: [],
+      updated: [],
+      removed: [clientId]
+    };
+    this.notifyListeners(change);
+    this.emitAwarenessEvent();
+  }
+  /**
+   * Register a handler for sending awareness messages through the transport.
+   * The sync engine calls this to wire outgoing awareness messages to the transport.
+   */
+  onSend(handler) {
+    this.sendHandler = handler;
+  }
+  /**
+   * Register a listener for awareness state changes.
+   * Returns an unsubscribe function.
+   */
+  on(_event, listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  /**
+   * Remove a specific change listener.
+   */
+  off(_event, listener) {
+    this.listeners.delete(listener);
+  }
+  /**
+   * Start the cleanup timer that removes stale remote states.
+   * Called when the sync engine transitions to streaming state.
+   */
+  startCleanupTimer() {
+    if (this.cleanupTimer) return;
+    this.cleanupTimer = setInterval(() => {
+      this.cleanupStaleStates();
+    }, this.timeoutMs);
+  }
+  /**
+   * Stop the cleanup timer.
+   */
+  stopCleanupTimer() {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+  }
+  /**
+   * Clean up all resources. After calling destroy(), the manager
+   * will no longer send or receive awareness updates.
+   * Broadcasts removal of local state before shutting down.
+   */
+  destroy() {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    if (this.localState) {
+      const message = {
+        type: "awareness",
+        clientId: this.clientId,
+        states: { [this.clientId]: null }
+      };
+      this.sendHandler?.(message);
+    }
+    this.localState = null;
+    this.remoteStates.clear();
+    this.lastUpdated.clear();
+    this.listeners.clear();
+    this.sendHandler = null;
+    this.stopCleanupTimer();
+  }
+  // --- Private ---
+  cleanupStaleStates() {
+    const now = Date.now();
+    const removed = [];
+    for (const [clientId, lastTime] of this.lastUpdated) {
+      if (now - lastTime > this.timeoutMs) {
+        this.remoteStates.delete(clientId);
+        this.lastUpdated.delete(clientId);
+        removed.push(clientId);
+      }
+    }
+    if (removed.length > 0) {
+      const change = { added: [], updated: [], removed };
+      this.notifyListeners(change);
+      this.emitAwarenessEvent();
+    }
+  }
+  notifyListeners(change) {
+    for (const listener of this.listeners) {
+      listener(change);
+    }
+  }
+  emitAwarenessEvent() {
+    const states = this.getStates();
+    this.emitter?.emit({ type: "awareness:updated", states });
+  }
+};
+
 // src/engine/outbound-queue.ts
 import { topologicalSort } from "@korajs/core/internal";
 var OutboundQueue = class {
@@ -1170,14 +1954,26 @@ var SyncEngine = class {
   emitter;
   outboundQueue;
   batchSize;
+  encryptor;
+  awarenessManager;
+  metricsCollector;
   remoteVector = /* @__PURE__ */ new Map();
   lastSyncedAt = null;
+  lastSuccessfulPush = null;
+  lastSuccessfulPull = null;
+  conflictCount = 0;
   currentBatch = null;
   reconnecting = false;
   // Track delta exchange state
   deltaBatchesReceived = 0;
   deltaReceiveComplete = false;
   deltaSendComplete = false;
+  /**
+   * The effective scope for this sync session.
+   * Starts as the configured scopeMap. After handshake, may be replaced
+   * with the server-accepted scope (server is authoritative).
+   */
+  activeScope;
   constructor(options) {
     this.transport = options.transport;
     this.store = options.store;
@@ -1185,8 +1981,27 @@ var SyncEngine = class {
     this.serializer = options.serializer ?? new NegotiatedMessageSerializer("json");
     this.emitter = options.emitter ?? null;
     this.batchSize = options.config.batchSize ?? DEFAULT_BATCH_SIZE;
+    this.encryptor = options.encryptor ?? null;
+    this.activeScope = options.config.scopeMap;
     const queueStorage = options.queueStorage ?? new MemoryQueueStorage();
     this.outboundQueue = new OutboundQueue(queueStorage);
+    this.metricsCollector = new SyncMetricsCollector(options.metricsConfig);
+    if (this.emitter) {
+      this.metricsCollector.attachEmitter(this.emitter);
+    }
+    this.awarenessManager = new AwarenessManager({
+      emitter: this.emitter ?? void 0
+    });
+    this.awarenessManager.onSend((message) => {
+      if (this.state !== "streaming") return;
+      const wireMessage = {
+        type: "awareness-update",
+        messageId: generateMessageId(),
+        clientId: message.clientId,
+        states: awarenessStatesToWire(message.states)
+      };
+      this.transport.send(wireMessage);
+    });
   }
   /**
    * Start the sync engine: connect → handshake → delta exchange → streaming.
@@ -1214,7 +2029,8 @@ var SyncEngine = class {
         versionVector: versionVectorToWire(localVector),
         schemaVersion: this.config.schemaVersion ?? DEFAULT_SCHEMA_VERSION,
         authToken,
-        supportedWireFormats: ["json", "protobuf"]
+        supportedWireFormats: ["json", "protobuf"],
+        ...this.config.scopeMap ? { syncScope: this.config.scopeMap } : {}
       };
       this.transport.send(handshake);
     } catch (err) {
@@ -1227,6 +2043,7 @@ var SyncEngine = class {
    */
   async stop() {
     if (this.state === "disconnected") return;
+    this.awarenessManager.stopCleanupTimer();
     if (this.currentBatch) {
       this.outboundQueue.returnBatch(this.currentBatch.batchId);
       this.currentBatch = null;
@@ -1245,8 +2062,14 @@ var SyncEngine = class {
   /**
    * Push a local operation to the outbound queue.
    * If streaming, flushes immediately.
+   *
+   * Operations outside the configured sync scope are silently skipped
+   * because they should remain local-only and not be sent to the server.
    */
   async pushOperation(op) {
+    if (!operationMatchesScope(op, this.activeScope)) {
+      return;
+    }
     await this.outboundQueue.enqueue(op);
     if (this.state === "streaming") {
       this.flushQueue();
@@ -1266,27 +2089,64 @@ var SyncEngine = class {
    */
   getStatus() {
     const pendingOperations = this.outboundQueue.totalPending;
+    const base = {
+      pendingOperations,
+      lastSyncedAt: this.lastSyncedAt,
+      lastSuccessfulPush: this.lastSuccessfulPush,
+      lastSuccessfulPull: this.lastSuccessfulPull,
+      conflicts: this.conflictCount
+    };
     switch (this.state) {
       case "disconnected":
-        return { status: "offline", pendingOperations, lastSyncedAt: this.lastSyncedAt };
+        return { ...base, status: "offline" };
       case "connecting":
       case "handshaking":
       case "syncing":
-        return {
-          status: this.reconnecting ? "offline" : "syncing",
-          pendingOperations,
-          lastSyncedAt: this.lastSyncedAt
-        };
+        return { ...base, status: this.reconnecting ? "offline" : "syncing" };
       case "streaming":
-        return {
-          status: pendingOperations > 0 ? "syncing" : "synced",
-          pendingOperations,
-          lastSyncedAt: this.lastSyncedAt
-        };
+        return { ...base, status: pendingOperations > 0 ? "syncing" : "synced" };
       case "error":
-        return { status: "error", pendingOperations, lastSyncedAt: this.lastSyncedAt };
+        return { ...base, status: "error" };
+    }
+  }
+  /**
+   * Record a merge conflict. Called by the merge-aware sync store
+   * to increment the conflict counter for status reporting.
+   */
+  recordConflict() {
+    this.conflictCount++;
+  }
+  /**
+   * Force an immediate reconnection attempt. If the engine is disconnected
+   * or in error state, restarts the sync. If already connected, no-op.
+   */
+  async retryNow() {
+    if (this.state === "disconnected" || this.state === "error") {
+      this.reconnecting = false;
+      await this.start();
     }
   }
+  /**
+   * Export a diagnostics snapshot for debugging and support tickets.
+   * Contains connection state, timing info, and queue metrics.
+   */
+  exportDiagnostics() {
+    return {
+      state: this.state,
+      status: this.getStatus(),
+      nodeId: this.store.getNodeId(),
+      url: this.config.url,
+      schemaVersion: this.config.schemaVersion ?? DEFAULT_SCHEMA_VERSION,
+      lastSyncedAt: this.lastSyncedAt,
+      lastSuccessfulPush: this.lastSuccessfulPush,
+      lastSuccessfulPull: this.lastSuccessfulPull,
+      conflicts: this.conflictCount,
+      pendingOperations: this.outboundQueue.totalPending,
+      hasInFlightBatch: this.currentBatch !== null,
+      reconnecting: this.reconnecting,
+      timestamp: Date.now()
+    };
+  }
   /**
    * Get the current internal state (for testing).
    */
@@ -1299,6 +2159,36 @@ var SyncEngine = class {
   getOutboundQueue() {
     return this.outboundQueue;
   }
+  /**
+   * Update the sync scope map. Takes effect on the next connection attempt.
+   *
+   * When the scope changes (e.g., user switches organization), call this method
+   * then reconnect. The new scope will be sent in the handshake, and the server
+   * will send back data matching the new scope.
+   *
+   * Data that no longer matches the new scope is NOT deleted locally.
+   * It simply stops being synced.
+   *
+   * @param scopeMap - New per-collection scope filters, or undefined to remove scope
+   */
+  updateScope(scopeMap) {
+    this.activeScope = scopeMap;
+    this.config.scopeMap = scopeMap;
+  }
+  /**
+   * Get the currently active scope map. Returns undefined if no scope is configured.
+   */
+  getActiveScope() {
+    return this.activeScope;
+  }
+  /**
+   * Get the awareness manager for collaborative presence.
+   * Use this to set local presence, observe remote collaborators,
+   * and track cursor positions in richtext fields.
+   */
+  getAwarenessManager() {
+    return this.awarenessManager;
+  }
   // --- Private methods ---
   handleMessage(message) {
     switch (message.type) {
@@ -1314,6 +2204,9 @@ var SyncEngine = class {
       case "error":
         this.handleError(message);
         break;
+      case "awareness-update":
+        this.handleAwarenessUpdate(message);
+        break;
     }
   }
   handleHandshakeResponse(msg) {
@@ -1331,7 +2224,13 @@ var SyncEngine = class {
     if (msg.selectedWireFormat) {
       this.setSerializerWireFormat(msg.selectedWireFormat);
     }
+    if (msg.acceptedScope) {
+      this.activeScope = msg.acceptedScope;
+    }
     this.emitter?.emit({ type: "sync:connected", nodeId: this.store.getNodeId() });
+    this.metricsCollector.recordConnected();
+    this.metricsCollector.updateStatus("syncing");
+    this.metricsCollector.recordSyncStarted();
     this.transitionTo("syncing");
     this.deltaBatchesReceived = 0;
     this.deltaReceiveComplete = false;
@@ -1340,7 +2239,8 @@ var SyncEngine = class {
   }
   async sendDelta() {
     const localVector = this.store.getVersionVector();
-    const missingOps = await this.collectDelta(localVector, this.remoteVector);
+    const allMissingOps = await this.collectDelta(localVector, this.remoteVector);
+    const missingOps = allMissingOps.filter((op) => operationMatchesScope(op, this.activeScope));
     if (missingOps.length === 0) {
       const emptyBatch = {
         type: "operation-batch",
@@ -1359,7 +2259,8 @@ var SyncEngine = class {
     for (let i = 0; i < totalBatches; i++) {
       const start = i * this.batchSize;
       const batchOps = sorted.slice(start, start + this.batchSize);
-      const serializedOps = batchOps.map((op) => this.serializer.encodeOperation(op));
+      const opsToSerialize = this.encryptor ? await this.encryptor.encryptBatch(batchOps) : batchOps;
+      const serializedOps = opsToSerialize.map((op) => this.serializer.encodeOperation(op));
       const batchMsg = {
         type: "operation-batch",
         messageId: generateMessageId(),
@@ -1389,15 +2290,18 @@ var SyncEngine = class {
     return missing;
   }
   async handleOperationBatch(msg) {
-    const operations = msg.operations.map((s) => this.serializer.decodeOperation(s));
-    for (const op of operations) {
+    const deserialized = msg.operations.map((s) => this.serializer.decodeOperation(s));
+    const operations = this.encryptor ? await this.encryptor.decryptBatch(deserialized) : deserialized;
+    const inScopeOps = operations.filter((op) => operationMatchesScope(op, this.activeScope));
+    for (const op of inScopeOps) {
       await this.store.applyRemoteOperation(op);
     }
-    if (operations.length > 0) {
+    if (inScopeOps.length > 0) {
+      this.lastSuccessfulPull = Date.now();
       this.emitter?.emit({
         type: "sync:received",
-        operations,
-        batchSize: operations.length
+        operations: inScopeOps,
+        batchSize: inScopeOps.length
       });
     }
     const lastOp = operations[operations.length - 1];
@@ -1424,7 +2328,9 @@ var SyncEngine = class {
     if (this.currentBatch) {
       this.outboundQueue.acknowledge(this.currentBatch.batchId);
       this.currentBatch = null;
-      this.lastSyncedAt = Date.now();
+      const now = Date.now();
+      this.lastSyncedAt = now;
+      this.lastSuccessfulPush = now;
     }
     if (this.state === "streaming" && this.outboundQueue.hasOperations) {
       this.flushQueue();
@@ -1442,6 +2348,11 @@ var SyncEngine = class {
     if (this.deltaSendComplete && this.deltaReceiveComplete) {
       this.lastSyncedAt = Date.now();
       this.transitionTo("streaming");
+      this.awarenessManager.startCleanupTimer();
+      const localState = this.awarenessManager.getLocalState();
+      if (localState) {
+        this.awarenessManager.setLocalState(localState);
+      }
       if (this.outboundQueue.hasOperations) {
         this.flushQueue();
       }
@@ -1453,20 +2364,57 @@ var SyncEngine = class {
     const batch = this.outboundQueue.takeBatch(this.batchSize);
     if (!batch) return;
     this.currentBatch = batch;
-    const serializedOps = batch.operations.map((op) => this.serializer.encodeOperation(op));
-    const batchMsg = {
-      type: "operation-batch",
-      messageId: generateMessageId(),
-      operations: serializedOps,
-      isFinal: true,
-      batchIndex: 0
+    if (this.encryptor) {
+      this.encryptor.encryptBatch(batch.operations).then(
+        (encrypted) => {
+          const serializedOps = encrypted.map((op) => this.serializer.encodeOperation(op));
+          const batchMsg = {
+            type: "operation-batch",
+            messageId: generateMessageId(),
+            operations: serializedOps,
+            isFinal: true,
+            batchIndex: 0
+          };
+          this.transport.send(batchMsg);
+          this.emitter?.emit({
+            type: "sync:sent",
+            operations: batch.operations,
+            batchSize: batch.operations.length
+          });
+        },
+        (err) => {
+          this.outboundQueue.returnBatch(batch.batchId);
+          this.currentBatch = null;
+          this.emitter?.emit({
+            type: "sync:disconnected",
+            reason: err instanceof Error ? err.message : "Encryption failed"
+          });
+        }
+      );
+    } else {
+      const serializedOps = batch.operations.map((op) => this.serializer.encodeOperation(op));
+      const batchMsg = {
+        type: "operation-batch",
+        messageId: generateMessageId(),
+        operations: serializedOps,
+        isFinal: true,
+        batchIndex: 0
+      };
+      this.transport.send(batchMsg);
+      this.emitter?.emit({
+        type: "sync:sent",
+        operations: batch.operations,
+        batchSize: batch.operations.length
+      });
+    }
+  }
+  handleAwarenessUpdate(msg) {
+    const awarenessMessage = {
+      type: "awareness",
+      clientId: msg.clientId,
+      states: wireToAwarenessStates(msg.states)
     };
-    this.transport.send(batchMsg);
-    this.emitter?.emit({
-      type: "sync:sent",
-      operations: batch.operations,
-      batchSize: batch.operations.length
-    });
+    this.awarenessManager.handleRemoteMessage(awarenessMessage);
   }
   handleTransportClose(reason) {
     if (this.currentBatch) {
@@ -1501,6 +2449,40 @@ var SyncEngine = class {
     }
   }
 };
+function awarenessStatesToWire(states) {
+  const wire = {};
+  for (const [clientId, state] of Object.entries(states)) {
+    if (state === null) {
+      wire[clientId] = null;
+    } else {
+      const wireState = {
+        user: { ...state.user }
+      };
+      if (state.cursor) {
+        wireState.cursor = { ...state.cursor };
+      }
+      wire[clientId] = wireState;
+    }
+  }
+  return wire;
+}
+function wireToAwarenessStates(wire) {
+  const states = {};
+  for (const [clientId, wireState] of Object.entries(wire)) {
+    if (wireState === null) {
+      states[Number(clientId)] = null;
+    } else {
+      const state = {
+        user: { ...wireState.user }
+      };
+      if (wireState.cursor) {
+        state.cursor = { ...wireState.cursor };
+      }
+      states[Number(clientId)] = state;
+    }
+  }
+  return states;
+}
 
 // src/engine/connection-monitor.ts
 var ConnectionMonitor = class {
@@ -1693,25 +2675,465 @@ var ReconnectionManager = class {
     });
   }
 };
+
+// src/encryption/sync-encryptor.ts
+import { SyncError as SyncError6 } from "@korajs/core";
+
+// src/encryption/key-derivation.ts
+import { SyncError as SyncError5 } from "@korajs/core";
+var KeyDerivationError = class extends SyncError5 {
+  constructor(message, context) {
+    super(message, { ...context, errorType: "KEY_DERIVATION_ERROR" });
+    this.name = "KeyDerivationError";
+  }
+};
+var SALT_LENGTH = 32;
+var PBKDF2_ITERATIONS = 6e5;
+var DERIVED_KEY_LENGTH = 256;
+function assertCryptoAvailable() {
+  if (typeof globalThis.crypto === "undefined" || typeof globalThis.crypto.subtle === "undefined") {
+    throw new KeyDerivationError(
+      "Web Crypto API (crypto.subtle) is not available in this environment. Sync encryption requires crypto.subtle, which is available in modern browsers and Node.js 20+."
+    );
+  }
+}
+function generateSalt() {
+  if (typeof globalThis.crypto === "undefined") {
+    throw new KeyDerivationError(
+      "Web Crypto API (crypto) is not available. Cannot generate random salt."
+    );
+  }
+  return globalThis.crypto.getRandomValues(new Uint8Array(SALT_LENGTH));
+}
+async function deriveKey(passphrase, salt) {
+  assertCryptoAvailable();
+  if (passphrase.length === 0) {
+    throw new KeyDerivationError(
+      "Passphrase must not be empty. Provide a non-empty string for encryption key derivation."
+    );
+  }
+  const usedSalt = salt ?? generateSalt();
+  try {
+    const passphraseBytes = new TextEncoder().encode(passphrase);
+    const baseKey = await globalThis.crypto.subtle.importKey(
+      "raw",
+      passphraseBytes,
+      "PBKDF2",
+      false,
+      ["deriveBits", "deriveKey"]
+    );
+    const derivedKey = await globalThis.crypto.subtle.deriveKey(
+      {
+        name: "PBKDF2",
+        salt: usedSalt,
+        iterations: PBKDF2_ITERATIONS,
+        hash: "SHA-256"
+      },
+      baseKey,
+      { name: "AES-GCM", length: DERIVED_KEY_LENGTH },
+      // extractable: true so the derived key can be exported for testing/debugging
+      true,
+      ["encrypt", "decrypt"]
+    );
+    return { key: derivedKey, salt: usedSalt };
+  } catch (cause) {
+    if (cause instanceof KeyDerivationError) {
+      throw cause;
+    }
+    throw new KeyDerivationError(
+      "Failed to derive encryption key from passphrase using PBKDF2. Ensure the runtime supports PBKDF2 with SHA-256.",
+      { cause: cause instanceof Error ? cause.message : String(cause) }
+    );
+  }
+}
+async function deriveVersionedKey(passphrase, version, salt) {
+  if (!Number.isInteger(version) || version < 1) {
+    throw new KeyDerivationError(`Key version must be a positive integer, received: ${version}`, {
+      version
+    });
+  }
+  const { key, salt: usedSalt } = await deriveKey(passphrase, salt);
+  return { version, key, salt: usedSalt };
+}
+
+// src/encryption/sync-encryptor.ts
+var EncryptionError = class extends SyncError6 {
+  constructor(message, context) {
+    super(message, { ...context, errorType: "ENCRYPTION_ERROR" });
+    this.name = "EncryptionError";
+  }
+};
+var DecryptionError = class extends SyncError6 {
+  constructor(message, context) {
+    super(message, { ...context, errorType: "DECRYPTION_ERROR" });
+    this.name = "DecryptionError";
+  }
+};
+var IV_LENGTH = 12;
+var ENCRYPTED_MARKER = "__kora_e2e_encrypted";
+var SyncEncryptor = class _SyncEncryptor {
+  /**
+   * Map of key version -> VersionedKey. The current (latest) version is used
+   * for encryption. All versions are available for decryption (key rotation).
+   */
+  keys;
+  /** The current key version used for encryption. */
+  currentVersion;
+  constructor(keys, currentVersion) {
+    this.keys = keys;
+    this.currentVersion = currentVersion;
+  }
+  /**
+   * Creates a SyncEncryptor from a {@link SyncEncryptionConfig}.
+   *
+   * Derives the encryption key from the passphrase using PBKDF2. The key
+   * derivation is async because it uses the Web Crypto API.
+   *
+   * @param config - Encryption configuration with passphrase
+   * @param salt - Optional salt for deterministic key derivation (mainly for testing).
+   *              If omitted, a random salt is generated.
+   * @returns A configured SyncEncryptor instance
+   * @throws {EncryptionError} If configuration is invalid
+   * @throws {KeyDerivationError} If key derivation fails
+   */
+  static async create(config, salt) {
+    if (!config.enabled) {
+      throw new EncryptionError(
+        "Cannot create SyncEncryptor with encryption disabled. Set enabled: true in the encryption config."
+      );
+    }
+    const passphrase = typeof config.key === "function" ? await config.key() : config.key;
+    if (passphrase.length === 0) {
+      throw new EncryptionError(
+        "Encryption key/passphrase must not be empty. Provide a non-empty string or key provider function."
+      );
+    }
+    const versionedKey = await deriveVersionedKey(passphrase, 1, salt);
+    const keys = /* @__PURE__ */ new Map();
+    keys.set(1, versionedKey);
+    return new _SyncEncryptor(keys, 1);
+  }
+  /**
+   * Creates a SyncEncryptor from pre-derived versioned keys.
+   *
+   * Use this when you need to support multiple key versions for key rotation,
+   * or when you have already derived the keys externally.
+   *
+   * @param versionedKeys - Array of versioned keys. The highest version is used for encryption.
+   * @returns A configured SyncEncryptor instance
+   * @throws {EncryptionError} If no keys are provided
+   */
+  static fromKeys(versionedKeys) {
+    if (versionedKeys.length === 0) {
+      throw new EncryptionError("At least one versioned key must be provided.");
+    }
+    const keys = /* @__PURE__ */ new Map();
+    let maxVersion = 0;
+    for (const vk of versionedKeys) {
+      keys.set(vk.version, vk);
+      if (vk.version > maxVersion) {
+        maxVersion = vk.version;
+      }
+    }
+    return new _SyncEncryptor(keys, maxVersion);
+  }
+  /**
+   * Add a new key version for key rotation.
+   *
+   * After adding, the new key becomes the current version used for encryption
+   * if its version number is higher than the current version. Previously-versioned
+   * keys remain available for decrypting older operations.
+   *
+   * @param key - The new versioned key to add
+   * @throws {EncryptionError} If the key version already exists
+   */
+  addKey(key) {
+    if (this.keys.has(key.version)) {
+      throw new EncryptionError(
+        `Key version ${key.version} already exists. Use a higher version number for rotation.`,
+        { existingVersion: key.version }
+      );
+    }
+    this.keys.set(key.version, key);
+    if (key.version > this.currentVersion) {
+      this.currentVersion = key.version;
+    }
+  }
+  /**
+   * Get the current encryption key version number.
+   */
+  getCurrentKeyVersion() {
+    return this.currentVersion;
+  }
+  /**
+   * Encrypt an operation's `data` and `previousData` fields.
+   *
+   * Returns a new Operation with encrypted field values. The original
+   * operation is not mutated (operations are immutable).
+   *
+   * Fields that are null (e.g., delete operations) remain null.
+   *
+   * @param operation - The operation to encrypt
+   * @returns A new operation with encrypted data fields
+   * @throws {EncryptionError} If encryption fails
+   */
+  async encryptOperation(operation) {
+    const [encryptedData, encryptedPreviousData] = await Promise.all([
+      this.encryptField(operation.data, operation.id, "data"),
+      this.encryptField(operation.previousData, operation.id, "previousData")
+    ]);
+    return {
+      ...operation,
+      data: encryptedData,
+      previousData: encryptedPreviousData
+    };
+  }
+  /**
+   * Decrypt an operation's `data` and `previousData` fields.
+   *
+   * Returns a new Operation with the original field values restored.
+   * The original operation is not mutated.
+   *
+   * If a field is null or not encrypted (no marker), it passes through unchanged.
+   * This enables mixed plaintext/encrypted operations during migration.
+   *
+   * @param operation - The operation to decrypt
+   * @returns A new operation with decrypted data fields
+   * @throws {DecryptionError} If decryption fails (wrong key, tampered data, unsupported version)
+   */
+  async decryptOperation(operation) {
+    const [decryptedData, decryptedPreviousData] = await Promise.all([
+      this.decryptField(operation.data, operation.id, "data"),
+      this.decryptField(operation.previousData, operation.id, "previousData")
+    ]);
+    return {
+      ...operation,
+      data: decryptedData,
+      previousData: decryptedPreviousData
+    };
+  }
+  /**
+   * Encrypt a serialized operation's `data` and `previousData` fields.
+   *
+   * Same as {@link encryptOperation} but works with the wire-format
+   * {@link SerializedOperation} type used by the serializer.
+   *
+   * @param serialized - The serialized operation to encrypt
+   * @returns A new serialized operation with encrypted data fields
+   * @throws {EncryptionError} If encryption fails
+   */
+  async encryptSerializedOperation(serialized) {
+    const [encryptedData, encryptedPreviousData] = await Promise.all([
+      this.encryptField(serialized.data, serialized.id, "data"),
+      this.encryptField(serialized.previousData, serialized.id, "previousData")
+    ]);
+    return {
+      ...serialized,
+      data: encryptedData,
+      previousData: encryptedPreviousData
+    };
+  }
+  /**
+   * Decrypt a serialized operation's `data` and `previousData` fields.
+   *
+   * Same as {@link decryptOperation} but works with the wire-format
+   * {@link SerializedOperation} type used by the serializer.
+   *
+   * @param serialized - The serialized operation to decrypt
+   * @returns A new serialized operation with decrypted data fields
+   * @throws {DecryptionError} If decryption fails
+   */
+  async decryptSerializedOperation(serialized) {
+    const [decryptedData, decryptedPreviousData] = await Promise.all([
+      this.decryptField(serialized.data, serialized.id, "data"),
+      this.decryptField(serialized.previousData, serialized.id, "previousData")
+    ]);
+    return {
+      ...serialized,
+      data: decryptedData,
+      previousData: decryptedPreviousData
+    };
+  }
+  /**
+   * Encrypt a batch of operations in parallel.
+   *
+   * @param operations - Operations to encrypt
+   * @returns New operations with encrypted data fields
+   */
+  async encryptBatch(operations) {
+    return Promise.all(operations.map((op) => this.encryptOperation(op)));
+  }
+  /**
+   * Decrypt a batch of operations in parallel.
+   *
+   * @param operations - Operations to decrypt
+   * @returns New operations with decrypted data fields
+   */
+  async decryptBatch(operations) {
+    return Promise.all(operations.map((op) => this.decryptOperation(op)));
+  }
+  /**
+   * Check if a field value contains an encrypted payload.
+   *
+   * @param field - An operation's `data` or `previousData` field
+   * @returns true if the field contains an encrypted payload
+   */
+  static isEncryptedPayload(field) {
+    return isEncryptedPayload(field);
+  }
+  // --- Private helpers ---
+  async encryptField(field, operationId, fieldName) {
+    if (field === null) {
+      return null;
+    }
+    const currentKey = this.keys.get(this.currentVersion);
+    if (!currentKey) {
+      throw new EncryptionError(
+        `Current encryption key version ${this.currentVersion} not found.`,
+        { operationId, fieldName }
+      );
+    }
+    try {
+      const plaintext = new TextEncoder().encode(JSON.stringify(field));
+      const iv = globalThis.crypto.getRandomValues(new Uint8Array(IV_LENGTH));
+      const ciphertextBuffer = await globalThis.crypto.subtle.encrypt(
+        { name: "AES-GCM", iv },
+        currentKey.key,
+        plaintext
+      );
+      const payload = {
+        v: this.currentVersion,
+        iv: toBase64(iv),
+        ct: toBase64(new Uint8Array(ciphertextBuffer)),
+        alg: "aes-256-gcm"
+      };
+      return {
+        [ENCRYPTED_MARKER]: true,
+        ...payload
+      };
+    } catch (cause) {
+      if (cause instanceof EncryptionError) {
+        throw cause;
+      }
+      throw new EncryptionError(
+        `Failed to encrypt operation ${fieldName} field. Ensure the encryption key is valid and crypto.subtle is available.`,
+        {
+          operationId,
+          fieldName,
+          cause: cause instanceof Error ? cause.message : String(cause)
+        }
+      );
+    }
+  }
+  async decryptField(field, operationId, fieldName) {
+    if (field === null) {
+      return null;
+    }
+    if (!isEncryptedPayload(field)) {
+      return field;
+    }
+    const payload = field;
+    const keyVersion = payload.v;
+    const key = this.keys.get(keyVersion);
+    if (!key) {
+      throw new DecryptionError(
+        `No encryption key available for version ${keyVersion}. This operation was encrypted with a key that is not registered. If you rotated keys, ensure all previous key versions are provided.`,
+        { operationId, fieldName, keyVersion, availableVersions: [...this.keys.keys()] }
+      );
+    }
+    if (payload.alg !== "aes-256-gcm") {
+      throw new DecryptionError(
+        `Unsupported encryption algorithm: "${payload.alg}". Only "aes-256-gcm" is supported. Update your @korajs/sync package.`,
+        { operationId, fieldName, algorithm: payload.alg }
+      );
+    }
+    try {
+      const iv = fromBase64(payload.iv);
+      const ciphertext = fromBase64(payload.ct);
+      const plaintextBuffer = await globalThis.crypto.subtle.decrypt(
+        { name: "AES-GCM", iv },
+        key.key,
+        ciphertext
+      );
+      const json = new TextDecoder().decode(plaintextBuffer);
+      const parsed = JSON.parse(json);
+      if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new DecryptionError(`Decrypted ${fieldName} is not a valid record object.`, {
+          operationId,
+          fieldName
+        });
+      }
+      return parsed;
+    } catch (cause) {
+      if (cause instanceof DecryptionError) {
+        throw cause;
+      }
+      throw new DecryptionError(
+        `Failed to decrypt operation ${fieldName} field. This may indicate a wrong encryption key, tampered ciphertext, or corrupted data.`,
+        {
+          operationId,
+          fieldName,
+          keyVersion,
+          cause: cause instanceof Error ? cause.message : String(cause)
+        }
+      );
+    }
+  }
+};
+function isEncryptedPayload(field) {
+  if (field === null || typeof field !== "object") {
+    return false;
+  }
+  return field[ENCRYPTED_MARKER] === true && typeof field.v === "number" && typeof field.iv === "string" && typeof field.ct === "string" && typeof field.alg === "string";
+}
+function toBase64(bytes) {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+function fromBase64(str) {
+  const binary = atob(str);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
 export {
+  AwarenessManager,
   ChaosTransport,
   ConnectionMonitor,
+  DecryptionError,
+  EncryptionError,
   HttpLongPollingTransport,
+  InvalidScopeError,
   JsonMessageSerializer,
+  KeyDerivationError,
   NegotiatedMessageSerializer,
   OutboundQueue,
   ProtobufMessageSerializer,
   ReconnectionManager,
   SYNC_STATES,
   SYNC_STATUSES,
+  ScopeViolationError,
+  SyncEncryptor,
   SyncEngine,
   WebSocketTransport,
+  deriveKey,
+  deriveVersionedKey,
+  filterOperationsByScope,
+  generateSalt,
   isAcknowledgmentMessage,
+  isAwarenessUpdateMessage,
+  isEncryptedPayload,
   isErrorMessage,
   isHandshakeMessage,
   isHandshakeResponseMessage,
   isOperationBatchMessage,
   isSyncMessage,
+  operationMatchesScope,
   versionVectorToWire,
   wireToVersionVector
 };