primitive-admin 1.1.0-alpha.73 → 1.1.0-alpha.74

package/dist/src/commands/documents.js

@@ -7,6 +7,20 @@ import { parseFilterOptions } from "../lib/record-filter.js";
 import { ulid } from "ulid";
 import * as fs from "fs";
 import * as path from "path";
+/**
+ * Report a document's format (#2816) — but only when it is a large document.
+ *
+ * The format is chosen at creation and never migrated, so an operator has to
+ * be able to read it back: `--large` that the server ignored would otherwise
+ * hand back an ordinary-looking document. A legacy document says nothing at
+ * all, so its output is byte-for-byte what it has always been, however the
+ * stored row spells the format (absent, null or 1).
+ */
+function printDocumentFormat(doc) {
+    if (Number(doc?.documentFormat) === 2) {
+        keyValue("Format", "2 (large document)");
+    }
+}
 /**
  * Resolve a `--owner` value to a userId. A value containing "@" is looked up
  * by exact email through the member-accessible `users/lookup` endpoint
@@ -108,6 +122,7 @@ Examples:
             keyValue("Created By", doc.createdBy);
             keyValue("Created", formatDate(doc.createdAt));
             keyValue("Modified", formatDate(doc.modifiedAt ?? doc.lastModified));
+            printDocumentFormat(doc);
             // `GET documents/:id` reports the caller's own access, not the
             // document's grant/alias/collection inventory — printing counts for
             // fields the endpoint never returns read as a definitive "0" for
@@ -135,6 +150,7 @@ Examples:
         .argument("<title>", "Document title")
         .option("--app <app-id>", "App ID")
         .option("--owner <userId-or-email>", "User ID or email to own the document (super-admin or assigned-console-admin tokens only)")
+        .option("--large", "Create a large document (format 2): base snapshots + epoch overlays, for documents that outgrow a single in-memory Y.Doc")
         .option("--json", "Output as JSON")
         .addHelpText("after", `
 Ownership:
@@ -166,6 +182,9 @@ Ownership:
             const result = await client.createDocument(resolvedAppId, {
                 title,
                 ...(ownerUserId ? { createdBy: ownerUserId } : {}),
+                // Opt-in only: without --large nothing is sent, so the document is
+                // created in the legacy format exactly as before (#2816).
+                ...(options.large ? { documentFormat: 2 } : {}),
             });
             if (options.json) {
                 json(result);
@@ -175,6 +194,9 @@ Ownership:
             keyValue("Document ID", result.documentId);
             keyValue("Title", result.title);
             keyValue("Owner", result.createdBy);
+            // Read back from the RESPONSE, not from `--large`: what the server
+            // created is what the document will be for the rest of its life.
+            printDocumentFormat(result);
         }
         catch (err) {
             error(err.message);
@@ -1149,8 +1171,28 @@ Permissions (enforced by the server, not the CLI):
                     warn(`Failed to export ${docId}: ${err.message}`);
                 }
             }
-            // Write manifest
+            // Write manifest. `export-all` is per-user, and each run REPLACES the
+            // manifest with its own ids — so exporting a second user into the same
+            // directory leaves the first user's documents on disk but unreachable
+            // through the manifest an import reads. The supported migration is one
+            // directory per user; a run that would drop ids says so (#3135).
             const manifestPath = path.join(options.output, "manifest.json");
+            if (fs.existsSync(manifestPath)) {
+                try {
+                    const existing = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+                    const dropped = (Array.isArray(existing?.documents) ? existing.documents : []).filter((id) => !exportedIds.includes(id));
+                    if (dropped.length > 0) {
+                        warn(`The manifest already in ${options.output} lists ` +
+                            `${dropped.length} document(s) this export does not: ` +
+                            `${dropped.join(", ")}. Replacing it leaves them on disk but ` +
+                            `no longer reachable through the manifest an import reads — ` +
+                            `export each user into their own directory.`);
+                    }
+                }
+                catch {
+                    // An unreadable manifest is not a reason to refuse the export.
+                }
+            }
             const manifest = {
                 version: 1,
                 exportedAt: new Date().toISOString(),
@@ -1179,7 +1221,12 @@ Permissions (enforced by the server, not the CLI):
         .argument("<path>", "Path to export directory or single document directory")
         .option("--app <app-id>", "App ID")
         .option("--aliases <mode>", "Alias conflict handling: overwrite or skip", "skip")
-        .option("--overwrite", "Replace existing documents if IDs collide")
+        // `--overwrite` has never replaced a document: the import path issues no
+        // delete and calls `import/state`, whose room handler merges the exported
+        // state into the document with `Y.applyUpdate`. The description says so
+        // (#3135), and names the one id remapping on top of it — plus the one
+        // format that is installed rather than merged.
+        .option("--overwrite", "Merge the exported state into a document that already exists (a root document export is merged into the target user's root document; a large-document export is installed, so it needs a document that holds nothing yet)")
         .option("--dry-run", "Show what would be imported without making changes")
         .option("--owner <userId-or-email>", "User ID or email to set as document owner (admin only)")
         .option("--json", "Output as JSON")
@@ -1251,9 +1298,30 @@ Permissions (enforced by the server, not the CLI):
                 blobsUploaded: 0,
                 aliasesSet: 0,
                 aliasesSkipped: 0,
+                rootDocuments: [],
             };
+            // Where every root-marked export in this run lands, decided from reads
+            // alone and before any write (#3135): a refusal, or two exports
+            // competing for one user's root document, is reported up front.
+            const rootPlans = await planRootImports(client, resolvedAppId, docDirs, options.owner, ownerUserId, options.overwrite || false);
+            // Nothing is created until every artifact is one this CLI can install:
+            // a refusal halfway through a multi-document import would leave the
+            // app half-populated (#2816). A root export is never installed as a
+            // chain — `planRootImports` has already refused a format-2 one — so it
+            // is not vouched for here.
             for (const docDir of docDirs) {
-                await importSingleDocument(client, resolvedAppId, docDir, options.overwrite || false, options.aliases || "skip", options.dryRun || false, summary, ownerUserId);
+                if (rootPlans.has(docDir))
+                    continue;
+                if (!largeDocumentArtifactAt(docDir))
+                    continue;
+                const metadataPath = path.join(docDir, "metadata.json");
+                const documentId = fs.existsSync(metadataPath)
+                    ? JSON.parse(fs.readFileSync(metadataPath, "utf-8")).documentId
+                    : path.basename(docDir);
+                readChainArtifact(docDir, documentId);
+            }
+            for (const docDir of docDirs) {
+                await importSingleDocument(client, resolvedAppId, docDir, options.overwrite || false, options.aliases || "skip", options.dryRun || false, summary, ownerUserId, rootPlans.get(docDir));
             }
             if (options.json) {
                 json(summary);
@@ -1317,14 +1385,105 @@ Permissions (enforced by the server, not the CLI):
 // ============================================
 // Helper functions for export/import
 // ============================================
+/**
+ * Write a large document's export chain into `docDir` (#2816, behavior 20).
+ *
+ * The layout mirrors the chain and is applied in that order on import:
+ *
+ * ```
+ *   chain.json          what this artifact is, and the order to apply it in
+ *   snapshot/           manifest.json + {model}/{n}.ndjson.gz, when there is a base
+ *   epochs/{E}.yjs      each sealed overlay after the base's epoch, oldest first
+ *   current.yjs         the open epoch's overlay
+ * ```
+ *
+ * The server refuses a chain it cannot vouch for, so nothing here has to guess
+ * whether an artifact is complete; what this function must not do is write a
+ * PARTIAL one, which is why `chain.json` — the file that says "this is a
+ * complete v2 export" — is written last.
+ *
+ * Returns the bytes written, which is what `--json` reports as the document's
+ * size: for a large document that is the artifact, not one Yjs update.
+ */
+async function exportLargeDocumentChain(client, appId, documentId, docDir) {
+    const chain = await client.exportDocumentChain(appId, documentId);
+    let bytes = 0;
+    // The open epoch's overlay travels inline: the rotation threshold bounds it.
+    const current = Buffer.from(chain.current.update, "base64");
+    fs.writeFileSync(path.join(docDir, "current.yjs"), current);
+    bytes += current.byteLength;
+    const overlays = [];
+    if (Array.isArray(chain.overlays) && chain.overlays.length > 0) {
+        const epochsDir = path.join(docDir, "epochs");
+        fs.mkdirSync(epochsDir, { recursive: true });
+        for (const overlay of chain.overlays) {
+            const archive = await client.downloadDocumentArtifact(appId, overlay.download.path);
+            fs.writeFileSync(path.join(epochsDir, `${overlay.epoch}.yjs`), archive);
+            bytes += archive.byteLength;
+            overlays.push({ epoch: overlay.epoch, sealedAt: overlay.sealedAt ?? null });
+        }
+    }
+    let base = null;
+    if (chain.base) {
+        const snapshotDir = path.join(docDir, "snapshot");
+        fs.mkdirSync(snapshotDir, { recursive: true });
+        const manifestBytes = await client.downloadDocumentArtifact(appId, chain.base.download.path);
+        fs.writeFileSync(path.join(snapshotDir, "manifest.json"), manifestBytes);
+        const manifest = JSON.parse(manifestBytes.toString("utf-8"));
+        for (const chunk of manifest.chunks ?? []) {
+            // Addressed within the granted build — `{model}/{n}` — never by key.
+            const index = chunkIndexFromKey(chunk.key);
+            const body = await client.downloadDocumentArtifact(appId, `${chain.base.download.path}/${chunk.model}/${index}`);
+            const modelDir = path.join(snapshotDir, chunk.model);
+            fs.mkdirSync(modelDir, { recursive: true });
+            fs.writeFileSync(path.join(modelDir, `${index}.ndjson.gz`), body);
+            bytes += body.byteLength;
+        }
+        base = {
+            epoch: chain.base.epoch,
+            buildId: chain.base.buildId,
+            rows: chain.base.rows,
+        };
+    }
+    // Last, and without the signatures: a grant is this run's read of the
+    // document, and an artifact that outlives it must not carry one.
+    fs.writeFileSync(path.join(docDir, "chain.json"), JSON.stringify({
+        version: 2,
+        documentFormat: 2,
+        documentId,
+        epoch: chain.epoch,
+        base,
+        overlays,
+        current: { epoch: chain.current.epoch, file: "current.yjs" },
+    }, null, 2));
+    return bytes;
+}
+/** The chunk number out of a manifest entry's key (`…/{model}/{n}.ndjson.gz`). */
+function chunkIndexFromKey(key) {
+    const match = /\/(\d+)\.ndjson\.gz$/.exec(String(key ?? ""));
+    if (!match) {
+        throw new Error(`Snapshot manifest names a chunk this CLI cannot address: ${key}`);
+    }
+    return Number(match[1]);
+}
 async function exportSingleDocument(client, appId, documentId, outputDir, includeBlobs, jsonOutput) {
     const docDir = path.join(outputDir, "documents", documentId);
     fs.mkdirSync(docDir, { recursive: true });
     // 1. Fetch document metadata
     const docMeta = await client.getDocument(appId, documentId);
-    // 2. Export Yjs state
-    const stateResult = await client.exportDocumentState(appId, documentId);
-    fs.writeFileSync(path.join(docDir, "document.yjs"), Buffer.from(stateResult.state, "base64"));
+    // 2. Export the document's state. A legacy document is one blob; a large
+    //    one (#2816) is the chain — snapshot, sealed overlays, open epoch —
+    //    because the blob is exactly the whole-document-in-memory cost format 2
+    //    exists to avoid.
+    let stateBytes;
+    if (Number(docMeta?.documentFormat) === 2) {
+        stateBytes = await exportLargeDocumentChain(client, appId, documentId, docDir);
+    }
+    else {
+        const stateResult = await client.exportDocumentState(appId, documentId);
+        fs.writeFileSync(path.join(docDir, "document.yjs"), Buffer.from(stateResult.state, "base64"));
+        stateBytes = stateResult.byteLength;
+    }
     // 3. Fetch permissions
     let permissions = [];
     try {
@@ -1370,11 +1529,15 @@ async function exportSingleDocument(client, appId, documentId, outputDir, includ
     catch {
         // May not have aliases
     }
-    // 6. Write metadata
+    // 6. Write metadata. A large document says so here as well as in
+    //    `chain.json`: the format decides how the artifact has to be installed,
+    //    and an import that reads only `metadata.json` must not mistake one for
+    //    a legacy document (#2816).
     const metadata = {
         documentId: docMeta.documentId || documentId,
         title: docMeta.title,
         tags: docMeta.tags || [],
+        ...(Number(docMeta?.documentFormat) === 2 ? { documentFormat: 2 } : {}),
         createdAt: docMeta.createdAt,
         createdBy: docMeta.createdByEmail || docMeta.createdBy,
         aliases: aliases.map((a) => ({
@@ -1415,7 +1578,7 @@ async function exportSingleDocument(client, appId, documentId, outputDir, includ
         json({
             documentId,
             title: metadata.title,
-            stateBytes: stateResult.byteLength,
+            stateBytes,
             permissions: permissionsExport.length,
             aliases: aliases.length,
             exportPath: docDir,
@@ -1425,7 +1588,388 @@ async function exportSingleDocument(client, appId, documentId, outputDir, includ
         success(`Exported document ${documentId} (${metadata.title || "untitled"}) to ${docDir}`);
     }
 }
-async function importSingleDocument(client, appId, docDir, overwrite, aliasMode, dryRun, summary, ownerUserId) {
+/**
+ * Whether `docDir` holds a large document's export (#2816, behavior 20).
+ *
+ * Either marker is enough: `chain.json` is what the chain export writes last,
+ * and `metadata.json` carries the format for artifacts inspected on their own.
+ */
+function largeDocumentArtifactAt(docDir) {
+    if (fs.existsSync(path.join(docDir, "chain.json")))
+        return true;
+    const metadataPath = path.join(docDir, "metadata.json");
+    if (!fs.existsSync(metadataPath))
+        return false;
+    try {
+        const metadata = JSON.parse(fs.readFileSync(metadataPath, "utf-8"));
+        return Number(metadata?.documentFormat) === 2;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read (and vouch for) a large document's chain artifact.
+ *
+ * `chain.json` is what the export writes LAST, so its absence means the
+ * artifact is partial — a directory recognizable as a large document with no
+ * description of what to install. Importing that as a legacy document would
+ * read a `document.yjs` that is not there, create an empty document, and
+ * report success: total data loss from the operator's point of view, since the
+ * export is the only copy they were told they had. Refusing is the honest
+ * answer, and it happens before anything is created.
+ */
+function readChainArtifact(docDir, documentId) {
+    const chainPath = path.join(docDir, "chain.json");
+    if (!fs.existsSync(chainPath)) {
+        throw new Error(`Document ${documentId} was exported as a large document (documentFormat 2), ` +
+            `but ${chainPath} is missing, so this artifact is incomplete. A large document's ` +
+            `data IS its chain — a base snapshot, the sealed overlays after it, and the open ` +
+            `epoch — and importing this directory as a legacy document would create an EMPTY ` +
+            `document. Nothing was imported.`);
+    }
+    let chain;
+    try {
+        chain = JSON.parse(fs.readFileSync(chainPath, "utf-8"));
+    }
+    catch (parseError) {
+        throw new Error(`Document ${documentId}: ${chainPath} is not readable as a chain description ` +
+            `(${parseError.message}), so nothing was imported.`);
+    }
+    if (!Number.isSafeInteger(Number(chain?.epoch))) {
+        throw new Error(`Document ${documentId}: ${chainPath} names no open epoch, so nothing was imported.`);
+    }
+    const artifact = {
+        epoch: Number(chain.epoch),
+        base: chain.base
+            ? {
+                epoch: Number(chain.base.epoch),
+                buildId: String(chain.base.buildId),
+                rows: Number(chain.base.rows ?? 0),
+            }
+            : null,
+        overlays: (Array.isArray(chain.overlays) ? chain.overlays : []).map((overlay) => ({ epoch: Number(overlay.epoch) })),
+    };
+    verifyChainArtifact(docDir, documentId, artifact);
+    return artifact;
+}
+/**
+ * Check that the directory holds every file the chain names, and that the
+ * chain is one.
+ *
+ * `chain.json` being present says the export finished writing; it does not say
+ * the files are there, and until this check the first missing chunk was found
+ * AFTER the destination document had been created — leaving an empty document
+ * behind, and in a multi-document import an app half-populated. The chain's
+ * shape is checked here too, for the same reason the server checks it: a
+ * chain with an epoch missing from the middle installs cleanly and is missing
+ * everything that epoch held.
+ */
+function verifyChainArtifact(docDir, documentId, chain) {
+    const refuse = (reason) => {
+        throw new Error(`Document ${documentId}: its large-document export ${reason}, so nothing was imported.`);
+    };
+    const from = chain.base ? chain.base.epoch : 1;
+    const expected = [];
+    for (let epoch = from; epoch < chain.epoch; epoch++)
+        expected.push(epoch);
+    const named = chain.overlays
+        .map((overlay) => overlay.epoch)
+        .sort((left, right) => left - right);
+    if (named.length !== expected.length ||
+        named.some((epoch, index) => epoch !== expected[index])) {
+        refuse(`describes sealed overlays [${named.join(", ")}] where the chain from ` +
+            (chain.base ? `its base at epoch ${chain.base.epoch}` : "epoch 1") +
+            ` to its open epoch ${chain.epoch} is [${expected.join(", ")}]`);
+    }
+    const require = (file, what) => {
+        if (!fs.existsSync(file))
+            refuse(`is missing ${what} (${file})`);
+    };
+    if (chain.base) {
+        const manifestPath = path.join(docDir, "snapshot", "manifest.json");
+        require(manifestPath, "its base snapshot's manifest");
+        let manifest;
+        try {
+            manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+        }
+        catch (parseError) {
+            refuse(`has a base snapshot manifest that is not readable ` +
+                `(${parseError.message})`);
+        }
+        for (const chunk of manifest.chunks ?? []) {
+            const index = chunkIndexFromKey(String(chunk.key));
+            require(path.join(docDir, "snapshot", String(chunk.model), `${index}.ndjson.gz`), `chunk ${index} of ${chunk.model}`);
+        }
+    }
+    for (const overlay of chain.overlays) {
+        require(path.join(docDir, "epochs", `${overlay.epoch}.yjs`), `the archived overlay of epoch ${overlay.epoch}`);
+    }
+    require(path.join(docDir, "current.yjs"), "its open epoch's overlay");
+}
+/** How long an install is waited on before the CLI gives up on it. */
+const CHAIN_INSTALL_TIMEOUT_MS = 60 * 60 * 1000;
+/** How often the install's progress is asked for. */
+const CHAIN_INSTALL_POLL_MS = 1000;
+/**
+ * Install a large document's chain export into a freshly created document
+ * (#2816, behavior 20).
+ *
+ * Every artifact is uploaded byte-for-byte into the new document's own prefix
+ * — the manifest's digests are over the STORED bytes, so re-encoding a chunk
+ * here would fail its own verification on install — and then the server
+ * streams them into the document's `records` table a tick at a time. The full
+ * document is never built as a Y.Doc on either side, which is what makes
+ * importing a multi-hundred-MB artifact possible at all; it is also the
+ * efficient way to bulk-seed a new large document.
+ */
+async function importLargeDocumentChain(client, appId, docDir, documentId) {
+    const chain = readChainArtifact(docDir, documentId);
+    // The base's manifest and chunks. The manifest names the chunks, so nothing
+    // here has to walk the directory and guess what belongs to the build.
+    if (chain.base) {
+        const manifestPath = path.join(docDir, "snapshot", "manifest.json");
+        const manifestBytes = fs.readFileSync(manifestPath);
+        await client.uploadDocumentChainArtifact(appId, documentId, {
+            kind: "manifest",
+            epoch: chain.base.epoch,
+            buildId: chain.base.buildId,
+        }, manifestBytes);
+        const manifest = JSON.parse(manifestBytes.toString("utf-8"));
+        for (const chunk of manifest.chunks ?? []) {
+            const index = chunkIndexFromKey(chunk.key);
+            await client.uploadDocumentChainArtifact(appId, documentId, {
+                kind: "chunk",
+                epoch: chain.base.epoch,
+                buildId: chain.base.buildId,
+                model: chunk.model,
+                index,
+            }, fs.readFileSync(path.join(docDir, "snapshot", chunk.model, `${index}.ndjson.gz`)));
+        }
+    }
+    // The sealed overlays, oldest first, then the open epoch's — which travels
+    // archived exactly like a sealed one, so the imported document's chain is
+    // the chain that was exported.
+    for (const overlay of chain.overlays) {
+        await client.uploadDocumentChainArtifact(appId, documentId, { kind: "overlay", epoch: overlay.epoch }, fs.readFileSync(path.join(docDir, "epochs", `${overlay.epoch}.yjs`)));
+    }
+    await client.uploadDocumentChainArtifact(appId, documentId, { kind: "overlay", epoch: chain.epoch }, fs.readFileSync(path.join(docDir, "current.yjs")));
+    await client.installDocumentChain(appId, documentId, {
+        base: chain.base
+            ? { epoch: chain.base.epoch, buildId: chain.base.buildId }
+            : null,
+        overlays: chain.overlays.map((overlay) => overlay.epoch),
+        currentEpoch: chain.epoch,
+    });
+    // The install runs on the document's alarm, a bounded tick at a time, so it
+    // is waited on rather than awaited: reporting "imported" while the records
+    // are still arriving is the failure this whole path exists to avoid.
+    const deadline = Date.now() + CHAIN_INSTALL_TIMEOUT_MS;
+    for (;;) {
+        const status = await client.getDocumentChainInstall(appId, documentId);
+        const install = status?.install;
+        if (install?.state === "complete")
+            return;
+        if (install?.state === "failed") {
+            throw new Error(`Document ${documentId}: installing its chain failed — ` +
+                `${install.error || "no reason given"}. The document is incomplete ` +
+                `and should be deleted before the import is retried.`);
+        }
+        if (Date.now() >= deadline) {
+            throw new Error(`Document ${documentId}: its chain install has not finished after ` +
+                `${Math.round(CHAIN_INSTALL_TIMEOUT_MS / 60000)} minutes. It continues ` +
+                `on the server; check with 'primitive documents get ${documentId}'.`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, CHAIN_INSTALL_POLL_MS));
+    }
+}
+/** Mirrors `ROOT_DOCUMENT_TAG` in `src/config/constants.ts`. */
+const ROOT_DOCUMENT_TAG = "__ROOT_TAG__";
+/** Does this `metadata.json` describe somebody's root document? */
+function isRootDocumentExport(tags) {
+    return Array.isArray(tags) && tags.includes(ROOT_DOCUMENT_TAG);
+}
+/**
+ * Why a large-document root export is refused (#3135, contract 7).
+ *
+ * A format-2 export is a chain installed wholesale into a freshly created
+ * format-2 document — a replace, not a merge, and not something that can be
+ * done to a root document, which the server only ever mints as a legacy
+ * document. Refusing says so rather than installing a chain somewhere it does
+ * not belong.
+ */
+const ROOT_LARGE_DOCUMENT_REFUSAL = "it is a root document exported as a large document (documentFormat 2). A " +
+    "root document is minted as a legacy document and a chain is installed " +
+    "wholesale into a new format-2 document, so the export cannot be applied " +
+    "to the target user's root. Nothing was imported for it.";
+/** Read an export directory's `metadata.json`, or null when it has none. */
+function readExportMetadata(docDir) {
+    const metadataPath = path.join(docDir, "metadata.json");
+    if (!fs.existsSync(metadataPath))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(metadataPath, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Decide what each root-marked export in this run resolves to (#3135).
+ *
+ * A root document is a per-user singleton the server owns: the exported id is
+ * the SOURCE user's root and means nothing here, so the export is mapped to
+ * the TARGET user's root document instead. The target is `--owner` when given,
+ * otherwise the owner `metadata.json` recorded — an email since #3135, which
+ * is the only owner identity that survives a move between environments.
+ *
+ * Only a definitive answer reads as absence: `exists: false` from the email
+ * lookup, or a 404 from the root-document read. Anything else (an expired
+ * login, a lost permission, a server fault) fails the run, exactly as the
+ * document-existence check does (#3096) — a failed read must never turn into a
+ * confident create.
+ */
+async function planRootImports(client, appId, docDirs, explicitOwner, explicitOwnerUserId, overwrite) {
+    const plans = new Map();
+    for (const docDir of docDirs) {
+        const metadata = readExportMetadata(docDir);
+        if (!metadata || !isRootDocumentExport(metadata.tags))
+            continue;
+        const exportedDocumentId = metadata.documentId || path.basename(docDir);
+        const owner = String(explicitOwner || metadata.createdBy || "");
+        const plan = {
+            docDir,
+            exportedDocumentId,
+            owner,
+            action: "refused",
+        };
+        const refuse = (reason) => {
+            plan.action = "refused";
+            plan.reason = reason;
+            plans.set(docDir, plan);
+        };
+        if (Number(metadata.documentFormat) === 2) {
+            refuse(ROOT_LARGE_DOCUMENT_REFUSAL);
+            continue;
+        }
+        if (!owner) {
+            refuse(`it is a root document export that records no owner, so there is no ` +
+                `user in ${appId} to restore it into. Pass --owner <userId-or-email>.`);
+            continue;
+        }
+        // Resolve the target user. An explicit `--owner` was already resolved,
+        // command-level, before anything was read.
+        let targetUserId = explicitOwnerUserId;
+        if (!targetUserId) {
+            if (owner.includes("@")) {
+                // Absence is what the lookup ANSWERS with — `exists: false` on a 200.
+                // A thrown lookup is a failed read (an expired login, a lost
+                // permission, a proxy), and a failed read must never pass for "no such
+                // user": it fails the run instead (#3096).
+                let lookup;
+                try {
+                    lookup = await client.lookupUserByEmail(appId, owner);
+                }
+                catch (error) {
+                    throw new Error(`Document ${exportedDocumentId}: looking up its recorded owner ` +
+                        `"${owner}" failed — ${error?.message || "no reason given"}. ` +
+                        `Nothing was imported.`);
+                }
+                if (!lookup?.exists || !lookup.user) {
+                    refuse(unresolvableRootOwner(appId, owner));
+                    continue;
+                }
+                targetUserId = lookup.user.userId;
+            }
+            else {
+                targetUserId = owner;
+            }
+        }
+        plan.targetUserId = targetUserId;
+        let assignment;
+        try {
+            assignment = await client.getUserRootDocument(appId, targetUserId);
+        }
+        catch (error) {
+            if (error?.statusCode !== 404) {
+                throw new Error(`Document ${exportedDocumentId}: reading the root document of ` +
+                    `"${owner}" failed — ${error?.message || "no reason given"}. ` +
+                    `Nothing was imported.`);
+            }
+            refuse(unresolvableRootOwner(appId, owner));
+            continue;
+        }
+        const rootDocId = assignment?.rootDocId || null;
+        if (!rootDocId) {
+            plan.action = "create";
+        }
+        else {
+            plan.targetRootDocId = rootDocId;
+            plan.action = overwrite ? "apply" : "skip";
+        }
+        plans.set(docDir, plan);
+    }
+    assertDistinctRootTargets(plans);
+    return plans;
+}
+/** Why a recorded owner cannot be restored into, and what to do about it. */
+function unresolvableRootOwner(appId, owner) {
+    return (`it is a root document export whose owner "${owner}" is not a user of ` +
+        `app ${appId}. A root document is restored into one specific user's own ` +
+        `root document, so name the target user with --owner <userId-or-email>, ` +
+        `or re-export so the owner's email is recorded.`);
+}
+/**
+ * Refuse a run in which two root exports would land in one user's root
+ * document (#3135, contract 5).
+ *
+ * The supported migration is one `export-all --user-id` directory per user,
+ * imported one directory per run. A hand-assembled directory holding two
+ * users' roots — or `--owner` given for a run containing more than one root
+ * export — would merge both sources into a single root and lose one of them,
+ * so it fails before anything is created rather than half-way through.
+ */
+function assertDistinctRootTargets(plans) {
+    const byUser = new Map();
+    for (const plan of plans.values()) {
+        if (plan.action === "refused" || !plan.targetUserId)
+            continue;
+        const seen = byUser.get(plan.targetUserId) ?? [];
+        seen.push(plan.exportedDocumentId);
+        byUser.set(plan.targetUserId, seen);
+    }
+    for (const [userId, documents] of byUser) {
+        if (documents.length > 1) {
+            throw new Error(`Root document exports ${documents.join(", ")} all resolve to user ` +
+                `${userId}, and a user has exactly one root document — importing ` +
+                `them would merge them into each other. Export one user per ` +
+                `directory and import one directory per run. Nothing was imported.`);
+        }
+    }
+}
+/**
+ * Does the target app already hold this document?
+ *
+ * Only an explicit 404 answers "no" (#3096). An expired login (401), a lost
+ * permission (403), a server fault or a transport failure says nothing about
+ * the document, and reading those as absence turns a failed lookup into a
+ * confident create — or, for a root-marked export, into a reported skip that
+ * silently omits the overwrite the operator asked for. Those propagate, and
+ * `documents import` fails the run.
+ */
+async function documentExists(client, appId, documentId) {
+    try {
+        await client.getDocument(appId, documentId);
+        return true;
+    }
+    catch (error) {
+        if (error?.statusCode === 404)
+            return false;
+        throw new Error(`Document ${documentId}: checking whether it already exists failed — ` +
+            `${error?.message || "no reason given"}. Nothing was imported for it.`);
+    }
+}
+async function importSingleDocument(client, appId, docDir, overwrite, aliasMode, dryRun, summary, ownerUserId, rootPlan) {
     const metadataPath = path.join(docDir, "metadata.json");
     if (!fs.existsSync(metadataPath)) {
         warn(`Skipping ${docDir}: no metadata.json found`);
@@ -1434,31 +1978,64 @@ async function importSingleDocument(client, appId, docDir, overwrite, aliasMode,
     }
     const metadata = JSON.parse(fs.readFileSync(metadataPath, "utf-8"));
     const documentId = metadata.documentId;
-    if (dryRun) {
-        info(`[dry-run] Would import document ${documentId} (${metadata.title || "untitled"})`);
-        summary.created++;
+    // A root-marked export is never restored under its exported id: that id is
+    // the SOURCE user's root document. It goes to the target user's own root
+    // instead, per the plan made before this run wrote anything (#3135).
+    //
+    // Decided BEFORE the chain artifact below is read, because a root export is
+    // never installed as a chain: a large-document root is refused by the plan,
+    // and reading its chain here would fail the whole run over an artifact this
+    // run has already decided not to touch.
+    if (isRootDocumentExport(metadata.tags)) {
+        await importRootDocument(client, appId, docDir, metadata, rootPlan, overwrite, aliasMode, dryRun, summary);
         return;
     }
-    // Check if document exists
-    let exists = false;
-    try {
-        await client.getDocument(appId, documentId);
-        exists = true;
-    }
-    catch {
-        exists = false;
-    }
+    // A large document's data is the chain, not `document.yjs` (#2816), and it
+    // is installed rather than replayed. Vouched for before anything is created.
+    const isLargeDocument = largeDocumentArtifactAt(docDir);
+    if (isLargeDocument)
+        readChainArtifact(docDir, documentId);
+    // `--dry-run` decides from the same facts the real run does (#3096), so a
+    // preview never promises a skip that the run turns into a merge: it looks
+    // the document up as well, and only the writes below are withheld.
+    const exists = await documentExists(client, appId, documentId);
+    const wouldSkip = dryRun ? "[dry-run] Would skip" : "Skipping";
     if (exists && !overwrite) {
-        warn(`Skipping ${documentId}: already exists (use --overwrite to replace)`);
+        // `--overwrite` merges a legacy document's state — but a large document is
+        // INSTALLED, and the server refuses to install a chain into a document
+        // that already holds records (`assertDocumentIsImportable`), so the remedy
+        // is only honest for the format the state path handles.
+        warn(isLargeDocument
+            ? `${wouldSkip} ${documentId}: already exists, and ` +
+                `a large-document export is installed rather than merged — ` +
+                `--overwrite can only install it into a document that holds ` +
+                `nothing yet`
+            : `${wouldSkip} ${documentId}: already exists (use --overwrite to merge ` +
+                `the exported state into it)`);
         summary.skipped++;
         return;
     }
-    // Create document if it doesn't exist
+    if (dryRun) {
+        info(`[dry-run] Would ${exists ? "update" : "import"} document ${documentId} ` +
+            `(${metadata.title || "untitled"})`);
+        if (exists)
+            summary.updated++;
+        else
+            summary.created++;
+        return;
+    }
+    // Create document if it doesn't exist. The format is decided at creation and
+    // never migrated, so a large document has to be created as one (#2816).
+    //
+    // Tags go back exactly as `metadata.json` recorded them (#3096): an export
+    // is a faithful record of what the document is, and editing the list on the
+    // way back in loses that.
     if (!exists) {
         await client.createDocument(appId, {
             title: metadata.title || "Imported Document",
             documentId,
             tags: metadata.tags,
+            ...(isLargeDocument ? { documentFormat: 2 } : {}),
             ...(ownerUserId ? { createdBy: ownerUserId } : {}),
         });
         summary.created++;
@@ -1466,12 +2043,19 @@ async function importSingleDocument(client, appId, docDir, overwrite, aliasMode,
     else {
         summary.updated++;
     }
-    // Import Yjs state
-    const yjsPath = path.join(docDir, "document.yjs");
-    if (fs.existsSync(yjsPath)) {
-        const stateBuffer = fs.readFileSync(yjsPath);
-        const stateBase64 = stateBuffer.toString("base64");
-        await client.importDocumentState(appId, documentId, stateBase64);
+    if (isLargeDocument) {
+        // The chain, installed: streamed into the document's records table on the
+        // server, never replayed here as one Yjs update.
+        await importLargeDocumentChain(client, appId, docDir, documentId);
+    }
+    else {
+        // Import Yjs state
+        const yjsPath = path.join(docDir, "document.yjs");
+        if (fs.existsSync(yjsPath)) {
+            const stateBuffer = fs.readFileSync(yjsPath);
+            const stateBase64 = stateBuffer.toString("base64");
+            await client.importDocumentState(appId, documentId, stateBase64);
+        }
     }
     // Upload blobs
     const blobIndexPath = path.join(docDir, "blobs", "index.json");
@@ -1513,4 +2097,140 @@ async function importSingleDocument(client, appId, docDir, overwrite, aliasMode,
     }
     info(`Imported document ${documentId} (${metadata.title || "untitled"})`);
 }
+/**
+ * Restore a root-marked export into the target user's own root document
+ * (#3135).
+ *
+ * The exported id is never created and never looked up: it is the source
+ * user's root id, which means nothing in this app. Everything — the Yjs state,
+ * the blobs, the user-scoped aliases — is written against the target user's
+ * root document id instead, so blob references inside the document still
+ * resolve and the app still holds exactly one root document per user.
+ *
+ * "Apply" is the merge `import/state` has always performed: keys only one side
+ * holds survive, and a key both sides set resolves by Yjs's own conflict rule,
+ * which guarantees neither source-wins nor target-wins. That is why merging
+ * into an existing root needs `--overwrite` — the default must not quietly
+ * rewrite a user's live preferences.
+ */
+async function importRootDocument(client, appId, docDir, metadata, plan, overwrite, aliasMode, dryRun, summary) {
+    const exportedDocumentId = metadata.documentId || path.basename(docDir);
+    const wouldSkip = dryRun ? "[dry-run] Would skip" : "Skipping";
+    const report = (action, targetRootDocId, reason) => {
+        summary.rootDocuments.push({
+            exportedDocumentId,
+            owner: plan?.owner ?? "",
+            ...(targetRootDocId ? { targetRootDocId } : {}),
+            action,
+            ...(reason ? { reason } : {}),
+        });
+    };
+    if (!plan || plan.action === "refused") {
+        const reason = plan?.reason ||
+            `it is a root document export this run could not resolve to a user in ` +
+                `app ${appId}. Pass --owner <userId-or-email>.`;
+        warn(`${wouldSkip} ${exportedDocumentId}: ${reason}`);
+        summary.skipped++;
+        report("refused", undefined, reason);
+        return;
+    }
+    if (plan.action === "skip") {
+        const reason = `the root document of ${plan.owner} already exists ` +
+            `(${plan.targetRootDocId}); use --overwrite to merge the exported ` +
+            `content into it`;
+        warn(`${wouldSkip} ${exportedDocumentId}: ${reason}`);
+        summary.skipped++;
+        report("skipped", plan.targetRootDocId, reason);
+        return;
+    }
+    if (dryRun) {
+        if (plan.action === "create") {
+            info(`[dry-run] Would create the root document for ${plan.owner} and ` +
+                `apply root document export ${exportedDocumentId} to it`);
+            summary.created++;
+            report("created");
+        }
+        else {
+            info(`[dry-run] Would apply root document export ${exportedDocumentId} to ` +
+                `${plan.owner}'s root document ${plan.targetRootDocId}`);
+            summary.updated++;
+            report("applied", plan.targetRootDocId);
+        }
+        return;
+    }
+    let targetRootDocId = plan.targetRootDocId;
+    let created = false;
+    if (plan.action === "create") {
+        // The server's own get-or-create, and the only place a root document is
+        // ever minted. Its answer — not the preflight read — decides both the id
+        // the content lands in and whether this run created it: a first sign-in
+        // may have minted the root between the read and this call.
+        const ensured = await client.ensureUserRootDocument(appId, plan.targetUserId);
+        targetRootDocId = ensured?.rootDocId;
+        if (!targetRootDocId) {
+            throw new Error(`Document ${exportedDocumentId}: the server returned no root document ` +
+                `for ${plan.owner}, so nothing was imported for it.`);
+        }
+        created = ensured.created === true;
+        if (!created && !overwrite) {
+            const reason = `the root document of ${plan.owner} (${targetRootDocId}) was created ` +
+                `by a concurrent sign-in while this import was running; use ` +
+                `--overwrite to merge the exported content into it`;
+            warn(`Skipping ${exportedDocumentId}: ${reason}`);
+            summary.skipped++;
+            report("skipped", targetRootDocId, reason);
+            return;
+        }
+    }
+    // Only content moves. The target root keeps its own id, title, tags and
+    // permissions — the ensure path already granted the owner read-write.
+    const yjsPath = path.join(docDir, "document.yjs");
+    if (fs.existsSync(yjsPath)) {
+        await client.importDocumentState(appId, targetRootDocId, fs.readFileSync(yjsPath).toString("base64"));
+    }
+    const blobIndexPath = path.join(docDir, "blobs", "index.json");
+    if (fs.existsSync(blobIndexPath)) {
+        const blobIndex = JSON.parse(fs.readFileSync(blobIndexPath, "utf-8"));
+        for (const blob of blobIndex) {
+            const blobPath = path.join(docDir, "blobs", `${blob.blobId}.bin`);
+            if (!fs.existsSync(blobPath))
+                continue;
+            // The blobId is preserved: a document's own references travel by blobId,
+            // so they resolve inside the target root as they did in the source.
+            await client.uploadBlob(appId, targetRootDocId, blob.blobId, fs.readFileSync(blobPath), {
+                filename: blob.filename,
+                contentType: blob.contentType,
+                sha256: blob.sha256,
+            });
+            summary.blobsUploaded++;
+        }
+    }
+    // A root document's user-scoped aliases belong to its owner by definition,
+    // so they are restored without `--owner` — the target user is already known.
+    if (Array.isArray(metadata.aliases)) {
+        for (const alias of metadata.aliases) {
+            if (alias.aliasScope !== "user")
+                continue;
+            try {
+                await client.setDocumentAlias(appId, alias.aliasScope, alias.aliasKey, targetRootDocId, plan.targetUserId, aliasMode === "skip");
+                summary.aliasesSet++;
+            }
+            catch {
+                summary.aliasesSkipped++;
+            }
+        }
+    }
+    if (created) {
+        summary.created++;
+        report("created", targetRootDocId);
+        info(`Created root document ${targetRootDocId} for ${plan.owner} and applied ` +
+            `root document export ${exportedDocumentId} to it`);
+    }
+    else {
+        summary.updated++;
+        report("applied", targetRootDocId);
+        info(`Applied root document export ${exportedDocumentId} to ${plan.owner}'s ` +
+            `root document ${targetRootDocId}`);
+    }
+}
 //# sourceMappingURL=documents.js.map