@open-mercato/documents 0.6.8-develop.7016.1.4ed7b1e49d

package/dist/server/documents-collab-server.js

@@ -0,0 +1,2260 @@
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { randomUUID } from "node:crypto";
+import { LockMode } from "@mikro-orm/core";
+import {
+  Connection as HocuspocusConnection,
+  IncomingMessage as HocuspocusIncomingMessage,
+  MessageReceiver as HocuspocusMessageReceiver,
+  MessageType,
+  OutgoingMessage as HocuspocusOutgoingMessage
+} from "@hocuspocus/server";
+import { Redis as HocuspocusRedis } from "@hocuspocus/extension-redis";
+import * as Y from "yjs";
+import { hasAllFeatures } from "@open-mercato/shared/lib/auth/featureMatch";
+import { isCrudHttpError } from "@open-mercato/shared/lib/crud/errors";
+import { findOneWithDecryption } from "@open-mercato/shared/lib/encryption/find";
+import { createLogger } from "@open-mercato/shared/lib/logger";
+import { OPTIMISTIC_LOCK_CONFLICT_CODE } from "@open-mercato/shared/lib/crud/optimistic-lock-headers";
+import {
+  COLLAB_TOKEN_CLOCK_SKEW_SECONDS,
+  COLLAB_TOKEN_TTL_SECONDS,
+  isCollabTokenV2Ready,
+  resolveLegacyCollabTokenVerifier,
+  verifyCollabTokenV2
+} from "@open-mercato/documents/modules/documents/lib/collabToken";
+import {
+  advanceDocumentCollaborationGeneration,
+  loadDocumentCollaborationGeneration,
+  loadDocumentContentForCollaboration,
+  normalizeDocumentCollaborationGeneration,
+  persistDocumentContent
+} from "@open-mercato/documents/modules/documents/lib/contentService";
+import {
+  htmlToYDoc,
+  yDocToContent
+} from "@open-mercato/documents/modules/documents/lib/collabMaterializer";
+import { Document, DocumentContent } from "@open-mercato/documents/modules/documents/data/entities";
+import { deriveDocumentCapabilities } from "@open-mercato/documents/modules/documents/lib/capabilities";
+import { resolveUserAccess } from "@open-mercato/documents/modules/documents/lib/permissions";
+import { resolveUserLabels } from "@open-mercato/documents/modules/documents/lib/userLabels";
+import { resolveOrganizationScopeService } from "@open-mercato/documents/modules/documents/lib/platformServices";
+import {
+  hasResolvedDocumentsOrganizationAccess
+} from "@open-mercato/documents/modules/documents/lib/organizationAccess";
+import {
+  createCanonicalCollaborationAwarenessUser
+} from "@open-mercato/documents/modules/documents/lib/collaborationAwareness";
+import {
+  assertDocumentContentResourceLimits,
+  assertDocumentYjsStateByteLength,
+  DOCUMENTS_COLLAB_MAX_PAYLOAD_BYTES
+} from "@open-mercato/documents/modules/documents/lib/resourceLimits";
+import { COLLAB_CONTENT_RESET_CLOSE_EVENT } from "@open-mercato/documents/modules/documents/lib/collabCloseEvents";
+const logger = createLogger("documents-collab");
+const MAX_COLLAB_STORE_ATTEMPTS = 4;
+const DOCUMENTS_COLLAB_MAX_AWARENESS_STATE_BYTES = 8 * 1024;
+const DOCUMENTS_COLLAB_MAX_AWARENESS_CLIENT_IDS_PER_CONNECTION = 1;
+const DOCUMENTS_COLLAB_MAX_AWARENESS_CLIENT_IDS_PER_ROOM = 256;
+const MAX_YJS_CLIENT_ID = 4294967295;
+const COLLAB_SERVER_TRANSPORT_OPTIONS = {
+  maxPayload: DOCUMENTS_COLLAB_MAX_PAYLOAD_BYTES
+};
+const DOCUMENTS_COLLAB_MAX_PENDING_MESSAGES = 128;
+const DOCUMENTS_COLLAB_MAX_PENDING_BYTES = DOCUMENTS_COLLAB_MAX_PAYLOAD_BYTES * 2;
+const DOCUMENTS_COLLAB_MAX_PENDING_DOCUMENTS = 32;
+const DOCUMENTS_COLLAB_MAX_AWARENESS_FRAME_BYTES = 32 * 1024;
+const DOCUMENTS_COLLAB_MAX_CONTROL_FRAME_BYTES = 64 * 1024;
+const DOCUMENTS_COLLAB_MAX_READ_ONLY_SYNC_FRAME_BYTES = 256 * 1024;
+const DOCUMENTS_COLLAB_AUTHORIZATION_TICKET_TIMEOUT_MS = 6e4;
+const DOCUMENTS_COLLAB_ACTIVE_REAUTHORIZATION_INTERVAL_MS = 15e3;
+const COLLAB_SERVER_WEBSOCKET_CONFIGURATION = {
+  websocketOptions: COLLAB_SERVER_TRANSPORT_OPTIONS
+};
+const COLLAB_SERVER_UNAUTHENTICATED_CONFIGURATION = {
+  maxUnauthenticatedQueueSize: DOCUMENTS_COLLAB_MAX_PENDING_BYTES,
+  maxUnauthenticatedQueueMessages: DOCUMENTS_COLLAB_MAX_PENDING_MESSAGES,
+  maxPendingDocuments: DOCUMENTS_COLLAB_MAX_PENDING_DOCUMENTS
+};
+const COLLAB_SERVER_RUNTIME_CONFIGURATION = {
+  ...COLLAB_SERVER_WEBSOCKET_CONFIGURATION,
+  ...COLLAB_SERVER_UNAUTHENTICATED_CONFIGURATION
+};
+const DEFAULT_DOCUMENTS_COLLAB_REDIS_PREFIX = "open-mercato:documents:collab:development";
+const LEGACY_DOCUMENTS_COLLAB_REDIS_PREFIX = "open-mercato:documents:collab";
+const DOCUMENTS_COLLAB_REDIS_PREFIX_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9._:-]{0,158}[A-Za-z0-9])?$/;
+function resolveDocumentsCollabRedisPrefix(environment) {
+  const configured = environment.DOCUMENTS_COLLAB_REDIS_PREFIX?.trim() ?? "";
+  if (!configured && environment.NODE_ENV === "production") {
+    throw new Error(
+      "[internal] DOCUMENTS_COLLAB_REDIS_PREFIX is required in production when collaboration Redis is configured"
+    );
+  }
+  const prefix = configured || DEFAULT_DOCUMENTS_COLLAB_REDIS_PREFIX;
+  if (prefix === LEGACY_DOCUMENTS_COLLAB_REDIS_PREFIX || !DOCUMENTS_COLLAB_REDIS_PREFIX_PATTERN.test(prefix)) {
+    throw new Error(
+      "[internal] DOCUMENTS_COLLAB_REDIS_PREFIX must be a deployment-scoped Redis key prefix using letters, numbers, dot, underscore, colon, or dash"
+    );
+  }
+  return prefix;
+}
+function resolveDocumentsCollabRedisConfiguration(environment = process.env) {
+  const configured = environment.DOCUMENTS_COLLAB_REDIS_URL?.trim() || environment.REDIS_URL?.trim() || "";
+  if (!configured) return null;
+  let parsed;
+  try {
+    parsed = new URL(configured);
+  } catch {
+    throw new Error("[internal] Documents collaboration Redis URL is invalid");
+  }
+  if (parsed.protocol !== "redis:" && parsed.protocol !== "rediss:" || !parsed.hostname) {
+    throw new Error("[internal] Documents collaboration Redis URL must use redis:// or rediss://");
+  }
+  const port = parsed.port ? Number(parsed.port) : 6379;
+  const databasePath = parsed.pathname.replace(/^\//, "");
+  const db = databasePath ? Number(databasePath) : void 0;
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error("[internal] Documents collaboration Redis port is invalid");
+  }
+  if (db !== void 0 && (!Number.isInteger(db) || db < 0)) {
+    throw new Error("[internal] Documents collaboration Redis database is invalid");
+  }
+  return {
+    host: parsed.hostname,
+    port,
+    prefix: resolveDocumentsCollabRedisPrefix(environment),
+    options: {
+      ...parsed.username ? { username: decodeURIComponent(parsed.username) } : {},
+      ...parsed.password ? { password: decodeURIComponent(parsed.password) } : {},
+      ...db !== void 0 ? { db } : {},
+      ...parsed.protocol === "rediss:" ? { tls: {} } : {},
+      maxRetriesPerRequest: null
+    }
+  };
+}
+const DOCUMENTS_COLLAB_REDIS_FANOUT_COMMAND_TIMEOUT_MS = 1e3;
+const DOCUMENTS_COLLAB_REDIS_FANOUT_RETRY_MIN_MS = 250;
+const DOCUMENTS_COLLAB_REDIS_FANOUT_RETRY_MAX_MS = 5e3;
+const DOCUMENTS_COLLAB_REDIS_FANOUT_SHUTDOWN_TIMEOUT_MS = 1500;
+const DOCUMENTS_COLLAB_REDIS_LOCK_RELEASE_TIMEOUT_MS = 1250;
+const DOCUMENTS_COLLAB_REDIS_SUBSCRIBE_TIMEOUT_MS = 5e3;
+const DOCUMENTS_COLLAB_REDIS_FANOUT_MAX_PENDING_ROOMS = 256;
+const DOCUMENTS_COLLAB_REDIS_FANOUT_MAX_PENDING_BYTES = DOCUMENTS_COLLAB_MAX_PAYLOAD_BYTES * 8;
+const DOCUMENTS_COLLAB_REDIS_FANOUT_MAGIC = Buffer.from("OMDF1", "ascii");
+const DOCUMENTS_COLLAB_REDIS_FANOUT_GENERATION_BYTES = 8;
+function isHocuspocusStoreLockContention(error) {
+  return error instanceof Error && error.name === "SkipFurtherHooksError";
+}
+function isDocumentsCollabSourceStore(payload) {
+  const origin = payload.lastTransactionOrigin;
+  return !(origin && typeof origin === "object" && "source" in origin && origin.source === "redis");
+}
+function enforceDocumentsCollabSourceStoreOwnership(extension) {
+  const onStoreDocument = extension.onStoreDocument.bind(extension);
+  extension.onStoreDocument = async (payload) => {
+    if (!isDocumentsCollabSourceStore(payload)) return;
+    try {
+      return await onStoreDocument(payload);
+    } catch (error) {
+      if (isHocuspocusStoreLockContention(error)) {
+        void payload.instance.storeDocumentHooks(payload.document, payload);
+      }
+      throw error;
+    }
+  };
+  return extension;
+}
+function assertDocumentsCollabRedisAggregateUpdate(document, update) {
+  const candidate = new Y.Doc();
+  try {
+    Y.applyUpdate(candidate, Y.encodeStateAsUpdate(document));
+    Y.applyUpdate(candidate, update);
+    return assertDocumentsCollabRedisAggregateState(candidate);
+  } finally {
+    candidate.destroy();
+  }
+}
+function assertDocumentsCollabRedisAggregateState(document) {
+  const materialized = yDocToContent(document);
+  const yjsState = Y.encodeStateAsUpdate(document);
+  assertDocumentContentResourceLimits({
+    yjsState,
+    contentHtml: materialized?.html,
+    contentText: materialized?.text
+  });
+  return yjsState.byteLength;
+}
+class DocumentsCollabRedisExtension extends HocuspocusRedis {
+  constructor(configuration, options = {}) {
+    super(configuration);
+    this.persistedStates = /* @__PURE__ */ new WeakMap();
+    this.pendingFanouts = /* @__PURE__ */ new Map();
+    this.activeFanouts = /* @__PURE__ */ new Set();
+    this.fanoutRetryAttempts = /* @__PURE__ */ new Map();
+    this.fanoutRetryTimers = /* @__PURE__ */ new Map();
+    this.pendingLocalAfterStoreDelays = /* @__PURE__ */ new Map();
+    this.invalidatedFanoutDocuments = /* @__PURE__ */ new WeakSet();
+    this.bufferedFanouts = /* @__PURE__ */ new WeakMap();
+    this.bufferedFanoutBytes = /* @__PURE__ */ new WeakMap();
+    this.nextFanoutRevision = 0;
+    this.pendingFanoutBytes = 0;
+    this.fanoutDestroyed = false;
+    /**
+     * Hocuspocus does not publish a loading document in instance.documents until
+     * after afterLoadDocument completes. Keep the hook payload reachable so a
+     * Redis update received while the scoped database snapshot is loading can be
+     * applied to that same Y.Doc instead of being silently dropped.
+     */
+    this.knownDocuments = /* @__PURE__ */ new Map();
+    /**
+     * EventEmitter never observes the promise an async listener returns, so a
+     * truncated frame, a receiver failure, or a failed reply publish would become
+     * an unhandled rejection and terminate the sidecar. Keep the registered
+     * listener synchronous and terminate every rejection here instead: one
+     * malformed frame must cost at most that frame.
+     */
+    this.receiveDocumentsRedisMessage = (channel, data) => {
+      void this.handleDocumentsRedisMessage(channel, data).catch((error) => {
+        logger.warn("rejected malformed Redis collaboration frame", {
+          error: error instanceof Error ? error.message : String(error)
+        });
+      });
+    };
+    this.handleDocumentsRedisMessage = async (_channel, data) => {
+      const identifierLength = data[0];
+      if (identifierLength === void 0 || data.byteLength <= identifierLength + 1) return;
+      const identifier = data.toString("utf8", 1, identifierLength + 1);
+      if (identifier === this.configuration.identifier) return;
+      const redisPayload = data.subarray(identifierLength + 1);
+      let collaborationGeneration;
+      let messageBuffer = redisPayload;
+      if (redisPayload.byteLength >= DOCUMENTS_COLLAB_REDIS_FANOUT_MAGIC.byteLength + DOCUMENTS_COLLAB_REDIS_FANOUT_GENERATION_BYTES && redisPayload.subarray(0, DOCUMENTS_COLLAB_REDIS_FANOUT_MAGIC.byteLength).equals(DOCUMENTS_COLLAB_REDIS_FANOUT_MAGIC)) {
+        const generationOffset = DOCUMENTS_COLLAB_REDIS_FANOUT_MAGIC.byteLength;
+        const encodedGeneration = redisPayload.readBigUInt64BE(generationOffset);
+        if (encodedGeneration > BigInt(Number.MAX_SAFE_INTEGER) || encodedGeneration < 1n) return;
+        collaborationGeneration = Number(encodedGeneration);
+        messageBuffer = redisPayload.subarray(
+          generationOffset + DOCUMENTS_COLLAB_REDIS_FANOUT_GENERATION_BYTES
+        );
+      }
+      const header = new HocuspocusIncomingMessage(messageBuffer);
+      const documentName = header.readVarString();
+      const document = this.instance.documents.get(documentName) ?? this.knownDocuments.get(documentName);
+      if (!document) return;
+      const messageType = header.readVarUint();
+      if (messageType === MessageType.Sync || messageType === MessageType.SyncReply) {
+        const syncType = header.readVarUint();
+        if (messageType !== MessageType.Sync || syncType !== 2) return;
+        if (collaborationGeneration === void 0) {
+          logger.warn("rejected unversioned Redis collaboration update", { room: documentName });
+          return;
+        }
+        const update = header.readVarUint8Array();
+        this.applyDurableFanout(
+          identifier,
+          documentName,
+          document,
+          collaborationGeneration,
+          update
+        );
+        return;
+      }
+      const receiverMessage = new HocuspocusIncomingMessage(messageBuffer);
+      receiverMessage.readVarString();
+      receiverMessage.writeVarString(documentName);
+      const receiver = new HocuspocusMessageReceiver(
+        receiverMessage,
+        this.redisTransactionOrigin
+      );
+      await receiver.apply(document, void 0, (reply) => {
+        void this.publishRedisMessage(documentName, reply).catch((error) => {
+          logger.warn("failed to publish Redis collaboration reply", {
+            room: documentName,
+            error: error instanceof Error ? error.message : String(error)
+          });
+        });
+      });
+    };
+    this.onRejectedAggregate = options.onRejectedAggregate;
+    this.onAcceptedAggregate = options.onAcceptedAggregate;
+    this.resolveCollaborationGeneration = options.resolveCollaborationGeneration;
+    this.fanoutPublisher = this.pub.duplicate({
+      autoResendUnfulfilledCommands: false,
+      commandTimeout: DOCUMENTS_COLLAB_REDIS_FANOUT_COMMAND_TIMEOUT_MS,
+      enableOfflineQueue: false,
+      maxRetriesPerRequest: 1
+    });
+    for (const listener of this.sub.listeners("messageBuffer")) {
+      this.sub.off("messageBuffer", listener);
+    }
+    this.sub.on("messageBuffer", this.receiveDocumentsRedisMessage);
+  }
+  markPersisted(document, yjsState, collaborationGeneration) {
+    if (this.invalidatedFanoutDocuments.has(document)) return;
+    this.persistedStates.set(document, {
+      collaborationGeneration,
+      state: Uint8Array.from(yjsState)
+    });
+  }
+  async onLoadDocument(data) {
+    const { documentName, document } = data;
+    this.knownDocuments.set(documentName, document);
+    const loadingDocument = data.instance.loadingDocuments.get(documentName);
+    if (loadingDocument) {
+      void loadingDocument.catch(() => {
+        if (this.knownDocuments.get(documentName) === document && !data.instance.documents.has(documentName)) {
+          this.knownDocuments.delete(documentName);
+          void this.sub.unsubscribe(this.redisKey(documentName)).catch(() => void 0);
+        }
+      });
+    }
+    try {
+      await this.subscribeDocument(documentName);
+    } catch (error) {
+      if (this.knownDocuments.get(documentName) === document) {
+        this.knownDocuments.delete(documentName);
+      }
+      throw error;
+    }
+  }
+  async afterLoadDocument({
+    documentName,
+    document
+  }) {
+    let aggregateByteLength;
+    try {
+      this.applyBufferedFanouts(documentName, document);
+      aggregateByteLength = assertDocumentsCollabRedisAggregateState(document);
+    } catch (error) {
+      this.onRejectedAggregate?.(documentName, document);
+      throw error;
+    }
+    this.onAcceptedAggregate?.(document, aggregateByteLength);
+    const awarenessQuery = new HocuspocusOutgoingMessage(documentName).writeQueryAwareness().toUint8Array();
+    await this.publishRedisMessage(documentName, awarenessQuery);
+  }
+  async afterUnloadDocument(data) {
+    if (data.instance.documents.has(data.documentName) || data.instance.loadingDocuments.has(data.documentName)) return;
+    this.knownDocuments.delete(data.documentName);
+    await super.afterUnloadDocument(data);
+  }
+  /**
+   * The subscriber client keeps ioredis' offline queue enabled, so a room load
+   * started during a Redis outage would otherwise wait for recovery with no
+   * deadline while its socket stays open. Fail the load instead: onLoadDocument
+   * releases the early subscription and Hocuspocus rejects the connection, so
+   * the client can retry rather than hanging against a green health check.
+   */
+  async subscribeDocument(documentName) {
+    await new Promise((resolve2, reject) => {
+      const deadline = setTimeout(() => {
+        reject(new Error("[internal] documents collab: Redis room subscription timed out"));
+      }, DOCUMENTS_COLLAB_REDIS_SUBSCRIBE_TIMEOUT_MS);
+      deadline.unref?.();
+      this.sub.subscribe(this.redisKey(documentName), (error) => {
+        clearTimeout(deadline);
+        if (error) reject(error);
+        else resolve2();
+      });
+    });
+  }
+  async onChange(_data) {
+  }
+  async afterStoreDocument(data) {
+    const persistedState = this.persistedStates.get(data.document);
+    this.persistedStates.delete(data.document);
+    try {
+      await this.releaseStoreLock(data);
+    } finally {
+      if (persistedState && isDocumentsCollabSourceStore(data) && !this.invalidatedFanoutDocuments.has(data.document)) {
+        this.queuePersistedFanout(
+          data.documentName,
+          data.document,
+          persistedState.state,
+          persistedState.collaborationGeneration
+        );
+      }
+    }
+  }
+  async releaseStoreLock(data) {
+    const lockKey = `${this.redisKey(data.documentName)}:lock`;
+    const lockState = this.locks.get(lockKey);
+    if (lockState) {
+      let timeout = null;
+      try {
+        const releasing = lockState.lock.release();
+        lockState.release = releasing;
+        const deadline = new Promise((resolve2) => {
+          timeout = setTimeout(
+            () => resolve2(false),
+            DOCUMENTS_COLLAB_REDIS_LOCK_RELEASE_TIMEOUT_MS
+          );
+          timeout.unref?.();
+        });
+        const released = await Promise.race([
+          releasing.then(
+            () => true,
+            () => true
+          ),
+          deadline
+        ]);
+        if (!released) {
+          void releasing.catch(() => void 0);
+          logger.warn("Redis collaboration store lock release timed out; continuing after TTL", {
+            room: data.documentName
+          });
+        }
+      } catch {
+      } finally {
+        if (timeout) clearTimeout(timeout);
+        if (this.locks.get(lockKey) === lockState) this.locks.delete(lockKey);
+      }
+    }
+    await this.delayLocalAfterStore(data);
+  }
+  async delayLocalAfterStore(data) {
+    const origin = data.lastTransactionOrigin;
+    if (!origin || typeof origin !== "object" || !("source" in origin) || origin.source !== "local") return;
+    const previous = this.pendingLocalAfterStoreDelays.get(data.documentName);
+    if (previous) {
+      clearTimeout(previous.timeout);
+      this.pendingLocalAfterStoreDelays.delete(data.documentName);
+      previous.resolve();
+    }
+    await new Promise((resolve2) => {
+      const finish = () => {
+        const current = this.pendingLocalAfterStoreDelays.get(data.documentName);
+        if (current?.resolve === finish) {
+          this.pendingLocalAfterStoreDelays.delete(data.documentName);
+        }
+        resolve2();
+      };
+      const timeout = setTimeout(finish, this.configuration.disconnectDelay);
+      this.pendingLocalAfterStoreDelays.set(data.documentName, { timeout, resolve: finish });
+    });
+  }
+  discardPendingFanout(documentName, document) {
+    if (document) this.invalidatedFanoutDocuments.add(document);
+    const pending = this.pendingFanouts.get(documentName);
+    if (document && pending && pending.document !== document) return;
+    this.forgetPendingFanout(documentName);
+  }
+  removePendingFanoutEntry(documentName) {
+    const pending = this.pendingFanouts.get(documentName);
+    if (!pending) return;
+    this.pendingFanoutBytes -= pending.message.byteLength;
+    this.pendingFanouts.delete(documentName);
+  }
+  forgetPendingFanout(documentName) {
+    this.removePendingFanoutEntry(documentName);
+    this.fanoutRetryAttempts.delete(documentName);
+    const retryTimer = this.fanoutRetryTimers.get(documentName);
+    if (retryTimer) clearTimeout(retryTimer);
+    this.fanoutRetryTimers.delete(documentName);
+  }
+  /**
+   * A pending fanout carries the room's complete post-store state and pins its
+   * Y.Doc, so an unreachable Redis would otherwise let one entry per edited
+   * document accumulate for the whole outage — long after those rooms unload.
+   * Bound the backlog by dropping the least recently refreshed rooms: their
+   * state is already durable, every later fanout for a room supersedes the one
+   * dropped here, and a peer that never sees the frame reloads authoritative
+   * content on its next load anyway.
+   */
+  evictOverflowingFanouts(retainedDocumentName) {
+    for (const documentName of this.pendingFanouts.keys()) {
+      if (this.pendingFanouts.size <= DOCUMENTS_COLLAB_REDIS_FANOUT_MAX_PENDING_ROOMS && this.pendingFanoutBytes <= DOCUMENTS_COLLAB_REDIS_FANOUT_MAX_PENDING_BYTES) return;
+      if (documentName === retainedDocumentName) continue;
+      this.forgetPendingFanout(documentName);
+      logger.warn("dropped a stale pending Redis collaboration fanout to bound the outage backlog", {
+        room: documentName,
+        pendingRooms: this.pendingFanouts.size,
+        pendingBytes: this.pendingFanoutBytes
+      });
+    }
+  }
+  queuePersistedFanout(documentName, document, persistedState, collaborationGeneration) {
+    if (this.fanoutDestroyed) return;
+    const message = new HocuspocusOutgoingMessage(documentName).createSyncMessage().writeUpdate(persistedState).toUint8Array();
+    this.removePendingFanoutEntry(documentName);
+    this.pendingFanouts.set(documentName, {
+      document,
+      collaborationGeneration,
+      revision: ++this.nextFanoutRevision,
+      message
+    });
+    this.pendingFanoutBytes += message.byteLength;
+    this.evictOverflowingFanouts(documentName);
+    this.startPersistedFanout(documentName);
+  }
+  startPersistedFanout(documentName) {
+    if (this.fanoutDestroyed || this.activeFanouts.has(documentName) || this.fanoutRetryTimers.has(documentName) || !this.pendingFanouts.has(documentName)) return;
+    this.activeFanouts.add(documentName);
+    void this.drainPersistedFanout(documentName).finally(() => {
+      this.activeFanouts.delete(documentName);
+      if (!this.fanoutDestroyed && this.pendingFanouts.has(documentName) && !this.fanoutRetryTimers.has(documentName)) {
+        this.startPersistedFanout(documentName);
+      }
+    });
+  }
+  async drainPersistedFanout(documentName) {
+    const pending = this.pendingFanouts.get(documentName);
+    if (!pending || this.fanoutDestroyed) return;
+    try {
+      await this.publishRedisMessage(
+        documentName,
+        pending.message,
+        this.fanoutPublisher,
+        pending.collaborationGeneration
+      );
+    } catch (error) {
+      if (this.fanoutDestroyed || !this.pendingFanouts.has(documentName)) return;
+      const attempt = (this.fanoutRetryAttempts.get(documentName) ?? 0) + 1;
+      this.fanoutRetryAttempts.set(documentName, attempt);
+      const delay = Math.min(
+        DOCUMENTS_COLLAB_REDIS_FANOUT_RETRY_MAX_MS,
+        DOCUMENTS_COLLAB_REDIS_FANOUT_RETRY_MIN_MS * 2 ** Math.min(attempt - 1, 8)
+      );
+      logger.warn("durable Redis collaboration fanout failed; retrying latest state", {
+        room: documentName,
+        attempt,
+        error: error instanceof Error ? error.message : String(error)
+      });
+      const retryTimer = setTimeout(() => {
+        this.fanoutRetryTimers.delete(documentName);
+        this.startPersistedFanout(documentName);
+      }, delay);
+      retryTimer.unref?.();
+      this.fanoutRetryTimers.set(documentName, retryTimer);
+      return;
+    }
+    this.fanoutRetryAttempts.delete(documentName);
+    if (this.pendingFanouts.get(documentName)?.revision === pending.revision) {
+      this.removePendingFanoutEntry(documentName);
+    }
+  }
+  redisKey(documentName) {
+    return `${this.configuration.prefix}:${documentName}`;
+  }
+  encodeRedisMessage(message) {
+    return Buffer.concat([this.messagePrefix, Buffer.from(message)]);
+  }
+  encodeDurableFanoutMessage(message, collaborationGeneration) {
+    if (!Number.isSafeInteger(collaborationGeneration) || collaborationGeneration < 1) {
+      throw new Error("[internal] documents collab: invalid Redis fanout generation");
+    }
+    const generation = Buffer.allocUnsafe(DOCUMENTS_COLLAB_REDIS_FANOUT_GENERATION_BYTES);
+    generation.writeBigUInt64BE(BigInt(collaborationGeneration));
+    return Buffer.concat([
+      this.messagePrefix,
+      DOCUMENTS_COLLAB_REDIS_FANOUT_MAGIC,
+      generation,
+      Buffer.from(message)
+    ]);
+  }
+  async publishRedisMessage(documentName, message, publisher = this.pub, collaborationGeneration) {
+    return await publisher.publish(
+      this.redisKey(documentName),
+      collaborationGeneration === void 0 ? this.encodeRedisMessage(message) : this.encodeDurableFanoutMessage(message, collaborationGeneration)
+    );
+  }
+  bufferDurableFanout(sender, documentName, document, collaborationGeneration, update) {
+    const buffered = this.bufferedFanouts.get(document) ?? /* @__PURE__ */ new Map();
+    const previous = buffered.get(sender);
+    const bufferedBytes = (this.bufferedFanoutBytes.get(document) ?? 0) - (previous?.update.byteLength ?? 0) + update.byteLength;
+    if (!previous && buffered.size >= DOCUMENTS_COLLAB_MAX_PENDING_MESSAGES || bufferedBytes > DOCUMENTS_COLLAB_MAX_PENDING_BYTES) {
+      this.bufferedFanouts.delete(document);
+      this.bufferedFanoutBytes.delete(document);
+      this.onRejectedAggregate?.(documentName, document);
+      logger.warn("rejected buffered Redis collaboration updates that exceeded load limits", {
+        room: documentName
+      });
+      return;
+    }
+    buffered.set(sender, {
+      collaborationGeneration,
+      update: Uint8Array.from(update)
+    });
+    this.bufferedFanouts.set(document, buffered);
+    this.bufferedFanoutBytes.set(document, bufferedBytes);
+  }
+  applyDurableFanout(sender, documentName, document, collaborationGeneration, update) {
+    const loadedGeneration = this.resolveCollaborationGeneration?.(document);
+    if (loadedGeneration === void 0) {
+      this.bufferDurableFanout(
+        sender,
+        documentName,
+        document,
+        collaborationGeneration,
+        update
+      );
+      return;
+    }
+    if (loadedGeneration !== collaborationGeneration) {
+      logger.warn("rejected stale Redis collaboration update from another generation", {
+        room: documentName,
+        expectedGeneration: loadedGeneration,
+        receivedGeneration: collaborationGeneration
+      });
+      return;
+    }
+    let aggregateByteLength;
+    try {
+      aggregateByteLength = assertDocumentsCollabRedisAggregateUpdate(document, update);
+    } catch (error) {
+      if (isCrudHttpError(error) && error.status === 413) {
+        this.onRejectedAggregate?.(documentName, document);
+        logger.warn("rejected Redis collaboration update that exceeded room limits", {
+          room: documentName
+        });
+        return;
+      }
+      logger.warn("rejected malformed Redis collaboration update", {
+        room: documentName,
+        error: error instanceof Error ? error.message : String(error)
+      });
+      return;
+    }
+    this.onAcceptedAggregate?.(document, aggregateByteLength);
+    Y.applyUpdate(document, update, this.redisTransactionOrigin);
+  }
+  applyBufferedFanouts(documentName, document) {
+    const buffered = this.bufferedFanouts.get(document);
+    this.bufferedFanouts.delete(document);
+    this.bufferedFanoutBytes.delete(document);
+    if (!buffered) return;
+    const loadedGeneration = this.resolveCollaborationGeneration?.(document);
+    if (loadedGeneration === void 0) {
+      this.onRejectedAggregate?.(documentName, document);
+      throw new Error("[internal] documents collab: loaded room has no collaboration generation");
+    }
+    for (const [sender, fanout] of buffered) {
+      this.applyDurableFanout(
+        sender,
+        documentName,
+        document,
+        fanout.collaborationGeneration,
+        fanout.update
+      );
+    }
+  }
+  async flushPendingFanoutsBeforeDestroy() {
+    const pending = [...this.pendingFanouts.entries()];
+    if (pending.length === 0) return;
+    const attempts = Promise.allSettled(pending.map(async ([documentName, fanout]) => {
+      await this.publishRedisMessage(
+        documentName,
+        fanout.message,
+        this.fanoutPublisher,
+        fanout.collaborationGeneration
+      );
+    }));
+    let timeout = null;
+    const deadline = new Promise((resolve2) => {
+      timeout = setTimeout(() => resolve2(null), DOCUMENTS_COLLAB_REDIS_FANOUT_SHUTDOWN_TIMEOUT_MS);
+      timeout.unref?.();
+    });
+    const results = await Promise.race([attempts, deadline]);
+    if (timeout) clearTimeout(timeout);
+    if (results === null) {
+      logger.warn("durable Redis collaboration fanout did not drain before shutdown", {
+        pending: pending.length
+      });
+      return;
+    }
+    const failed = results.filter((result) => result.status === "rejected").length;
+    if (failed > 0) {
+      logger.warn("durable Redis collaboration fanout failed during shutdown", {
+        pending: pending.length,
+        failed
+      });
+    }
+  }
+  async onDestroy() {
+    this.fanoutDestroyed = true;
+    for (const retryTimer of this.fanoutRetryTimers.values()) clearTimeout(retryTimer);
+    this.fanoutRetryTimers.clear();
+    const pendingLocalDelays = [...this.pendingLocalAfterStoreDelays.values()];
+    this.pendingLocalAfterStoreDelays.clear();
+    for (const pending of pendingLocalDelays) {
+      clearTimeout(pending.timeout);
+      pending.resolve();
+    }
+    try {
+      await this.flushPendingFanoutsBeforeDestroy();
+    } finally {
+      this.pendingFanouts.clear();
+      this.pendingFanoutBytes = 0;
+      this.fanoutRetryAttempts.clear();
+      this.fanoutPublisher.disconnect(false);
+      this.pub.disconnect(false);
+      this.sub.disconnect(false);
+    }
+  }
+}
+function resolveDocumentsCollabRedisExtensions(environment, createRedisExtension) {
+  const configuration = resolveDocumentsCollabRedisConfiguration(environment);
+  if (!configuration) {
+    logger.warn(
+      "DOCUMENTS_COLLAB_REDIS_URL and REDIS_URL are unset; running in single-node mode. Multi-instance deployments require Redis for cross-instance document sync."
+    );
+    return [];
+  }
+  return [createRedisExtension(configuration)];
+}
+function collabAuthorizationStateKey(documentName, scope) {
+  return scope ? `${documentName}\0${scope.tenantId}\0${scope.organizationId}` : documentName;
+}
+function liveCollabConnectionCount(document) {
+  const getConnectionsCount = document.getConnectionsCount;
+  if (typeof getConnectionsCount !== "function") return null;
+  try {
+    const count = getConnectionsCount.call(document);
+    return typeof count === "number" && Number.isSafeInteger(count) && count >= 0 ? count : null;
+  } catch {
+    return null;
+  }
+}
+function captureCollabPendingMessageReadiness(document) {
+  const getConnections = document.getConnections;
+  if (typeof getConnections !== "function") return null;
+  let connections;
+  try {
+    connections = getConnections.call(document);
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(connections) || connections.length === 0) return null;
+  const pending = connections.map((candidate) => {
+    const connection = candidate;
+    if (typeof connection?.waitForPendingMessages !== "function") {
+      return Promise.reject(new Error(
+        "[internal] documents collab: connection queue readiness is unavailable"
+      ));
+    }
+    try {
+      const readiness = connection.waitForPendingMessages();
+      if (!readiness || typeof readiness !== "object" && typeof readiness !== "function" || typeof readiness.then !== "function") {
+        return Promise.reject(new Error(
+          "[internal] documents collab: connection queue readiness is invalid"
+        ));
+      }
+      return Promise.resolve(readiness);
+    } catch (error) {
+      return Promise.reject(error);
+    }
+  });
+  return Promise.all(pending).then(() => void 0);
+}
+function createCollabFinalDrainRegistry(resolveLiveConnections = liveCollabConnectionCount) {
+  const markedDocuments = /* @__PURE__ */ new WeakMap();
+  const authorizationStates = /* @__PURE__ */ new Map();
+  const releaseAuthorization = (ticket) => {
+    if (ticket.released) return;
+    ticket.released = true;
+    if (ticket.expiry) clearTimeout(ticket.expiry);
+    const state = authorizationStates.get(ticket.stateKey);
+    if (state !== ticket.state) return;
+    state.active = Math.max(0, state.active - 1);
+    if (state.active === 0) authorizationStates.delete(ticket.stateKey);
+  };
+  return {
+    mark(document, readiness) {
+      const guardedReadiness = readiness.then(
+        () => true,
+        () => false
+      );
+      if ((resolveLiveConnections(document) ?? 0) <= 0) return false;
+      if (markedDocuments.has(document)) return true;
+      markedDocuments.set(document, {
+        readiness: guardedReadiness
+      });
+      return true;
+    },
+    isMarked(document) {
+      return markedDocuments.has(document);
+    },
+    async consume(document) {
+      const state = markedDocuments.get(document);
+      if (!state) return "unmarked";
+      if (state.consuming || state.granted) return "busy";
+      const consuming = (async () => {
+        const ready = await state.readiness;
+        if (markedDocuments.get(document) !== state) return "unmarked";
+        if (!ready) return "failed";
+        if (resolveLiveConnections(document) !== 0) return "connected";
+        state.granted = true;
+        return "consumed";
+      })();
+      state.consuming = consuming;
+      return consuming;
+    },
+    complete(document) {
+      const state = markedDocuments.get(document);
+      if (state?.granted) state.completed = true;
+    },
+    discard(document) {
+      markedDocuments.delete(document);
+    },
+    beginAuthorization(documentName, scope) {
+      const stateKey = collabAuthorizationStateKey(documentName, scope);
+      let state = authorizationStates.get(stateKey);
+      if (!state) {
+        state = { active: 0, epoch: 0 };
+        authorizationStates.set(stateKey, state);
+      }
+      state.active += 1;
+      const ticket = {
+        documentName,
+        epoch: state.epoch,
+        released: false,
+        stateKey,
+        state
+      };
+      ticket.expiry = setTimeout(() => {
+        releaseAuthorization(ticket);
+      }, DOCUMENTS_COLLAB_AUTHORIZATION_TICKET_TIMEOUT_MS);
+      ticket.expiry.unref?.();
+      return ticket;
+    },
+    bumpAuthorization(documentName, scope) {
+      const state = authorizationStates.get(collabAuthorizationStateKey(documentName, scope));
+      if (state) state.epoch += 1;
+    },
+    isAuthorizationCurrent(ticket) {
+      const internalTicket = ticket;
+      const state = authorizationStates.get(internalTicket.stateKey);
+      return !internalTicket.released && state === ticket.state && state.epoch === ticket.epoch;
+    },
+    endAuthorization(ticket) {
+      releaseAuthorization(ticket);
+    }
+  };
+}
+function markCollabFinalDrainForReauth(document, registry) {
+  const readiness = captureCollabPendingMessageReadiness(document);
+  if (!readiness) return false;
+  return registry.mark(document, readiness);
+}
+const collabIngressStates = /* @__PURE__ */ new WeakMap();
+const boundedCollabConnections = /* @__PURE__ */ new WeakSet();
+const guardedCollabConnectionPrototypes = /* @__PURE__ */ new WeakSet();
+function closeCollabIngress(connection, state) {
+  if (state.blocked) return;
+  state.blocked = true;
+  try {
+    connection.close();
+  } catch {
+  }
+  try {
+    connection.webSocket.close(1009, "Collaboration ingress limit exceeded");
+  } catch {
+  }
+}
+function handleBoundedCollabIngress(connection, data, handleMessage, limits) {
+  const socketKey = connection.webSocket;
+  let state = collabIngressStates.get(socketKey);
+  if (!state) {
+    state = { blocked: false, pendingBytes: 0, pendingMessages: 0 };
+    collabIngressStates.set(socketKey, state);
+  }
+  if (state.blocked) return;
+  const pendingBytes = state.pendingBytes + data.byteLength;
+  const pendingMessages = state.pendingMessages + 1;
+  if (pendingBytes > limits.maxPendingBytes || pendingMessages > limits.maxPendingMessages) {
+    closeCollabIngress(connection, state);
+    return;
+  }
+  state.pendingBytes = pendingBytes;
+  state.pendingMessages = pendingMessages;
+  let released = false;
+  const release = () => {
+    if (released) return;
+    released = true;
+    state.pendingBytes = Math.max(0, state.pendingBytes - data.byteLength);
+    state.pendingMessages = Math.max(0, state.pendingMessages - 1);
+  };
+  try {
+    handleMessage(data);
+    void connection.waitForPendingMessages().then(release, release);
+  } catch (error) {
+    release();
+    throw error;
+  }
+}
+function installBoundedCollabIngress(connection, limits = {
+  maxPendingBytes: DOCUMENTS_COLLAB_MAX_PENDING_BYTES,
+  maxPendingMessages: DOCUMENTS_COLLAB_MAX_PENDING_MESSAGES
+}) {
+  const connectionKey = connection;
+  if (boundedCollabConnections.has(connectionKey)) return;
+  boundedCollabConnections.add(connectionKey);
+  const handleMessage = connection.handleMessage.bind(connection);
+  connection.handleMessage = (data) => {
+    handleBoundedCollabIngress(connection, data, handleMessage, limits);
+  };
+}
+function installHocuspocusCollabIngressGuard(ConnectionClass = HocuspocusConnection) {
+  const prototype = ConnectionClass.prototype;
+  if (guardedCollabConnectionPrototypes.has(prototype)) return;
+  guardedCollabConnectionPrototypes.add(prototype);
+  const handleMessage = prototype.handleMessage;
+  prototype.handleMessage = function guardedHandleMessage(data) {
+    if (boundedCollabConnections.has(this)) {
+      handleMessage.call(this, data);
+      return;
+    }
+    handleBoundedCollabIngress(
+      this,
+      data,
+      (input) => handleMessage.call(this, input),
+      {
+        maxPendingBytes: DOCUMENTS_COLLAB_MAX_PENDING_BYTES,
+        maxPendingMessages: DOCUMENTS_COLLAB_MAX_PENDING_MESSAGES
+      }
+    );
+  };
+}
+function assertCollabInboundFramePolicy(update, options) {
+  if (update.byteLength > DOCUMENTS_COLLAB_MAX_PAYLOAD_BYTES) {
+    throw new Error("[internal] documents collab: frame exceeds transport limit");
+  }
+  let messageType;
+  try {
+    const message = new HocuspocusIncomingMessage(update);
+    message.readVarString();
+    messageType = message.readVarUint();
+  } catch {
+    throw new Error("[internal] documents collab: malformed frame envelope");
+  }
+  const isSync = messageType === MessageType.Sync || messageType === MessageType.SyncReply;
+  if (messageType === MessageType.Awareness && update.byteLength > DOCUMENTS_COLLAB_MAX_AWARENESS_FRAME_BYTES) {
+    throw new Error("[internal] documents collab: awareness frame exceeds limit");
+  }
+  if (!isSync && update.byteLength > DOCUMENTS_COLLAB_MAX_CONTROL_FRAME_BYTES) {
+    throw new Error("[internal] documents collab: control frame exceeds limit");
+  }
+  if (options.readOnly && isSync && update.byteLength > DOCUMENTS_COLLAB_MAX_READ_ONLY_SYNC_FRAME_BYTES) {
+    throw new Error("[internal] documents collab: read-only sync frame exceeds limit");
+  }
+}
+const COLLAB_AUTHORIZATION_LIFECYCLE = /* @__PURE__ */ Symbol("documents.collab.authorization-lifecycle");
+async function loadFreshCollabAcl(rbacService, userId, scope) {
+  if (typeof rbacService?.invalidateUserCache !== "function" || typeof rbacService.loadAcl !== "function") {
+    return null;
+  }
+  await rbacService.invalidateUserCache(userId);
+  return rbacService.loadAcl(userId, scope);
+}
+function readHeader(headers, name) {
+  const value = headers?.[name] ?? headers?.[name.toLowerCase()];
+  if (Array.isArray(value)) return value[0];
+  return value;
+}
+function normalizeTrustedOrigin(value) {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:" ? url.origin : null;
+  } catch {
+    return null;
+  }
+}
+function resolveCollabAllowedOrigins(env) {
+  const candidates = [
+    ...(env.DOCUMENTS_COLLAB_ALLOWED_ORIGINS ?? "").split(","),
+    env.APP_URL ?? "",
+    env.NEXT_PUBLIC_APP_URL ?? ""
+  ];
+  return Array.from(new Set(candidates.map((candidate) => candidate.trim()).filter(Boolean).map(normalizeTrustedOrigin).filter((origin) => Boolean(origin))));
+}
+function isCollabRequestOriginAllowed(input) {
+  if (!input.origin) return !input.requireOrigin;
+  const origin = normalizeTrustedOrigin(input.origin);
+  if (!origin) return false;
+  const allowedOrigins = input.allowedOrigins ?? [];
+  if (allowedOrigins.length === 0) return !input.requireOrigin;
+  return allowedOrigins.includes(origin);
+}
+function assertScopedContext(context) {
+  if (!context?.tenantId || !context.organizationId) {
+    throw new Error("[internal] documents collab: missing tenant scope");
+  }
+}
+function normalizeContentVersion(value) {
+  if (value instanceof Date) {
+    return Number.isFinite(value.getTime()) ? value.toISOString() : null;
+  }
+  if (typeof value !== "string" || !value.trim()) return null;
+  const parsed = new Date(value);
+  return Number.isFinite(parsed.getTime()) ? parsed.toISOString() : null;
+}
+function isReadOnlyTier(tier) {
+  return tier === "viewer" || tier === "commenter";
+}
+function toContext(claims, readOnly, exp) {
+  return {
+    userId: claims.userId,
+    tenantId: claims.tenantId,
+    organizationId: claims.organizationId,
+    documentId: claims.documentId,
+    tier: claims.tier,
+    readOnly,
+    exp
+  };
+}
+function resolveCollabClaims(deps, token) {
+  const v2Claims = deps.verifyTokenV2?.(token) ?? null;
+  if (v2Claims) return toContext(v2Claims, v2Claims.readOnly, v2Claims.exp);
+  const legacyClaims = deps.verifyToken?.(token) ?? null;
+  if (!legacyClaims) return null;
+  const exp = readLegacyTokenExpiration(token);
+  return exp === null ? null : toContext(legacyClaims, isReadOnlyTier(legacyClaims.tier), exp);
+}
+function bindCollabAwarenessStates(context, states, ownership) {
+  if (!context?.awarenessUser) {
+    throw new Error("[internal] documents collab: awareness identity is not authenticated");
+  }
+  const admittedThisUpdate = /* @__PURE__ */ new Set();
+  for (const [clientId, state] of states) {
+    if (!state || typeof state !== "object" || Array.isArray(state) || Object.keys(state).length === 0) {
+      states.delete(clientId);
+      continue;
+    }
+    if (!Number.isSafeInteger(clientId) || clientId < 0 || clientId > MAX_YJS_CLIENT_ID || !isBoundedAwarenessState(state)) {
+      states.delete(clientId);
+      continue;
+    }
+    if (ownership?.occupiedClientIds.has(clientId) && !ownership.ownedClientIds.has(clientId)) {
+      states.delete(clientId);
+      continue;
+    }
+    const roomOwner = ownership?.roomClientOwners?.get(clientId);
+    if (roomOwner !== void 0 && roomOwner !== context.awarenessUser.id) {
+      states.delete(clientId);
+      continue;
+    }
+    const knownToConnection = Boolean(
+      ownership?.ownedClientIds.has(clientId) || ownership?.claimedClientIds?.has(clientId)
+    );
+    const connectionClientCount = (/* @__PURE__ */ new Set([
+      ...ownership?.ownedClientIds ?? [],
+      ...ownership?.claimedClientIds ?? [],
+      ...admittedThisUpdate
+    ])).size;
+    if (!knownToConnection && connectionClientCount >= DOCUMENTS_COLLAB_MAX_AWARENESS_CLIENT_IDS_PER_CONNECTION) {
+      states.delete(clientId);
+      continue;
+    }
+    if (roomOwner === void 0 && (ownership?.roomClientOwners?.size ?? 0) >= DOCUMENTS_COLLAB_MAX_AWARENESS_CLIENT_IDS_PER_ROOM) {
+      states.delete(clientId);
+      continue;
+    }
+    const cursor = sanitizeAwarenessCursor(state.cursor);
+    const canonicalState = {
+      user: { ...context.awarenessUser }
+    };
+    if (cursor) canonicalState.cursor = cursor;
+    states.set(clientId, canonicalState);
+    admittedThisUpdate.add(clientId);
+    ownership?.claimedClientIds?.add(clientId);
+    if (roomOwner === void 0) {
+      ownership?.roomClientOwners?.set(clientId, context.awarenessUser.id);
+    }
+  }
+}
+function isBoundedAwarenessState(state) {
+  try {
+    const serialized = JSON.stringify(state);
+    return typeof serialized === "string" && Buffer.byteLength(serialized, "utf8") <= DOCUMENTS_COLLAB_MAX_AWARENESS_STATE_BYTES;
+  } catch {
+    return false;
+  }
+}
+function sanitizeAwarenessId(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const record = value;
+  if (!Number.isSafeInteger(record.client) || record.client < 0 || record.client > MAX_YJS_CLIENT_ID || !Number.isSafeInteger(record.clock) || record.clock < 0) {
+    return null;
+  }
+  return { client: record.client, clock: record.clock };
+}
+function sanitizeAwarenessPosition(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const record = value;
+  const assoc = record.assoc === void 0 ? 0 : record.assoc;
+  if (!Number.isSafeInteger(assoc) || assoc < -1 || assoc > 1) {
+    return null;
+  }
+  const item = sanitizeAwarenessId(record.item);
+  if (item) return { item, assoc };
+  if (typeof record.tname === "string" && record.tname.length > 0 && record.tname.length <= 120) {
+    return { tname: record.tname, assoc };
+  }
+  const type = sanitizeAwarenessId(record.type);
+  return type ? { type, assoc } : null;
+}
+function sanitizeAwarenessCursor(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const record = value;
+  const anchor = sanitizeAwarenessPosition(record.anchor);
+  const head = sanitizeAwarenessPosition(record.head);
+  return anchor && head ? { anchor, head } : null;
+}
+function readLegacyTokenExpiration(token) {
+  const encodedPayload = token.split(".")[1];
+  if (!encodedPayload) return null;
+  try {
+    const payload = JSON.parse(Buffer.from(encodedPayload, "base64url").toString("utf8"));
+    if (!payload || typeof payload !== "object") return null;
+    const { exp, iat } = payload;
+    const now = Math.floor(Date.now() / 1e3);
+    if (typeof exp !== "number" || !Number.isInteger(exp) || typeof iat !== "number" || !Number.isInteger(iat) || exp <= now || exp <= iat || exp - iat > COLLAB_TOKEN_TTL_SECONDS || iat > now + COLLAB_TOKEN_CLOCK_SKEW_SECONDS || exp > now + COLLAB_TOKEN_TTL_SECONDS + COLLAB_TOKEN_CLOCK_SKEW_SECONDS) {
+      return null;
+    }
+    return exp;
+  } catch {
+    return null;
+  }
+}
+function scheduleCollabConnectionExpiry(connection, exp) {
+  let timer = null;
+  const clearExpiry = () => {
+    if (timer === null) return;
+    clearTimeout(timer);
+    timer = null;
+  };
+  timer = setTimeout(() => {
+    timer = null;
+    connection.close();
+  }, Math.max(0, exp * 1e3 - Date.now()));
+  connection.onClose(clearExpiry);
+  return clearExpiry;
+}
+function scheduleCollabConnectionReauthorization(connection, authorize, intervalMs = DOCUMENTS_COLLAB_ACTIVE_REAUTHORIZATION_INTERVAL_MS) {
+  let stopped = false;
+  let timer = null;
+  const stop = () => {
+    stopped = true;
+    if (timer === null) return;
+    clearTimeout(timer);
+    timer = null;
+  };
+  const schedule = () => {
+    if (stopped) return;
+    timer = setTimeout(() => {
+      timer = null;
+      void (async () => {
+        let authorized = false;
+        try {
+          authorized = await authorize();
+        } catch {
+          authorized = false;
+        }
+        if (stopped) return;
+        if (!authorized) {
+          stop();
+          connection.close();
+          return;
+        }
+        schedule();
+      })();
+    }, Math.max(1, intervalMs));
+    timer.unref?.();
+  };
+  connection.onClose(stop);
+  schedule();
+  return stop;
+}
+function handleCollabHealthRequest(request, response) {
+  const pathname = new URL(request.url ?? "/", "http://documents-collab.local").pathname;
+  if (pathname !== "/healthz") return false;
+  response.setHeader("Cache-Control", "no-store");
+  if (request.method !== "GET") {
+    response.statusCode = 405;
+    response.setHeader("Allow", "GET");
+    response.end();
+    return true;
+  }
+  const ready = isCollabTokenV2Ready();
+  response.statusCode = ready ? 200 : 503;
+  response.setHeader("Content-Type", "application/json");
+  response.end(JSON.stringify({
+    status: ready ? "ok" : "unavailable",
+    service: "documents-collab",
+    capabilityTokenVersion: 2
+  }));
+  return true;
+}
+async function handleCollabServerRequest(input) {
+  if (handleCollabHealthRequest(input.request, input.response)) {
+    return Promise.reject();
+  }
+}
+async function initializeDocumentYjsState(em, documentId, scope) {
+  return em.transactional(async (transactionalEm) => {
+    const document = await findOneWithDecryption(
+      transactionalEm,
+      Document,
+      {
+        id: documentId,
+        tenantId: scope.tenantId,
+        organizationId: scope.organizationId,
+        deletedAt: null
+      },
+      { lockMode: LockMode.PESSIMISTIC_WRITE },
+      scope
+    );
+    if (!document) return null;
+    let content = await findOneWithDecryption(
+      transactionalEm,
+      DocumentContent,
+      {
+        documentId,
+        tenantId: scope.tenantId,
+        organizationId: scope.organizationId
+      },
+      { filters: false, lockMode: LockMode.PESSIMISTIC_WRITE },
+      scope
+    );
+    if (!content) {
+      content = transactionalEm.create(DocumentContent, {
+        id: randomUUID(),
+        documentId,
+        tenantId: scope.tenantId,
+        organizationId: scope.organizationId,
+        contentHtml: "",
+        contentText: "",
+        yjsState: null,
+        collaborationGeneration: 1,
+        deletedAt: null,
+        updatedAt: /* @__PURE__ */ new Date()
+      });
+      transactionalEm.persist(content);
+      await transactionalEm.flush();
+      return null;
+    }
+    if (content.deletedAt) {
+      const now = /* @__PURE__ */ new Date();
+      content.yjsState = null;
+      content.contentHtml = "";
+      content.contentText = "";
+      content.deletedAt = null;
+      advanceDocumentCollaborationGeneration(content);
+      content.updatedAt = now.getTime() > content.updatedAt.getTime() ? now : new Date(content.updatedAt.getTime() + 1);
+      await transactionalEm.flush();
+    }
+    if (content.yjsState && content.yjsState.length > 0) {
+      assertDocumentContentResourceLimits({
+        yjsState: content.yjsState,
+        contentHtml: content.contentHtml,
+        contentText: content.contentText
+      });
+      return Buffer.from(content.yjsState);
+    }
+    if (!content.contentHtml) return null;
+    assertDocumentContentResourceLimits({
+      contentHtml: content.contentHtml,
+      contentText: content.contentText
+    });
+    const materialized = htmlToYDoc(content.contentHtml);
+    const yjsState = Buffer.from(Y.encodeStateAsUpdate(materialized));
+    assertDocumentContentResourceLimits({ yjsState, contentHtml: content.contentHtml });
+    await transactionalEm.nativeUpdate(
+      DocumentContent,
+      {
+        id: content.id,
+        documentId,
+        tenantId: scope.tenantId,
+        organizationId: scope.organizationId,
+        deletedAt: null
+      },
+      { yjsState }
+    );
+    return yjsState;
+  });
+}
+function isCollabAuthorizationCurrent(context, snapshot) {
+  if (!hasResolvedDocumentsOrganizationAccess(
+    snapshot,
+    context.organizationId,
+    snapshot.organizationScope
+  )) {
+    return false;
+  }
+  const features = snapshot.isSuperAdmin ? ["*"] : snapshot.features;
+  const managerOverride = hasAllFeatures(["documents.manage"], features);
+  const relationshipTier = managerOverride ? "owner" : snapshot.relationshipTier;
+  const capabilities = deriveDocumentCapabilities({
+    relationshipTier,
+    managerOverride,
+    archived: snapshot.archived === true,
+    userFeatures: features
+  });
+  return capabilities.canView && relationshipTier === context.tier && context.readOnly === !capabilities.canEdit;
+}
+async function authorizeCollabContext(container, context) {
+  try {
+    const scope = {
+      tenantId: context.tenantId,
+      organizationId: context.organizationId
+    };
+    const em = container.resolve("em");
+    const rbacService = container.resolve("rbacService");
+    let acl = await loadFreshCollabAcl(rbacService, context.userId, scope);
+    if (!acl) return false;
+    let organizationScope = null;
+    if (!hasResolvedDocumentsOrganizationAccess(acl, context.organizationId)) {
+      const organizationScopeService = resolveOrganizationScopeService(container);
+      if (!organizationScopeService) return false;
+      const freshAuthorization = await organizationScopeService.resolveFresh({
+        auth: {
+          sub: context.userId,
+          userId: context.userId,
+          tenantId: context.tenantId,
+          orgId: context.organizationId,
+          isSuperAdmin: false
+        },
+        selectedId: context.organizationId,
+        tenantId: context.tenantId
+      });
+      organizationScope = freshAuthorization.scope;
+      acl = freshAuthorization.acl;
+      if (!hasResolvedDocumentsOrganizationAccess(
+        acl,
+        context.organizationId,
+        organizationScope
+      )) {
+        return false;
+      }
+    }
+    const features = acl.isSuperAdmin ? ["*"] : acl.features;
+    const managerOverride = hasAllFeatures(["documents.manage"], features);
+    const relationshipTier = managerOverride ? "owner" : await resolveUserAccess(
+      em,
+      context.documentId,
+      scope,
+      context.userId,
+      container
+    );
+    const documentRow = await findOneWithDecryption(
+      em,
+      Document,
+      { id: context.documentId, tenantId: scope.tenantId, organizationId: scope.organizationId },
+      { fields: ["id", "archivedAt", "deletedAt"], filters: false },
+      scope
+    );
+    if (!documentRow || documentRow.deletedAt) return false;
+    return isCollabAuthorizationCurrent(context, {
+      relationshipTier,
+      isSuperAdmin: acl.isSuperAdmin,
+      features: acl.features,
+      organizations: acl.organizations,
+      organizationScope,
+      archived: documentRow?.archivedAt != null
+    });
+  } catch (error) {
+    logger.warn("collab authorization check failed; failing closed", {
+      error: error instanceof Error ? error.message : String(error)
+    });
+    return false;
+  }
+}
+function createCollabHooks(deps) {
+  const materializationWarningRooms = /* @__PURE__ */ new Set();
+  const loadedContentVersions = /* @__PURE__ */ new WeakMap();
+  const loadedCollaborationGenerations = /* @__PURE__ */ new WeakMap();
+  const roomResourceBudgets = /* @__PURE__ */ new WeakMap();
+  const roomScopes = /* @__PURE__ */ new WeakMap();
+  const awarenessConnectionClientIds = /* @__PURE__ */ new WeakMap();
+  const awarenessRoomClientOwners = /* @__PURE__ */ new WeakMap();
+  const roomWritableContexts = /* @__PURE__ */ new WeakMap();
+  const rememberWritableContext = (document, context) => {
+    if (!document || !context || context.readOnly) return;
+    roomWritableContexts.set(document, context);
+  };
+  const isInvalidated = (documentName, document) => deps.isRoomInvalidated?.(documentName, document) ?? (document ? deps.isRoomClosing?.(documentName, document) : false) ?? false;
+  const isFinalDrainPending = (documentName) => {
+    const room = deps.resolveRoomDocument?.(documentName);
+    return Boolean(room && deps.finalDrainRegistry?.isMarked(room));
+  };
+  const assertRoomAcceptsAuthentication = (documentName) => {
+    if (isInvalidated(documentName)) {
+      throw new Error("[internal] documents collab: room is reloading authoritative content");
+    }
+    if (isFinalDrainPending(documentName)) {
+      throw new Error("[internal] documents collab: room is draining accepted edits");
+    }
+  };
+  const invalidateStoreRoom = (data) => {
+    deps.finalDrainRegistry?.discard(data.document);
+    deps.invalidateRoom?.(data.documentName, data.document);
+  };
+  const retireFailedStore = (data, ownsGrant = false) => {
+    const invalidated = isInvalidated(data.documentName, data.document);
+    if (!ownsGrant && !invalidated && !deps.finalDrainRegistry?.isMarked(data.document)) return false;
+    if (invalidated) {
+      deps.finalDrainRegistry?.discard(data.document);
+    } else {
+      invalidateStoreRoom(data);
+    }
+    logger.error(invalidated ? "invalidated store failed; retiring in-memory room" : "final drain failed; retiring in-memory room");
+    return true;
+  };
+  const assertConnectionAuthorization = (context) => {
+    if (!deps.finalDrainRegistry) return;
+    const lifecycle = context[COLLAB_AUTHORIZATION_LIFECYCLE];
+    if (lifecycle?.established) return;
+    if (!lifecycle?.ticket || !deps.finalDrainRegistry.isAuthorizationCurrent(lifecycle.ticket)) {
+      throw new Error("[internal] documents collab: access changed during connection setup");
+    }
+    assertRoomAcceptsAuthentication(context.documentId);
+  };
+  const establishConnectionAuthorization = (context) => {
+    if (!deps.finalDrainRegistry) return;
+    assertConnectionAuthorization(context);
+    const lifecycle = context[COLLAB_AUTHORIZATION_LIFECYCLE];
+    if (!lifecycle) return;
+    if (lifecycle.ticket) deps.finalDrainRegistry.endAuthorization(lifecycle.ticket);
+    lifecycle.ticket = void 0;
+    lifecycle.established = true;
+  };
+  const releaseConnectionAuthorization = (context) => {
+    if (!deps.finalDrainRegistry) return;
+    const ticketedContext = context;
+    const lifecycle = ticketedContext[COLLAB_AUTHORIZATION_LIFECYCLE];
+    if (lifecycle?.ticket) deps.finalDrainRegistry.endAuthorization(lifecycle.ticket);
+    delete ticketedContext[COLLAB_AUTHORIZATION_LIFECYCLE];
+  };
+  const authorizeStoreAttempt = async (data) => {
+    let finalDrain = "unmarked";
+    if (deps.finalDrainRegistry?.isMarked(data.document)) {
+      finalDrain = await deps.finalDrainRegistry.consume(data.document);
+      if (finalDrain === "busy") {
+        return "denied";
+      }
+      if (finalDrain === "connected" || finalDrain === "failed") {
+        invalidateStoreRoom(data);
+        return "denied";
+      }
+    }
+    let authorized;
+    try {
+      authorized = await deps.authorizeContext(data.context);
+    } catch {
+      invalidateStoreRoom(data);
+      logger.error("store authorization failed; retiring in-memory room");
+      return "denied";
+    }
+    if (isInvalidated(data.documentName, data.document)) {
+      deps.finalDrainRegistry?.discard(data.document);
+      return "denied";
+    }
+    if (finalDrain === "unmarked") {
+      finalDrain = await (deps.finalDrainRegistry?.consume(data.document) ?? Promise.resolve("unmarked"));
+    }
+    if (finalDrain === "busy") return "denied";
+    if (finalDrain === "connected" || finalDrain === "failed") {
+      invalidateStoreRoom(data);
+      return "denied";
+    }
+    if (finalDrain === "consumed") return "final-drain";
+    if (authorized) return "normal";
+    invalidateStoreRoom(data);
+    return "denied";
+  };
+  const reauthorizeActiveConnection = async (context) => {
+    if (isInvalidated(context.documentId) || isFinalDrainPending(context.documentId)) {
+      return false;
+    }
+    let authorized = false;
+    try {
+      authorized = await deps.authorizeContext(context);
+    } catch {
+      authorized = false;
+    }
+    if (isInvalidated(context.documentId) || isFinalDrainPending(context.documentId)) {
+      return false;
+    }
+    if (authorized) {
+      const resolveRoomDocument = deps.resolveRoomDocument;
+      if (!resolveRoomDocument) return true;
+      const room2 = resolveRoomDocument(context.documentId);
+      if (!room2) return false;
+      const loadedGeneration = loadedCollaborationGenerations.get(room2);
+      let durableGeneration = null;
+      try {
+        const container = await deps.resolveContainer();
+        const em = container.resolve("em");
+        const scope = {
+          tenantId: context.tenantId,
+          organizationId: context.organizationId
+        };
+        if (deps.loadCollaborationGeneration) {
+          durableGeneration = await deps.loadCollaborationGeneration(
+            em,
+            context.documentId,
+            scope
+          );
+        } else {
+          const content = await deps.loadContent(em, context.documentId, scope);
+          durableGeneration = normalizeDocumentCollaborationGeneration(
+            content?.collaborationGeneration
+          );
+        }
+      } catch {
+        durableGeneration = null;
+      }
+      if (isInvalidated(context.documentId) || isFinalDrainPending(context.documentId)) {
+        return false;
+      }
+      if (resolveRoomDocument(context.documentId) !== room2) return false;
+      if (loadedGeneration !== void 0 && durableGeneration !== null && durableGeneration === loadedGeneration) {
+        rememberWritableContext(room2, context);
+        return true;
+      }
+      invalidateStoreRoom({
+        documentName: context.documentId,
+        document: room2
+      });
+      return false;
+    }
+    const room = deps.resolveRoomDocument?.(context.documentId);
+    if (room) {
+      invalidateStoreRoom({
+        documentName: context.documentId,
+        document: room
+      });
+    }
+    return false;
+  };
+  return {
+    assertConnectionAuthorization,
+    establishConnectionAuthorization,
+    releaseConnectionAuthorization,
+    reauthorizeActiveConnection,
+    recordRedisAggregate(document, byteLength) {
+      const previous = roomResourceBudgets.get(document);
+      roomResourceBudgets.set(document, {
+        bytes: byteLength,
+        revision: (previous?.revision ?? 0) + 1
+      });
+    },
+    resolveCollaborationGeneration(document) {
+      return loadedCollaborationGenerations.get(document);
+    },
+    resolveRoomScope(document) {
+      return roomScopes.get(document) ?? null;
+    },
+    async onAuthenticate(data) {
+      if (!isCollabRequestOriginAllowed({
+        origin: readHeader(data.requestHeaders, "origin"),
+        allowedOrigins: deps.allowedOrigins,
+        requireOrigin: deps.requireOrigin ?? process.env.NODE_ENV === "production"
+      })) {
+        throw new Error("[internal] documents collab: origin not allowed");
+      }
+      const context = resolveCollabClaims(deps, data.token ?? "");
+      if (!context) {
+        throw new Error("[internal] documents collab: invalid token");
+      }
+      if (context.documentId !== data.documentName) {
+        throw new Error("[internal] documents collab: room mismatch");
+      }
+      const authorizationTicket = deps.finalDrainRegistry?.beginAuthorization(data.documentName, {
+        tenantId: context.tenantId,
+        organizationId: context.organizationId
+      });
+      let retainAuthorizationTicket = false;
+      try {
+        assertRoomAcceptsAuthentication(data.documentName);
+        if (!await deps.authorizeContext(context)) {
+          throw new Error("[internal] documents collab: stale or revoked token");
+        }
+        const awarenessName = await deps.resolveAwarenessName?.(context);
+        if (!await deps.authorizeContext(context)) {
+          throw new Error("[internal] documents collab: stale or revoked token");
+        }
+        if (authorizationTicket && !deps.finalDrainRegistry?.isAuthorizationCurrent(authorizationTicket)) {
+          throw new Error("[internal] documents collab: access changed during authentication");
+        }
+        assertRoomAcceptsAuthentication(data.documentName);
+        context.awarenessUser = createCanonicalCollaborationAwarenessUser(
+          context.userId,
+          awarenessName
+        );
+        data.connection.readOnly = context.readOnly;
+        if (authorizationTicket) {
+          context[COLLAB_AUTHORIZATION_LIFECYCLE] = {
+            established: false,
+            ticket: authorizationTicket
+          };
+          retainAuthorizationTicket = true;
+        }
+        return context;
+      } finally {
+        if (authorizationTicket && !retainAuthorizationTicket) {
+          deps.finalDrainRegistry?.endAuthorization(authorizationTicket);
+        }
+      }
+    },
+    async beforeHandleAwareness(data) {
+      let claimedClientIds;
+      if (data.connection) {
+        claimedClientIds = awarenessConnectionClientIds.get(data.connection);
+        if (!claimedClientIds) {
+          claimedClientIds = /* @__PURE__ */ new Set();
+          awarenessConnectionClientIds.set(data.connection, claimedClientIds);
+        }
+      }
+      let roomClientOwners;
+      if (data.document) {
+        roomClientOwners = awarenessRoomClientOwners.get(data.document);
+        if (!roomClientOwners) {
+          roomClientOwners = /* @__PURE__ */ new Map();
+          awarenessRoomClientOwners.set(data.document, roomClientOwners);
+        }
+      }
+      bindCollabAwarenessStates(
+        data.context,
+        data.states,
+        data.ownedClientIds && data.occupiedClientIds ? {
+          ownedClientIds: data.ownedClientIds,
+          occupiedClientIds: data.occupiedClientIds,
+          claimedClientIds,
+          roomClientOwners
+        } : void 0
+      );
+    },
+    async onLoadDocument(data) {
+      assertScopedContext(data.context);
+      roomScopes.set(data.document, {
+        tenantId: data.context.tenantId,
+        organizationId: data.context.organizationId
+      });
+      rememberWritableContext(data.document, data.context);
+      const container = await deps.resolveContainer();
+      const em = container.resolve("em");
+      const scope = {
+        tenantId: data.context.tenantId,
+        organizationId: data.context.organizationId
+      };
+      let content = await deps.loadContent(em, data.documentName, scope);
+      if (!content) {
+        await deps.initializeYjsState(em, data.documentName, scope);
+        content = await deps.loadContent(em, data.documentName, scope);
+      }
+      const loadedVersion = normalizeContentVersion(content?.updatedAt);
+      if (!loadedVersion) {
+        throw new Error("[internal] documents collab: content row has no durable version");
+      }
+      if (content?.yjsState && content.yjsState.length > 0) {
+        assertDocumentContentResourceLimits({
+          yjsState: content.yjsState,
+          contentHtml: content.contentHtml
+        });
+        Y.applyUpdate(data.document, new Uint8Array(content.yjsState));
+        roomResourceBudgets.set(data.document, {
+          bytes: content.yjsState.byteLength,
+          revision: 0
+        });
+      } else if (content?.contentHtml) {
+        assertDocumentContentResourceLimits({ contentHtml: content.contentHtml });
+        const initializedState = await deps.initializeYjsState(
+          em,
+          data.documentName,
+          scope
+        );
+        if (initializedState && initializedState.length > 0) {
+          Y.applyUpdate(data.document, new Uint8Array(initializedState));
+          roomResourceBudgets.set(data.document, {
+            bytes: initializedState.byteLength,
+            revision: 0
+          });
+        }
+      }
+      if (!roomResourceBudgets.has(data.document)) {
+        roomResourceBudgets.set(data.document, { bytes: 0, revision: 0 });
+      }
+      const collaborationGeneration = normalizeDocumentCollaborationGeneration(
+        content?.collaborationGeneration
+      );
+      if (collaborationGeneration === null) {
+        throw new Error("[internal] documents collab: content row has no durable collaboration generation");
+      }
+      loadedContentVersions.set(data.document, loadedVersion);
+      loadedCollaborationGenerations.set(data.document, collaborationGeneration);
+      return data.document;
+    },
+    async beforeSync(data) {
+      if (data.connection.readOnly || data.type !== 1 && data.type !== 2) return;
+      let authorized = false;
+      if (data.context && !isInvalidated(data.context.documentId, data.document)) {
+        try {
+          authorized = await deps.authorizeContext(data.context);
+        } catch {
+          authorized = false;
+        }
+      }
+      if (!authorized || !data.context || isInvalidated(data.context.documentId, data.document) || isFinalDrainPending(data.context.documentId)) {
+        data.connection.close?.();
+        if (data.context) {
+          invalidateStoreRoom({
+            documentName: data.context.documentId,
+            document: data.document
+          });
+        }
+        throw new Error("[internal] documents collab: write authorization is no longer current");
+      }
+      rememberWritableContext(data.document, data.context);
+      const budget = roomResourceBudgets.get(data.document) ?? { bytes: 0, revision: 0 };
+      const nextBytes = budget.bytes + data.payload.byteLength;
+      assertDocumentYjsStateByteLength(nextBytes);
+      budget.bytes = nextBytes;
+      budget.revision += 1;
+      roomResourceBudgets.set(data.document, budget);
+    },
+    async onStoreDocument(data) {
+      try {
+        assertScopedContext(data.context);
+      } catch (error) {
+        if (retireFailedStore(data)) return;
+        throw error;
+      }
+      if (isInvalidated(data.documentName, data.document)) return;
+      if (data.context.readOnly) {
+        const writableContext = roomWritableContexts.get(data.document);
+        if (!writableContext) {
+          retireFailedStore(data);
+          return;
+        }
+        data = { ...data, context: writableContext };
+      } else {
+        rememberWritableContext(data.document, data.context);
+      }
+      let expectedUpdatedAt = loadedContentVersions.get(data.document);
+      let collaborationGeneration = loadedCollaborationGenerations.get(data.document);
+      if (!expectedUpdatedAt || collaborationGeneration === void 0) {
+        const error = new Error("[internal] documents collab: room store has no loaded content version");
+        if (retireFailedStore(data)) return;
+        throw error;
+      }
+      let em;
+      let searchIndexer = null;
+      try {
+        const container = await deps.resolveContainer();
+        em = container.resolve("em");
+        try {
+          searchIndexer = container.resolve("searchIndexer");
+        } catch {
+          searchIndexer = null;
+        }
+      } catch (error) {
+        if (retireFailedStore(data)) return;
+        throw error;
+      }
+      const scope = {
+        tenantId: data.context.tenantId,
+        organizationId: data.context.organizationId
+      };
+      let finalDrainAuthorized = false;
+      try {
+        for (let attempt = 0; attempt < MAX_COLLAB_STORE_ATTEMPTS; attempt += 1) {
+          if (isInvalidated(data.documentName, data.document)) {
+            if (finalDrainAuthorized) deps.finalDrainRegistry?.discard(data.document);
+            return;
+          }
+          if (!finalDrainAuthorized) {
+            const authorization = await authorizeStoreAttempt(data);
+            if (authorization === "denied") return;
+            finalDrainAuthorized = authorization === "final-drain";
+          }
+          if (isInvalidated(data.documentName, data.document)) {
+            if (finalDrainAuthorized) deps.finalDrainRegistry?.discard(data.document);
+            return;
+          }
+          const materialized = yDocToContent(data.document);
+          if (materialized) materializationWarningRooms.delete(data.documentName);
+          if (!materialized && !materializationWarningRooms.has(data.documentName)) {
+            materializationWarningRooms.add(data.documentName);
+            logger.warn("materialization failed; preserving previous html/text", { room: data.documentName });
+          }
+          const yjsState = Buffer.from(Y.encodeStateAsUpdate(data.document));
+          const resourceBudgetRevision = roomResourceBudgets.get(data.document)?.revision ?? 0;
+          assertDocumentContentResourceLimits({
+            yjsState,
+            contentHtml: materialized?.html,
+            contentText: materialized?.text
+          });
+          let persisted;
+          try {
+            persisted = await deps.persistContent(
+              em,
+              data.documentName,
+              scope,
+              materialized ? {
+                yjsState,
+                contentHtml: materialized.html,
+                contentText: materialized.text
+              } : { yjsState },
+              {
+                searchIndexer,
+                expectedUpdatedAt,
+                expectedCollaborationGeneration: collaborationGeneration,
+                requireExpectedVersion: true
+              }
+            );
+          } catch (error) {
+            if (isInvalidated(data.documentName, data.document)) {
+              if (finalDrainAuthorized) deps.finalDrainRegistry?.discard(data.document);
+              return;
+            }
+            const isVersionConflict = isCrudHttpError(error) && error.status === 409 && error.body.code === OPTIMISTIC_LOCK_CONFLICT_CODE;
+            if (!isVersionConflict) throw error;
+            const authoritative = await deps.loadContent(em, data.documentName, scope);
+            const authoritativeVersion = normalizeContentVersion(authoritative?.updatedAt);
+            if (!authoritativeVersion) {
+              invalidateStoreRoom(data);
+              return;
+            }
+            const authoritativeGeneration = normalizeDocumentCollaborationGeneration(
+              authoritative?.collaborationGeneration
+            );
+            if (authoritativeGeneration === null) {
+              invalidateStoreRoom(data);
+              return;
+            }
+            const authoritativeDocument = authoritative?.yjsState?.length ? new Y.Doc() : htmlToYDoc(authoritative?.contentHtml ?? "");
+            if (authoritative?.yjsState?.length) {
+              assertDocumentContentResourceLimits({
+                yjsState: authoritative.yjsState,
+                contentHtml: authoritative.contentHtml
+              });
+              Y.applyUpdate(authoritativeDocument, new Uint8Array(authoritative.yjsState));
+            }
+            if (authoritativeGeneration !== collaborationGeneration || isInvalidated(data.documentName, data.document)) {
+              invalidateStoreRoom(data);
+              return;
+            }
+            Y.applyUpdate(
+              data.document,
+              Y.encodeStateAsUpdate(authoritativeDocument),
+              {
+                source: "local",
+                skipStoreHooks: true,
+                context: data.context
+              }
+            );
+            expectedUpdatedAt = authoritativeVersion;
+            collaborationGeneration = authoritativeGeneration;
+            loadedContentVersions.set(data.document, authoritativeVersion);
+            loadedCollaborationGenerations.set(data.document, authoritativeGeneration);
+            if (attempt + 1 >= MAX_COLLAB_STORE_ATTEMPTS) throw error;
+            continue;
+          }
+          if (isInvalidated(data.documentName, data.document)) {
+            if (finalDrainAuthorized) deps.finalDrainRegistry?.discard(data.document);
+            return;
+          }
+          const persistedVersion = normalizeContentVersion(persisted.updatedAt);
+          if (!persistedVersion) {
+            throw new Error("[internal] documents collab: content store returned no durable version");
+          }
+          if (persisted.collaborationGeneration !== collaborationGeneration) {
+            invalidateStoreRoom(data);
+            return;
+          }
+          loadedContentVersions.set(data.document, persistedVersion);
+          loadedCollaborationGenerations.set(data.document, collaborationGeneration);
+          const currentBudget = roomResourceBudgets.get(data.document);
+          if (!currentBudget || currentBudget.revision === resourceBudgetRevision) {
+            roomResourceBudgets.set(data.document, {
+              bytes: yjsState.byteLength,
+              revision: resourceBudgetRevision
+            });
+          }
+          deps.onPersisted?.(data.document, yjsState, collaborationGeneration);
+          if (finalDrainAuthorized) deps.finalDrainRegistry?.complete(data.document);
+          return;
+        }
+      } catch (error) {
+        if (isCrudHttpError(error) && error.status === 413) {
+          invalidateStoreRoom(data);
+          logger.warn("retiring collaboration room that exceeded content limits", {
+            room: data.documentName
+          });
+          return;
+        }
+        if (retireFailedStore(data, finalDrainAuthorized)) return;
+        throw error;
+      }
+    }
+  };
+}
+function headersToRecord(headers) {
+  return { origin: headers.get("origin") ?? void 0 };
+}
+function eventDocumentId(payload) {
+  if (!payload || typeof payload !== "object") return null;
+  const record = payload;
+  const id = record.documentId ?? record.id;
+  return typeof id === "string" && id.length > 0 ? id : null;
+}
+function closeCollabRoomConnectionsForContentReset(registry, documentName) {
+  const room = registry.documents.get(documentName);
+  if (!room) return 0;
+  let closed = 0;
+  room.connections.forEach((_clients, connection) => {
+    connection.close(COLLAB_CONTENT_RESET_CLOSE_EVENT);
+    closed += 1;
+  });
+  return closed;
+}
+function resolveCollabRoomEventAction(event, payload) {
+  if (event === "documents.document.shared" || event === "documents.document.unshared" || event === "documents.document.archived" || event === "documents.document.unarchived") {
+    return "reauth";
+  }
+  const record = payload && typeof payload === "object" ? payload : null;
+  if (event === "documents.document.deleted" || event === "documents.version.restored" || event === "documents.document.updated" && record?.contentEpochReset === true) {
+    return "invalidate";
+  }
+  return "ignore";
+}
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : null;
+}
+function resolveTrustedDocumentsCrossProcessEvent(envelope) {
+  if (envelope.options?.emitterModuleId !== "documents") return null;
+  const tenantId = nonEmptyString(envelope.options?.tenantId);
+  const organizationId = nonEmptyString(envelope.options?.organizationId);
+  if (!tenantId || !organizationId) return null;
+  const action = resolveCollabRoomEventAction(envelope.event, envelope.payload);
+  if (action === "ignore") return null;
+  const documentId = eventDocumentId(envelope.payload);
+  if (!documentId) return null;
+  return {
+    action,
+    documentId,
+    scope: { tenantId, organizationId }
+  };
+}
+function isTrustedDocumentsCollabRoomScope(event, roomScope) {
+  return roomScope?.tenantId === event.scope.tenantId && roomScope.organizationId === event.scope.organizationId;
+}
+function isOwnDocumentsCrossProcessEvent(envelope, ownInstanceId) {
+  return envelope.originInstanceId === ownInstanceId;
+}
+function isMainModule() {
+  const entry = process.argv[1];
+  return Boolean(entry && import.meta.url === pathToFileURL(resolve(entry)).href);
+}
+async function main() {
+  const [
+    { Connection, Server },
+    { bootstrapFromAppRoot },
+    { createRequestContainer },
+    { registerCrossProcessEventListener, CROSS_PROCESS_EVENT_INSTANCE_ID }
+  ] = await Promise.all([
+    import("@hocuspocus/server"),
+    import("@open-mercato/shared/lib/bootstrap/dynamicLoader"),
+    import("@open-mercato/shared/lib/di/container"),
+    import("@open-mercato/events")
+  ]);
+  installHocuspocusCollabIngressGuard(Connection);
+  const appRoot = process.env.DOCUMENTS_COLLAB_APP_ROOT || void 0;
+  await bootstrapFromAppRoot(appRoot);
+  const port = Number(process.env.DOCUMENTS_COLLAB_PORT || 4101);
+  const allowedOrigins = resolveCollabAllowedOrigins(process.env);
+  const invalidatedRoomDocuments = /* @__PURE__ */ new WeakSet();
+  const finalDrainRegistry = createCollabFinalDrainRegistry();
+  let server = null;
+  let redisStoreExtension = null;
+  const closeRoomConnectionsForContentReset = (documentName) => {
+    if (server) closeCollabRoomConnectionsForContentReset(server.hocuspocus, documentName);
+  };
+  const invalidateRoom = (documentName, document) => {
+    redisStoreExtension?.discardPendingFanout(documentName, document);
+    finalDrainRegistry.discard(document);
+    invalidatedRoomDocuments.add(document);
+    closeRoomConnectionsForContentReset(documentName);
+  };
+  const legacyTokenVerifier = resolveLegacyCollabTokenVerifier(process.env);
+  const hooks = createCollabHooks({
+    ...legacyTokenVerifier ? { verifyToken: legacyTokenVerifier } : {},
+    verifyTokenV2: verifyCollabTokenV2,
+    authorizeContext: async (context) => {
+      const container = await createRequestContainer();
+      return authorizeCollabContext(container, context);
+    },
+    resolveAwarenessName: async (context) => {
+      const container = await createRequestContainer();
+      const labels = await resolveUserLabels(
+        container,
+        {
+          tenantId: context.tenantId,
+          organizationId: context.organizationId
+        },
+        [context.userId]
+      );
+      return labels.get(context.userId)?.label ?? null;
+    },
+    resolveContainer: () => createRequestContainer(),
+    loadContent: async (em, id, scope) => {
+      const content = await loadDocumentContentForCollaboration(
+        em,
+        id,
+        scope
+      );
+      if (!content) return null;
+      return {
+        yjsState: content.yjsState ?? null,
+        contentHtml: content.contentHtml ?? null,
+        updatedAt: content.updatedAt,
+        collaborationGeneration: content.collaborationGeneration
+      };
+    },
+    loadCollaborationGeneration: (em, id, scope) => loadDocumentCollaborationGeneration(
+      em,
+      id,
+      scope
+    ),
+    initializeYjsState: (em, id, scope) => initializeDocumentYjsState(
+      em,
+      id,
+      scope
+    ),
+    persistContent: (em, id, scope, input, serviceDeps) => persistDocumentContent(
+      em,
+      id,
+      scope,
+      input,
+      serviceDeps
+    ),
+    allowedOrigins,
+    requireOrigin: process.env.NODE_ENV === "production",
+    onPersisted: (document, yjsState, collaborationGeneration) => {
+      redisStoreExtension?.markPersisted(document, yjsState, collaborationGeneration);
+    },
+    finalDrainRegistry,
+    resolveRoomDocument: (documentName) => server?.hocuspocus.documents.get(documentName),
+    isRoomInvalidated: (documentName, document) => {
+      const room = document ?? server?.hocuspocus.documents.get(documentName);
+      return Boolean(room && invalidatedRoomDocuments.has(room));
+    },
+    invalidateRoom
+  });
+  const runningServer = new Server({
+    port,
+    ...COLLAB_SERVER_RUNTIME_CONFIGURATION,
+    extensions: resolveDocumentsCollabRedisExtensions(
+      process.env,
+      (configuration) => {
+        redisStoreExtension = new DocumentsCollabRedisExtension(configuration, {
+          resolveCollaborationGeneration: hooks.resolveCollaborationGeneration,
+          onRejectedAggregate: invalidateRoom,
+          onAcceptedAggregate: (document, byteLength) => {
+            hooks.recordRedisAggregate(document, byteLength);
+          }
+        });
+        return enforceDocumentsCollabSourceStoreOwnership(redisStoreExtension);
+      }
+    ),
+    async onAuthenticate(data) {
+      return await hooks.onAuthenticate({
+        token: data.token,
+        documentName: data.documentName,
+        connection: data.connectionConfig,
+        requestHeaders: headersToRecord(data.requestHeaders)
+      });
+    },
+    async connected(data) {
+      try {
+        hooks.establishConnectionAuthorization(data.context);
+      } catch (error) {
+        data.connection.close();
+        hooks.releaseConnectionAuthorization(data.context);
+        throw error;
+      }
+      if (data.context.exp !== null) {
+        scheduleCollabConnectionExpiry(data.connection, data.context.exp);
+      }
+      scheduleCollabConnectionReauthorization(
+        data.connection,
+        () => hooks.reauthorizeActiveConnection(data.context)
+      );
+    },
+    async beforeHandleMessage(data) {
+      try {
+        hooks.assertConnectionAuthorization(data.context);
+      } catch (error) {
+        data.connection.close();
+        hooks.releaseConnectionAuthorization(data.context);
+        throw error;
+      }
+      assertCollabInboundFramePolicy(data.update, {
+        readOnly: data.connection.readOnly
+      });
+    },
+    async beforeHandleAwareness(data) {
+      if (!data.connection) return;
+      return hooks.beforeHandleAwareness({
+        context: data.context,
+        states: data.states,
+        ownedClientIds: new Set(data.document.getClients(data.connection)),
+        occupiedClientIds: new Set(data.awareness.getStates().keys()),
+        connection: data.connection,
+        document: data.document
+      });
+    },
+    async beforeSync(data) {
+      return hooks.beforeSync({
+        type: data.type,
+        payload: data.payload,
+        document: data.document,
+        connection: data.connection,
+        context: data.context
+      });
+    },
+    async onLoadDocument(data) {
+      try {
+        hooks.assertConnectionAuthorization(data.context);
+        const document = await hooks.onLoadDocument({
+          documentName: data.documentName,
+          context: data.context,
+          document: data.document
+        });
+        hooks.assertConnectionAuthorization(data.context);
+        return document;
+      } catch (error) {
+        hooks.releaseConnectionAuthorization(data.context);
+        data.document.destroy();
+        throw error;
+      }
+    },
+    async afterLoadDocument(data) {
+      try {
+        hooks.assertConnectionAuthorization(data.context);
+      } catch (error) {
+        hooks.releaseConnectionAuthorization(data.context);
+        data.document.destroy();
+        throw error;
+      }
+    },
+    async onStoreDocument(data) {
+      if (!isDocumentsCollabSourceStore(data)) return;
+      return await hooks.onStoreDocument({
+        documentName: data.documentName,
+        context: data.lastContext,
+        document: data.document
+      });
+    },
+    async onRequest(data) {
+      return handleCollabServerRequest(data);
+    },
+    async onDisconnect(data) {
+      hooks.releaseConnectionAuthorization(data.context);
+    }
+  });
+  server = runningServer;
+  await runningServer.listen();
+  registerCrossProcessEventListener((envelope) => {
+    if (isOwnDocumentsCrossProcessEvent(envelope, CROSS_PROCESS_EVENT_INSTANCE_ID)) return;
+    const trustedEvent = resolveTrustedDocumentsCrossProcessEvent(envelope);
+    if (!trustedEvent) return;
+    const { action, documentId, scope } = trustedEvent;
+    finalDrainRegistry.bumpAuthorization(documentId, scope);
+    const roomDocument = runningServer.hocuspocus.documents.get(documentId);
+    if (roomDocument && !isTrustedDocumentsCollabRoomScope(trustedEvent, hooks.resolveRoomScope(roomDocument))) {
+      return;
+    }
+    if (roomDocument && action === "reauth") {
+      markCollabFinalDrainForReauth(roomDocument, finalDrainRegistry);
+    }
+    if (action === "invalidate") {
+      redisStoreExtension?.discardPendingFanout(documentId);
+      if (roomDocument) {
+        redisStoreExtension?.discardPendingFanout(documentId, roomDocument);
+        finalDrainRegistry.discard(roomDocument);
+        invalidatedRoomDocuments.add(roomDocument);
+      }
+      closeRoomConnectionsForContentReset(documentId);
+      return;
+    }
+    runningServer.hocuspocus.closeConnections(documentId);
+  });
+  let shuttingDown = false;
+  const shutdown = (signal) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    logger.info("shutting down; draining pending document stores", { signal });
+    void runningServer.destroy().catch((error) => {
+      logger.error("graceful shutdown failed", {
+        error: error instanceof Error ? error.message : String(error)
+      });
+      process.exitCode = 1;
+    }).finally(() => {
+      process.exit(process.exitCode ?? 0);
+    });
+  };
+  process.once("SIGTERM", shutdown);
+  process.once("SIGINT", shutdown);
+  logger.info(`listening on :${port}`);
+}
+if (process.env.DOCUMENTS_COLLAB_START !== "off" && isMainModule()) {
+  void main().catch((error) => {
+    logger.error("failed to start", {
+      error: error instanceof Error ? error.stack ?? error.message : String(error)
+    });
+    process.exitCode = 1;
+  });
+}
+export {
+  COLLAB_SERVER_RUNTIME_CONFIGURATION,
+  COLLAB_SERVER_TRANSPORT_OPTIONS,
+  COLLAB_SERVER_UNAUTHENTICATED_CONFIGURATION,
+  COLLAB_SERVER_WEBSOCKET_CONFIGURATION,
+  DOCUMENTS_COLLAB_ACTIVE_REAUTHORIZATION_INTERVAL_MS,
+  DOCUMENTS_COLLAB_AUTHORIZATION_TICKET_TIMEOUT_MS,
+  DOCUMENTS_COLLAB_MAX_AWARENESS_CLIENT_IDS_PER_CONNECTION,
+  DOCUMENTS_COLLAB_MAX_AWARENESS_CLIENT_IDS_PER_ROOM,
+  DOCUMENTS_COLLAB_MAX_AWARENESS_FRAME_BYTES,
+  DOCUMENTS_COLLAB_MAX_AWARENESS_STATE_BYTES,
+  DOCUMENTS_COLLAB_MAX_CONTROL_FRAME_BYTES,
+  DOCUMENTS_COLLAB_MAX_PENDING_BYTES,
+  DOCUMENTS_COLLAB_MAX_PENDING_DOCUMENTS,
+  DOCUMENTS_COLLAB_MAX_PENDING_MESSAGES,
+  DOCUMENTS_COLLAB_MAX_READ_ONLY_SYNC_FRAME_BYTES,
+  DOCUMENTS_COLLAB_REDIS_FANOUT_MAX_PENDING_BYTES,
+  DOCUMENTS_COLLAB_REDIS_FANOUT_MAX_PENDING_ROOMS,
+  DOCUMENTS_COLLAB_REDIS_SUBSCRIBE_TIMEOUT_MS,
+  DocumentsCollabRedisExtension,
+  assertCollabInboundFramePolicy,
+  assertDocumentsCollabRedisAggregateUpdate,
+  authorizeCollabContext,
+  bindCollabAwarenessStates,
+  closeCollabRoomConnectionsForContentReset,
+  createCollabFinalDrainRegistry,
+  createCollabHooks,
+  enforceDocumentsCollabSourceStoreOwnership,
+  handleCollabHealthRequest,
+  handleCollabServerRequest,
+  htmlToYDoc,
+  initializeDocumentYjsState,
+  installBoundedCollabIngress,
+  installHocuspocusCollabIngressGuard,
+  isCollabAuthorizationCurrent,
+  isCollabRequestOriginAllowed,
+  isDocumentsCollabSourceStore,
+  isOwnDocumentsCrossProcessEvent,
+  isTrustedDocumentsCollabRoomScope,
+  main,
+  markCollabFinalDrainForReauth,
+  resolveCollabAllowedOrigins,
+  resolveCollabRoomEventAction,
+  resolveDocumentsCollabRedisConfiguration,
+  resolveDocumentsCollabRedisExtensions,
+  resolveTrustedDocumentsCrossProcessEvent,
+  scheduleCollabConnectionExpiry,
+  scheduleCollabConnectionReauthorization,
+  yDocToContent
+};
+//# sourceMappingURL=documents-collab-server.js.map