@korajs/server 0.4.0 → 0.6.0

package/dist/index.js

@@ -1,3 +1,59 @@
+// src/logging/structured-logger.ts
+function defaultJsonSerializer(entry) {
+  return JSON.stringify(entry);
+}
+function defaultPrettySerializer(entry) {
+  const time = new Date(entry.timestamp).toISOString().slice(11, 23);
+  const levelTag = { info: " INFO", warn: " WARN", error: "ERROR" }[entry.level];
+  const node = entry.nodeId ? ` [${entry.nodeId.slice(0, 8)}]` : "";
+  const session = entry.sessionId ? ` [session:${entry.sessionId.slice(0, 8)}]` : "";
+  const dur = entry.duration !== void 0 ? ` +${entry.duration}ms` : "";
+  const count3 = entry.count !== void 0 ? ` (${entry.count})` : "";
+  const err = entry.error ? ` \u2014 ${entry.error}` : "";
+  return `${time} ${levelTag}${node}${session} ${entry.event}${count3}${dur}${err}`;
+}
+function createJsonLogger(writer) {
+  const out = writer ?? {
+    info: (s) => process.stdout.write(`${s}
+`),
+    error: (s) => process.stderr.write(`${s}
+`)
+  };
+  return {
+    log(entry) {
+      const line = defaultJsonSerializer(entry);
+      if (entry.level === "error") {
+        out.error(line);
+      } else {
+        out.info(line);
+      }
+    }
+  };
+}
+function createPrettyLogger(writer) {
+  const out = writer ?? { write: (s) => process.stdout.write(`${s}
+`) };
+  return {
+    log(entry) {
+      out.write(defaultPrettySerializer(entry));
+    }
+  };
+}
+function createSilentLogger() {
+  return { log() {
+  } };
+}
+function createDefaultLogger() {
+  switch (process.env.NODE_ENV) {
+    case "production":
+      return createJsonLogger();
+    case "test":
+      return createSilentLogger();
+    default:
+      return createPrettyLogger();
+  }
+}
+
 // src/store/memory-server-store.ts
 import { generateUUIDv7 } from "@korajs/core";
 
