primitive-admin 1.2.0-alpha.0 → 1.2.0-alpha.2

package/dist/src/commands/documents.js

@@ -10,7 +10,8 @@ import { pageCursorOption, pageLimitOption, parsePageLimit, printEmptyPage, prin
 import { normalizeCliListEnvelope, wholeListEnvelope, } from "../lib/paginate.js";
 import { parseDataOption } from "../lib/data-input.js";
 import { parseFilterOptions } from "../lib/record-filter.js";
-import { buildPermissionsExport } from "../lib/document-export-permissions.js";
+import { buildPermissionsExport, PENDING_INVITATIONS_ABSENT_STATUSES, } from "../lib/document-export-permissions.js";
+import { readExportLookup } from "../lib/document-export-lookups.js";
 import { chunkAddressOf, renumberManifestForExport, } from "../lib/snapshot-manifest-layout.js";
 import { validateSnapshotManifest } from "js-bao";
 import { auditSnapshotChain, } from "../lib/snapshot-audit.js";
@@ -19,9 +20,12 @@ import { createAuditLocalStore, createChainFingerprintReader, } from "../lib/sna
 import { discoverIngestInput, } from "../lib/document-ingest-input.js";
 import { buildIngestArtifact, ingestSchemaFromIntrospection, } from "../lib/document-ingest-artifact.js";
 import { driveDocumentIngest, summariseIngestPlan, assertIngestConfirmable, } from "../lib/document-ingest.js";
+import { withTransientRetry } from "../lib/transient-retry.js";
 import { ulid } from "ulid";
+import * as Y from "yjs";
 import * as fs from "fs";
 import * as path from "path";
+import { decideRootImport, rootDocumentFormatOf, } from "../lib/root-import-decision.js";
 /**
  * One bulk-load session as rows (#3434, #3435, #3598).
  *
@@ -124,6 +128,32 @@ export function describeBulkFailure(err) {
         },
     };
 }
+/**
+ * The `--data-file` help of `documents records bulk`: the op shapes the route
+ * accepts, including the `upsert` action addressed by a declared unique
+ * constraint (#3750).
+ */
+export const BULK_DATA_FILE_HELP = "JSON file with { operations: [...] } or a bare operations array. " +
+    "Each op is { model, action: create|patch|delete, id, data, precondition? } " +
+    "— `data` holds the record fields and is required (non-empty) on " +
+    "create/patch, not allowed on delete; a create `id` must be a 26-char " +
+    "uppercase Crockford ULID. An upsert op is { model, action: upsert, " +
+    "constraint, data, id?, precondition? } — `constraint` names a unique " +
+    "constraint the model declares and `data` carries its fields; the record " +
+    "holding that key is merged into, or created (at `id` when given)";
+/**
+ * The success line of `documents records bulk` (#3750): the blob's counts,
+ * with the upsert ops and how many of them created their record. An answer
+ * without `upserted` (an older server) reads as no upserts.
+ */
+export function describeBulkResult(result) {
+    const upserted = Array.isArray(result.upserted) ? result.upserted : [];
+    const created = upserted.filter((entry) => entry.created).length;
+    return (`Applied ${result.applied} operation(s): ` +
+        `${result.added.length} added, ${result.updated.length} updated, ` +
+        `${result.deleted} deleted, ${upserted.length} upserted` +
+        `${upserted.length > 0 ? ` (${created} created)` : ""}.`);
+}
 /**
  * A document's tags as a list, from whatever the wire handed back (#3644).
  *
@@ -1034,13 +1064,9 @@ Permissions (enforced by the server, not the CLI):
     // Apply an atomic multi-model operations blob
     records
         .command("bulk")
-        .description("Apply an atomic create/patch/delete operations blob to a document")
+        .description("Apply an atomic create/patch/delete/upsert operations blob to a document")
         .argument("<document-id>", "Document ID")
-        .requiredOption("--data-file <file>", "JSON file with { operations: [...] } or a bare operations array. " +
-        "Each op is { model, action: create|patch|delete, id, data, precondition? } " +
-        "— `data` holds the record fields and is required (non-empty) on " +
-        "create/patch, not allowed on delete; a create `id` must be a 26-char " +
-        "uppercase Crockford ULID")
+        .requiredOption("--data-file <file>", BULK_DATA_FILE_HELP)
         .option("--app <app-id>", "App ID")
         .option(DOCUMENT_FORMAT_FLAG, DOCUMENT_FORMAT_HELP)
         .option("-y, --yes", "Skip confirmation prompt")
@@ -1079,8 +1105,7 @@ Permissions (enforced by the server, not the CLI):
                 json(result);
                 return;
             }
-            success(`Applied ${result.applied} operation(s): ` +
-                `${result.added.length} added, ${result.updated.length} updated, ${result.deleted} deleted.`);
+            success(describeBulkResult(result));
         }
         catch (err) {
             const report = describeBulkFailure(err);
@@ -1135,7 +1160,7 @@ Permissions (enforced by the server, not the CLI):
     // Document statistics (platform-vocabulary projection)
     documents
         .command("stats")
-        .description("Show a document's record/model/blob counts and approximate size")
+        .description("Show a document's record/model/blob counts and size")
         .argument("<document-id>", "Document ID")
         .option("--app <app-id>", "App ID")
         .option("--json", "Output as JSON")
@@ -1152,7 +1177,11 @@ Permissions (enforced by the server, not the CLI):
             keyValue("Records", result.recordCount);
             keyValue("Models", result.modelCount);
             keyValue("Blobs", result.blobCount);
-            keyValue("Size (bytes, approx)", result.sizeBytes);
+            // A large document's size is its records' stored JSON, exact; an
+            // ordinary document's is an estimate (#4193).
+            keyValue(result.sizeBasis === "records"
+                ? "Size (bytes, records)"
+                : "Size (bytes, approx)", result.sizeBytes);
             keyValue("Last modified", result.lastModifiedAt ? formatDate(result.lastModifiedAt) : "—");
         }
         catch (err) {
@@ -1925,6 +1954,9 @@ Permissions (enforced by the server, not the CLI):
         const resolvedAppId = resolveAppId(appIdArg, options);
         const client = new ApiClient();
         const includeBlobs = options.blobs !== false;
+        // A document that fails does not stop the others; the run reports each
+        // one by id and exits non-zero (#4149).
+        const failed = [];
         try {
             const documents = await client.listAdminDocuments(resolvedAppId, options.userId);
             let docList = Array.isArray(documents) ? documents : [];
@@ -1945,6 +1977,7 @@ Permissions (enforced by the server, not the CLI):
                 }
                 catch (err) {
                     warn(`Failed to export ${docId}: ${err.message}`);
+                    failed.push({ documentId: docId, error: String(err?.message ?? err) });
                 }
             }
             // Write manifest. `export-all` is per-user, and each run REPLACES the
@@ -1979,16 +2012,25 @@ Permissions (enforced by the server, not the CLI):
             fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
             fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
             if (options.json) {
-                json(manifest);
+                json(failed.length > 0 ? { ...manifest, failed } : manifest);
             }
             else {
                 success(`Exported ${exportedIds.length} document(s) to ${options.output}`);
+                if (failed.length > 0) {
+                    error(`Failed to export ${failed.length} document(s): ` +
+                        `${failed.map((entry) => entry.documentId).join(", ")}. ` +
+                        `The manifest lists only the documents exported.`);
+                }
             }
         }
         catch (err) {
             error(err.message);
             process.exit(1);
         }
+        if (failed.length > 0) {
+            await flushOutput();
+            process.exit(1);
+        }
     });
     documents
         .command("import")
@@ -2023,6 +2065,7 @@ Permissions (enforced by the server, not the CLI):
             process.exit(1);
         }
         const client = new ApiClient();
+        let failedCount = 0;
         // Resolve --owner to a userId through the one shared lookup (#2763).
         let ownerUserId;
         if (options.owner) {
@@ -2075,7 +2118,9 @@ Permissions (enforced by the server, not the CLI):
                 blobsUploaded: 0,
                 aliasesSet: 0,
                 aliasesSkipped: 0,
+                completed: 0,
                 rootDocuments: [],
+                failed: [],
             };
             // Where every root-marked export in this run lands, decided from reads
             // alone and before any write (#3135): a refusal, or two exports
@@ -2083,12 +2128,18 @@ Permissions (enforced by the server, not the CLI):
             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.
+            // app half-populated (#2816). A root export is vouched for only when
+            // its plan installs it (#4195): a refused or skipped root export is
+            // never read past `metadata.json`, so a broken chain in it cannot
+            // fail the run.
             for (const docDir of docDirs) {
-                if (rootPlans.has(docDir))
+                const rootPlan = rootPlans.get(docDir);
+                if (rootPlan) {
+                    if (rootPlan.mode === "install") {
+                        readChainArtifact(docDir, rootPlan.exportedDocumentId);
+                    }
                     continue;
+                }
                 if (!largeDocumentArtifactAt(docDir))
                     continue;
                 const metadataPath = path.join(docDir, "metadata.json");
@@ -2097,17 +2148,44 @@ Permissions (enforced by the server, not the CLI):
                     : path.basename(docDir);
                 readChainArtifact(docDir, documentId);
             }
+            // One document failing does not stop the run (#4148): it is recorded
+            // by id, the rest are imported, and the run exits non-zero at the end.
             for (const docDir of docDirs) {
-                await importSingleDocument(client, resolvedAppId, docDir, options.overwrite || false, options.aliases || "skip", options.dryRun || false, summary, ownerUserId, rootPlans.get(docDir));
+                const progress = {
+                    documentId: readExportMetadata(docDir)?.documentId || path.basename(docDir),
+                    exists: false,
+                };
+                try {
+                    await importSingleDocument(client, resolvedAppId, docDir, options.overwrite || false, options.aliases || "skip", options.dryRun || false, summary, progress, ownerUserId, rootPlans.get(docDir));
+                }
+                catch (err) {
+                    const failure = {
+                        documentId: progress.documentId,
+                        status: progress.exists ? "incomplete" : "failed",
+                        error: err?.message || String(err),
+                    };
+                    summary.failed.push(failure);
+                    error(`Document ${failure.documentId} ` +
+                        `${failure.status === "incomplete" ? "is incomplete" : "failed"}: ` +
+                        failure.error);
+                }
             }
+            failedCount = summary.failed.length;
             if (options.json) {
                 json(summary);
             }
             else {
-                success(`Import complete:`);
+                if (failedCount === 0) {
+                    success(`Import complete:`);
+                }
+                else {
+                    error(`Import finished, ${failedCount} document(s) not imported:`);
+                }
                 keyValue("  Documents created", String(summary.created));
                 if (summary.updated > 0)
                     keyValue("  Documents updated", String(summary.updated));
+                if (summary.completed > 0)
+                    keyValue("  Documents completed", String(summary.completed));
                 if (summary.skipped > 0)
                     keyValue("  Documents skipped", String(summary.skipped));
                 if (summary.blobsUploaded > 0)
@@ -2116,12 +2194,25 @@ Permissions (enforced by the server, not the CLI):
                     keyValue("  Aliases set", String(summary.aliasesSet));
                 if (summary.aliasesSkipped > 0)
                     keyValue("  Aliases skipped", String(summary.aliasesSkipped));
+                for (const failure of summary.failed) {
+                    keyValue(`  ${failure.documentId}`, `${failure.status}: ${failure.error}`);
+                }
+                if (failedCount > 0) {
+                    info("Re-run the same import to finish them: a document a run left " +
+                        "incomplete is completed, and one already imported is skipped.");
+                }
             }
         }
         catch (err) {
             error(err.message);
             process.exit(1);
         }
+        if (failedCount > 0) {
+            // The summary names every failed document, and can be larger than a
+            // pipe's buffer: it has to reach the pipe before the process ends.
+            await flushOutput();
+            process.exit(1);
+        }
     });
     // Revoke group permission
     groupPermissions
@@ -2253,6 +2344,12 @@ function chunkFileOf(chunk) {
 async function exportSingleDocument(client, appId, documentId, outputDir, includeBlobs, jsonOutput) {
     const docDir = path.join(outputDir, "documents", documentId);
     fs.mkdirSync(docDir, { recursive: true });
+    // `metadata.json` is what marks the directory a finished export — import
+    // skips one without it — and it is written last. A rerun into an earlier
+    // export's directory drops it before overwriting anything, so a run that
+    // fails part-way leaves no new state beside the old aliases and grants
+    // looking complete (#4149).
+    fs.rmSync(path.join(docDir, "metadata.json"), { force: true });
     // 1. Fetch document metadata
     const docMeta = await client.getDocument(appId, documentId);
     // 2. Export the document's state. A legacy document is one blob; a large
@@ -2268,35 +2365,32 @@ async function exportSingleDocument(client, appId, documentId, outputDir, includ
         fs.writeFileSync(path.join(docDir, "document.yjs"), Buffer.from(stateResult.state, "base64"));
         stateBytes = stateResult.byteLength;
     }
-    // 3. Fetch permissions
-    let permResult = null;
-    try {
-        permResult = await client.listDocumentPermissions(appId, documentId);
-    }
-    catch {
-        // Permissions endpoint might not return data for all docs
-    }
-    // 4. Fetch pending invitations (deferred grants). An older server answers
-    // 403/404 here; the export still writes the permission rows.
-    let pendingResult = null;
-    try {
-        pendingResult = await client.listDocumentPendingInvitations(appId, documentId);
-    }
-    catch {
-        // May not have pending invitations, or the server predates the endpoint
-    }
+    // 3. Read the permissions, pending invitations (deferred grants), aliases
+    //    and blob list — all before `permissions.json` or `metadata.json` is
+    //    written. Only a documented "none" answer reads as empty (a 404, and an
+    //    older server's 403/404 on pending invitations); any other failure fails
+    //    the document, because an export missing them reports success and the
+    //    import restores less than the document had (#4149).
+    //
+    //    A root document cannot be shared, and the server answers both sharing
+    //    reads on one with a 403 (`validateNonRootDocument`). It has no grants
+    //    to export, so those reads are skipped rather than failing the document.
+    const isRoot = isRootDocumentExport(docMeta?.tags);
+    const permResult = isRoot
+        ? null
+        : await readExportLookup(documentId, "permissions", () => client.listDocumentPermissions(appId, documentId));
+    const pendingResult = isRoot
+        ? null
+        : await readExportLookup(documentId, "pending invitations", () => client.listDocumentPendingInvitations(appId, documentId), { absentStatuses: PENDING_INVITATIONS_ABSENT_STATUSES });
+    const aliasResult = await readExportLookup(documentId, "aliases", () => client.listDocumentAliases(appId, documentId));
+    const blobs = includeBlobs
+        ? await readExportBlobList(client, appId, documentId)
+        : [];
+    // 4. Write permissions
     const permissionsExport = buildPermissionsExport(permResult, pendingResult);
     fs.writeFileSync(path.join(docDir, "permissions.json"), JSON.stringify(permissionsExport, null, 2));
-    // 5. Fetch aliases (user-scoped only)
-    let aliases = [];
-    try {
-        const aliasResult = await client.listDocumentAliases(appId, documentId);
-        aliases = (Array.isArray(aliasResult) ? aliasResult : aliasResult?.aliases || [])
-            .filter((a) => (a.scope || a.aliasScope) === "user");
-    }
-    catch {
-        // May not have aliases
-    }
+    // 5. Aliases (user-scoped only)
+    const aliases = (Array.isArray(aliasResult) ? aliasResult : aliasResult?.aliases || []).filter((a) => (a.scope || a.aliasScope) === "user");
     // 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
@@ -2316,14 +2410,6 @@ async function exportSingleDocument(client, appId, documentId, outputDir, includ
     fs.writeFileSync(path.join(docDir, "metadata.json"), JSON.stringify(metadata, null, 2));
     // 7. Blobs
     if (includeBlobs) {
-        let blobs = [];
-        try {
-            const blobResult = await client.listDocumentBlobs(appId, documentId);
-            blobs = Array.isArray(blobResult) ? blobResult : blobResult?.items || blobResult?.blobs || [];
-        }
-        catch {
-            // May not have blobs
-        }
         if (blobs.length > 0) {
             const blobsDir = path.join(docDir, "blobs");
             fs.mkdirSync(blobsDir, { recursive: true });
@@ -2356,6 +2442,40 @@ async function exportSingleDocument(client, appId, documentId, outputDir, includ
         success(`Exported document ${documentId} (${metadata.title || "untitled"}) to ${docDir}`);
     }
 }
+/**
+ * Every uploaded blob of a document, read page by page (#4149).
+ *
+ * The list answers one page at a time (`{ items, hasMore, nextCursor }`), so
+ * a document with more blobs than a page holds would otherwise export only
+ * the first page and report success. Each page is its own lookup: a 404 on
+ * the first means the document has no blobs, but a later page that fails —
+ * a 404 included — fails the document, because the list is already known to
+ * be longer. A page that says more follow without a new cursor to read them
+ * by fails the document too: stopping there exports part of the list, and
+ * rereading the same cursor never ends.
+ */
+async function readExportBlobList(client, appId, documentId) {
+    const blobs = [];
+    const seen = new Set();
+    let cursor;
+    do {
+        const pageCursor = cursor;
+        const page = await readExportLookup(documentId, "blob list", () => client.listDocumentBlobs(appId, documentId, pageCursor ? { cursor: pageCursor } : undefined), pageCursor ? { absentStatuses: [] } : {});
+        if (Array.isArray(page))
+            return [...blobs, ...page];
+        blobs.push(...(page?.items || page?.blobs || []));
+        if (!page?.hasMore)
+            break;
+        cursor = page?.nextCursor || undefined;
+        if (!cursor || seen.has(cursor)) {
+            throw new Error(`Document ${documentId}: reading its blob list failed — a page said ` +
+                `more follow but gave no new cursor to read them by. Its export ` +
+                `would be incomplete, so it was not exported.`);
+        }
+        seen.add(cursor);
+    } while (cursor);
+    return blobs;
+}
 /**
  * Whether `docDir` holds a large document's export (#2816, behavior 20).
  *
@@ -2485,6 +2605,24 @@ function verifyChainArtifact(docDir, documentId, chain) {
     }
     require(path.join(docDir, "current.yjs"), "its open epoch's overlay");
 }
+/**
+ * One idempotent write of an import, retried through a transient failure
+ * (#4148): a blob PUT, a state merge, an artifact upload or an install read.
+ * Each retry is said, so a slow run is not mistaken for a stuck one.
+ */
+function retryingImportStep(what, attempt) {
+    return withTransientRetry(attempt, (failure, delayMs) => warn(`${what} failed (${failure?.message || "no reason given"}); ` +
+        `retrying in ${delayMs / 1000}s`));
+}
+/** Upload one chain artifact; the server stores it under a fixed key. */
+function uploadChainArtifact(client, appId, documentId, query, body) {
+    const what = query.kind === "chunk"
+        ? `chunk ${query.index} of ${query.model}`
+        : query.kind === "overlay"
+            ? `the overlay of epoch ${query.epoch}`
+            : "the base snapshot's manifest";
+    return retryingImportStep(`Uploading ${what} of ${documentId}`, () => client.uploadDocumentChainArtifact(appId, documentId, query, body));
+}
 /** 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. */
@@ -2503,12 +2641,17 @@ const CHAIN_INSTALL_POLL_MS = 1000;
  */
 async function importLargeDocumentChain(client, appId, docDir, documentId) {
     const chain = readChainArtifact(docDir, documentId);
+    await uploadAndInstallChain(client, appId, docDir, documentId, chain);
+    await awaitChainInstall(client, appId, documentId);
+}
+/** Upload every artifact of the chain, then start installing it. */
+async function uploadAndInstallChain(client, appId, docDir, documentId, chain) {
     // 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, {
+        await uploadChainArtifact(client, appId, documentId, {
             kind: "manifest",
             epoch: chain.base.epoch,
             buildId: chain.base.buildId,
@@ -2517,7 +2660,7 @@ async function importLargeDocumentChain(client, appId, docDir, documentId) {
         for (const chunk of manifest.chunks ?? []) {
             // Addressed by the entry's `path` (#3432); the server installs by it too.
             const { model, index } = chunkFileOf(chunk);
-            await client.uploadDocumentChainArtifact(appId, documentId, {
+            await uploadChainArtifact(client, appId, documentId, {
                 kind: "chunk",
                 epoch: chain.base.epoch,
                 buildId: chain.base.buildId,
@@ -2530,9 +2673,9 @@ async function importLargeDocumentChain(client, appId, docDir, documentId) {
     // 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 uploadChainArtifact(client, 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 uploadChainArtifact(client, 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 }
@@ -2540,19 +2683,25 @@ async function importLargeDocumentChain(client, appId, docDir, documentId) {
         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.
+}
+/**
+ * Wait for the document's chain install to finish.
+ *
+ * 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.
+ */
+async function awaitChainInstall(client, appId, documentId) {
     const deadline = Date.now() + CHAIN_INSTALL_TIMEOUT_MS;
     for (;;) {
-        const status = await client.getDocumentChainInstall(appId, documentId);
+        const status = await retryingImportStep(`Reading the chain install of ${documentId}`, () => 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.`);
+                `${install.error || "no reason given"}. The document is incomplete; ` +
+                `re-run the import to install it again.`);
         }
         if (Date.now() >= deadline) {
             throw new Error(`Document ${documentId}: its chain install has not finished after ` +
@@ -2568,19 +2717,6 @@ const ROOT_DOCUMENT_TAG = "__ROOT_TAG__";
 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");
@@ -2610,6 +2746,24 @@ function readExportMetadata(docDir) {
  */
 async function planRootImports(client, appId, docDirs, explicitOwner, explicitOwnerUserId, overwrite) {
     const plans = new Map();
+    // The app's `rootDocumentFormat`, read once and only when some target user
+    // has no root yet (#4195). A failed read fails the run: a guessed format is
+    // a confident create into the wrong kind of root.
+    let appSetting;
+    const readAppSetting = async (exportedDocumentId) => {
+        if (!appSetting) {
+            try {
+                const app = await client.getApp(appId);
+                appSetting = { value: app?.rootDocumentFormat ?? null };
+            }
+            catch (error) {
+                throw new Error(`Document ${exportedDocumentId}: reading app ${appId}'s ` +
+                    `rootDocumentFormat failed — ${error?.message || "no reason given"}. ` +
+                    `Nothing was imported.`);
+            }
+        }
+        return appSetting.value;
+    };
     for (const docDir of docDirs) {
         const metadata = readExportMetadata(docDir);
         if (!metadata || !isRootDocumentExport(metadata.tags))
@@ -2621,16 +2775,13 @@ async function planRootImports(client, appId, docDirs, explicitOwner, explicitOw
             exportedDocumentId,
             owner,
             action: "refused",
+            exportFormat: rootDocumentFormatOf(metadata.documentFormat),
         };
         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>.`);
@@ -2678,13 +2829,33 @@ async function planRootImports(client, appId, docDirs, explicitOwner, explicitOw
             refuse(unresolvableRootOwner(appId, owner));
             continue;
         }
+        // The export's format against the root it would land in (#4195): the
+        // existing root's, or the one the app's setting says the mint produces.
         const rootDocId = assignment?.rootDocId || null;
-        if (!rootDocId) {
-            plan.action = "create";
+        if (rootDocId)
+            plan.targetRootDocId = rootDocId;
+        const decision = decideRootImport({
+            exportFormat: plan.exportFormat,
+            existingRootFormat: rootDocId
+                ? rootDocumentFormatOf(assignment.documentFormat)
+                : null,
+            appSetting: rootDocId ? null : await readAppSetting(exportedDocumentId),
+            overwrite,
+            owner,
+            ...(rootDocId ? { targetRootDocId: rootDocId } : {}),
+        });
+        plan.targetFormat = decision.targetFormat;
+        if (decision.outcome === "refuse") {
+            refuse(decision.reason);
+            continue;
+        }
+        if (decision.outcome === "skip") {
+            plan.action = "skip";
+            plan.reason = decision.reason;
         }
         else {
-            plan.targetRootDocId = rootDocId;
-            plan.action = overwrite ? "apply" : "skip";
+            plan.action = rootDocId ? "apply" : "create";
+            plan.mode = decision.outcome;
         }
         plans.set(docDir, plan);
     }
@@ -2727,7 +2898,7 @@ function assertDistinctRootTargets(plans) {
     }
 }
 /**
- * Does the target app already hold this document?
+ * The target app's copy of this document, or null when it holds none.
  *
  * 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
@@ -2736,19 +2907,18 @@ function assertDistinctRootTargets(plans) {
  * silently omits the overwrite the operator asked for. Those propagate, and
  * `documents import` fails the run.
  */
-async function documentExists(client, appId, documentId) {
+async function existingDocument(client, appId, documentId) {
     try {
-        await client.getDocument(appId, documentId);
-        return true;
+        return (await client.getDocument(appId, documentId)) ?? {};
     }
     catch (error) {
         if (error?.statusCode === 404)
-            return false;
+            return null;
         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) {
+async function importSingleDocument(client, appId, docDir, overwrite, aliasMode, dryRun, summary, progress, ownerUserId, rootPlan) {
     const metadataPath = path.join(docDir, "metadata.json");
     if (!fs.existsSync(metadataPath)) {
         warn(`Skipping ${docDir}: no metadata.json found`);
@@ -2761,12 +2931,12 @@ async function importSingleDocument(client, appId, docDir, overwrite, aliasMode,
     // 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.
+    // Decided BEFORE the chain artifact below is read: a root export's chain is
+    // installed into the target user's root, never under its exported id, and
+    // only when the plan says so (#4195) — reading it here would fail the whole
+    // run over an artifact a refused or skipped plan never touches.
     if (isRootDocumentExport(metadata.tags)) {
-        await importRootDocument(client, appId, docDir, metadata, rootPlan, overwrite, aliasMode, dryRun, summary);
+        await importRootDocument(client, appId, docDir, metadata, rootPlan, overwrite, aliasMode, dryRun, summary, progress);
         return;
     }
     // A large document's data is the chain, not `document.yjs` (#2816), and it
@@ -2777,9 +2947,78 @@ async function importSingleDocument(client, appId, docDir, overwrite, aliasMode,
     // `--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 existing = await existingDocument(client, appId, documentId);
+    const exists = existing !== null;
+    progress.exists = exists;
     const wouldSkip = dryRun ? "[dry-run] Would skip" : "Skipping";
     if (exists && !overwrite) {
+        // A same-id document of the other format is not one this import created:
+        // the format is decided at creation and never migrated. It is skipped
+        // before any read of what it lacks, which its format's endpoints refuse.
+        if ((Number(existing?.documentFormat) === 2) !== isLargeDocument) {
+            warn(`${wouldSkip} ${documentId}: already exists as a ` +
+                `${isLargeDocument ? "legacy" : "large"} document, and the export ` +
+                `is a ${isLargeDocument ? "large" : "legacy"} one`);
+            summary.skipped++;
+            return;
+        }
+        // A document an earlier run created and did not finish is completed, not
+        // skipped (#4148): what it lacks of the export is read from the server,
+        // and only that is written. A document that lacks nothing, or that holds
+        // content of its own, is skipped, so a re-run never merges into or
+        // re-uploads to one already imported, nor writes to one it did not start.
+        // With an owner named, the export's user aliases are among what it can
+        // lack.
+        const gaps = await findImportGaps(client, appId, docDir, documentId, isLargeDocument, ownerUserId
+            ? { userId: ownerUserId, aliasMode, exported: metadata.aliases }
+            : undefined);
+        // Never installed and not empty: a document of its own, which the server
+        // would refuse to install into.
+        const skipHoldingRecords = (held = "holds records of its own") => {
+            warn(`${wouldSkip} ${documentId}: already exists and ${held}, so its ` +
+                `large-document export cannot be installed into it`);
+            summary.skipped++;
+        };
+        if (gaps === "holds-records") {
+            skipHoldingRecords();
+            return;
+        }
+        if (gaps === "rotated-epoch") {
+            skipHoldingRecords("has rotated an epoch of its own");
+            return;
+        }
+        if (gaps) {
+            if (dryRun) {
+                info(`[dry-run] Would complete document ${documentId} ` +
+                    `(${metadata.title || "untitled"}): it is missing ${describeImportGaps(gaps)}`);
+                summary.completed++;
+                return;
+            }
+            if (gaps.state)
+                await importExportedState(client, appId, docDir, documentId);
+            if (gaps.chain === "install") {
+                try {
+                    await uploadAndInstallChain(client, appId, docDir, documentId, readChainArtifact(docDir, documentId));
+                }
+                catch (refusal) {
+                    // The server's own check, at the first artifact and before it
+                    // stores anything: it decides when the document changed after the
+                    // reads above.
+                    if (refusal?.code !== "DOCUMENT_NOT_IMPORTABLE")
+                        throw refusal;
+                    skipHoldingRecords();
+                    return;
+                }
+            }
+            if (gaps.chain)
+                await awaitChainInstall(client, appId, documentId);
+            await uploadExportedBlobs(client, appId, documentId, docDir, gaps.blobs, summary);
+            await restoreExportedAliases(client, appId, documentId, ownerUserId ? { ...metadata, aliases: gaps.aliases } : metadata, ownerUserId, aliasMode, summary);
+            summary.completed++;
+            info(`Completed document ${documentId} (${metadata.title || "untitled"}): ` +
+                `imported ${describeImportGaps(gaps)}`);
+            return;
+        }
         // `--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
@@ -2817,6 +3056,7 @@ async function importSingleDocument(client, appId, docDir, overwrite, aliasMode,
             ...(isLargeDocument ? { documentFormat: 2 } : {}),
             ...(ownerUserId ? { createdBy: ownerUserId } : {}),
         });
+        progress.exists = true;
         summary.created++;
     }
     else {
@@ -2828,57 +3068,254 @@ async function importSingleDocument(client, appId, docDir, overwrite, aliasMode,
         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);
-        }
+        await importExportedState(client, appId, docDir, documentId);
     }
-    // Upload blobs
+    await uploadExportedBlobs(client, appId, documentId, docDir, exportedBlobsOf(docDir), summary);
+    // Permissions are exported for reference but not restored during import.
+    // The importing admin is the new owner; sharing is managed in the target app.
+    await restoreExportedAliases(client, appId, documentId, metadata, ownerUserId, aliasMode, summary);
+    info(`Imported document ${documentId} (${metadata.title || "untitled"})`);
+}
+/** Merge the exported Yjs state into the document, when the export has one. */
+async function importExportedState(client, appId, docDir, documentId) {
+    const yjsPath = path.join(docDir, "document.yjs");
+    if (!fs.existsSync(yjsPath))
+        return;
+    const stateBase64 = fs.readFileSync(yjsPath).toString("base64");
+    await retryingImportStep(`Importing the state of ${documentId}`, () => client.importDocumentState(appId, documentId, stateBase64));
+}
+/** The blobs the export lists whose bytes are in it. */
+function exportedBlobsOf(docDir) {
     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)) {
-                const data = fs.readFileSync(blobPath);
-                await client.uploadBlob(appId, documentId, blob.blobId, data, {
-                    filename: blob.filename,
-                    contentType: blob.contentType,
-                    sha256: blob.sha256,
-                });
-                summary.blobsUploaded++;
-            }
+    if (!fs.existsSync(blobIndexPath))
+        return [];
+    const blobIndex = JSON.parse(fs.readFileSync(blobIndexPath, "utf-8"));
+    return (Array.isArray(blobIndex) ? blobIndex : []).filter((blob) => fs.existsSync(path.join(docDir, "blobs", `${blob.blobId}.bin`)));
+}
+/** Upload exported blobs under their own ids. */
+async function uploadExportedBlobs(client, appId, documentId, docDir, blobs, summary) {
+    for (const blob of blobs) {
+        const data = fs.readFileSync(path.join(docDir, "blobs", `${blob.blobId}.bin`));
+        await retryingImportStep(`Uploading blob ${blob.blobId} of ${documentId}`, () => client.uploadBlob(appId, documentId, blob.blobId, data, {
+            filename: blob.filename,
+            contentType: blob.contentType,
+            sha256: blob.sha256,
+        }));
+        summary.blobsUploaded++;
+    }
+}
+/** Restore the export's user-scoped aliases, when an owner was named. */
+async function restoreExportedAliases(client, appId, documentId, metadata, ownerUserId, aliasMode, summary) {
+    if (!Array.isArray(metadata.aliases))
+        return;
+    for (const alias of metadata.aliases) {
+        if (alias.aliasScope !== "user")
+            continue;
+        if (!ownerUserId) {
+            summary.aliasesSkipped++;
+            continue;
+        }
+        try {
+            await retryingImportStep(`Setting alias ${alias.aliasKey} of ${documentId}`, () => client.setDocumentAlias(appId, alias.aliasScope, alias.aliasKey, documentId, ownerUserId, aliasMode === "skip" // mustNotExist: true for skip mode, false for overwrite
+            ));
+            summary.aliasesSet++;
+        }
+        catch (failure) {
+            // An alias the user already holds is the answer `--aliases skip` asks
+            // for, and it is left where it is. Any other failure leaves the
+            // document without an alias its export holds: it is incomplete, and
+            // reported as such (#4148).
+            if (failure?.statusCode !== 409)
+                throw failure;
+            summary.aliasesSkipped++;
         }
     }
-    // Permissions are exported for reference but not restored during import.
-    // The importing admin is the new owner; sharing is managed in the target app.
-    // Restore aliases
-    if (metadata.aliases && Array.isArray(metadata.aliases)) {
-        for (const alias of metadata.aliases) {
-            if (alias.aliasScope !== "user")
-                continue;
-            if (!ownerUserId) {
-                summary.aliasesSkipped++;
-                continue;
-            }
+}
+/** "its state and 2 blobs", for the line that reports a completion. */
+function describeImportGaps(gaps) {
+    const parts = [];
+    if (gaps.state)
+        parts.push("its state");
+    if (gaps.chain === "install")
+        parts.push("its chain");
+    if (gaps.chain === "await")
+        parts.push("its chain (installing)");
+    if (gaps.blobs.length > 0) {
+        parts.push(`${gaps.blobs.length} blob${gaps.blobs.length === 1 ? "" : "s"}`);
+    }
+    if (gaps.aliases.length > 0) {
+        parts.push(`${gaps.aliases.length} alias${gaps.aliases.length === 1 ? "" : "es"}`);
+    }
+    return parts.join(" and ");
+}
+/** A Yjs update that holds nothing: no items and no deletions. */
+function isEmptyYjsUpdate(update) {
+    return update.length === 0 || (update.length === 2 && update[0] === 0 && update[1] === 0);
+}
+/** The export's Yjs state, or null when it has none or an empty one. */
+function exportedStateOf(docDir) {
+    const yjsPath = path.join(docDir, "document.yjs");
+    if (!fs.existsSync(yjsPath))
+        return null;
+    const state = fs.readFileSync(yjsPath);
+    return isEmptyYjsUpdate(state) ? null : state;
+}
+/**
+ * Whether `held` already contains all of `exported`: for each client the
+ * export wrote as, the document holds at least as far as the export does, and
+ * it holds every deletion the export does. A deletion advances no clock, so
+ * the clocks alone take a document read before a deletion for one after it.
+ */
+function holdsYjsUpdate(held, exported) {
+    const heldClocks = Y.decodeStateVector(Y.encodeStateVectorFromUpdate(held));
+    const exportedClocks = Y.decodeStateVector(Y.encodeStateVectorFromUpdate(exported));
+    for (const [clientId, clock] of exportedClocks) {
+        if ((heldClocks.get(clientId) ?? 0) < clock)
+            return false;
+    }
+    // Every item the export deletes is held, so applying it changes the held
+    // snapshot only if it deletes one the document has not.
+    const doc = new Y.Doc();
+    Y.applyUpdate(doc, held);
+    const before = Y.snapshot(doc);
+    Y.applyUpdate(doc, exported);
+    return Y.equalSnapshots(before, Y.snapshot(doc));
+}
+/**
+ * Read what an existing document lacks of its export (#4148): the gaps, null
+ * when there is nothing a re-run may write, or `"holds-records"` /
+ * `"rotated-epoch"` for a large document that was never imported into and
+ * holds records or has rotated an epoch of its own.
+ *
+ * A legacy document is only completed when it is the one an earlier run
+ * started: it holds no state at all — what `createDocument` leaves, and what a
+ * failed `import/state` leaves, since the server stores the merge before it
+ * applies it — or it already holds the exported state, and then only its
+ * blobs can be missing. A document holding state of its own is not written
+ * to at all, neither merged into nor given blobs or aliases: that is
+ * `--overwrite`'s decision, not a re-run's. A large document's chain is
+ * missing unless its install completed; the server takes a new install over a
+ * failed one, but never one into a document with records and no install
+ * behind them. Blobs are compared by id against every page the document
+ * lists. When `aliasOwner` is given, the export's user aliases are read as
+ * well: one the owner holds for another document counts as missing only when
+ * the alias mode would move it.
+ */
+async function findImportGaps(client, appId, docDir, documentId, isLargeDocument, aliasOwner) {
+    let state = false;
+    let chain = null;
+    const exported = exportedBlobsOf(docDir);
+    if (isLargeDocument) {
+        const status = await retryingImportStep(`Reading the chain install of ${documentId}`, () => client.getDocumentChainInstall(appId, documentId));
+        const installState = status?.install?.state;
+        if (installState === "installing")
+            chain = "await";
+        else if (installState !== "complete")
+            chain = "install";
+        // Read, not discovered by the first artifact upload, so `--dry-run`
+        // reaches the same decision the run does.
+        // `tableModels` is every model the document's records table holds.
+        if (chain === "install" && !status?.install) {
+            const schema = await retryingImportStep(`Reading the records of ${documentId}`, () => client.getDocumentSchema(appId, documentId));
+            if (Array.isArray(schema?.tableModels) && schema.tableModels.length > 0) {
+                return "holds-records";
+            }
+            // The server refuses one past its first epoch as well. Its open epoch is
+            // the one its chain ends on; a chain it cannot describe has sealed an
+            // epoch, which only a rotation does.
+            let openEpoch;
             try {
-                await client.setDocumentAlias(appId, alias.aliasScope, alias.aliasKey, documentId, ownerUserId, aliasMode === "skip" // mustNotExist: true for skip mode, false for overwrite
-                );
-                summary.aliasesSet++;
+                const described = await retryingImportStep(`Reading the epoch of ${documentId}`, () => client.exportDocumentChain(appId, documentId));
+                openEpoch = Number(described?.epoch);
             }
-            catch {
-                summary.aliasesSkipped++;
+            catch (refusal) {
+                if (refusal?.code !== "EXPORT_CHAIN_INCOMPLETE")
+                    throw refusal;
+                return "rotated-epoch";
             }
+            if (openEpoch !== 1)
+                return "rotated-epoch";
         }
     }
-    info(`Imported document ${documentId} (${metadata.title || "untitled"})`);
+    else {
+        const exportedState = exportedStateOf(docDir);
+        // An export with no state and no blobs can still carry a root's aliases.
+        const exportsUserAliases = (Array.isArray(aliasOwner?.exported) ? aliasOwner.exported : [])
+            .some((alias) => alias?.aliasScope === "user");
+        if (!exportedState && exported.length === 0 && !exportsUserAliases)
+            return null;
+        const held = await retryingImportStep(`Reading the state of ${documentId}`, () => client.exportDocumentState(appId, documentId));
+        const heldState = Buffer.from(String(held?.state ?? ""), "base64");
+        if (isEmptyYjsUpdate(heldState)) {
+            state = exportedState !== null;
+        }
+        else if (!exportedState || !holdsYjsUpdate(heldState, exportedState)) {
+            return null;
+        }
+    }
+    let blobs = [];
+    if (exported.length > 0) {
+        const listed = await listedBlobIds(client, appId, documentId);
+        blobs = exported.filter((blob) => !listed.has(blob.blobId));
+    }
+    const aliases = aliasOwner
+        ? await findMissingAliases(client, appId, documentId, aliasOwner)
+        : [];
+    return state || chain || blobs.length > 0 || aliases.length > 0
+        ? { state, chain, blobs, aliases }
+        : null;
+}
+/** The form the server stores an alias key in. */
+function normalizedAliasKey(aliasKey) {
+    return String(aliasKey ?? "").trim().toLowerCase();
+}
+/**
+ * The exported user aliases that do not point at the document for their
+ * owner. One the owner holds for another document is only missing under
+ * `--aliases overwrite`: under `skip` the restore leaves it where it is, so a
+ * re-run would have nothing to write for it.
+ */
+async function findMissingAliases(client, appId, documentId, owner) {
+    const wanted = (Array.isArray(owner.exported) ? owner.exported : []).filter((alias) => alias?.aliasScope === "user");
+    if (wanted.length === 0)
+        return [];
+    const listed = await retryingImportStep(`Listing the aliases of ${documentId}`, () => client.listDocumentAliases(appId, documentId));
+    const held = new Set((Array.isArray(listed) ? listed : (listed?.aliases ?? []))
+        .filter((alias) => (alias?.scope || alias?.aliasScope) === "user" && alias?.userId === owner.userId)
+        .map((alias) => normalizedAliasKey(alias.aliasKey)));
+    const missing = [];
+    for (const alias of wanted) {
+        if (held.has(normalizedAliasKey(alias.aliasKey)))
+            continue;
+        if (owner.aliasMode === "skip") {
+            const current = await retryingImportStep(`Reading alias ${alias.aliasKey}`, () => client.getDocumentAlias(appId, "user", alias.aliasKey, owner.userId));
+            if (current)
+                continue;
+        }
+        missing.push(alias);
+    }
+    return missing;
+}
+/** Every blob id a document lists, read to the last page. */
+async function listedBlobIds(client, appId, documentId) {
+    const ids = new Set();
+    let cursor;
+    for (;;) {
+        const page = await retryingImportStep(`Listing the blobs of ${documentId}`, () => client.listDocumentBlobs(appId, documentId, cursor ? { cursor } : undefined));
+        const items = Array.isArray(page) ? page : (page?.items ?? []);
+        for (const item of items) {
+            if (item?.blobId)
+                ids.add(String(item.blobId));
+        }
+        if (Array.isArray(page) || !page?.nextCursor)
+            return ids;
+        cursor = String(page.nextCursor);
+    }
 }
 /**
  * Restore a root-marked export into the target user's own root document
- * (#3135).
+ * (#3135), by format (#4195): a legacy export's state is merged into a legacy
+ * root, a large-document export's chain is installed into a large root.
  *
  * 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,
@@ -2890,18 +3327,22 @@ async function importSingleDocument(client, appId, docDir, overwrite, aliasMode,
  * 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.
+ * rewrite a user's live preferences. Without it, an existing legacy root is
+ * only completed (#4148): one an earlier run of this import started and did
+ * not finish gets what it lacks, exactly as a legacy document does. An
+ * existing large root is skipped.
  */
-async function importRootDocument(client, appId, docDir, metadata, plan, overwrite, aliasMode, dryRun, summary) {
+async function importRootDocument(client, appId, docDir, metadata, plan, overwrite, aliasMode, dryRun, summary, progress) {
     const exportedDocumentId = metadata.documentId || path.basename(docDir);
     const wouldSkip = dryRun ? "[dry-run] Would skip" : "Skipping";
-    const report = (action, targetRootDocId, reason) => {
+    const report = (action, targetRootDocId, reason, targetFormat) => {
         summary.rootDocuments.push({
             exportedDocumentId,
             owner: plan?.owner ?? "",
             ...(targetRootDocId ? { targetRootDocId } : {}),
             action,
             ...(reason ? { reason } : {}),
+            ...(targetFormat === 2 ? { documentFormat: 2 } : {}),
         });
     };
     if (!plan || plan.action === "refused") {
@@ -2913,31 +3354,64 @@ async function importRootDocument(client, appId, docDir, metadata, plan, overwri
         report("refused", undefined, reason);
         return;
     }
+    let targetRootDocId = plan.targetRootDocId;
+    // What a root an earlier run started still lacks (#4148), when completing it.
+    let gaps = null;
     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;
+        // The root exists and `--overwrite` was not given. A legacy root an
+        // earlier run started and did not finish is completed, by the same rule
+        // as any legacy document: it holds no state, or already holds the
+        // exported state. A root holding state of its own — its user's — is never
+        // merged into. A large root is skipped as before: a chain is installed
+        // only into a root that holds nothing, which `--overwrite` asks for.
+        progress.exists = true;
+        const found = plan.targetFormat === 2
+            ? null
+            : await findImportGaps(client, appId, docDir, targetRootDocId, false, {
+                userId: plan.targetUserId,
+                aliasMode,
+                exported: metadata.aliases,
+            });
+        if (!found || typeof found === "string") {
+            const reason = plan.reason ||
+                `the root document of ${plan.owner} already exists ` +
+                    `(${targetRootDocId}); use --overwrite to merge the exported ` +
+                    `content into it`;
+            warn(`${wouldSkip} ${exportedDocumentId}: ${reason}`);
+            summary.skipped++;
+            report("skipped", targetRootDocId, reason, plan.targetFormat);
+            return;
+        }
+        gaps = found;
     }
+    const install = plan.mode === "install";
     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`);
+        if (gaps) {
+            info(`[dry-run] Would complete root document export ${exportedDocumentId} ` +
+                `in ${plan.owner}'s root document ${targetRootDocId}: it is missing ` +
+                describeImportGaps(gaps));
+            summary.completed++;
+            report("completed", targetRootDocId);
+        }
+        else if (plan.action === "create") {
+            info(install
+                ? `[dry-run] Would create the root document (large) for ` +
+                    `${plan.owner} and install root document export ` +
+                    `${exportedDocumentId} into it`
+                : `[dry-run] Would create the root document for ${plan.owner} and ` +
+                    `apply root document export ${exportedDocumentId} to it`);
             summary.created++;
-            report("created");
+            report("created", undefined, undefined, plan.targetFormat);
         }
         else {
-            info(`[dry-run] Would apply root document export ${exportedDocumentId} to ` +
+            info(`[dry-run] Would ${install ? "install" : "apply"} root document ` +
+                `export ${exportedDocumentId} ${install ? "into" : "to"} ` +
                 `${plan.owner}'s root document ${plan.targetRootDocId}`);
             summary.updated++;
-            report("applied", plan.targetRootDocId);
+            report("applied", plan.targetRootDocId, undefined, plan.targetFormat);
         }
         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
@@ -2951,64 +3425,75 @@ async function importRootDocument(client, appId, docDir, metadata, plan, overwri
                 `for ${plan.owner}, so nothing was imported for it.`);
         }
         created = ensured.created === true;
+        // The root the server returned is the truth, not the plan's prediction
+        // (#4195): the app's setting can change, or a sign-in can mint the root,
+        // between the plan and this call. Decided before the concurrent-sign-in
+        // skip, so a root of the other format is refused, never offered to
+        // --overwrite.
+        const minted = decideRootImport({
+            exportFormat: plan.exportFormat,
+            existingRootFormat: rootDocumentFormatOf(ensured.documentFormat),
+            predictedFormat: plan.targetFormat,
+            appSetting: null,
+            overwrite: true,
+            owner: plan.owner,
+            targetRootDocId,
+        });
+        if (minted.outcome === "refuse") {
+            warn(`Skipping ${exportedDocumentId}: ${minted.reason}`);
+            summary.skipped++;
+            report("refused", targetRootDocId, minted.reason, minted.targetFormat);
+            return;
+        }
         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`;
+                `--overwrite to ${install ? "install" : "merge"} the exported ` +
+                `content into it`;
             warn(`Skipping ${exportedDocumentId}: ${reason}`);
             summary.skipped++;
-            report("skipped", targetRootDocId, reason);
+            report("skipped", targetRootDocId, reason, minted.targetFormat);
             return;
         }
     }
+    progress.exists = true;
     // 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"));
+    if (install) {
+        // A large root's content is its chain, installed — the server refuses a
+        // root that already holds records or has rotated, as it does for any
+        // large document (#4195).
+        await importLargeDocumentChain(client, appId, docDir, targetRootDocId);
     }
-    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++;
-        }
+    else if (!gaps || gaps.state) {
+        await importExportedState(client, appId, docDir, targetRootDocId);
     }
+    // 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 uploadExportedBlobs(client, appId, targetRootDocId, docDir, gaps ? gaps.blobs : exportedBlobsOf(docDir), summary);
     // 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++;
-            }
-        }
+    // A completion restores only the ones the root is missing.
+    await restoreExportedAliases(client, appId, targetRootDocId, gaps ? { ...metadata, aliases: gaps.aliases } : metadata, plan.targetUserId, aliasMode, summary);
+    const verb = install ? "installed" : "applied";
+    if (gaps) {
+        summary.completed++;
+        report("completed", targetRootDocId);
+        info(`Completed root document export ${exportedDocumentId} in ` +
+            `${plan.owner}'s root document ${targetRootDocId}: imported ` +
+            describeImportGaps(gaps));
     }
-    if (created) {
+    else if (created) {
         summary.created++;
-        report("created", targetRootDocId);
-        info(`Created root document ${targetRootDocId} for ${plan.owner} and applied ` +
-            `root document export ${exportedDocumentId} to it`);
+        report("created", targetRootDocId, undefined, plan.targetFormat);
+        info(`Created root document ${targetRootDocId} for ${plan.owner} and ${verb} ` +
+            `root document export ${exportedDocumentId} ${install ? "into" : "to"} it`);
     }
     else {
         summary.updated++;
-        report("applied", targetRootDocId);
-        info(`Applied root document export ${exportedDocumentId} to ${plan.owner}'s ` +
+        report("applied", targetRootDocId, undefined, plan.targetFormat);
+        info(`${install ? "Installed" : "Applied"} root document export ` +
+            `${exportedDocumentId} ${install ? "into" : "to"} ${plan.owner}'s ` +
             `root document ${targetRootDocId}`);
     }
 }