@superdoc/v2-collaboration-upgrade

Node-only, fail-closed tooling for moving a collaboration document from SuperDoc v1 to a separate v2 room.

import { upgradeCollaboration } from '@superdoc/v2-collaboration-upgrade';
import { createBinaryStoreUpgradeAdapter } from '@superdoc/v2-collaboration-upgrade/binary-store';

const provider = createBinaryStoreUpgradeAdapter({
  read: async (roomId) => storage.read(roomId),
  create: async (roomId, update) => storage.createIfAbsent(roomId, update),
});

await upgradeCollaboration({
  documentId: 'invoice-123',
  sourceRoomId: 'invoice-123-v1',
  provider,
  activate: ({ documentId, targetRoomId, idempotencyKey }) =>
    routing.activateOnce({ documentId, targetRoomId, idempotencyKey }),
});

Pause edits for the document before calling the API and resume them only after it succeeds. The source room is read but never written. A new v2 room is created and freshly read back through the provider. SuperDoc then re-reads the complete v1 source and refuses to call activate if its bytes, storage identity, or fencing generation changed.

The final source check is defense in depth, not a replacement for pausing writers: a provider read and your routing transaction cannot be made atomic by a provider-neutral library.

activateOnce is your one durable routing compare-and-set. It must return { disposition: 'activated' | 'already-active', routingVersion: string }. SuperDoc supplies the same idempotencyKey on every retry and rejects a void or malformed response. A retry may call this function again, but it must return already-active instead of changing routing a second time.

Persist targetRoomId as the v2 collaboration document ID. providerRoomName is the encoded physical provider key exposed only for diagnostics and custom storage adapters.

Provider adapters are separate imports so the root package does not load y-websocket, Hocuspocus, or Liveblocks clients. superdoc is a peer dependency: the package loads its narrow Node upgrade engine instead of bundling the interactive editor or renderer.

This is the only upgrade package customers install. It includes a frozen [email protected] reader that runs in an isolated child process. The v1 runtime never shares an editor process with v2 and never receives a writable provider.