@@ -157,6 +213,9 @@ var MemoryServerStore = class {
   getNodeId() {
     return this.nodeId;
   }
+  getSchema() {
+    return this.schema;
+  }
   async setSchema(schema) {
     this.assertOpen();
     this.schema = schema;
@@ -306,6 +365,49 @@ var MemoryServerStore = class {
   async close() {
     this.closed = true;
   }
+  /**
+   * Wipes all in-memory state. For tests and E2E isolation only.
+   */
+  resetForTests() {
+    this.assertOpen();
+    this.operations.length = 0;
+    this.operationIndex.clear();
+    this.versionVector.clear();
+    this.materializedRecords.clear();
+    this.schema = null;
+  }
+  async exportBackup() {
+    this.assertOpen();
+    const { buildServerBackup } = await import("./server-backup-MOICK6MI.js");
+    return buildServerBackup(this.nodeId, this.operations, this.versionVector);
+  }
+  async importBackup(data, merge) {
+    this.assertOpen();
+    const { parseServerBackup } = await import("./server-backup-MOICK6MI.js");
+    const { operations: operations2, versionVector } = parseServerBackup(data);
+    if (merge) {
+      let restored = 0;
+      for (const op of operations2) {
+        const result = await this.applyRemoteOperation(op);
+        if (result === "applied") restored++;
+      }
+      return { operationsRestored: restored, success: true };
+    }
+    this.operations.length = 0;
+    this.operationIndex.clear();
+    this.versionVector.clear();
+    for (const [nid, seq] of versionVector) {
+      this.versionVector.set(nid, seq);
+    }
+    for (const op of operations2) {
+      this.operations.push(op);
+      this.operationIndex.set(op.id, op);
+      if (this.schema?.collections[op.collection]) {
+        this.rebuildMaterializedRecord(op.collection, op.recordId);
+      }
+    }
+    return { operationsRestored: operations2.length, success: true };
+  }
   // --- Testing helpers (not on interface) ---
   /**
    * Get all stored operations (for test assertions).
@@ -497,6 +599,9 @@ var PostgresServerStore = class {
   getNodeId() {
     return this.nodeId;
   }
+  getSchema() {
+    return this.schema;
+  }
   async setSchema(schema) {
     this.assertOpen();
     await this.ready;
@@ -625,6 +730,45 @@ var PostgresServerStore = class {
   async close() {
     this.closed = true;
   }
+  async exportBackup() {
+    this.assertOpen();
+    await this.ready;
+    const { buildServerBackup } = await import("./server-backup-MOICK6MI.js");
+    const rows = await this.db.select().from(pgOperations).orderBy(asc(pgOperations.sequenceNumber));
+    const operations2 = rows.map((row) => this.deserializeOperation(row));
+    return buildServerBackup(this.nodeId, operations2, this.versionVector);
+  }
+  async importBackup(data, merge) {
+    this.assertOpen();
+    await this.ready;
+    const { parseServerBackup } = await import("./server-backup-MOICK6MI.js");
+    const { operations: operations2, versionVector } = parseServerBackup(data);
+    if (merge) {
+      let restored = 0;
+      for (const op of operations2) {
+        const result = await this.applyRemoteOperation(op);
+        if (result === "applied") restored++;
+      }
+      return { operationsRestored: restored, success: true };
+    }
+    const now = Date.now();
+    await this.db.transaction(async (tx) => {
+      await tx.delete(pgOperations);
+      await tx.delete(pgSyncState);
+      for (const [nid, seq] of versionVector) {
+        await tx.insert(pgSyncState).values({ nodeId: nid, maxSequenceNumber: seq, lastSeenAt: now }).onConflictDoNothing({ target: pgSyncState.nodeId });
+      }
+      for (const op of operations2) {
+        const row = this.serializeOperation(op, now);
+        await tx.insert(pgOperations).values(row).onConflictDoNothing({ target: pgOperations.id });
+      }
+    });
+    this.versionVector.clear();
+    for (const [nid, seq] of versionVector) {
+      this.versionVector.set(nid, seq);
+    }
+    return { operationsRestored: operations2.length, success: true };
+  }
   // ---------------------------------------------------------------------------
   // Materialization internals
   // ---------------------------------------------------------------------------
@@ -1042,6 +1186,9 @@ var SqliteServerStore = class {
   getNodeId() {
     return this.nodeId;
   }
+  getSchema() {
+    return this.schema;
+  }
   async setSchema(schema) {
     this.assertOpen();
     this.schema = schema;
@@ -1155,6 +1302,39 @@ var SqliteServerStore = class {
   async close() {
     this.closed = true;
   }
+  async exportBackup() {
+    this.assertOpen();
+    const { buildServerBackup } = await import("./server-backup-MOICK6MI.js");
+    const rows = this.db.select().from(operations).all();
+    const deserialized = rows.map((row) => this.deserializeOperation(row));
+    const vv = this.getVersionVector();
+    return buildServerBackup(this.nodeId, deserialized, vv);
+  }
+  async importBackup(data, merge) {
+    this.assertOpen();
+    const { parseServerBackup } = await import("./server-backup-MOICK6MI.js");
+    const { operations: ops, versionVector } = parseServerBackup(data);
+    if (merge) {
+      let restored = 0;
+      for (const op of ops) {
+        const result = await this.applyRemoteOperation(op);
+        if (result === "applied") restored++;
+      }
+      return { operationsRestored: restored, success: true };
+    }
+    this.db.transaction((tx) => {
+      tx.run(sql2.raw("DELETE FROM operations"));
+      tx.run(sql2.raw("DELETE FROM sync_state"));
+      for (const [nid, seq] of versionVector) {
+        tx.insert(syncState).values({ nodeId: nid, maxSequenceNumber: seq, lastSeenAt: Date.now() }).run();
+      }
+      for (const op of ops) {
+        const row = this.serializeOperation(op, Date.now());
+        tx.insert(operations).values(row).run();
+      }
+    });
+    return { operationsRestored: ops.length, success: true };
+  }
   // ---------------------------------------------------------------------------
   // Materialization internals
   // ---------------------------------------------------------------------------
@@ -1634,7 +1814,220 @@ var WsServerTransport = class {
 // src/session/client-session.ts
 import { generateUUIDv7 as generateUUIDv74 } from "@korajs/core";
 import { topologicalSort } from "@korajs/core/internal";
-import { NegotiatedMessageSerializer, versionVectorToWire, wireToVersionVector } from "@korajs/sync";
+import {
+  NegotiatedMessageSerializer,
+  SCHEMA_MISMATCH_PREFIX,
+  createDeltaCursorFromBatch,
+  decodeDeltaCursor,
+  dedupeQuerySubsets,
+  encodeDeltaCursor,
+  isClientSchemaVersionSupported,
+  operationMatchesQuerySubsets,
+  sliceOperationsAfterCursor,
+  versionVectorToWire,
+  wireToVersionVector
+} from "@korajs/sync";
+
+// src/apply/apply-server-operation.ts
+import { buildMergeRelationLookup, checkReferentialIntegrityOnDelete } from "@korajs/merge";
+
+// src/constraints/operation-constraint-validator.ts
+import { checkConstraints } from "@korajs/merge";
+
+// src/constraints/server-constraint-context.ts
+function createServerConstraintContext(store) {
+  return {
+    async queryRecords(collection, where) {
+      const rows = await store.queryCollection(collection, { where });
+      return rows.map((row) => ({ ...row }));
+    },
+    async countRecords(collection, where) {
+      return store.countCollection(collection, where);
+    }
+  };
+}
+
+// src/constraints/operation-constraint-validator.ts
+async function validateIncomingOperationConstraints(store, op, schema) {
+  if (!schema) {
+    return { valid: true };
+  }
+  if (op.type === "delete") {
+    return { valid: true };
+  }
+  const collectionDef = schema.collections[op.collection];
+  if (!collectionDef || collectionDef.constraints.length === 0) {
+    return { valid: true };
+  }
+  const candidate = await projectCandidateRecord(store, op);
+  if (candidate === null) {
+    return { valid: true };
+  }
+  const ctx = createServerConstraintContext(store);
+  const violations = await checkConstraints(
+    candidate,
+    op.recordId,
+    op.collection,
+    collectionDef,
+    ctx
+  );
+  if (violations.length === 0) {
+    return { valid: true };
+  }
+  const first = violations[0];
+  if (first === void 0) {
+    return { valid: true };
+  }
+  return {
+    valid: false,
+    code: "CONSTRAINT_VIOLATION",
+    message: first.message
+  };
+}
+async function projectCandidateRecord(store, op) {
+  if (op.data === null) {
+    return null;
+  }
+  const existing = await store.findRecord(op.collection, op.recordId);
+  const base = existing ? { ...existing } : {};
+  if (op.type === "insert") {
+    return { ...op.data, id: op.recordId };
+  }
+  return { ...base, ...op.data, id: op.recordId };
+}
+
+// src/constraints/server-referential-context.ts
+function createServerReferentialContext(store) {
+  return {
+    async queryRecords(collection, where) {
+      const rows = await store.queryCollection(collection, { where });
+      return rows.map((row) => ({ ...row }));
+    },
+    async recordExists(collection, recordId) {
+      const row = await store.findRecord(collection, recordId);
+      return row !== null && row._deleted !== 1;
+    }
+  };
+}
+
+// src/apply/server-side-effect-operation.ts
+import { HybridLogicalClock, createOperation } from "@korajs/core";
+async function createServerSideEffectOperation(store, parentOp, effect, schemaVersion, sequenceNumber) {
+  const nodeId = store.getNodeId();
+  const clock = new HybridLogicalClock(nodeId);
+  clock.receive(parentOp.timestamp);
+  return createOperation(
+    {
+      nodeId,
+      type: effect.type === "delete" ? "delete" : "update",
+      collection: effect.collection,
+      recordId: effect.recordId,
+      data: effect.data,
+      previousData: effect.previousData,
+      sequenceNumber,
+      causalDeps: [parentOp.id],
+      schemaVersion
+    },
+    clock
+  );
+}
+function nextServerSequenceNumber(store) {
+  const nodeId = store.getNodeId();
+  const current = store.getVersionVector().get(nodeId) ?? 0;
+  return current + 1;
+}
+
+// src/apply/apply-server-operation.ts
+async function applyServerOperation(store, op, relationLookup) {
+  const schema = store.getSchema();
+  const lookup = relationLookup ?? (schema ? buildMergeRelationLookup(schema) : /* @__PURE__ */ new Map());
+  const constraintCheck = await validateIncomingOperationConstraints(store, op, schema);
+  if (!constraintCheck.valid) {
+    return {
+      result: "skipped",
+      appliedOperations: [],
+      rejection: {
+        code: constraintCheck.code ?? "CONSTRAINT_VIOLATION",
+        message: constraintCheck.message ?? `Operation "${op.id}" violates a schema constraint`
+      }
+    };
+  }
+  if (op.type === "delete" && schema) {
+    const refCtx = createServerReferentialContext(store);
+    const referential = await checkReferentialIntegrityOnDelete(op, schema, refCtx, lookup);
+    if (!referential.allowed) {
+      return {
+        result: "skipped",
+        appliedOperations: [],
+        rejection: {
+          code: "REFERENTIAL_INTEGRITY",
+          message: `Operation "${op.id}" violates referential integrity on "${op.collection}"`
+        }
+      };
+    }
+    const primaryResult = await store.applyRemoteOperation(op);
+    if (primaryResult !== "applied") {
+      return { result: primaryResult, appliedOperations: [] };
+    }
+    const appliedOperations = [op];
+    let serverSeq = nextServerSequenceNumber(store);
+    for (const effect of referential.sideEffectOps) {
+      const sideOp = await createServerSideEffectOperation(
+        store,
+        op,
+        effect,
+        op.schemaVersion,
+        serverSeq
+      );
+      serverSeq += 1;
+      const sideResult = await store.applyRemoteOperation(sideOp);
+      if (sideResult === "applied") {
+        appliedOperations.push(sideOp);
+      }
+    }
+    return { result: "applied", appliedOperations };
+  }
+  const result = await store.applyRemoteOperation(op);
+  return {
+    result,
+    appliedOperations: result === "applied" ? [op] : []
+  };
+}
+
+// src/scopes/resolve-session-scopes.ts
+import { buildScopeMap } from "@korajs/core";
+function resolveSessionScopes(schema, options) {
+  const { handshakeScope, authScopes, scopeValues } = options;
+  let resolved;
+  if (schema && scopeValues && Object.keys(scopeValues).length > 0) {
+    resolved = buildScopeMap(schema, scopeValues);
+  } else if (handshakeScope) {
+    resolved = { ...handshakeScope };
+  } else if (authScopes) {
+    resolved = { ...authScopes };
+  }
+  if (schema && !resolved && scopeValues) {
+    resolved = buildScopeMap(schema, scopeValues);
+  }
+  if (authScopes) {
+    resolved = mergeScopeMaps(resolved, authScopes, "auth");
+  }
+  if (handshakeScope) {
+    resolved = mergeScopeMaps(resolved, handshakeScope, "handshake");
+  }
+  return resolved && Object.keys(resolved).length > 0 ? resolved : void 0;
+}
+function mergeScopeMaps(base, overlay, source) {
+  const merged = { ...base ?? {} };
+  for (const [collection, overlayScope] of Object.entries(overlay)) {
+    if (source === "auth") {
+      merged[collection] = { ...merged[collection] ?? {}, ...overlayScope };
+    } else {
+      merged[collection] = { ...overlayScope ?? {}, ...merged[collection] ?? {} };
+    }
+  }
+  return merged;
+}
 
 // src/scopes/server-scope-filter.ts
 function operationMatchesScopes(op, scopes) {
@@ -1666,6 +2059,55 @@ function asRecord(value) {
   return value;
 }
 
+// src/session/operation-validation.ts
+var SERVER_MAX_TIMESTAMP_FUTURE_MS = 6e4;
+function isOperationTimestampValid(op, now = Date.now()) {
+  return op.timestamp.wallTime <= now + SERVER_MAX_TIMESTAMP_FUTURE_MS;
+}
+
+// src/session/session-operation-limits.ts
+var DEFAULT_MAX_OPERATION_BYTES = 256 * 1024;
+var DEFAULT_MAX_OPS_PER_MINUTE = 600;
+function measureOperationBytes(op) {
+  return Buffer.byteLength(JSON.stringify(op), "utf8");
+}
+function validateOperationSize(op, maxBytes = DEFAULT_MAX_OPERATION_BYTES) {
+  const bytes = measureOperationBytes(op);
+  if (bytes <= maxBytes) {
+    return { valid: true, bytes };
+  }
+  return {
+    valid: false,
+    bytes,
+    message: `Operation "${op.id}" exceeds max size (${String(bytes)} > ${String(maxBytes)} bytes)`
+  };
+}
+var SessionRateLimiter = class {
+  constructor(maxOpsPerMinute = DEFAULT_MAX_OPS_PER_MINUTE) {
+    this.maxOpsPerMinute = maxOpsPerMinute;
+  }
+  maxOpsPerMinute;
+  windowStartMs = Date.now();
+  count = 0;
+  get limit() {
+    return this.maxOpsPerMinute;
+  }
+  /** Record N operations and return false when the limit is exceeded. */
+  allow(count3 = 1) {
+    const now = Date.now();
+    if (now - this.windowStartMs >= 6e4) {
+      this.windowStartMs = now;
+      this.count = 0;
+    }
+    this.count += count3;
+    return this.count <= this.maxOpsPerMinute;
+  }
+  reset() {
+    this.windowStartMs = Date.now();
+    this.count = 0;
+  }
+};
+
 // src/session/client-session.ts
 var DEFAULT_BATCH_SIZE = 100;
 var DEFAULT_SCHEMA_VERSION = 1;
@@ -1673,6 +2115,8 @@ var ClientSession = class {
   state = "connected";
   clientNodeId = null;
   authContext = null;
+  syncQuerySubsets = [];
+  resumeDeltaCursor = null;
   sessionId;
   transport;
   store;
@@ -1681,9 +2125,14 @@ var ClientSession = class {
   emitter;
   batchSize;
   schemaVersion;
+  supportedSchemaVersions;
   onRelay;
   onAwarenessUpdate;
+  onYjsDocUpdate;
   onClose;
+  maxOperationBytes;
+  maxOpsPerMinute;
+  rateLimiter;
   constructor(options) {
     this.sessionId = options.sessionId;
     this.transport = options.transport;
@@ -1693,15 +2142,24 @@ var ClientSession = class {
     this.emitter = options.emitter ?? null;
     this.batchSize = options.batchSize ?? DEFAULT_BATCH_SIZE;
     this.schemaVersion = options.schemaVersion ?? DEFAULT_SCHEMA_VERSION;
+    const supported = options.supportedSchemaVersions;
+    this.supportedSchemaVersions = supported ?? {
+      min: this.schemaVersion,
+      max: this.schemaVersion
+    };
     this.onRelay = options.onRelay ?? null;
     this.onAwarenessUpdate = options.onAwarenessUpdate ?? null;
+    this.onYjsDocUpdate = options.onYjsDocUpdate ?? null;
     this.onClose = options.onClose ?? null;
+    this.maxOperationBytes = options.maxOperationBytes ?? DEFAULT_MAX_OPERATION_BYTES;
+    this.maxOpsPerMinute = options.maxOpsPerMinute ?? DEFAULT_MAX_OPS_PER_MINUTE;
+    this.rateLimiter = new SessionRateLimiter(this.maxOpsPerMinute);
   }
   /**
    * Start handling messages from the client transport.
    */
   start() {
-    this.transport.onMessage((msg) => this.handleMessage(msg));
+    this.transport.onMessage((msg) => this.enqueueMessage(msg));
     this.transport.onClose((_code, _reason) => this.handleTransportClose());
     this.transport.onError((_err) => {
       if (this.state !== "closed") {
@@ -1716,9 +2174,7 @@ var ClientSession = class {
   relayOperations(operations2) {
     if (this.state !== "streaming" || !this.transport.isConnected()) return;
     if (operations2.length === 0) return;
-    const visibleOperations = operations2.filter(
-      (op) => operationMatchesScopes(op, this.authContext?.scopes)
-    );
+    const visibleOperations = operations2.filter((op) => this.operationVisibleToClient(op));
     if (visibleOperations.length === 0) return;
     const serializedOps = visibleOperations.map((op) => this.serializer.encodeOperation(op));
     const msg = {
@@ -1728,7 +2184,7 @@ var ClientSession = class {
       isFinal: true,
       batchIndex: 0
     };
-    this.transport.send(msg);
+    this.sendToClient(msg);
   }
   /**
    * Close this session.
@@ -1765,15 +2221,30 @@ var ClientSession = class {
     return this.transport;
   }
   // --- Private protocol handlers ---
-  handleMessage(message) {
+  messageChain = Promise.resolve();
+  /** Send to the client when the transport is still connected; no-op otherwise. */
+  sendToClient(message) {
+    if (!this.transport.isConnected()) {
+      return false;
+    }
+    try {
+      this.transport.send(message);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  enqueueMessage(message) {
+    this.messageChain = this.messageChain.then(() => this.handleMessageAsync(message)).catch((error) => this.handleMessageFailure(error));
+  }
+  async handleMessageAsync(message) {
     switch (message.type) {
       case "handshake":
-        this.handleHandshake(message);
+        await this.handleHandshake(message);
         break;
       case "operation-batch":
-        this.handleOperationBatch(message);
+        await this.handleOperationBatch(message);
         break;
-      // Acknowledgments from clients are noted but no action needed on server
       case "acknowledgment":
         break;
       case "error":
@@ -1781,8 +2252,16 @@ var ClientSession = class {
       case "awareness-update":
         this.handleAwarenessUpdate(message);
         break;
+      case "yjs-doc-update":
+        this.handleYjsDocUpdate(message);
+        break;
     }
   }
+  handleMessageFailure(error) {
+    const reason = error instanceof Error ? error.message : "Message handling failed";
+    this.sendError("SYNC_ERROR", reason, true);
+    this.close(reason);
+  }
   async handleHandshake(msg) {
     if (this.state !== "connected") {
       this.sendError("DUPLICATE_HANDSHAKE", "Handshake already completed", false);
@@ -1800,22 +2279,43 @@ var ClientSession = class {
       this.authContext = context;
       this.state = "authenticated";
     }
-    if (msg.syncScope) {
-      const mergedScopes = { ...msg.syncScope };
-      if (this.authContext?.scopes) {
-        for (const [collection, authScope] of Object.entries(this.authContext.scopes)) {
-          mergedScopes[collection] = { ...mergedScopes[collection] ?? {}, ...authScope };
-        }
-      }
+    const resolvedScopes = resolveSessionScopes(this.store.getSchema(), {
+      handshakeScope: msg.syncScope,
+      authScopes: this.authContext?.scopes
+    });
+    if (resolvedScopes) {
       if (this.authContext) {
-        this.authContext = { ...this.authContext, scopes: mergedScopes };
+        this.authContext = { ...this.authContext, scopes: resolvedScopes };
       } else {
-        this.authContext = { userId: msg.nodeId, scopes: mergedScopes };
+        this.authContext = { userId: msg.nodeId, scopes: resolvedScopes };
       }
     }
+    if (msg.syncQueries && msg.syncQueries.length > 0) {
+      this.syncQuerySubsets = dedupeQuerySubsets(msg.syncQueries);
+    } else {
+      this.syncQuerySubsets = [];
+    }
+    this.resumeDeltaCursor = msg.deltaCursor ? decodeDeltaCursor(msg.deltaCursor) : null;
     const serverVector = this.store.getVersionVector();
     const selectedWireFormat = selectWireFormat(msg.supportedWireFormats);
     this.setSerializerWireFormat(selectedWireFormat);
+    if (!isClientSchemaVersionSupported(msg.schemaVersion, this.supportedSchemaVersions)) {
+      const { min, max } = this.supportedSchemaVersions;
+      const response2 = {
+        type: "handshake-response",
+        messageId: generateUUIDv74(),
+        nodeId: this.store.getNodeId(),
+        versionVector: versionVectorToWire(serverVector),
+        schemaVersion: this.schemaVersion,
+        accepted: false,
+        rejectReason: `${SCHEMA_MISMATCH_PREFIX}: client schema version ${msg.schemaVersion} not in supported range [${min}, ${max}]`,
+        supportedSchemaMin: min,
+        supportedSchemaMax: max
+      };
+      this.sendToClient(response2);
+      this.close("schema version mismatch");
+      return;
+    }
     const response = {
       type: "handshake-response",
       messageId: generateUUIDv74(),
@@ -1828,7 +2328,7 @@ var ClientSession = class {
       // This may differ from what the client requested if auth scopes are narrower.
       ...this.authContext?.scopes ? { acceptedScope: this.authContext.scopes } : {}
     };
-    this.transport.send(response);
+    this.sendToClient(response);
     this.emitter?.emit({ type: "sync:connected", nodeId: msg.nodeId });
     this.state = "syncing";
     const clientVector = wireToVersionVector(msg.versionVector);
@@ -1840,13 +2340,45 @@ var ClientSession = class {
     const applied = [];
     const rejected = [];
     for (const op of operations2) {
-      if (!operationMatchesScopes(op, this.authContext?.scopes)) {
+      if (!this.operationVisibleToClient(op)) {
         rejected.push(op);
         continue;
       }
-      const result = await this.store.applyRemoteOperation(op);
-      if (result === "applied") {
-        applied.push(op);
+      if (!isOperationTimestampValid(op)) {
+        this.sendError(
+          "INVALID_TIMESTAMP",
+          `Operation "${op.id}" timestamp is too far in the future`,
+          false
+        );
+        continue;
+      }
+      if (!this.rateLimiter.allow(1)) {
+        this.sendError(
+          "RATE_LIMIT",
+          `Session exceeded operation rate limit (${String(this.maxOpsPerMinute)} ops/min)`,
+          true
+        );
+        continue;
+      }
+      const sizeCheck = validateOperationSize(op, this.maxOperationBytes);
+      if (!sizeCheck.valid) {
+        this.sendError(
+          "OPERATION_TOO_LARGE",
+          sizeCheck.message ?? `Operation "${op.id}" is too large`,
+          false
+        );
+        continue;
+      }
+      try {
+        const applyResult = await applyServerOperation(this.store, op);
+        if (applyResult.rejection) {
+          this.sendError(applyResult.rejection.code, applyResult.rejection.message, false);
+          continue;
+        }
+        if (applyResult.result === "applied") {
+          applied.push(...applyResult.appliedOperations);
+        }
+      } catch {
       }
     }
     if (rejected.length > 0) {
@@ -1872,7 +2404,7 @@ var ClientSession = class {
       acknowledgedMessageId: msg.messageId,
       lastSequenceNumber: lastOp ? lastOp.sequenceNumber : 0
     };
-    this.transport.send(ack);
+    this.sendToClient(ack);
     if (applied.length > 0) {
       this.onRelay?.(this.sessionId, applied);
     }
@@ -1884,7 +2416,7 @@ var ClientSession = class {
       const clientSeq = clientVector.get(nodeId) ?? 0;
       if (serverSeq > clientSeq) {
         const ops = await this.store.getOperationRange(nodeId, clientSeq + 1, serverSeq);
-        const visible = ops.filter((op) => operationMatchesScopes(op, this.authContext?.scopes));
+        const visible = ops.filter((op) => this.operationVisibleToClient(op));
         missing.push(...visible);
       }
     }
@@ -1894,25 +2426,42 @@ var ClientSession = class {
         messageId: generateUUIDv74(),
         operations: [],
         isFinal: true,
-        batchIndex: 0
+        batchIndex: 0,
+        totalBatches: 1
       };
-      this.transport.send(emptyBatch);
+      this.sendToClient(emptyBatch);
       return;
     }
     const sorted = topologicalSort(missing);
-    const totalBatches = Math.ceil(sorted.length / this.batchSize);
+    const afterCursor = sliceOperationsAfterCursor(sorted, this.resumeDeltaCursor);
+    const totalBatches = Math.ceil(afterCursor.length / this.batchSize);
+    if (afterCursor.length === 0) {
+      const emptyBatch = {
+        type: "operation-batch",
+        messageId: generateUUIDv74(),
+        operations: [],
+        isFinal: true,
+        batchIndex: this.resumeDeltaCursor?.batchIndex ?? 0,
+        totalBatches: 1
+      };
+      this.sendToClient(emptyBatch);
+      return;
+    }
     for (let i = 0; i < totalBatches; i++) {
       const start = i * this.batchSize;
-      const batchOps = sorted.slice(start, start + this.batchSize);
+      const batchOps = afterCursor.slice(start, start + this.batchSize);
       const serializedOps = batchOps.map((op) => this.serializer.encodeOperation(op));
+      const batchCursor = createDeltaCursorFromBatch(batchOps, i);
       const batchMsg = {
         type: "operation-batch",
         messageId: generateUUIDv74(),
         operations: serializedOps,
         isFinal: i === totalBatches - 1,
-        batchIndex: i
+        batchIndex: i,
+        totalBatches,
+        ...batchCursor ? { cursor: encodeDeltaCursor(batchCursor) } : {}
       };
-      this.transport.send(batchMsg);
+      this.sendToClient(batchMsg);
       this.emitter?.emit({
         type: "sync:sent",
         operations: batchOps,
@@ -1920,9 +2469,18 @@ var ClientSession = class {
       });
     }
   }
+  operationVisibleToClient(op) {
+    if (!operationMatchesScopes(op, this.authContext?.scopes)) {
+      return false;
+    }
+    return operationMatchesQuerySubsets(op, this.syncQuerySubsets);
+  }
   handleAwarenessUpdate(msg) {
     this.onAwarenessUpdate?.(this.sessionId, msg);
   }
+  handleYjsDocUpdate(msg) {
+    this.onYjsDocUpdate?.(this.sessionId, msg);
+  }
   sendError(code, message, retriable) {
     const errorMsg = {
       type: "error",
@@ -1931,7 +2489,7 @@ var ClientSession = class {
       message,
       retriable
     };
-    this.transport.send(errorMsg);
+    this.sendToClient(errorMsg);
   }
   setSerializerWireFormat(format) {
     if (typeof this.serializer.setWireFormat === "function") {
@@ -1954,6 +2512,7 @@ function selectWireFormat(supportedWireFormats) {
 
 // src/server/kora-sync-server.ts
 import { SyncError as SyncError4, generateUUIDv7 as generateUUIDv76 } from "@korajs/core";
+import { SimpleEventEmitter } from "@korajs/core/internal";
 import { JsonMessageSerializer as JsonMessageSerializer2 } from "@korajs/sync";
 
 // src/awareness/awareness-relay.ts
@@ -2053,6 +2612,156 @@ var AwarenessRelay = class {
   }
 };
 
+// src/diagnostics/server-metrics-collector.ts
+function estimateByteSize(operations2) {
+  let total = 0;
+  for (const op of operations2) {
+    total += JSON.stringify(op).length;
+  }
+  return total;
+}
+var ServerMetricsCollector = class {
+  startedAt = Date.now();
+  peakConnections = 0;
+  connectionsTotal = 0;
+  operationsReceived = 0;
+  operationsSent = 0;
+  bytesReceived = 0;
+  bytesSent = 0;
+  errorCount = 0;
+  schemaVersion = 1;
+  clientMetrics = /* @__PURE__ */ new Map();
+  /** Record a new client connection. */
+  recordConnection(sessionId) {
+    this.connectionsTotal++;
+    this.clientMetrics.set(sessionId, {
+      sessionId,
+      nodeId: null,
+      state: "connected",
+      connectedAt: Date.now(),
+      operationsReceived: 0,
+      operationsSent: 0,
+      authContext: null
+    });
+    this.peakConnections = Math.max(this.peakConnections, this.clientMetrics.size);
+  }
+  /** Record a client disconnection. */
+  recordDisconnection(sessionId) {
+    this.clientMetrics.delete(sessionId);
+  }
+  /** Update the node ID after a handshake completes. */
+  recordHandshake(sessionId, nodeId) {
+    const client = this.clientMetrics.get(sessionId);
+    if (client) {
+      client.nodeId = nodeId;
+    }
+  }
+  /** Update session state. */
+  updateSessionState(sessionId, state) {
+    const client = this.clientMetrics.get(sessionId);
+    if (client) {
+      client.state = state;
+    }
+  }
+  /** Record authentication context for a session. */
+  recordAuth(sessionId, authContext) {
+    const client = this.clientMetrics.get(sessionId);
+    if (client) {
+      client.authContext = authContext;
+    }
+  }
+  /** Record operations received from a client. */
+  recordReceived(sessionId, count3, byteSize) {
+    this.operationsReceived += count3;
+    this.bytesReceived += byteSize;
+    const client = this.clientMetrics.get(sessionId);
+    if (client) {
+      client.operationsReceived += count3;
+    }
+  }
+  /** Record operations sent to a client. */
+  recordSent(sessionId, count3, byteSize) {
+    this.operationsSent += count3;
+    this.bytesSent += byteSize;
+    const client = this.clientMetrics.get(sessionId);
+    if (client) {
+      client.operationsSent += count3;
+    }
+  }
+  /** Record an error. */
+  recordError() {
+    this.errorCount++;
+  }
+  /** Set the schema version. */
+  setSchemaVersion(version) {
+    this.schemaVersion = version;
+  }
+  /** Return a full snapshot of current metrics. */
+  getSnapshot(totalOperations) {
+    return {
+      connectedClients: this.clientMetrics.size,
+      connectedNodeIds: Array.from(this.clientMetrics.values()).filter((c) => c.nodeId !== null).map((c) => c.nodeId),
+      peakConnections: this.peakConnections,
+      connectionsTotal: this.connectionsTotal,
+      operationsReceived: this.operationsReceived,
+      operationsSent: this.operationsSent,
+      bytesReceived: this.bytesReceived,
+      bytesSent: this.bytesSent,
+      clients: Array.from(this.clientMetrics.values()),
+      uptime: Date.now() - this.startedAt,
+      totalOperations,
+      errorCount: this.errorCount,
+      schemaVersion: this.schemaVersion
+    };
+  }
+  /** Reset all metrics. */
+  reset() {
+    this.startedAt = Date.now();
+    this.peakConnections = 0;
+    this.connectionsTotal = 0;
+    this.operationsReceived = 0;
+    this.operationsSent = 0;
+    this.bytesReceived = 0;
+    this.bytesSent = 0;
+    this.errorCount = 0;
+    this.clientMetrics.clear();
+  }
+};
+
+// src/richtext/yjs-doc-relay.ts
+var YjsDocRelay = class {
+  clients = /* @__PURE__ */ new Map();
+  addClient(sessionId, transport) {
+    this.clients.set(sessionId, { sessionId, transport });
+  }
+  removeClient(sessionId) {
+    this.clients.delete(sessionId);
+  }
+  handleUpdate(sourceSessionId, message) {
+    if (!this.clients.has(sourceSessionId)) {
+      return;
+    }
+    this.broadcastExcept(sourceSessionId, message);
+  }
+  getClientCount() {
+    return this.clients.size;
+  }
+  clear() {
+    this.clients.clear();
+  }
+  broadcastExcept(excludeSessionId, message) {
+    for (const [, client] of this.clients) {
+      if (client.sessionId === excludeSessionId) {
+        continue;
+      }
+      if (!client.transport.isConnected()) {
+        continue;
+      }
+      client.transport.send(message);
+    }
+  }
+};
+
 // src/server/kora-sync-server.ts
 var DEFAULT_MAX_CONNECTIONS = 0;
 var DEFAULT_BATCH_SIZE2 = 100;
@@ -2067,13 +2776,18 @@ var KoraSyncServer = class {
   maxConnections;
   batchSize;
   schemaVersion;
+  supportedSchemaVersions;
   port;
   host;
   path;
+  logger;
+  metrics;
   awarenessRelay = new AwarenessRelay();
+  yjsDocRelay = new YjsDocRelay();
   sessions = /* @__PURE__ */ new Map();
   httpClients = /* @__PURE__ */ new Map();
   httpSessionToClient = /* @__PURE__ */ new Map();
+  serverVersion = "0.4.0";
   wsServer = null;
   running = false;
   constructor(config) {
@@ -2084,9 +2798,80 @@ var KoraSyncServer = class {
     this.maxConnections = config.maxConnections ?? DEFAULT_MAX_CONNECTIONS;
     this.batchSize = config.batchSize ?? DEFAULT_BATCH_SIZE2;
     this.schemaVersion = config.schemaVersion ?? DEFAULT_SCHEMA_VERSION2;
+    this.supportedSchemaVersions = config.supportedSchemaVersions ?? {
+      min: this.schemaVersion,
+      max: this.schemaVersion
+    };
     this.port = config.port;
     this.host = config.host ?? DEFAULT_HOST;
     this.path = config.path ?? DEFAULT_PATH;
+    this.logger = config.logger ?? createDefaultLogger();
+    this.metrics = config.metricsCollector ?? new ServerMetricsCollector();
+    this.metrics.setSchemaVersion(this.schemaVersion);
+    if (!this.emitter) {
+      this.emitter = new SimpleEventEmitter();
+    }
+  }
+  /**
+   * Subscribe to session-level events for metrics collection and logging.
+   * Called when a new session is created.
+   */
+  attachSessionEvents(sessionId, sessionEmitter) {
+    sessionEmitter.on("sync:connected", (event) => {
+      this.metrics.recordHandshake(sessionId, event.nodeId);
+      this.logger.log({
+        timestamp: Date.now(),
+        level: "info",
+        event: "session.handshake",
+        sessionId,
+        nodeId: event.nodeId
+      });
+    });
+    sessionEmitter.on("sync:received", (event) => {
+      const byteSize = estimateByteSize(event.operations);
+      this.metrics.recordReceived(sessionId, event.batchSize, byteSize);
+      this.logger.log({
+        timestamp: Date.now(),
+        level: "info",
+        event: "operations.received",
+        sessionId,
+        count: event.batchSize,
+        bytes: byteSize
+      });
+    });
+    sessionEmitter.on("sync:sent", (event) => {
+      const byteSize = estimateByteSize(event.operations);
+      this.metrics.recordSent(sessionId, event.batchSize, byteSize);
+      this.logger.log({
+        timestamp: Date.now(),
+        level: "info",
+        event: "operations.sent",
+        sessionId,
+        count: event.batchSize,
+        bytes: byteSize
+      });
+    });
+    sessionEmitter.on("sync:disconnected", (event) => {
+      this.logger.log({
+        timestamp: Date.now(),
+        level: "info",
+        event: "session.disconnected",
+        sessionId,
+        details: { reason: event.reason }
+      });
+    });
+  }
+  /**
+   * Get the metrics collector for external access (e.g., HTTP endpoints).
+   */
+  getMetricsCollector() {
+    return this.metrics;
+  }
+  /**
+   * Get the logger for external access (e.g., event streaming).
+   */
+  getLogger() {
+    return this.logger;
   }
   /**
    * Start the WebSocket server in standalone mode.
@@ -2127,12 +2912,25 @@ var KoraSyncServer = class {
       this.handleConnection(transport);
     });
     this.running = true;
+    this.logger.log({
+      timestamp: Date.now(),
+      level: "info",
+      event: "server.started",
+      details: { port: this.port, host: this.host, path: this.path }
+    });
   }
   /**
    * Stop the server. Closes all sessions and the WebSocket server.
    */
   async stop() {
+    this.logger.log({
+      timestamp: Date.now(),
+      level: "info",
+      event: "server.stopping",
+      details: { connectedClients: this.sessions.size }
+    });
     this.awarenessRelay.clear();
+    this.yjsDocRelay.clear();
     for (const session of this.sessions.values()) {
       session.close("server shutting down");
     }
@@ -2146,6 +2944,11 @@ var KoraSyncServer = class {
       this.wsServer = null;
     }
     this.running = false;
+    this.logger.log({
+      timestamp: Date.now(),
+      level: "info",
+      event: "server.stopped"
+    });
   }
   /**
    * Handle one HTTP sync request for a long-polling client.
@@ -2195,44 +2998,119 @@ var KoraSyncServer = class {
         retriable: true
       });
       transport.close(4029, "max connections reached");
+      this.metrics.recordError();
+      this.logger.log({
+        timestamp: Date.now(),
+        level: "warn",
+        event: "connection.rejected",
+        details: { reason: "max_connections", max: this.maxConnections }
+      });
       throw new SyncError4("Maximum connections reached", {
         current: this.sessions.size,
         max: this.maxConnections
       });
     }
     const sessionId = generateUUIDv76();
+    this.metrics.recordConnection(sessionId);
+    const sessionEmitter = new SimpleEventEmitter();
+    sessionEmitter.on("sync:connected", (event) => {
+      this.metrics.recordHandshake(sessionId, event.nodeId);
+      this.metrics.updateSessionState(sessionId, "authenticated");
+      this.logger.log({
+        timestamp: Date.now(),
+        level: "info",
+        event: "session.handshake",
+        sessionId,
+        nodeId: event.nodeId
+      });
+    });
+    sessionEmitter.on("sync:received", (event) => {
+      const byteSize = estimateOperationByteSize(event.operations);
+      this.metrics.recordReceived(sessionId, event.batchSize, byteSize);
+      this.logger.log({
+        timestamp: Date.now(),
+        level: "info",
+        event: "operations.received",
+        sessionId,
+        count: event.batchSize,
+        bytes: byteSize
+      });
+    });
+    sessionEmitter.on("sync:sent", (event) => {
+      const byteSize = estimateOperationByteSize(event.operations);
+      this.metrics.recordSent(sessionId, event.batchSize, byteSize);
+      this.logger.log({
+        timestamp: Date.now(),
+        level: "info",
+        event: "operations.sent",
+        sessionId,
+        count: event.batchSize,
+        bytes: byteSize
+      });
+    });
+    sessionEmitter.on("sync:disconnected", () => {
+      this.logger.log({
+        timestamp: Date.now(),
+        level: "info",
+        event: "session.disconnected",
+        sessionId
+      });
+    });
     const session = new ClientSession({
       sessionId,
       transport,
       store: this.store,
       auth: this.auth ?? void 0,
       serializer: this.serializer,
-      emitter: this.emitter ?? void 0,
+      emitter: sessionEmitter,
       batchSize: this.batchSize,
       schemaVersion: this.schemaVersion,
+      supportedSchemaVersions: this.supportedSchemaVersions,
       onRelay: (sourceSessionId, operations2) => {
         this.handleRelay(sourceSessionId, operations2);
       },
       onAwarenessUpdate: (sourceSessionId, message) => {
         this.handleAwarenessRelay(sourceSessionId, message);
       },
+      onYjsDocUpdate: (sourceSessionId, message) => {
+        this.handleYjsDocRelay(sourceSessionId, message);
+      },
       onClose: (sid) => {
         this.handleSessionClose(sid);
       }
     });
     this.sessions.set(sessionId, session);
+    this.yjsDocRelay.addClient(sessionId, transport);
     session.start();
+    this.logger.log({
+      timestamp: Date.now(),
+      level: "info",
+      event: "session.connected",
+      sessionId,
+      details: { totalSessions: this.sessions.size }
+    });
     return sessionId;
   }
   /**
    * Get the current server status.
    */
   async getStatus() {
+    const totalOps = await this.store.getOperationCount();
+    const snapshot = this.metrics.getSnapshot(totalOps);
     return {
       running: this.running,
-      connectedClients: this.sessions.size,
+      connectedClients: snapshot.connectedClients,
       port: this.port ?? null,
-      totalOperations: await this.store.getOperationCount()
+      totalOperations: snapshot.totalOperations,
+      uptime: snapshot.uptime,
+      version: this.serverVersion,
+      schemaVersion: this.schemaVersion,
+      connectedNodeIds: snapshot.connectedNodeIds,
+      peakConnections: snapshot.peakConnections,
+      connectionsTotal: snapshot.connectionsTotal,
+      operationsReceived: snapshot.operationsReceived,
+      operationsSent: snapshot.operationsSent,
+      errorCount: snapshot.errorCount
     };
   }
   /**
@@ -2243,13 +3121,31 @@ var KoraSyncServer = class {
   }
   // --- Private ---
   handleRelay(sourceSessionId, operations2) {
+    const targetCount = this.sessions.size - 1;
+    const byteSize = estimateOperationByteSize(operations2);
+    this.metrics.recordSent(
+      sourceSessionId,
+      operations2.length * targetCount,
+      byteSize * targetCount
+    );
+    this.logger.log({
+      timestamp: Date.now(),
+      level: "info",
+      event: "operations.relayed",
+      sessionId: sourceSessionId,
+      count: operations2.length,
+      bytes: byteSize * targetCount,
+      details: { targetSessions: targetCount }
+    });
     for (const [sessionId, session] of this.sessions) {
       if (sessionId === sourceSessionId) continue;
       session.relayOperations(operations2);
     }
   }
   handleSessionClose(sessionId) {
+    this.metrics.recordDisconnection(sessionId);
     this.awarenessRelay.removeClient(sessionId);
+    this.yjsDocRelay.removeClient(sessionId);
     this.sessions.delete(sessionId);
     const clientId = this.httpSessionToClient.get(sessionId);
     if (clientId) {
@@ -2266,6 +3162,12 @@ var KoraSyncServer = class {
     this.awarenessRelay.addClient(sourceSessionId, message.clientId, transport);
     this.awarenessRelay.handleUpdate(sourceSessionId, message);
   }
+  handleYjsDocRelay(sourceSessionId, message) {
+    if (!this.sessions.has(sourceSessionId)) {
+      return;
+    }
+    this.yjsDocRelay.handleUpdate(sourceSessionId, message);
+  }
   getOrCreateHttpClient(clientId) {
     const existing = this.httpClients.get(clientId);
     if (existing) {
@@ -2279,6 +3181,13 @@ var KoraSyncServer = class {
     return client;
   }
 };
+function estimateOperationByteSize(operations2) {
+  let total = 0;
+  for (const op of operations2) {
+    total += JSON.stringify(op).length;
+  }
+  return total;
+}
 function normalizeHttpBody(body, contentType) {
   if (body instanceof Uint8Array) {
     return body;
@@ -2320,7 +3229,7 @@ var KoraAuthProvider = class {
     this.resolveScopes = options.resolveScopes;
   }
   async authenticate(token) {
-    const payload = this.tokenValidator.validateToken(token);
+    const payload = this.tokenValidator.validateTokenWithRevocation ? await this.tokenValidator.validateTokenWithRevocation(token) : this.tokenValidator.validateToken(token);
     if (payload === null) {
       return null;
     }
@@ -2397,9 +3306,143 @@ function createProductionServer(config) {
   const syncPath = config.syncPath ?? "/kora-sync";
   const syncServer = new KoraSyncServer({
     store: config.store,
+    enableDashboard: true,
     ...config.syncOptions
   });
   let httpServer = null;
+  function getOperationalToken(kind) {
+    const auth = config.operationalAuth;
+    if (!auth) return void 0;
+    if (kind === "metrics") return auth.metricsToken || auth.adminToken;
+    if (kind === "backup") return auth.backupToken || auth.adminToken;
+    return auth.adminToken;
+  }
+  function extractRequestToken(req) {
+    const authorization = req.headers.authorization;
+    if (authorization?.startsWith("Bearer ")) {
+      return authorization.slice("Bearer ".length).trim();
+    }
+    const headerNames = ["x-kora-admin-token", "x-kora-metrics-token", "x-kora-backup-token"];
+    for (const name of headerNames) {
+      const value = req.headers[name];
+      if (typeof value === "string" && value.length > 0) return value;
+      if (Array.isArray(value) && typeof value[0] === "string" && value[0].length > 0) {
+        return value[0];
+      }
+    }
+    return null;
+  }
+  function isOperationalRequestAllowed(req, kind) {
+    const expected = getOperationalToken(kind);
+    if (!expected) return true;
+    return extractRequestToken(req) === expected;
+  }
+  function rejectUnauthorized(res) {
+    res.writeHead(401, {
+      "Content-Type": "application/json",
+      "WWW-Authenticate": 'Bearer realm="kora"'
+    });
+    res.end(JSON.stringify({ error: "Unauthorized" }));
+  }
+  function formatPrometheusMetrics() {
+    const status = syncServer.getMetricsCollector().getSnapshot(0);
+    const lines = [
+      "# HELP kora_connected_clients Current number of connected clients",
+      "# TYPE kora_connected_clients gauge",
+      `kora_connected_clients ${status.connectedClients}`,
+      "",
+      "# HELP kora_peak_connections Peak number of simultaneous connections since server start",
+      "# TYPE kora_peak_connections gauge",
+      `kora_peak_connections ${status.peakConnections}`,
+      "",
+      "# HELP kora_connections_total Total number of connections handled since server start",
+      "# TYPE kora_connections_total counter",
+      `kora_connections_total ${status.connectionsTotal}`,
+      "",
+      "# HELP kora_operations_received_total Total operations received from clients",
+      "# TYPE kora_operations_received_total counter",
+      `kora_operations_received_total ${status.operationsReceived}`,
+      "",
+      "# HELP kora_operations_sent_total Total operations sent to clients",
+      "# TYPE kora_operations_sent_total counter",
+      `kora_operations_sent_total ${status.operationsSent}`,
+      "",
+      "# HELP kora_bytes_received_total Total bytes received from clients",
+      "# TYPE kora_bytes_received_total counter",
+      `kora_bytes_received_total ${status.bytesReceived}`,
+      "",
+      "# HELP kora_bytes_sent_total Total bytes sent to clients",
+      "# TYPE kora_bytes_sent_total counter",
+      `kora_bytes_sent_total ${status.bytesSent}`,
+      "",
+      "# HELP kora_errors_total Total errors since server start",
+      "# TYPE kora_errors_total counter",
+      `kora_errors_total ${status.errorCount}`,
+      "",
+      "# HELP kora_uptime_seconds Server uptime in seconds",
+      "# TYPE kora_uptime_seconds gauge",
+      `kora_uptime_seconds ${Math.floor(status.uptime / 1e3)}`,
+      "",
+      "# HELP kora_schema_version Schema version the server expects",
+      "# TYPE kora_schema_version gauge",
+      `kora_schema_version ${status.schemaVersion}`,
+      ""
+    ];
+    return lines.join("\n");
+  }
+  function readBodyBuffer(req) {
+    return new Promise((resolve) => {
+      const chunks = [];
+      req.on("data", (chunk) => chunks.push(chunk));
+      req.on("end", () => resolve(Buffer.concat(chunks)));
+    });
+  }
+  async function readJsonBody(req) {
+    const buffer = await readBodyBuffer(req);
+    if (buffer.byteLength === 0) return void 0;
+    try {
+      return JSON.parse(buffer.toString("utf8"));
+    } catch {
+      return void 0;
+    }
+  }
+  function matchesRoutePrefix(pathname, prefix) {
+    const normalizedPrefix = normalizeRoutePath(prefix);
+    return pathname === normalizedPrefix || pathname.startsWith(`${normalizedPrefix}/`);
+  }
+  function normalizeRoutePath(path) {
+    const prefixed = path.startsWith("/") ? path : `/${path}`;
+    return prefixed.length > 1 ? prefixed.replace(/\/+$/, "") : prefixed;
+  }
+  function getClientIp(req) {
+    const forwarded = req.headers["x-forwarded-for"];
+    if (typeof forwarded === "string" && forwarded.length > 0) {
+      return forwarded.split(",")[0]?.trim();
+    }
+    return req.socket.remoteAddress;
+  }
+  function getQuery(url) {
+    const query = {};
+    for (const [key, value] of url.searchParams) {
+      const existing = query[key];
+      if (existing === void 0) {
+        query[key] = value;
+      } else if (Array.isArray(existing)) {
+        existing.push(value);
+      } else {
+        query[key] = [existing, value];
+      }
+    }
+    return query;
+  }
+  function writeJsonResponse(res, result) {
+    const headers = {
+      "Content-Type": "application/json",
+      ...result.headers ?? {}
+    };
+    res.writeHead(result.status, headers);
+    res.end(JSON.stringify(result.body ?? null));
+  }
   return {
     async start() {
       const { createServer } = await import("http");
@@ -2407,13 +3450,137 @@ function createProductionServer(config) {
       const { extname, join, resolve } = await import("path");
       const { WebSocketServer } = await import("ws");
       const distDir = resolve(staticDir);
-      httpServer = createServer((req, res) => {
+      httpServer = createServer(async (req, res) => {
         res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
         res.setHeader("Cross-Origin-Embedder-Policy", "require-corp");
         const url = new URL(req.url || "/", `http://${req.headers.host}`);
         if (url.pathname === "/health") {
+          const status = await syncServer.getStatus();
+          res.writeHead(200, { "Content-Type": "application/json" });
+          res.end(
+            JSON.stringify({
+              status: "ok",
+              version: status.version,
+              uptime: status.uptime,
+              connectedClients: status.connectedClients,
+              totalOperations: status.totalOperations,
+              timestamp: Date.now()
+            })
+          );
+          return;
+        }
+        if (url.pathname === "/__kora/status") {
+          if (!isOperationalRequestAllowed(req, "admin")) {
+            rejectUnauthorized(res);
+            return;
+          }
+          const status = await syncServer.getStatus();
           res.writeHead(200, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ status: "ok", timestamp: Date.now() }));
+          res.end(JSON.stringify(status, null, 2));
+          return;
+        }
+        if (url.pathname === "/__kora/metrics") {
+          if (!isOperationalRequestAllowed(req, "metrics")) {
+            rejectUnauthorized(res);
+            return;
+          }
+          res.writeHead(200, { "Content-Type": "text/plain; version=0.0.4" });
+          res.end(formatPrometheusMetrics());
+          return;
+        }
+        if (url.pathname === "/__kora/events") {
+          if (!isOperationalRequestAllowed(req, "admin")) {
+            rejectUnauthorized(res);
+            return;
+          }
+          res.writeHead(200, {
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache",
+            Connection: "keep-alive",
+            "X-Accel-Buffering": "no"
+          });
+          const status = await syncServer.getStatus();
+          res.write(`event: status
+data: ${JSON.stringify(status)}
+
+`);
+          const interval = setInterval(async () => {
+            try {
+              const s = await syncServer.getStatus();
+              res.write(`event: status
+data: ${JSON.stringify(s)}
+
+`);
+            } catch {
+            }
+          }, 2e3);
+          req.on("close", () => {
+            clearInterval(interval);
+          });
+          return;
+        }
+        if (url.pathname === "/__kora" || url.pathname === "/__kora/") {
+          if (!isOperationalRequestAllowed(req, "admin")) {
+            rejectUnauthorized(res);
+            return;
+          }
+          const status = await syncServer.getStatus();
+          res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+          res.end(renderDashboardHtml(status));
+          return;
+        }
+        if (url.pathname === "/__kora/backup/export" && req.method === "POST") {
+          if (!isOperationalRequestAllowed(req, "backup")) {
+            rejectUnauthorized(res);
+            return;
+          }
+          try {
+            const backup = await config.store.exportBackup();
+            res.writeHead(200, {
+              "Content-Type": "application/octet-stream",
+              "Content-Disposition": `attachment; filename="kora-backup-${Date.now()}.kora"`,
+              "Content-Length": String(backup.byteLength)
+            });
+            res.end(Buffer.from(backup));
+          } catch (error) {
+            res.writeHead(500, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Backup failed", message: error.message }));
+          }
+          return;
+        }
+        if (url.pathname === "/__kora/backup/import" && req.method === "POST") {
+          if (!isOperationalRequestAllowed(req, "backup")) {
+            rejectUnauthorized(res);
+            return;
+          }
+          try {
+            const body = await readBodyBuffer(req);
+            const merge = url.searchParams.get("merge") === "true";
+            const result = await config.store.importBackup(
+              new Uint8Array(body.buffer, body.byteOffset, body.byteLength),
+              merge
+            );
+            res.writeHead(result.success ? 200 : 400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify(result));
+          } catch (error) {
+            res.writeHead(500, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Restore failed", message: error.message }));
+          }
+          return;
+        }
+        const customRoute = config.httpRoutes?.find(
+          (route) => matchesRoutePrefix(url.pathname, route.path)
+        );
+        if (customRoute) {
+          const result = await customRoute.handle({
+            method: req.method ?? "GET",
+            path: url.pathname,
+            body: await readJsonBody(req),
+            headers: req.headers,
+            query: getQuery(url),
+            ip: getClientIp(req)
+          });
+          writeJsonResponse(res, result);
           return;
         }
         let filePath = join(distDir, url.pathname);
@@ -2475,6 +3642,82 @@ function createProductionServer(config) {
     }
   };
 }
+function renderDashboardHtml(status) {
+  const version = status.version;
+  const uptime = formatUptime(status.uptime);
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Kora Dashboard</title>
+<style>
+  * { box-sizing: border-box; margin: 0; padding: 0 }
+  body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #0f172a; color: #e2e8f0; padding: 2rem }
+  h1 { font-size: 1.5rem; font-weight: 600; margin-bottom: 0.25rem }
+  .subtitle { color: #64748b; margin-bottom: 2rem; font-size: 0.875rem }
+  .grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(200px, 1fr)); gap: 1rem; margin-bottom: 2rem }
+  .card { background: #1e293b; border: 1px solid #334155; border-radius: 0.75rem; padding: 1.25rem }
+  .card .label { font-size: 0.75rem; text-transform: uppercase; letter-spacing: 0.05em; color: #64748b; margin-bottom: 0.5rem }
+  .card .value { font-size: 1.75rem; font-weight: 700; color: #38bdf8 }
+  .card .value.green { color: #4ade80 }
+  .card .value.red { color: #f87171 }
+  .card .value.yellow { color: #fbbf24 }
+  .section-title { font-size: 1rem; font-weight: 600; margin-bottom: 0.75rem; margin-top: 1.5rem }
+  table { width: 100%; border-collapse: collapse; font-size: 0.875rem }
+  th { text-align: left; padding: 0.5rem 0.75rem; color: #64748b; font-weight: 500; border-bottom: 1px solid #334155 }
+  td { padding: 0.5rem 0.75rem; border-bottom: 1px solid #1e293b }
+  .status-dot { display: inline-block; width: 0.5rem; height: 0.5rem; border-radius: 50%; margin-right: 0.375rem }
+  .status-dot.running { background: #4ade80 }
+  .status-dot.stopped { background: #f87171 }
+</style>
+</head>
+<body>
+<h1>Kora Sync Server</h1>
+<p class="subtitle">v${version} &middot; <span class="status-dot running"></span>Running</p>
+<div class="grid">
+  <div class="card"><div class="label">Uptime</div><div class="value">${uptime}</div></div>
+  <div class="card"><div class="label">Connected Clients</div><div class="value" id="connectedClients">${status.connectedClients}</div></div>
+  <div class="card"><div class="label">Total Operations</div><div class="value" id="totalOperations">${status.totalOperations}</div></div>
+  <div class="card"><div class="label">Peak Connections</div><div class="value green" id="peakConnections">${status.peakConnections}</div></div>
+  <div class="card"><div class="label">Ops Received</div><div class="value" id="opsReceived">${status.operationsReceived}</div></div>
+  <div class="card"><div class="label">Ops Sent</div><div class="value" id="opsSent">${status.operationsSent}</div></div>
+  <div class="card"><div class="label">Errors</div><div class="value ${status.errorCount > 0 ? "red" : "green"}" id="errors">${status.errorCount}</div></div>
+  <div class="card"><div class="label">Schema Version</div><div class="value">${status.schemaVersion}</div></div>
+</div>
+<script>
+(function() {
+  const es = new EventSource('/__kora/events');
+  es.addEventListener('status', (e) => {
+    const s = JSON.parse(e.data);
+    for (const [id, val] of Object.entries({
+      connectedClients: s.connectedClients,
+      totalOperations: s.totalOperations,
+      peakConnections: s.peakConnections,
+      opsReceived: s.operationsReceived,
+      opsSent: s.operationsSent,
+      errors: s.errorCount,
+    })) {
+      const el = document.getElementById(id);
+      if (el) { el.textContent = String(val); el.className = 'value' + (id === 'errors' && val > 0 ? ' red' : id === 'errors' ? ' green' : ''); }
+    }
+  });
+  es.onerror = () => { setTimeout(() => document.location.reload(), 5000); };
+})();
+</script>
+</body>
+</html>`;
+}
+function formatUptime(ms) {
+  const seconds = Math.floor(ms / 1e3);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+  const parts = [];
+  if (hours > 0) parts.push(`${hours}h`);
+  if (minutes % 60 > 0) parts.push(`${minutes % 60}m`);
+  parts.push(`${seconds % 60}s`);
+  return parts.join(" ");
+}
 export {
   AwarenessRelay,
   ClientSession,
@@ -2488,9 +3731,13 @@ export {
   SqliteServerStore,
   TokenAuthProvider,
   WsServerTransport,
+  createDefaultLogger,
+  createJsonLogger,
   createKoraServer,
   createPostgresServerStore,
+  createPrettyLogger,
   createProductionServer,
+  createSilentLogger,
   createSqliteServerStore
 };
 //# sourceMappingURL=index.js.map