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

package/dist/src/commands/documents.js

@@ -1,27 +1,32 @@
-import { snapshotBuildRows } from "../lib/snapshot-build-rows.js";
+import { segmentRows, snapshotBuildRows } from "../lib/snapshot-build-rows.js";
+import { exportRecordLogDocument } from "../lib/document-export-record-log.js";
 import { driveSnapshotBuild } from "../lib/snapshot-build.js";
 import { ingestClientRows, ingestSessionRows, } from "../lib/document-ingest-rows.js";
 import { ApiClient } from "../lib/api-client.js";
+import { documentSchemaRows } from "../lib/document-schema-rows.js";
 import { resolveAppId } from "../lib/config.js";
 import { success, error, info, formatTable, formatId, formatDate, json, keyValue, result as printResult, warn, flushOutput, } from "../lib/output.js";
+import { renderAggregateResult } from "../lib/aggregate-output.js";
 import { confirmPrompt } from "../lib/confirm-prompt.js";
 import { resolveOwnerUserId } from "../lib/resolve-owner.js";
-import { pageCursorOption, pageLimitOption, parsePageLimit, printEmptyPage, printPageHint, } from "../lib/list-options.js";
+import { pageCursorOption, pageLimitOption, parsePageLimit, printEmptyPage, printPageHint, quoteCursorArg, } from "../lib/list-options.js";
 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 { chunkAddressOf, renumberManifestForExport, } from "../lib/snapshot-manifest-layout.js";
-import { validateSnapshotManifest } from "js-bao";
-import { auditSnapshotChain, } from "../lib/snapshot-audit.js";
-import { createAuditApiSource } from "../lib/snapshot-audit-source.js";
-import { createAuditLocalStore, createChainFingerprintReader, } from "../lib/snapshot-audit-store.js";
+import { buildPermissionsExport, PENDING_INVITATIONS_ABSENT_STATUSES, } from "../lib/document-export-permissions.js";
+import { readExportLookup } from "../lib/document-export-lookups.js";
 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 { driveDocumentIngest, summariseIngestPlan, assertIngestConfirmable, assertIngestRefreshKeepsRefused, ingestCreateBody, parseIngestFlags, } from "../lib/document-ingest.js";
+import { withTransientRetry } from "../lib/transient-retry.js";
+import { recordLogSchemaToToml } from "js-bao";
+import { DOCUMENT_ROUTES } from "../lib/records-verbs.js";
+import { DOCUMENT_LOAD_ROUTES } from "../lib/load-routes.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).
  *
@@ -35,6 +40,17 @@ function printIngestSession(session) {
         printResult(label, value);
     }
 }
+/**
+ * One refused document call, as one line for an operator: the server's
+ * sentence and, when it sent one, the stable code a script branches on — a
+ * large document's refusal names `DOCUMENT_FORMAT_UNSUPPORTED` on every verb
+ * that reaches its data (#4313).
+ */
+export function describeDocumentFailure(err) {
+    const message = (typeof err?.message === "string" && err.message) || String(err);
+    const code = typeof err?.code === "string" && err.code ? err.code : undefined;
+    return code && !message.includes(code) ? `${message} [${code}]` : message;
+}
 /**
  * One refused records call, as one line for an operator (#3764).
  *
@@ -53,7 +69,8 @@ export function describeRecordsFailure(err) {
     return `${message}${code ? ` [${code}]` : ""}${status !== undefined ? ` (${status})` : ""}`;
 }
 /**
- * Report a document's format (#2816) — but only when it is a large document.
+ * Report a document's format (#2816) — but only when it is a large (2) or a
+ * record-log (3, #4306) 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
@@ -62,9 +79,13 @@ export function describeRecordsFailure(err) {
  * stored row spells the format (absent, null or 1).
  */
 function printDocumentFormat(doc) {
-    if (Number(doc?.documentFormat) === 2) {
+    const format = Number(doc?.documentFormat);
+    if (format === 2) {
         keyValue("Format", "2 (large document)");
     }
+    else if (format === 3) {
+        keyValue("Format", "3 (record log)");
+    }
 }
 /**
  * The `--document-format` an operator stated, or the refusal (#3764, E10).
@@ -72,24 +93,65 @@ function printDocumentFormat(doc) {
  * Refused HERE rather than by the server, because an operator CAN act on it
  * (principle 6) and a round trip to be told what they typed wrong is a round
  * trip they do not need to spend. Commander hands the raw string over, so the
- * digits are what is read; an unset flag states nothing.
+ * digits are what is read; an unset flag states nothing. `flag` names the
+ * option in the refusal: `documents create` reads its `--format` here too.
+ *
+ * `2` — a large document, which the platform no longer serves — is refused
+ * with `DOCUMENT_FORMAT_UNSUPPORTED` named, as the server would refuse it.
  */
-export function parseDocumentFormatOption(value) {
+export function parseDocumentFormatOption(value, flag = "--document-format") {
     if (value === undefined || value === null)
         return undefined;
     const text = String(value).trim();
     if (text === "1")
         return 1;
-    if (text === "2")
-        return 2;
-    throw new Error(`Invalid --document-format "${String(value)}". Expected 1 (an ordinary ` +
-        `document) or 2 (a large document).`);
+    if (text === "3")
+        return 3;
+    if (text === "2") {
+        throw new Error(`documentFormat 2 (large document) is no longer served; use ${flag} 3 (DOCUMENT_FORMAT_UNSUPPORTED)`);
+    }
+    throw new Error(`Invalid ${flag} "${String(value)}". Expected 1 (an ordinary ` +
+        `document) or 3 (a record-log document).`);
 }
-/** The `--document-format <1|2>` flag, said once for every records verb. */
-const DOCUMENT_FORMAT_FLAG = "--document-format <1|2>";
-const DOCUMENT_FORMAT_HELP = "The document format you expect: 1 (ordinary) or 2 (large). A disagreement " +
+/**
+ * The `documentFormat` a `documents create` sends, from its two flags.
+ *
+ * `--format` is read by {@link parseDocumentFormatOption}, so a value outside
+ * 1 and 3 is refused before any request with the same sentence every records
+ * verb uses, and 2 with `DOCUMENT_FORMAT_UNSUPPORTED`. `--large` is
+ * `--format 3`: alone it sends 3, beside `--format 3` it changes nothing, and
+ * beside `--format 1` the two disagree and the command is refused rather than
+ * guessing which one was meant. Neither flag sends nothing, so the server's
+ * default stands.
+ *
+ * @param flags - The raw `--format` value and whether `--large` was given.
+ * @returns The format to send, or `undefined` to send none.
+ * @throws Error when `--format` is not 1 or 3, or disagrees with `--large`.
+ */
+export function documentFormatForCreate(flags) {
+    const format = parseDocumentFormatOption(flags.format, "--format");
+    if (!flags.large)
+        return format;
+    if (format !== undefined && format !== 3) {
+        throw new Error("--large is --format 3; pass one of them");
+    }
+    return 3;
+}
+/** The `--document-format <1|3>` flag, said once for every records verb. */
+const DOCUMENT_FORMAT_FLAG = "--document-format <1|3>";
+const DOCUMENT_FORMAT_HELP = "The document format you expect: 1 (ordinary) or 3 (record log). A disagreement " +
     "with the platform's own answer is refused with DOCUMENT_FORMAT_MISMATCH " +
     "rather than answered out of the wrong tables";
+/**
+ * One row of `documents inspect --refused`, as the label and value it prints:
+ * the code, a constraint refusal's constraint and holder, and the reason a
+ * record-log rule refusal carries (#4621).
+ */
+export function refusedRowLine(row) {
+    const conflicting = row.conflicting ? ` (held by ${row.conflicting.model} ${row.conflicting.id})` : "";
+    const reason = row.reason ? `: ${row.reason}` : "";
+    return [`  ${row.model} ${row.id}`, `${row.code}${row.constraint ? ` ${row.constraint}` : ""}${conflicting}${reason}`];
+}
 /**
  * What `documents records bulk` reports when the write is refused (#3619).
  *
@@ -124,6 +186,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).
  *
@@ -181,6 +269,7 @@ Examples:
   $ primitive documents get <document-id>
   $ primitive documents create "My Doc"
   $ primitive documents create "My Doc" --owner user@example.com
+  $ primitive documents create "Ledger" --format 3
   $ primitive documents delete <document-id> -y
   $ primitive documents permissions list <document-id>
   $ primitive documents permissions grant <document-id> --user-id <user-id> --permission reader
@@ -188,6 +277,7 @@ Examples:
   $ primitive documents records models <document-id>
   $ primitive documents records describe <document-id> <model-name>
   $ primitive documents records query <document-id> <model-name> --filter '{"status":"open"}'
+  $ primitive documents records query <document-id> <model-name> --sort '{"createdAt":-1}' --limit 50
   $ primitive documents records count <document-id> <model-name>
   $ primitive documents records save <document-id> <model-name> --data '{"qty":10}'
   $ primitive documents records patch <document-id> <model-name> <record-id> --data '{"qty":11}'
@@ -303,15 +393,17 @@ 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("--format <n>", "Document format: 1 (ordinary) or 3 (record log). Chosen at creation and never changed")
+        .option("--large", "Create a record-log document (format 3), for documents that outgrow a single in-memory Y.Doc. The same as --format 3")
         .option("--json", "Output as JSON")
         .addHelpText("after", `
 Ownership:
   An app-user token — member, admin, or owner — always creates the document
   owned by the caller: the server ignores --owner for those tokens.
   A super-admin token, or a console-admin token assigned to this app, acts
-  through an admin shadow app user — without --owner that shadow user owns the
-  document, with --owner the named user does.
+  through an admin shadow app user — without --owner that shadow user owns an
+  ordinary document and the app holds a record-log document (--format 3),
+  which no member owns; with --owner the named user does.
   A console admin not assigned to this app has no access to the app at all.
 
   An email given to --owner is resolved to a user id before anything is
@@ -319,6 +411,20 @@ Ownership:
   document.
 `)
         .action(async (title, options) => {
+        // Decided before anything else: a format the operator mistyped, one that
+        // disagrees with --large, or 2 (a large document, no longer served) is
+        // refused without a request (#4308, #4313).
+        let documentFormat;
+        try {
+            documentFormat = documentFormatForCreate({
+                format: options.format,
+                large: options.large === true,
+            });
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         let ownerUserId;
@@ -335,9 +441,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 } : {}),
+                // Opt-in only: without --format or --large nothing is sent, so the
+                // document is created in the legacy format exactly as before (#2816).
+                ...(documentFormat !== undefined ? { documentFormat } : {}),
             });
             if (options.json) {
                 json(result);
@@ -347,7 +453,7 @@ 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
+            // Read back from the RESPONSE, not from the flags: what the server
             // created is what the document will be for the rest of its life.
             printDocumentFormat(result);
         }
@@ -407,7 +513,7 @@ Permissions (enforced by the server, not the CLI):
         catch (err) {
             // Server refusals (404 not found, 403 root document / owner-only, the
             // non-owner fail-closed 503) are printed verbatim, never swallowed.
-            error(err.message);
+            error(describeDocumentFailure(err));
             process.exit(1);
         }
     });
@@ -549,29 +655,7 @@ Permissions (enforced by the server, not the CLI):
         .option("--app <app-id>", "App ID")
         .option("--json", "Output as JSON")
         .action(async (documentId, options) => {
-        const resolvedAppId = resolveAppId(undefined, options);
-        const client = new ApiClient();
-        try {
-            const result = await client.getDocumentSchema(resolvedAppId, documentId);
-            const models = result?.modelNames ?? Object.keys(result?.schema?.models ?? {});
-            if (options.json) {
-                json(models);
-                return;
-            }
-            if (models.length === 0) {
-                info("No models found.");
-                return;
-            }
-            for (const m of models) {
-                console.log(`  ${m}`);
-            }
-        }
-        catch (err) {
-            // #3764 — the server's sentence, the stable code and the status, so a
-            // refused records call is scriptable rather than only readable.
-            error(describeRecordsFailure(err));
-            process.exit(1);
-        }
+        await modelsAction(DOCUMENT_ROUTES, documentId, options);
     });
     // Describe a model's fields and indexes
     records
@@ -582,49 +666,7 @@ Permissions (enforced by the server, not the CLI):
         .option("--app <app-id>", "App ID")
         .option("--json", "Output as JSON")
         .action(async (documentId, modelName, options) => {
-        const resolvedAppId = resolveAppId(undefined, options);
-        const client = new ApiClient();
-        try {
-            const result = await client.getDocumentSchema(resolvedAppId, documentId);
-            const model = result?.schema?.models?.[modelName];
-            if (!model) {
-                if (options.json) {
-                    json(null);
-                    return;
-                }
-                info(`Model '${modelName}' not found in this document.`);
-                return;
-            }
-            const fieldsObj = model.fields ?? {};
-            const rows = Object.entries(fieldsObj).map(([name, meta]) => ({
-                field: name,
-                type: meta?.type ?? "unknown",
-                indexed: meta?.indexed ? "yes" : "",
-                unique: meta?.unique ? "yes" : "",
-                required: meta?.required ? "yes" : "",
-            }));
-            if (options.json) {
-                json({ fields: fieldsObj, constraints: model.constraints ?? {} });
-                return;
-            }
-            if (rows.length === 0) {
-                info("No fields detected for this model.");
-                return;
-            }
-            console.log(formatTable(rows, [
-                { header: "FIELD", key: "field", flex: true },
-                { header: "TYPE", key: "type" },
-                { header: "INDEXED", key: "indexed" },
-                { header: "UNIQUE", key: "unique" },
-                { header: "REQUIRED", key: "required" },
-            ]));
-        }
-        catch (err) {
-            // #3764 — the server's sentence, the stable code and the status, so a
-            // refused records call is scriptable rather than only readable.
-            error(describeRecordsFailure(err));
-            process.exit(1);
-        }
+        await describeAction(DOCUMENT_ROUTES, documentId, modelName, options);
     });
     // Query records in a document model
     records
@@ -635,8 +677,12 @@ Permissions (enforced by the server, not the CLI):
         .option("--app <app-id>", "App ID")
         .option("--filter <json>", "Filter as JSON (e.g. '{\"status\":\"open\"}')")
         .option("--filter-file <path>", "Read filter from a JSON or TOML file")
-        .option("--limit <n>", "Maximum number of records to return (max 100)", parseInt)
-        .option("--cursor <cursor>", "Pagination cursor from a previous query")
+        .option("--sort <json>", "Sort as JSON, e.g. '{\"createdAt\":-1}'; 1 ascending, -1 descending, key order is precedence; repeat it with --cursor")
+        // Forwarded as typed: the server refuses a value outside 1–10000 with a
+        // sentence naming the maximum, which a CLI-side parse would hide.
+        .option("--limit <n>", "Records per page (default 100, max 10000)")
+        .option("--cursor <cursor>", "Pagination cursor from a previous query (valid only with the same --sort)")
+        .option("--include <json>", "Related records as a JSON array of include specs, e.g. '[{\"model\":\"customer\",\"type\":\"refersTo\",\"sourceField\":\"customerId\"}]'; answered on a db3 as _related")
         .option(DOCUMENT_FORMAT_FLAG, DOCUMENT_FORMAT_HELP)
         .option("--json", "Output as JSON")
         .action(async (documentId, modelName, options) => {
@@ -651,52 +697,7 @@ Permissions (enforced by the server, not the CLI):
             error(describeRecordsFailure(err));
             process.exit(1);
         }
-        const filter = parseFilterOptions(options);
-        const client = new ApiClient();
-        try {
-            const result = await client.queryDocumentRecords(resolvedAppId, documentId, modelName, { filter, limit: options.limit, cursor: options.cursor, documentFormat });
-            if (options.json) {
-                json(result);
-                return;
-            }
-            const items = result.items;
-            if (items.length === 0) {
-                info("No records found.");
-                return;
-            }
-            const allKeys = new Set();
-            for (const rec of items) {
-                for (const key of Object.keys(rec))
-                    allKeys.add(key);
-            }
-            const orderedKeys = [];
-            if (allKeys.has("id")) {
-                orderedKeys.push("id");
-                allKeys.delete("id");
-            }
-            orderedKeys.push(...[...allKeys].sort());
-            const columns = orderedKeys.map((key) => ({
-                header: key.toUpperCase(),
-                key,
-                format: (v) => {
-                    if (v === null || v === undefined)
-                        return "—";
-                    if (typeof v === "object")
-                        return JSON.stringify(v);
-                    return String(v);
-                },
-            }));
-            console.log(formatTable(items, columns));
-            if (result.nextCursor) {
-                info(`More results available. Use --cursor ${result.nextCursor}`);
-            }
-        }
-        catch (err) {
-            // #3764 — the server's sentence, the stable code and the status, so a
-            // refused records call is scriptable rather than only readable.
-            error(describeRecordsFailure(err));
-            process.exit(1);
-        }
+        await queryRecordsAction(DOCUMENT_ROUTES, resolvedAppId, documentId, modelName, options, documentFormat);
     });
     // Get a single record by id (mirrors `databases records get`, issue #2357).
     records
@@ -778,28 +779,12 @@ Permissions (enforced by the server, not the CLI):
             error(describeRecordsFailure(err));
             process.exit(1);
         }
-        const filter = parseFilterOptions(options);
-        const client = new ApiClient();
-        try {
-            const result = await client.countDocumentRecords(resolvedAppId, documentId, modelName, { filter, documentFormat });
-            if (options.json) {
-                json(result);
-                return;
-            }
-            console.log(`  ${result.count}`);
-        }
-        catch (err) {
-            // #3764 — the server's sentence, the stable code and the status, so a
-            // refused records call is scriptable rather than only readable.
-            error(describeRecordsFailure(err));
-            process.exit(1);
-        }
+        await countRecordsAction(DOCUMENT_ROUTES, resolvedAppId, documentId, modelName, options, documentFormat);
     });
     // Aggregate records in a document model (issue #2437). Mirrors
     // `databases records aggregate` flag for flag and rendering for rendering —
     // including the deliberate `keyValue()` for the ungrouped scalar, so the two
     // twins keep printing the same thing.
-    const AGGREGATE_OPS = ["count", "sum", "avg", "min", "max"];
     records
         .command("aggregate")
         .description("Aggregate records in a document model (count/sum/avg/min/max, optional group-by)")
@@ -825,70 +810,7 @@ Permissions (enforced by the server, not the CLI):
             error(describeRecordsFailure(err));
             process.exit(1);
         }
-        if (!AGGREGATE_OPS.includes(options.op)) {
-            error(`Invalid --op "${options.op}". Expected one of: ${AGGREGATE_OPS.join(", ")}.`);
-            process.exit(1);
-        }
-        const operation = { type: options.op };
-        if (options.op === "count") {
-            if (options.field) {
-                error("--field is not valid for --op count.");
-                process.exit(1);
-            }
-        }
-        else {
-            if (!options.field) {
-                error(`--op ${options.op} requires --field.`);
-                process.exit(1);
-            }
-            operation.field = options.field;
-        }
-        const filter = parseFilterOptions(options);
-        const groupBy = options.groupBy || [];
-        const client = new ApiClient();
-        try {
-            const response = await client.aggregateDocumentRecords(resolvedAppId, documentId, modelName, { operations: [operation], groupBy, filter }, { documentFormat });
-            if (options.json) {
-                json(response);
-                return;
-            }
-            const aggregated = response?.result;
-            // Same labelling rule as the databases twin: the field name is
-            // reproduced verbatim, never case-folded (issue #2357).
-            const valueLabel = options.op === "count"
-                ? "COUNT"
-                : `${options.op.toUpperCase()}(${options.field})`;
-            const scalarLabel = options.op === "count"
-                ? "count"
-                : `${options.op.toLowerCase()}(${options.field})`;
-            if (groupBy.length === 0) {
-                const value = (aggregated ?? {})[options.op === "count" ? "count" : `${options.op}_${options.field}`];
-                keyValue(scalarLabel, value === null || value === undefined ? "—" : String(value));
-                return;
-            }
-            if (aggregated &&
-                typeof aggregated === "object" &&
-                !Array.isArray(aggregated) &&
-                Object.values(aggregated).every((v) => typeof v !== "object" || v === null)) {
-                const rows = Object.entries(aggregated).map(([group, value]) => ({
-                    group,
-                    value: value === null || value === undefined ? "—" : String(value),
-                }));
-                console.log(formatTable(rows, [
-                    { header: "GROUP", key: "group" },
-                    { header: valueLabel, key: "value" },
-                ]));
-            }
-            else {
-                console.log(JSON.stringify(aggregated ?? {}, null, 2));
-            }
-        }
-        catch (err) {
-            // #3764 — the server's sentence, the stable code and the status, so a
-            // refused records call is scriptable rather than only readable.
-            error(describeRecordsFailure(err));
-            process.exit(1);
-        }
+        await aggregateRecordsAction(DOCUMENT_ROUTES, resolvedAppId, documentId, modelName, options, documentFormat);
     });
     // ---- Record writes (#1964 Phase 4) ----
     // Server-side writes through the document facade: Yjs-first, CRDT-safe,
@@ -924,23 +846,7 @@ Permissions (enforced by the server, not the CLI):
             error(describeRecordsFailure(err));
             process.exit(1);
         }
-        const recordId = options.id || ulid();
-        const writeOptions = options.upsertOn ? { upsertOn: options.upsertOn } : undefined;
-        const client = new ApiClient();
-        try {
-            const result = await client.saveDocumentRecord(resolvedAppId, documentId, modelName, { id: recordId, data, ...(writeOptions ? { options: writeOptions } : {}) }, { documentFormat });
-            if (options.json) {
-                json(result);
-                return;
-            }
-            success(`Record saved: ${result.record?.id ?? recordId}`);
-        }
-        catch (err) {
-            // #3764 — the server's sentence, the stable code and the status, so a
-            // refused records call is scriptable rather than only readable.
-            error(describeRecordsFailure(err));
-            process.exit(1);
-        }
+        await saveRecordAction(DOCUMENT_ROUTES, resolvedAppId, documentId, modelName, data, options, documentFormat);
     });
     // Merge fields into an existing record
     records
@@ -967,21 +873,7 @@ Permissions (enforced by the server, not the CLI):
             error(describeRecordsFailure(err));
             process.exit(1);
         }
-        const client = new ApiClient();
-        try {
-            const result = await client.patchDocumentRecord(resolvedAppId, documentId, modelName, recordId, { data }, { documentFormat });
-            if (options.json) {
-                json(result);
-                return;
-            }
-            success(`Record patched: ${recordId}`);
-        }
-        catch (err) {
-            // #3764 — the server's sentence, the stable code and the status, so a
-            // refused records call is scriptable rather than only readable.
-            error(describeRecordsFailure(err));
-            process.exit(1);
-        }
+        await patchRecordAction(DOCUMENT_ROUTES, resolvedAppId, documentId, modelName, recordId, data, options, documentFormat);
     });
     // Delete a record
     records
@@ -1006,41 +898,14 @@ Permissions (enforced by the server, not the CLI):
             error(describeRecordsFailure(err));
             process.exit(1);
         }
-        if (!options.yes) {
-            const confirmed = await confirmPrompt(`Delete record ${recordId} from ${modelName} in document ${documentId}?`);
-            if (!confirmed) {
-                info("Cancelled.");
-                return;
-            }
-        }
-        const client = new ApiClient();
-        try {
-            const result = await client.deleteDocumentRecord(resolvedAppId, documentId, modelName, recordId, { documentFormat });
-            if (options.json) {
-                json(result);
-                return;
-            }
-            // A delete of a missing record is a silent no-op server-side, so
-            // this reports the request outcome, not record existence.
-            success(`Record deleted: ${recordId}`);
-        }
-        catch (err) {
-            // #3764 — the server's sentence, the stable code and the status, so a
-            // refused records call is scriptable rather than only readable.
-            error(describeRecordsFailure(err));
-            process.exit(1);
-        }
+        await deleteRecordAction(DOCUMENT_ROUTES, resolvedAppId, documentId, modelName, recordId, options, documentFormat);
     });
     // 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")
@@ -1056,40 +921,7 @@ Permissions (enforced by the server, not the CLI):
             error(describeRecordsFailure(err));
             process.exit(1);
         }
-        const parsed = parseDataOption(options, "operations blob", {
-            allowArray: true,
-        });
-        const operations = Array.isArray(parsed) ? parsed : parsed?.operations;
-        if (!Array.isArray(operations) || operations.length === 0) {
-            error("--data-file must contain { operations: [...] } or a non-empty operations array.");
-            process.exit(1);
-        }
-        const resolvedAppId = resolveAppId(undefined, options);
-        if (!options.yes) {
-            const confirmed = await confirmPrompt(`Apply ${operations.length} operation(s) atomically to document ${documentId}?`);
-            if (!confirmed) {
-                info("Cancelled.");
-                return;
-            }
-        }
-        const client = new ApiClient();
-        try {
-            const result = await client.bulkDocumentRecords(resolvedAppId, documentId, operations, { documentFormat });
-            if (options.json) {
-                json(result);
-                return;
-            }
-            success(`Applied ${result.applied} operation(s): ` +
-                `${result.added.length} added, ${result.updated.length} updated, ${result.deleted} deleted.`);
-        }
-        catch (err) {
-            const report = describeBulkFailure(err);
-            if (options.json)
-                json(report.envelope);
-            else
-                error(report.line);
-            process.exit(1);
-        }
+        await bulkRecordsAction(DOCUMENT_ROUTES, documentId, options, documentFormat);
     });
     // Dump a document's records grouped by model (CLI-side composition)
     documents
@@ -1128,37 +960,45 @@ Permissions (enforced by the server, not the CLI):
             console.log(output);
         }
         catch (err) {
-            error(err.message);
+            error(describeDocumentFailure(err));
             process.exit(1);
         }
     });
     // 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")
         .action(async (documentId, options) => {
-        const resolvedAppId = resolveAppId(undefined, options);
-        const client = new ApiClient();
-        try {
-            const result = await client.getDocumentStats(resolvedAppId, documentId);
-            if (options.json) {
-                json(result);
-                return;
-            }
-            keyValue("Document ID", result.documentId);
-            keyValue("Records", result.recordCount);
-            keyValue("Models", result.modelCount);
-            keyValue("Blobs", result.blobCount);
-            keyValue("Size (bytes, approx)", result.sizeBytes);
-            keyValue("Last modified", result.lastModifiedAt ? formatDate(result.lastModifiedAt) : "—");
-        }
-        catch (err) {
-            error(err.message);
-            process.exit(1);
-        }
+        await statsAction(DOCUMENT_ROUTES, documentId, options);
+    });
+    // #4623 — a document's models and fields as the room declared and observed
+    // them (`GET .../schema`): a table, the route's JSON, or a schema.toml the
+    // client's `schemaToml` option and js-bao-codegen-v2 accept.
+    documents
+        .command("schema")
+        .description("Show a document's models and fields as declared and observed, or export them as a schema.toml")
+        .argument("<document-id>", "Document ID")
+        .option("--app <app-id>", "App ID")
+        .option("--toml", "Print a schema.toml the client's schemaToml option and js-bao-codegen-v2 accept")
+        .option("--output <file>", "With --toml: write the TOML to this file (overwriting it) instead of stdout")
+        .option("--json", "Output the /schema answer as JSON")
+        .action(async (documentId, options) => {
+        await schemaAction(DOCUMENT_ROUTES, documentId, options);
+    });
+    // #4306 — a record-log document's room: the inspection route's payload.
+    documents
+        .command("inspect")
+        .description("Show a record-log document's room: epochs, log number, floors, writers, the bulk load in progress and checkpoint")
+        .argument("<document-id>", "Document ID")
+        .option("--app <app-id>", "App ID")
+        .option("--refused <session-id>", "Print every row that bulk load refused, with its code, instead")
+        .option("--limit <n>", "With --refused: rows per page read (1–100)", "100")
+        .option("--json", "Output as JSON")
+        .action(async (documentId, options) => {
+        await inspectAction(DOCUMENT_ROUTES, documentId, options);
     });
     // The action verb (#3435, criterion 9): a directory of records becomes a
     // chunked, digested, uploaded artifact and one atomic swap of the
@@ -1174,132 +1014,23 @@ Permissions (enforced by the server, not the CLI):
         .argument("<document-id>", "Document ID")
         .requiredOption("--input <dir>", "Directory of <model>.ndjson[.gz] files, or a `documents export` output")
         .option("--app <app-id>", "App ID")
+        .option("--reserve-epoch <when>", "Record-log (format 3) documents: reserve the load's epoch at session open (open, the default) or at commit")
+        .option("--mode <mode>", "Record-log (format 3) documents: merge the rows (merge, the default), or refresh: also delete every record of the input's models that no row names")
         .option("-y, --yes", "Skip the confirmation prompt")
         .option("--no-wait", "Exit once the session is committed")
         .option("--timeout <seconds>", "Give up waiting after this many seconds")
         .option("--json", "Output as JSON")
         .action(async (documentId, options) => {
-        const resolvedAppId = resolveAppId(undefined, options);
-        const client = new ApiClient();
-        let plan = null;
-        // The exit code is carried out of here rather than taken inside: a
-        // `process.exit` does not unwind, so ending the process in the try block
-        // would skip the cleanup in the finally and leave the compressed
-        // artifact — up to the whole input, gzipped — in the OS temp directory
-        // on every run, successful or not (finding 3435-FROZEN-05).
-        const run = async () => {
-            // The preflight, in this order and before a byte is read from disk:
-            // the schema read says whether this caller may see the document's
-            // declarations at all and hands over the ones the lines are checked
-            // against, and the session reader says whether this is a large
-            // document. Both are READS on the arm the ingest routes admit, so a
-            // caller who would be refused halfway is refused at once, and neither
-            // opens a session.
-            const introspection = await client.getDocumentSchema(resolvedAppId, documentId);
-            await client.listDocumentIngests(resolvedAppId, documentId, { limit: 1 });
-            const schema = ingestSchemaFromIntrospection(introspection);
-            const input = discoverIngestInput(options.input, documentId);
-            for (const ignored of input.ignored) {
-                info(`Ignoring ${ignored}: a bulk load reads the snapshot only.`);
-            }
-            // #3598 — reading, checking, sorting, cutting and gzipping is this
-            // side's biggest phase on a large input, and it used to be invisible
-            // inside one wall-clock number that also covered the platform's work.
-            const buildStartedAt = Date.now();
-            plan = await buildIngestArtifact({ input, schema });
-            const buildMs = Date.now() - buildStartedAt;
-            info(`Built artifact in ${(buildMs / 1000).toFixed(1)}s.`);
-            for (const line of summariseIngestPlan(plan))
-                info(line);
-            assertIngestConfirmable({
-                yes: Boolean(options.yes),
-                isTTY: Boolean(process.stdin.isTTY),
-            });
-            if (!options.yes) {
-                const confirmed = await confirmPrompt(`Bulk-load ${plan.rows} records into ${documentId}? ` +
-                    "This replaces records in a live document and cannot be undone.");
-                if (!confirmed) {
-                    info("Nothing was uploaded.");
-                    return 1;
-                }
-            }
-            // Ctrl-C is a decision the driver makes differently depending on
-            // where it lands, so it is handed the signal rather than killing the
-            // process: mid-upload the session is aborted, mid-poll it is left
-            // running, because by then the document is already being changed.
-            const interrupt = new AbortController();
-            const onSignal = () => interrupt.abort();
-            process.on("SIGINT", onSignal);
-            let outcome;
-            try {
-                outcome = await driveDocumentIngest({
-                    client: {
-                        createIngest: (id) => client.createDocumentIngest(resolvedAppId, id),
-                        uploadIngestChunk: (id, sessionId, chunk) => client.uploadDocumentIngestChunk(resolvedAppId, id, sessionId, chunk),
-                        commitIngest: (id, sessionId) => client.commitDocumentIngest(resolvedAppId, id, sessionId),
-                        abortIngest: (id, sessionId) => client.abortDocumentIngest(resolvedAppId, id, sessionId),
-                        getIngest: (id, sessionId) => client.getDocumentIngest(resolvedAppId, id, sessionId),
-                    },
-                    documentId,
-                    plan,
-                    wait: options.wait !== false,
-                    timeoutMs: options.timeout ? Number(options.timeout) * 1000 : null,
-                    signal: interrupt.signal,
-                    onProgress: (line) => info(line),
-                });
-            }
-            finally {
-                process.off("SIGINT", onSignal);
-            }
-            if (outcome.message)
-                error(outcome.message);
-            // #3598 — the two sides, side by side. The session's own `timings`
-            // say where the platform's share went; `client` says what this
-            // process spent before and around it, so a slow load can be blamed on
-            // the side that was actually slow.
-            const clientTimings = { buildMs, ...outcome.timings };
-            if (options.json) {
-                json({
-                    ...(outcome.session ?? { sessionId: outcome.sessionId }),
-                    client: clientTimings,
-                });
-            }
-            else {
-                if (outcome.session) {
-                    printIngestSession(outcome.session);
-                }
-                else if (outcome.sessionId) {
-                    printResult("Session", outcome.sessionId);
-                }
-                for (const [label, value] of ingestClientRows(clientTimings)) {
-                    printResult(label, value);
-                }
-            }
-            return outcome.exitCode;
-        };
-        let code = 1;
-        try {
-            code = await run();
-        }
-        catch (err) {
-            error(err.message);
-            code = 1;
-        }
-        finally {
-            await plan?.cleanup().catch(() => undefined);
-        }
-        // The result has to reach the pipe before the process ends: stdout to a
-        // pipe is asynchronous and `process.exit` does not wait for it.
-        await flushOutput();
-        process.exit(code);
+        await ingestAction(DOCUMENT_LOAD_ROUTES, documentId, options);
     });
     // Bulk-load sessions of a large document (#3434, criterion 9): a data noun
     // with `list` and `get` readers, per docs/cli-design.md, beside `snapshots`
     // below. The ACTION verb `documents ingest` is #3435's; these two are how an
-    // operator sees what a session did and why one stopped.
+    // operator sees what a session did and why one stopped, and `abort` (#4475)
+    // is how they give one up.
     const ingests = documents
         .command("ingests")
-        .description("Inspect a large document's bulk-load sessions");
+        .description("Inspect or abort a large document's bulk-load sessions");
     ingests
         .command("list")
         .description("List a large document's bulk-load sessions, newest first")
@@ -1309,42 +1040,7 @@ Permissions (enforced by the server, not the CLI):
         .option("--cursor <cursor>", "Continue from a previous page's nextCursor")
         .option("--json", "Output as JSON")
         .action(async (documentId, options) => {
-        const limit = parsePageLimit(options.limit);
-        const resolvedAppId = resolveAppId(undefined, options);
-        const client = new ApiClient();
-        try {
-            const page = normalizeCliListEnvelope(await client.listDocumentIngests(resolvedAppId, documentId, {
-                limit,
-                ...(options.cursor ? { cursor: options.cursor } : {}),
-            }));
-            if (options.json) {
-                json(page);
-                return;
-            }
-            if (page.items.length === 0) {
-                info("No ingest sessions yet.");
-                return;
-            }
-            console.log(formatTable(page.items, [
-                { header: "SESSION", key: "sessionId" },
-                { header: "STATE", key: "state" },
-                { header: "CREATED", key: "createdAt", format: formatDate },
-                { header: "CHUNKS", key: "chunks" },
-                { header: "ROWS", key: "rows" },
-                {
-                    header: "COMPLETED",
-                    key: "completedAt",
-                    format: (at) => (at ? formatDate(at) : "—"),
-                },
-            ]));
-            if (page.hasMore && page.nextCursor) {
-                info(`More sessions: --cursor ${page.nextCursor}`);
-            }
-        }
-        catch (err) {
-            error(err.message);
-            process.exit(1);
-        }
+        await listIngestsAction(DOCUMENT_LOAD_ROUTES, documentId, options);
     });
     ingests
         .command("get")
@@ -1354,27 +1050,28 @@ Permissions (enforced by the server, not the CLI):
         .option("--app <app-id>", "App ID")
         .option("--json", "Output as JSON")
         .action(async (documentId, sessionId, options) => {
-        const resolvedAppId = resolveAppId(undefined, options);
-        const client = new ApiClient();
-        try {
-            const session = await client.getDocumentIngest(resolvedAppId, documentId, sessionId);
-            if (options.json) {
-                json(session);
-                return;
-            }
-            printIngestSession(session);
-        }
-        catch (err) {
-            error(err.message);
-            process.exit(1);
-        }
+        await getIngestAction(DOCUMENT_LOAD_ROUTES, documentId, sessionId, options);
+    });
+    // Destructive — what the session uploaded is discarded — so it confirms
+    // unless `-y`, and a non-TTY stdin without `-y` is refused before any
+    // request, as `documents ingest` refuses it (#4475).
+    ingests
+        .command("abort")
+        .description("Abort a bulk-load session and discard what it uploaded")
+        .argument("<document-id>", "Document ID")
+        .argument("<session-id>", "Session ID")
+        .option("--app <app-id>", "App ID")
+        .option("-y, --yes", "Skip the confirmation prompt")
+        .option("--json", "Output as JSON")
+        .action(async (documentId, sessionId, options) => {
+        await abortIngestAction(DOCUMENT_LOAD_ROUTES, documentId, sessionId, options);
     });
     // Snapshot builds of a large document (#3432, criterion 9): a data noun
     // with `list` and `get` readers, per docs/cli-design.md, over the app API's
     // read-only inspection routes.
     const snapshots = documents
         .command("snapshots")
-        .description("Inspect a large document's snapshot builds and their verification");
+        .description("Inspect a large document's snapshots (its segments)");
     snapshots
         .command("list")
         .description("List a large document's snapshot builds, newest first")
@@ -1384,77 +1081,17 @@ Permissions (enforced by the server, not the CLI):
         .option("--cursor <cursor>", "Continue from a previous page's nextCursor")
         .option("--json", "Output as JSON")
         .action(async (documentId, options) => {
-        const limit = parsePageLimit(options.limit);
-        const resolvedAppId = resolveAppId(undefined, options);
-        const client = new ApiClient();
-        try {
-            const page = normalizeCliListEnvelope(await client.listDocumentSnapshots(resolvedAppId, documentId, {
-                limit,
-                ...(options.cursor ? { cursor: options.cursor } : {}),
-            }));
-            if (options.json) {
-                json(page);
-                return;
-            }
-            if (page.items.length === 0) {
-                info("No snapshot builds yet.");
-                return;
-            }
-            console.log(formatTable(page.items, [
-                { header: "BUILD", key: "buildId" },
-                { header: "EPOCH", key: "epoch" },
-                { header: "STATE", key: "state" },
-                { header: "SOURCE", key: "source" },
-                {
-                    header: "VERIFICATION",
-                    key: "verification",
-                    format: (verification) => verification
-                        ? verification.code
-                            ? `${verification.state} (${verification.code})`
-                            : verification.state
-                        : "-",
-                },
-                { header: "ROWS", key: "rows" },
-                { header: "CHUNKS", key: "chunks" },
-                { header: "STARTED", key: "startedAt", format: formatDate },
-                { header: "COMPLETED", key: "completedAt", format: formatDate },
-            ]));
-            if (page.hasMore && page.nextCursor) {
-                info(`More builds: --cursor ${page.nextCursor}`);
-            }
-        }
-        catch (err) {
-            error(err.message);
-            process.exit(1);
-        }
+        await listSnapshotsAction(DOCUMENT_LOAD_ROUTES, documentId, options);
     });
     snapshots
         .command("get")
-        .description("Show one snapshot build, its verification result and where its time went")
+        .description("Show one snapshot (a segment): its state, rows and chunks")
         .argument("<document-id>", "Document ID")
         .argument("<build-id>", "Build ID")
         .option("--app <app-id>", "App ID")
         .option("--json", "Output as JSON")
         .action(async (documentId, buildId, options) => {
-        const resolvedAppId = resolveAppId(undefined, options);
-        const client = new ApiClient();
-        try {
-            const build = await client.getDocumentSnapshot(resolvedAppId, documentId, buildId);
-            if (options.json) {
-                json(build);
-                return;
-            }
-            // The rows are composed by a pure function (#3435), so what a
-            // terminal shows is checkable without spawning one; the command still
-            // owns the printing.
-            for (const [label, value] of snapshotBuildRows(build)) {
-                printResult(label, value);
-            }
-        }
-        catch (err) {
-            error(err.message);
-            process.exit(1);
-        }
+        await getSnapshotAction(DOCUMENT_LOAD_ROUTES, documentId, buildId, options);
     });
     // #3666, criterion 7 — the one ACTION verb in this group: snapshot the
     // document now instead of waiting for the size or age trigger. Its exit
@@ -1467,152 +1104,14 @@ Permissions (enforced by the server, not the CLI):
     // on its own several times a day.
     snapshots
         .command("build")
-        .description("Snapshot a large document now: seal the open epoch and build a base")
+        .description("Snapshot a large document now: start a segment export of its records")
         .argument("<document-id>", "Document ID")
         .option("--app <app-id>", "App ID")
-        .option("--wait", "Poll until the build has verified or failed")
+        .option("--wait", "Poll until the segment is complete or failed")
         .option("--timeout <seconds>", "Give up waiting after this many seconds")
         .option("--json", "Output as JSON")
         .action(async (documentId, options) => {
-        const resolvedAppId = resolveAppId(undefined, options);
-        const client = new ApiClient();
-        const run = async () => {
-            // Ctrl-C while polling leaves the build running — by then the room is
-            // already building it and giving up on watching is not giving up on
-            // the build — so the signal is handed to the driver rather than
-            // killing the process.
-            const interrupt = new AbortController();
-            const onSignal = () => interrupt.abort();
-            process.on("SIGINT", onSignal);
-            let outcome;
-            try {
-                outcome = await driveSnapshotBuild({
-                    client: {
-                        requestSnapshot: (id) => client.requestDocumentSnapshot(resolvedAppId, id),
-                        getSnapshot: (id, buildId) => client.getDocumentSnapshot(resolvedAppId, id, buildId),
-                    },
-                    documentId,
-                    wait: Boolean(options.wait),
-                    timeoutMs: options.timeout ? Number(options.timeout) * 1000 : null,
-                    signal: interrupt.signal,
-                    onProgress: (line) => info(line),
-                });
-            }
-            finally {
-                process.off("SIGINT", onSignal);
-            }
-            if (outcome.message)
-                error(outcome.message);
-            if (options.json) {
-                // The route's answer as received, with the build the wait settled
-                // on beside it when there was one — so a script branches on the
-                // verdict rather than on an exit code alone.
-                json(outcome.build ? { ...outcome.response, build: outcome.build } : outcome.response);
-                return outcome.exitCode;
-            }
-            if (outcome.response?.sealed === false) {
-                printResult("Sealed", "no — the open epoch carried nothing");
-                printResult("Reason", outcome.response.reason);
-                printResult("Covering build", outcome.response.coveringBuildId ?? "—");
-                return outcome.exitCode;
-            }
-            printResult("Sealed epoch", outcome.response.sealedEpoch);
-            printResult("Open epoch", outcome.response.nextEpoch);
-            printResult("Build", outcome.response.buildId);
-            if (outcome.build) {
-                for (const [label, value] of snapshotBuildRows(outcome.build)) {
-                    printResult(label, value);
-                }
-            }
-            return outcome.exitCode;
-        };
-        let code = 1;
-        try {
-            code = await run();
-        }
-        catch (err) {
-            // The server's own sentence, plus the code a script branches on
-            // (#3403) — a refused loop that only says "too young to seal" leaves
-            // a caller parsing prose to tell it from a permission refusal.
-            error(err.code ? `${err.message} (${err.code})` : err.message);
-            const retryAfterMs = err.details?.retryAfterMs;
-            if (typeof retryAfterMs === "number") {
-                error(`Ask again in ${Math.ceil(retryAfterMs / 1000)}s.`);
-            }
-            code = 1;
-        }
-        // The result has to reach the pipe before the process ends: stdout to a
-        // pipe is asynchronous and `process.exit` does not wait for it.
-        await flushOutput();
-        process.exit(code);
-    });
-    // #3433, criterion 10 — the operator audit: `snapshot ⊕ overlays == table`,
-    // recomputed on this side with the CLIENT's loader and fold and compared
-    // with the authoritative table page by page. The one check that can catch a
-    // DO/client fold divergence, which per-build verification runs on one side
-    // of and therefore cannot see.
-    snapshots
-        .command("audit")
-        .description("Recompute a large document's snapshot chain locally and compare it with the table")
-        .argument("<document-id>", "Document ID")
-        .option("--app <app-id>", "App ID")
-        .option("--retries <n>", "Attempts before giving up on a document that keeps changing", "3")
-        .option("--json", "Output as JSON")
-        .action(async (documentId, options) => {
-        const resolvedAppId = resolveAppId(undefined, options);
-        const client = new ApiClient();
-        const report = await auditDocumentChain(client, resolvedAppId, documentId, Number(options.retries));
-        if (options.json) {
-            json(report);
-        }
-        else if (report.verdict === "none") {
-            // No verdict is not a clean bill of health, so nothing that could be
-            // read as one is printed: the reason, and nothing else.
-            error(`No verdict: ${report.reason}`);
-        }
-        else {
-            printResult("Document", documentId);
-            printResult("Base build", report.buildId);
-            printResult("Base epoch", report.epoch);
-            printResult("Attempts", report.attempts);
-            printResult("Verdict", report.verdict === "match"
-                ? "match — the table is the chain"
-                : "DIVERGENCE");
-            console.log(formatTable(report.models, [
-                { header: "MODEL", key: "model" },
-                { header: "COMPARED", key: "compared" },
-                {
-                    header: "ONLY IN CHAIN",
-                    key: "onlyRecomputed",
-                    format: (ids) => (ids.length ? ids.join(", ") : "-"),
-                },
-                {
-                    header: "ONLY IN TABLE",
-                    key: "onlyTable",
-                    format: (ids) => (ids.length ? ids.join(", ") : "-"),
-                },
-                {
-                    header: "DIFFERING",
-                    key: "differing",
-                    format: (rows) => rows.length
-                        ? rows.map((row) => `${row.id} (${row.fields.join(", ")})`).join("; ")
-                        : "-",
-                },
-            ]));
-            if (report.models.some((model) => model.truncated)) {
-                info("Some lists were truncated; re-run with --json for the full report.");
-            }
-            if (report.verdict === "match")
-                success("snapshot ⊕ overlays == table");
-        }
-        // The report has to reach the pipe before the process ends: stdout to a
-        // pipe is asynchronous and `process.exit` does not wait for it, so a
-        // large report piped into anything that is not reading as fast as this
-        // writes used to arrive cut off mid-document (3433-C12).
-        await flushOutput();
-        // 0 match, 1 divergence, 2 no verdict — so the validation child can
-        // script on "no verdict" without reading the text.
-        process.exit(report.verdict === "match" ? 0 : report.verdict === "divergence" ? 1 : 2);
+        await buildSnapshotAction(DOCUMENT_LOAD_ROUTES, documentId, options);
     });
     // Transfer document ownership
     documents
@@ -1907,7 +1406,7 @@ Permissions (enforced by the server, not the CLI):
             await exportSingleDocument(client, resolvedAppId, documentId, options.output, options.blobs !== false ? true : false, options.json);
         }
         catch (err) {
-            error(err.message);
+            error(describeDocumentFailure(err));
             process.exit(1);
         }
     });
@@ -1925,6 +1424,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 +1447,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 +1482,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")
@@ -2001,9 +1513,8 @@ Permissions (enforced by the server, not the CLI):
         // `--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)")
+        // (#3135), and names the one id remapping on top of it.
+        .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)")
         .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")
@@ -2023,6 +1534,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) {
@@ -2068,6 +1580,30 @@ Permissions (enforced by the server, not the CLI):
                 info("No documents to import.");
                 return;
             }
+            // A record-log (format 3) export is a document's rows at one log
+            // number, not a state to install (#4310): it is loaded with a bulk
+            // load. Refused before any request, naming the way in.
+            // A large-document (format 2) export cannot be installed: the platform
+            // no longer serves the format. Its snapshot row chunks are the way
+            // across, loaded into a record-log document. Refused before any write.
+            const largeDocumentExports = docDirs.filter((docDir) => isLargeDocumentExport(docDir));
+            if (largeDocumentExports.length > 0) {
+                for (const docDir of largeDocumentExports) {
+                    error(`${docDir}: this export is a large document (format 2), which the platform no longer serves; ` +
+                        `create a record-log document and run \`primitive documents ingest <document-id> --input ${docDir}\` to load its row chunks`);
+                }
+                await flushOutput();
+                process.exit(1);
+            }
+            const recordLogExports = docDirs.filter((docDir) => Number(readExportMetadata(docDir)?.documentFormat) === 3);
+            if (recordLogExports.length > 0) {
+                for (const docDir of recordLogExports) {
+                    error(`${docDir} is a record-log (format 3) export; \`documents import\` does not install one. ` +
+                        `Load its rows into a format-3 document with \`documents ingest <document-id> --input ${docDir}\`.`);
+                }
+                await flushOutput();
+                process.exit(1);
+            }
             const summary = {
                 created: 0,
                 updated: 0,
@@ -2075,39 +1611,52 @@ 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
             // 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) {
-                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);
-            }
+            // 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 +1665,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
@@ -2159,153 +1721,79 @@ 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);
-        const downloaded = JSON.parse(manifestBytes.toString("utf-8"));
-        // Addressed within the granted build by each entry's `path` — the
-        // own-build `{model}/{n}` or the `{epoch}-{buildId}/{model}/{n}` of a
-        // chunk reused from an earlier build — never by key (#3432). On disk the
-        // chunks are renumbered per model into the own-build form and the stored
-        // manifest says so, which is the one layout `documents import` reads.
-        const { manifest, files } = renumberManifestForExport(downloaded);
-        for (const file of files) {
-            const body = await client.downloadDocumentArtifact(appId, `${chain.base.download.path}/${file.download}`);
-            const target = path.join(snapshotDir, file.file);
-            fs.mkdirSync(path.dirname(target), { recursive: true });
-            fs.writeFileSync(target, body);
-            bytes += body.byteLength;
-        }
-        fs.writeFileSync(path.join(snapshotDir, "manifest.json"), JSON.stringify(manifest, null, 2));
-        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;
-}
-/**
- * Where a stored manifest entry's chunk is on disk: `snapshot/{model}/{n}`.
- *
- * An exported manifest is in the own-build form (renumbered per model), so
- * the entry's `path` — or, for an artifact written before the field existed,
- * its key — names the file directly.
- */
-function chunkFileOf(chunk) {
-    const address = chunkAddressOf(chunk);
-    return { model: address.model, index: address.index };
-}
 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
-    //    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.
+    // 2. Export the document's state. A legacy document is one blob; a
+    //    record-log document is its rows at one log number. A large document
+    //    (format 2) is no longer served, and the server refuses its export.
     let stateBytes;
-    if (Number(docMeta?.documentFormat) === 2) {
-        stateBytes = await exportLargeDocumentChain(client, appId, documentId, docDir);
+    if (Number(docMeta?.documentFormat) === 3) {
+        // A record-log document (#4310): its current segment, with the rows
+        // written while it exported merged in, so the directory is the document
+        // at one log number.
+        const exported = await exportRecordLogDocument({
+            client: {
+                requestSegment: () => client.requestDocumentSnapshot(appId, documentId),
+                getSegment: (segmentId) => client.getDocumentSnapshot(appId, documentId, segmentId),
+                listSegments: () => client.listDocumentSnapshots(appId, documentId, { limit: 100 }),
+                exportChain: () => client.exportDocumentChain(appId, documentId),
+                download: (artifactPath) => client.downloadDocumentArtifact(appId, artifactPath),
+            },
+            documentId,
+            docDir,
+        });
+        stateBytes = exported.bytes;
     }
     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 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
-    }
-    // 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).
+    // 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 or record-log 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, #4310).
     const metadata = {
         documentId: docMeta.documentId || documentId,
         title: docMeta.title,
         tags: docMeta.tags || [],
         ...(Number(docMeta?.documentFormat) === 2 ? { documentFormat: 2 } : {}),
+        ...(Number(docMeta?.documentFormat) === 3 ? { documentFormat: 3 } : {}),
         createdAt: docMeta.createdAt,
         createdBy: docMeta.createdByEmail || docMeta.createdBy,
         aliases: aliases.map((a) => ({
@@ -2316,14 +1804,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 });
@@ -2357,210 +1837,47 @@ async function exportSingleDocument(client, appId, documentId, outputDir, includ
     }
 }
 /**
- * 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.
+ * Every uploaded blob of a document, read page by page (#4149).
  *
- * `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.
+ * 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.
  */
-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})`);
-        }
-        // Validated where it enters (#3432): the fields the server keys on — an
-        // entry's ordinal, its path, its range — fail silently rather than loudly
-        // if they are wrong, and the server refuses the same manifest later with
-        // the same message.
-        try {
-            validateSnapshotManifest(manifest);
-        }
-        catch (invalid) {
-            refuse(`has a base snapshot manifest that is not valid (${invalid.message})`);
-        }
-        for (const chunk of manifest.chunks ?? []) {
-            const { model, index } = chunkFileOf(chunk);
-            require(path.join(docDir, "snapshot", model, `${index}.ndjson.gz`), `chunk ${index} of ${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");
+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;
 }
-/** 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.
+ * 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.
  */
-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 ?? []) {
-            // Addressed by the entry's `path` (#3432); the server installs by it too.
-            const { model, index } = chunkFileOf(chunk);
-            await client.uploadDocumentChainArtifact(appId, documentId, {
-                kind: "chunk",
-                epoch: chain.base.epoch,
-                buildId: chain.base.buildId,
-                model,
-                index,
-            }, fs.readFileSync(path.join(docDir, "snapshot", 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));
-    }
+function retryingImportStep(what, attempt) {
+    return withTransientRetry(attempt, (failure, delayMs) => warn(`${what} failed (${failure?.message || "no reason given"}); ` +
+        `retrying in ${delayMs / 1000}s`));
 }
 /** Mirrors `ROOT_DOCUMENT_TAG` in `src/config/constants.ts`. */
 const ROOT_DOCUMENT_TAG = "__ROOT_TAG__";
@@ -2569,18 +1886,14 @@ 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.
+ * Whether `docDir` holds a large document's (format 2) export: the
+ * `chain.json` its export wrote last, or a `metadata.json` naming format 2.
  */
-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.";
+function isLargeDocumentExport(docDir) {
+    if (fs.existsSync(path.join(docDir, "chain.json")))
+        return true;
+    return Number(readExportMetadata(docDir)?.documentFormat) === 2;
+}
 /** 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 +1923,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 +1952,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 +2006,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 +2075,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 +2084,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`);
@@ -2760,37 +2107,46 @@ async function importSingleDocument(client, appId, docDir, overwrite, aliasMode,
     // 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);
+        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
-    // 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 existing = await existingDocument(client, appId, documentId);
+    const exists = existing !== null;
+    progress.exists = exists;
     const wouldSkip = dryRun ? "[dry-run] Would skip" : "Skipping";
     if (exists && !overwrite) {
-        // `--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)`);
+        // 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, ownerUserId
+            ? { userId: ownerUserId, aliasMode, exported: metadata.aliases }
+            : undefined);
+        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);
+            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;
+        }
+        warn(`${wouldSkip} ${documentId}: already exists (use --overwrite to merge ` +
+            `the exported state into it)`);
         summary.skipped++;
         return;
     }
@@ -2803,8 +2159,7 @@ async function importSingleDocument(client, appId, docDir, overwrite, aliasMode,
             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).
+    // Create document if it doesn't exist.
     //
     // 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
@@ -2814,72 +2169,217 @@ async function importSingleDocument(client, appId, docDir, overwrite, aliasMode,
             title: metadata.title || "Imported Document",
             documentId,
             tags: metadata.tags,
-            ...(isLargeDocument ? { documentFormat: 2 } : {}),
             ...(ownerUserId ? { createdBy: ownerUserId } : {}),
         });
+        progress.exists = true;
         summary.created++;
     }
     else {
         summary.updated++;
     }
-    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);
+    await importExportedState(client, appId, docDir, documentId);
+    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))
+        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++;
     }
-    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);
+}
+/** 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;
         }
-    }
-    // Upload blobs
-    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++;
-            }
+        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;
-            }
-            try {
-                await client.setDocumentAlias(appId, alias.aliasScope, alias.aliasKey, documentId, ownerUserId, aliasMode === "skip" // mustNotExist: true for skip mode, false for overwrite
-                );
-                summary.aliasesSet++;
-            }
-            catch {
-                summary.aliasesSkipped++;
-            }
-        }
+}
+/** "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.blobs.length > 0) {
+        parts.push(`${gaps.blobs.length} blob${gaps.blobs.length === 1 ? "" : "s"}`);
     }
-    info(`Imported document ${documentId} (${metadata.title || "untitled"})`);
+    if (gaps.aliases.length > 0) {
+        parts.push(`${gaps.aliases.length} alias${gaps.aliases.length === 1 ? "" : "es"}`);
+    }
+    return parts.join(" and ");
 }
-/**
- * Restore a root-marked export into the target user's own root document
- * (#3135).
- *
+/** 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, or
+ * null when there is nothing a re-run may write.
+ *
+ * A 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. 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, aliasOwner) {
+    let state = false;
+    const exported = exportedBlobsOf(docDir);
+    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 || blobs.length > 0 || aliases.length > 0
+        ? { state, 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): its state is merged into the target user's 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,
  * the blobs, the user-scoped aliases — is written against the target user's
@@ -2890,12 +2390,15 @@ 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 ?? "",
@@ -2913,31 +2416,54 @@ 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 root an earlier run
+        // started and did not finish is completed, by the same rule as any
+        // 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.
+        progress.exists = true;
+        const found = await findImportGaps(client, appId, docDir, targetRootDocId, {
+            userId: plan.targetUserId,
+            aliasMode,
+            exported: metadata.aliases,
+        });
+        if (!found) {
+            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;
     }
     if (dryRun) {
-        if (plan.action === "create") {
+        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(`[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 ` +
-                `${plan.owner}'s root document ${plan.targetRootDocId}`);
+            info(`[dry-run] Would apply root document export ${exportedDocumentId} ` +
+                `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,94 +2477,918 @@ 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`;
             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"));
-    }
-    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++;
-        }
+    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);
+    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);
+        report("created", targetRootDocId, undefined, plan.targetFormat);
         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}`);
+        report("applied", targetRootDocId, undefined, plan.targetFormat);
+        info(`Applied root document export ${exportedDocumentId} to ` +
+            `${plan.owner}'s root document ${targetRootDocId}`);
+    }
+}
+/** The aggregate operations `records aggregate` takes. */
+const AGGREGATE_OPS = ["count", "sum", "avg", "min", "max"];
+// ---- The records, schema and inspect verbs' bodies (#4696) ----
+// Shared by the `documents` verbs and their `db3` twins (`./db3.ts`): each
+// sends its request through `routes` and prints the answer, so both nouns
+// print the same thing for the same answer. The caller has resolved the app
+// (where the body does not) and read its own flags, `--document-format`
+// included.
+/** `records query`: one page of a model's records, as a table or `--json`. */
+export async function queryRecordsAction(routes, resolvedAppId, documentId, modelName, options, documentFormat) {
+    const filter = parseFilterOptions(options);
+    // The JSON is checked here; its shape (`{ field: 1 | -1 }`) is the
+    // route's to refuse, with its own `Invalid sort` message.
+    let sort;
+    if (options.sort !== undefined) {
+        try {
+            sort = JSON.parse(options.sort);
+        }
+        catch {
+            error("Invalid --sort JSON.");
+            process.exit(1);
+        }
+    }
+    // The same for `--include`: its specs are the route's to refuse.
+    let include;
+    if (options.include !== undefined) {
+        try {
+            include = JSON.parse(options.include);
+        }
+        catch {
+            error("Invalid --include JSON.");
+            process.exit(1);
+        }
+    }
+    const client = new ApiClient();
+    try {
+        const result = await routes.query(client, resolvedAppId, documentId, modelName, { filter, sort, limit: options.limit, cursor: options.cursor, documentFormat, include });
+        if (options.json) {
+            json(result);
+            return;
+        }
+        const items = result.items;
+        if (items.length === 0) {
+            info("No records found.");
+            return;
+        }
+        const allKeys = new Set();
+        for (const rec of items) {
+            for (const key of Object.keys(rec))
+                allKeys.add(key);
+        }
+        const orderedKeys = [];
+        if (allKeys.has("id")) {
+            orderedKeys.push("id");
+            allKeys.delete("id");
+        }
+        orderedKeys.push(...[...allKeys].sort());
+        const columns = orderedKeys.map((key) => ({
+            header: key.toUpperCase(),
+            key,
+            format: (v) => {
+                if (v === null || v === undefined)
+                    return "—";
+                if (typeof v === "object")
+                    return JSON.stringify(v);
+                return String(v);
+            },
+        }));
+        console.log(formatTable(items, columns));
+        if (result.nextCursor) {
+            // A cursor continues only the sort that minted it.
+            const sortArg = sort !== undefined ? ` --sort ${quoteCursorArg(JSON.stringify(sort))}` : "";
+            info(`More results available. Use --cursor ${result.nextCursor}${sortArg}`);
+        }
+    }
+    catch (err) {
+        // #3764 — the server's sentence, the stable code and the status, so a
+        // refused records call is scriptable rather than only readable.
+        error(describeRecordsFailure(err));
+        process.exit(1);
+    }
+}
+/** `records count`: how many of a model's records match the filter. */
+export async function countRecordsAction(routes, resolvedAppId, documentId, modelName, options, documentFormat) {
+    const filter = parseFilterOptions(options);
+    const client = new ApiClient();
+    try {
+        const result = await routes.count(client, resolvedAppId, documentId, modelName, { filter, documentFormat });
+        if (options.json) {
+            json(result);
+            return;
+        }
+        console.log(`  ${result.count}`);
+    }
+    catch (err) {
+        // #3764 — the server's sentence, the stable code and the status, so a
+        // refused records call is scriptable rather than only readable.
+        error(describeRecordsFailure(err));
+        process.exit(1);
+    }
+}
+/** `records aggregate`: one operation over a model's records, optionally grouped. */
+export async function aggregateRecordsAction(routes, resolvedAppId, documentId, modelName, options, documentFormat) {
+    if (!AGGREGATE_OPS.includes(options.op)) {
+        error(`Invalid --op "${options.op}". Expected one of: ${AGGREGATE_OPS.join(", ")}.`);
+        process.exit(1);
+    }
+    const operation = { type: options.op };
+    if (options.op === "count") {
+        if (options.field) {
+            error("--field is not valid for --op count.");
+            process.exit(1);
+        }
+    }
+    else {
+        if (!options.field) {
+            error(`--op ${options.op} requires --field.`);
+            process.exit(1);
+        }
+        operation.field = options.field;
+    }
+    const filter = parseFilterOptions(options);
+    const groupBy = options.groupBy || [];
+    const client = new ApiClient();
+    try {
+        const response = await routes.aggregate(client, resolvedAppId, documentId, modelName, { operations: [operation], groupBy, filter }, { documentFormat });
+        if (options.json) {
+            json(response);
+            return;
+        }
+        // The route answers rows (#4265): one key/value line when
+        // ungrouped, a table with one column per group key when grouped.
+        const rendered = renderAggregateResult(response?.result, {
+            groupBy,
+            op: options.op,
+            field: options.field,
+        });
+        if (rendered.kind === "scalar") {
+            keyValue(rendered.label, rendered.value);
+        }
+        else {
+            console.log(rendered.text);
+        }
+    }
+    catch (err) {
+        // #3764 — the server's sentence, the stable code and the status, so a
+        // refused records call is scriptable rather than only readable.
+        error(describeRecordsFailure(err));
+        process.exit(1);
+    }
+}
+/** `records save`: create or replace a record with the parsed `data`. */
+export async function saveRecordAction(routes, resolvedAppId, documentId, modelName, data, options, documentFormat) {
+    const recordId = options.id || ulid();
+    const writeOptions = options.upsertOn ? { upsertOn: options.upsertOn } : undefined;
+    const client = new ApiClient();
+    try {
+        const result = await routes.save(client, resolvedAppId, documentId, modelName, { id: recordId, data, ...(writeOptions ? { options: writeOptions } : {}) }, { documentFormat });
+        if (options.json) {
+            json(result);
+            return;
+        }
+        success(`Record saved: ${result.record?.id ?? recordId}`);
+    }
+    catch (err) {
+        // #3764 — the server's sentence, the stable code and the status, so a
+        // refused records call is scriptable rather than only readable.
+        error(describeRecordsFailure(err));
+        process.exit(1);
+    }
+}
+/** `records patch`: merge the parsed `data` into a record. */
+export async function patchRecordAction(routes, resolvedAppId, documentId, modelName, recordId, data, options, documentFormat) {
+    const client = new ApiClient();
+    try {
+        const result = await routes.patch(client, resolvedAppId, documentId, modelName, recordId, { data }, { documentFormat });
+        if (options.json) {
+            json(result);
+            return;
+        }
+        success(`Record patched: ${recordId}`);
+    }
+    catch (err) {
+        // #3764 — the server's sentence, the stable code and the status, so a
+        // refused records call is scriptable rather than only readable.
+        error(describeRecordsFailure(err));
+        process.exit(1);
+    }
+}
+/** `records delete`: delete a record, confirming first unless `--yes`. */
+export async function deleteRecordAction(routes, resolvedAppId, documentId, modelName, recordId, options, documentFormat) {
+    if (!options.yes) {
+        const confirmed = await confirmPrompt(`Delete record ${recordId} from ${modelName} in ${routes.noun} ${documentId}?`);
+        if (!confirmed) {
+            info("Cancelled.");
+            return;
+        }
+    }
+    const client = new ApiClient();
+    try {
+        const result = await routes.delete(client, resolvedAppId, documentId, modelName, recordId, { documentFormat });
+        if (options.json) {
+            json(result);
+            return;
+        }
+        // A delete of a missing record is a silent no-op server-side, so
+        // this reports the request outcome, not record existence.
+        success(`Record deleted: ${recordId}`);
+    }
+    catch (err) {
+        // #3764 — the server's sentence, the stable code and the status, so a
+        // refused records call is scriptable rather than only readable.
+        error(describeRecordsFailure(err));
+        process.exit(1);
+    }
+}
+/** `records bulk`: apply an operations blob atomically, confirming first unless `--yes`. */
+export async function bulkRecordsAction(routes, documentId, options, documentFormat) {
+    const parsed = parseDataOption(options, "operations blob", {
+        allowArray: true,
+    });
+    const operations = Array.isArray(parsed) ? parsed : parsed?.operations;
+    if (!Array.isArray(operations) || operations.length === 0) {
+        error("--data-file must contain { operations: [...] } or a non-empty operations array.");
+        process.exit(1);
+    }
+    const resolvedAppId = resolveAppId(undefined, options);
+    if (!options.yes) {
+        const confirmed = await confirmPrompt(`Apply ${operations.length} operation(s) atomically to ${routes.noun} ${documentId}?`);
+        if (!confirmed) {
+            info("Cancelled.");
+            return;
+        }
+    }
+    const client = new ApiClient();
+    try {
+        const result = await routes.bulk(client, resolvedAppId, documentId, operations, { documentFormat });
+        if (options.json) {
+            json(result);
+            return;
+        }
+        success(describeBulkResult(result));
+    }
+    catch (err) {
+        const report = describeBulkFailure(err);
+        if (options.json)
+            json(report.envelope);
+        else
+            error(report.line);
+        process.exit(1);
+    }
+}
+/** `schema`: the models and fields as declared and observed, a table, the JSON or a schema.toml. */
+/** `records models` (shared with `db3 records models`, #4804): the model names the schema route answers. */
+export async function modelsAction(routes, documentId, options) {
+    const resolvedAppId = resolveAppId(undefined, options);
+    const client = new ApiClient();
+    try {
+        const result = await routes.schema(client, resolvedAppId, documentId);
+        const models = result?.modelNames ?? Object.keys(result?.schema?.models ?? {});
+        if (options.json) {
+            json(models);
+            return;
+        }
+        if (models.length === 0) {
+            info("No models found.");
+            return;
+        }
+        for (const m of models) {
+            console.log(`  ${m}`);
+        }
+    }
+    catch (err) {
+        // #3764 — the server's sentence, the stable code and the status, so a
+        // refused records call is scriptable rather than only readable.
+        error(describeRecordsFailure(err));
+        process.exit(1);
+    }
+}
+/** `records describe` (shared with `db3 records describe`, #4804): one model's fields and indexes. */
+export async function describeAction(routes, documentId, modelName, options) {
+    const resolvedAppId = resolveAppId(undefined, options);
+    const client = new ApiClient();
+    try {
+        const result = await routes.schema(client, resolvedAppId, documentId);
+        const model = result?.schema?.models?.[modelName];
+        if (!model) {
+            if (options.json) {
+                json(null);
+                return;
+            }
+            info(`Model '${modelName}' not found in this ${routes.noun}.`);
+            return;
+        }
+        const fieldsObj = model.fields ?? {};
+        const rows = Object.entries(fieldsObj).map(([name, meta]) => ({
+            field: name,
+            type: meta?.type ?? "unknown",
+            indexed: meta?.indexed ? "yes" : "",
+            unique: meta?.unique ? "yes" : "",
+            required: meta?.required ? "yes" : "",
+        }));
+        if (options.json) {
+            json({ fields: fieldsObj, constraints: model.constraints ?? {} });
+            return;
+        }
+        if (rows.length === 0) {
+            info("No fields detected for this model.");
+            return;
+        }
+        console.log(formatTable(rows, [
+            { header: "FIELD", key: "field", flex: true },
+            { header: "TYPE", key: "type" },
+            { header: "INDEXED", key: "indexed" },
+            { header: "UNIQUE", key: "unique" },
+            { header: "REQUIRED", key: "required" },
+        ]));
+    }
+    catch (err) {
+        // #3764 — the server's sentence, the stable code and the status, so a
+        // refused records call is scriptable rather than only readable.
+        error(describeRecordsFailure(err));
+        process.exit(1);
+    }
+}
+/** `stats` (shared with `db3 stats`, #4804): record, model and blob counts and the size. */
+export async function statsAction(routes, documentId, options) {
+    const resolvedAppId = resolveAppId(undefined, options);
+    const client = new ApiClient();
+    try {
+        const result = await routes.stats(client, resolvedAppId, documentId);
+        if (options.json) {
+            json(result);
+            return;
+        }
+        keyValue(routes.noun === "db3" ? "db3 ID" : "Document ID", result.documentId);
+        keyValue("Records", result.recordCount);
+        keyValue("Models", result.modelCount);
+        keyValue("Blobs", result.blobCount);
+        // 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) {
+        error(describeDocumentFailure(err));
+        process.exit(1);
+    }
+}
+export async function schemaAction(routes, documentId, options) {
+    if (options.output && !options.toml) {
+        error("--output writes the TOML: pass --toml with it.");
+        process.exit(1);
+    }
+    const resolvedAppId = resolveAppId(undefined, options);
+    const client = new ApiClient();
+    try {
+        const answer = await routes.schema(client, resolvedAppId, documentId);
+        if (options.json) {
+            json(answer);
+            return;
+        }
+        if (options.toml) {
+            // Each field, constraint or model the export leaves out is one warn line.
+            const toml = recordLogSchemaToToml(answer, { warn: (line) => warn(line) });
+            if (options.output) {
+                fs.writeFileSync(options.output, toml);
+                success(`Wrote ${options.output}.`);
+                return;
+            }
+            process.stdout.write(toml);
+            return;
+        }
+        const rows = documentSchemaRows(answer);
+        if (rows.length === 0) {
+            info("No models found.");
+            return;
+        }
+        console.log(formatTable(rows, [
+            { key: "model", header: "Model" },
+            { key: "field", header: "Field" },
+            { key: "type", header: "Type" },
+            { key: "kinds", header: "Kinds" },
+            { key: "counts", header: "Counts" },
+            { key: "hint", header: "Hint" },
+        ]));
+    }
+    catch (err) {
+        error(describeRecordsFailure(err));
+        process.exit(1);
+    }
+}
+/** `inspect`: the room's state, or every row a bulk load refused. */
+export async function inspectAction(routes, documentId, options) {
+    const resolvedAppId = resolveAppId(undefined, options);
+    const client = new ApiClient();
+    try {
+        if (options.refused !== undefined) {
+            // Every page, in order: the room keeps each refused row with its code.
+            const items = [];
+            let cursor;
+            do {
+                const page = await routes.room(client, resolvedAppId, documentId, {
+                    refused: options.refused,
+                    limit: Number(options.limit),
+                    cursor,
+                });
+                items.push(...page.refused.items);
+                cursor = page.refused.hasMore ? page.refused.nextCursor : undefined;
+            } while (cursor);
+            if (options.json) {
+                json({ documentId, sessionId: options.refused, items });
+                return;
+            }
+            keyValue("Document ID", documentId);
+            keyValue("Session", options.refused);
+            keyValue("Refused rows", items.length);
+            for (const row of items)
+                keyValue(...refusedRowLine(row));
+            return;
+        }
+        const result = await routes.room(client, resolvedAppId, documentId);
+        if (options.json) {
+            json(result);
+            return;
+        }
+        keyValue("Document ID", result.documentId);
+        printDocumentFormat(result);
+        const room = result.room;
+        if (!room) {
+            keyValue("Room", `no record room (format ${result.documentFormat ?? 1})`);
+            return;
+        }
+        keyValue("Log number", room.lsn);
+        keyValue("Epochs", `current ${room.epochs.current}, next ${room.epochs.next}, high ${room.epochs.high}`);
+        keyValue("Epoch floor", room.epochs.floor);
+        keyValue("Cursor floor", room.cursorFloor);
+        keyValue("Entries since rotation", room.epochs.entriesSinceRotation);
+        keyValue("Rotated", room.epochs.rotatedAt ? formatDate(room.epochs.rotatedAt) : "—");
+        keyValue("Writers", `${room.writers.count} (${room.writers.connected} connected)`);
+        keyValue("Subscribers", room.subscribers);
+        keyValue("Held entries", room.held.entries);
+        const load = room.load;
+        keyValue("Load", load
+            ? `${load.sessionId} ${load.state} (${load.mode}, epoch reserved at ${load.reserveEpoch}` +
+                (load.epoch !== null ? `: epoch ${load.epoch} from log number ${load.k}` : "") +
+                `), ${load.chunksApplied}/${load.chunks} chunks, ${load.rowsApplied} rows applied, ` +
+                `${load.refusedRows} refused, ${load.touched} keys touched`
+            : "none");
+        const loads = Array.isArray(room.loads) ? room.loads : [];
+        keyValue("Loads", loads.length
+            ? loads
+                .map((l) => `${l.sessionId} (${l.mode}, log numbers ${l.firstLsn ?? "—"}–${l.lastLsn ?? "—"}, ${l.rows} rows, ${l.touched} keys touched)`)
+                .join("; ")
+            : "none kept");
+        const segmentLine = (s) => `${s.segmentId} ${s.state} (log number ${s.lsn}` +
+            (s.completedLsn !== null && s.completedLsn !== undefined ? `, completed at ${s.completedLsn}` : "") +
+            `, ${s.rows} rows, ${s.chunks} chunks)`;
+        keyValue("Segment", room.segment ? segmentLine(room.segment) : "none");
+        keyValue("Segment export", room.segmentExport ? segmentLine(room.segmentExport) : "none");
+        keyValue("Last checkpoint", room.checkpoint
+            ? `${formatDate(room.checkpoint.at)} (${room.checkpoint.durationMs} ms, ` +
+                `${room.checkpoint.pruned} pruned, ${room.checkpoint.dropped} dropped, ` +
+                `${room.checkpoint.writersDropped} writers dropped)`
+            : "none yet");
+        keyValue("Next alarm", room.nextAlarmAt ? formatDate(room.nextAlarmAt) : "—");
+        keyValue("Storage (bytes)", room.storage?.databaseSize ?? "—");
+    }
+    catch (err) {
+        error(describeDocumentFailure(err));
+        process.exit(1);
     }
 }
 /**
- * Wire the audit to the app API (#3433, criterion 10).
- *
- * Two permissions, not one (3433-C08): the chain export takes the app-admin
- * arm, and the schema and records reads it is compared against take the
- * console arm or a read grant on the document — the documents surface grants
- * no app-role bypass on a read (#3279, D3279-002). The schema is read first,
- * so a caller holding only the first is refused before anything is exported.
+ * `documents ingest` and `db3 ingest` (#4889): load a directory into a
+ * document or a db3 through `routes`, confirming unless `-y`, then exit with
+ * the load's code.
  */
-async function auditDocumentChain(client, appId, documentId, retries) {
-    // One page's worth of records is the audit's whole working set on the
-    // server side; everything else lives in the local store.
-    const AUDIT_PAGE_SIZE = 200;
-    const fingerprint = await createChainFingerprintReader();
-    // Nothing the server answers is carried from one attempt to the next: the
-    // attempt a moved document discards is exactly the one whose schema has
-    // changed under it (3433-C09).
-    const source = createAuditApiSource(client, {
-        appId,
-        documentId,
-        pageSize: AUDIT_PAGE_SIZE,
-    });
-    return await auditSnapshotChain(source, {
-        store: () => createAuditLocalStore(documentId),
-        fingerprint,
-        retries,
-        pageSize: AUDIT_PAGE_SIZE,
-    });
+export async function ingestAction(routes, documentId, options) {
+    const resolvedAppId = resolveAppId(undefined, options);
+    const client = new ApiClient();
+    let plan = null;
+    // The exit code is carried out of here rather than taken inside: a
+    // `process.exit` does not unwind, so ending the process in the try block
+    // would skip the cleanup in the finally and leave the compressed
+    // artifact — up to the whole input, gzipped — in the OS temp directory
+    // on every run, successful or not (finding 3435-FROZEN-05).
+    const run = async () => {
+        // A flag's value is checked before any request.
+        const flags = parseIngestFlags({ reserveEpoch: options.reserveEpoch, mode: options.mode });
+        // The preflight, in this order and before a byte is read from disk:
+        // the schema read says whether this caller may see the document's
+        // declarations at all and hands over the ones the lines are checked
+        // against, and the session reader says whether this is a large
+        // document. Both are READS on the arm the ingest routes admit, so a
+        // caller who would be refused halfway is refused at once, and neither
+        // opens a session.
+        const introspection = await routes.schema(client, resolvedAppId, documentId);
+        await routes.listIngests(client, resolvedAppId, documentId, { limit: 1 });
+        const schema = ingestSchemaFromIntrospection(introspection);
+        // A record-log (format 3) document takes models and fields it does
+        // not declare, as its writes do (#4310); its schema read says so.
+        const recordLog = Number(introspection?.documentFormat) === 3;
+        const input = discoverIngestInput(options.input, documentId);
+        for (const ignored of input.ignored) {
+            info(`Ignoring ${ignored}: a bulk load reads the snapshot only.`);
+        }
+        const body = ingestCreateBody(flags, input.sources.map((source) => source.model));
+        // #3598 — reading, checking, sorting, cutting and gzipping is this
+        // side's biggest phase on a large input, and it used to be invisible
+        // inside one wall-clock number that also covered the platform's work.
+        const buildStartedAt = Date.now();
+        plan = await buildIngestArtifact({ input, schema, open: recordLog });
+        const buildMs = Date.now() - buildStartedAt;
+        info(`Built artifact in ${(buildMs / 1000).toFixed(1)}s.`);
+        for (const line of summariseIngestPlan(plan))
+            info(line);
+        // A format-2 export's row that cannot be one record (#4638): left
+        // out, and named, before anything is uploaded.
+        for (const row of plan.refused) {
+            warn(`Refused before upload: ${row.where}: ${row.reason}`);
+        }
+        assertIngestRefreshKeepsRefused(flags, plan.refused);
+        assertIngestConfirmable({
+            yes: Boolean(options.yes),
+            isTTY: Boolean(process.stdin.isTTY),
+        });
+        if (!options.yes) {
+            const confirmed = await confirmPrompt(`Bulk-load ${plan.rows} records into ${documentId}? ` +
+                `This replaces records in a live ${routes.noun} and cannot be undone.`);
+            if (!confirmed) {
+                info("Nothing was uploaded.");
+                return 1;
+            }
+        }
+        // Ctrl-C is a decision the driver makes differently depending on
+        // where it lands, so it is handed the signal rather than killing the
+        // process: mid-upload the session is aborted, mid-poll it is left
+        // running, because by then the document is already being changed.
+        const interrupt = new AbortController();
+        const onSignal = () => interrupt.abort();
+        process.on("SIGINT", onSignal);
+        let outcome;
+        try {
+            outcome = await driveDocumentIngest({
+                client: {
+                    createIngest: (id) => routes.createIngest(client, resolvedAppId, id, body),
+                    uploadIngestChunk: (id, sessionId, chunk) => routes.uploadIngestChunk(client, resolvedAppId, id, sessionId, chunk),
+                    commitIngest: (id, sessionId) => routes.commitIngest(client, resolvedAppId, id, sessionId),
+                    abortIngest: (id, sessionId) => routes.abortIngest(client, resolvedAppId, id, sessionId),
+                    getIngest: (id, sessionId) => routes.getIngest(client, resolvedAppId, id, sessionId),
+                },
+                documentId,
+                plan,
+                wait: options.wait !== false,
+                timeoutMs: options.timeout ? Number(options.timeout) * 1000 : null,
+                signal: interrupt.signal,
+                onProgress: (line) => info(line),
+            });
+        }
+        finally {
+            process.off("SIGINT", onSignal);
+        }
+        if (outcome.message)
+            error(outcome.message);
+        // #3598 — the two sides, side by side. The session's own `timings`
+        // say where the platform's share went; `client` says what this
+        // process spent before and around it, so a slow load can be blamed on
+        // the side that was actually slow.
+        const clientTimings = { buildMs, ...outcome.timings };
+        if (options.json) {
+            json({
+                ...(outcome.session ?? { sessionId: outcome.sessionId }),
+                client: clientTimings,
+                refusedBeforeUpload: plan.refused,
+            });
+        }
+        else {
+            if (outcome.session) {
+                printIngestSession(outcome.session);
+            }
+            else if (outcome.sessionId) {
+                printResult("Session", outcome.sessionId);
+            }
+            for (const [label, value] of ingestClientRows(clientTimings)) {
+                printResult(label, value);
+            }
+        }
+        return outcome.exitCode;
+    };
+    let code = 1;
+    try {
+        code = await run();
+    }
+    catch (err) {
+        error(describeDocumentFailure(err));
+        code = 1;
+    }
+    finally {
+        await plan?.cleanup().catch(() => undefined);
+    }
+    // The result has to reach the pipe before the process ends: stdout to a
+    // pipe is asynchronous and `process.exit` does not wait for it.
+    await flushOutput();
+    process.exit(code);
+}
+/** `documents ingests list` and `db3 ingests list` (#4889). */
+export async function listIngestsAction(routes, documentId, options) {
+    const limit = parsePageLimit(options.limit);
+    const resolvedAppId = resolveAppId(undefined, options);
+    const client = new ApiClient();
+    try {
+        const page = normalizeCliListEnvelope(await routes.listIngests(client, resolvedAppId, documentId, {
+            limit,
+            ...(options.cursor ? { cursor: options.cursor } : {}),
+        }));
+        if (options.json) {
+            json(page);
+            return;
+        }
+        if (page.items.length === 0) {
+            info("No ingest sessions yet.");
+            return;
+        }
+        console.log(formatTable(page.items, [
+            { header: "SESSION", key: "sessionId" },
+            { header: "STATE", key: "state" },
+            { header: "CREATED", key: "createdAt", format: formatDate },
+            { header: "CHUNKS", key: "chunks" },
+            { header: "ROWS", key: "rows" },
+            {
+                header: "COMPLETED",
+                key: "completedAt",
+                format: (at) => (at ? formatDate(at) : "—"),
+            },
+        ]));
+        if (page.hasMore && page.nextCursor) {
+            info(`More sessions: --cursor ${page.nextCursor}`);
+        }
+    }
+    catch (err) {
+        error(describeDocumentFailure(err));
+        process.exit(1);
+    }
+}
+/** `documents ingests get` and `db3 ingests get` (#4889). */
+export async function getIngestAction(routes, documentId, sessionId, options) {
+    const resolvedAppId = resolveAppId(undefined, options);
+    const client = new ApiClient();
+    try {
+        const session = await routes.getIngest(client, resolvedAppId, documentId, sessionId);
+        if (options.json) {
+            json(session);
+            return;
+        }
+        printIngestSession(session);
+    }
+    catch (err) {
+        error(describeDocumentFailure(err));
+        process.exit(1);
+    }
+}
+/** `documents ingests abort` and `db3 ingests abort` (#4889). */
+export async function abortIngestAction(routes, documentId, sessionId, options) {
+    const resolvedAppId = resolveAppId(undefined, options);
+    if (!options.yes) {
+        if (!process.stdin.isTTY) {
+            error("Aborting a bulk load discards what it uploaded. " +
+                "Re-run with -y to confirm it without a prompt.");
+            process.exit(1);
+        }
+        const confirmed = await confirmPrompt(`Abort bulk load ${sessionId} on ${documentId}? What it uploaded is ` +
+            "discarded; rows a committed load already applied stay.");
+        if (!confirmed) {
+            info("Cancelled.");
+            return;
+        }
+    }
+    const client = new ApiClient();
+    try {
+        const session = await routes.abortIngest(client, resolvedAppId, documentId, sessionId);
+        if (options.json) {
+            json(session);
+            return;
+        }
+        printIngestSession(session);
+    }
+    catch (err) {
+        error(describeDocumentFailure(err));
+        process.exit(1);
+    }
+}
+/** `documents snapshots list` and `db3 snapshots list` (#4889). */
+export async function listSnapshotsAction(routes, documentId, options) {
+    const limit = parsePageLimit(options.limit);
+    const resolvedAppId = resolveAppId(undefined, options);
+    const client = new ApiClient();
+    try {
+        const page = normalizeCliListEnvelope(await routes.listSnapshots(client, resolvedAppId, documentId, {
+            limit,
+            ...(options.cursor ? { cursor: options.cursor } : {}),
+        }));
+        if (options.json) {
+            json(page);
+            return;
+        }
+        if (page.items.length === 0) {
+            info("No snapshot builds yet.");
+            return;
+        }
+        // A record-log (format 3) document's are its segments (#4310).
+        if (page.items.some((item) => typeof item?.segmentId === "string")) {
+            console.log(formatTable(page.items, [
+                { header: "SEGMENT", key: "segmentId" },
+                { header: "LOG NUMBER", key: "lsn" },
+                { header: "COMPLETED AT LOG NUMBER", key: "completedLsn", format: (v) => (v === null || v === undefined ? "-" : String(v)) },
+                { header: "STATE", key: "state" },
+                { header: "ROWS", key: "rows" },
+                { header: "CHUNKS", key: "chunks" },
+                { header: "STARTED", key: "startedAt", format: formatDate },
+                { header: "COMPLETED", key: "completedAt", format: formatDate },
+            ]));
+            return;
+        }
+        console.log(formatTable(page.items, [
+            { header: "BUILD", key: "buildId" },
+            { header: "EPOCH", key: "epoch" },
+            { header: "STATE", key: "state" },
+            { header: "SOURCE", key: "source" },
+            {
+                header: "VERIFICATION",
+                key: "verification",
+                format: (verification) => verification
+                    ? verification.code
+                        ? `${verification.state} (${verification.code})`
+                        : verification.state
+                    : "-",
+            },
+            { header: "ROWS", key: "rows" },
+            { header: "CHUNKS", key: "chunks" },
+            { header: "STARTED", key: "startedAt", format: formatDate },
+            { header: "COMPLETED", key: "completedAt", format: formatDate },
+        ]));
+        if (page.hasMore && page.nextCursor) {
+            info(`More builds: --cursor ${page.nextCursor}`);
+        }
+    }
+    catch (err) {
+        error(describeDocumentFailure(err));
+        process.exit(1);
+    }
+}
+/** `documents snapshots get` and `db3 snapshots get` (#4889). */
+export async function getSnapshotAction(routes, documentId, buildId, options) {
+    const resolvedAppId = resolveAppId(undefined, options);
+    const client = new ApiClient();
+    try {
+        const build = await routes.getSnapshot(client, resolvedAppId, documentId, buildId);
+        if (options.json) {
+            json(build);
+            return;
+        }
+        // The rows are composed by a pure function (#3435), so what a
+        // terminal shows is checkable without spawning one; the command still
+        // owns the printing. A record-log document's build is a segment (#4310).
+        const rows = typeof build?.segmentId === "string" ? segmentRows(build) : snapshotBuildRows(build);
+        for (const [label, value] of rows) {
+            printResult(label, value);
+        }
+    }
+    catch (err) {
+        error(describeDocumentFailure(err));
+        process.exit(1);
+    }
+}
+/** `documents snapshots build` and `db3 snapshots build` (#4889). */
+export async function buildSnapshotAction(routes, documentId, options) {
+    const resolvedAppId = resolveAppId(undefined, options);
+    const client = new ApiClient();
+    const run = async () => {
+        // Ctrl-C while polling leaves the build running — by then the room is
+        // already building it and giving up on watching is not giving up on
+        // the build — so the signal is handed to the driver rather than
+        // killing the process.
+        const interrupt = new AbortController();
+        const onSignal = () => interrupt.abort();
+        process.on("SIGINT", onSignal);
+        let outcome;
+        try {
+            outcome = await driveSnapshotBuild({
+                client: {
+                    requestSnapshot: (id) => routes.requestSnapshot(client, resolvedAppId, id),
+                    getSnapshot: (id, buildId) => routes.getSnapshot(client, resolvedAppId, id, buildId),
+                },
+                documentId,
+                wait: Boolean(options.wait),
+                timeoutMs: options.timeout ? Number(options.timeout) * 1000 : null,
+                signal: interrupt.signal,
+                onProgress: (line) => info(line),
+            });
+        }
+        finally {
+            process.off("SIGINT", onSignal);
+        }
+        if (outcome.message)
+            error(outcome.message);
+        if (options.json) {
+            // The route's answer as received, with the build the wait settled
+            // on beside it when there was one — so a script branches on the
+            // verdict rather than on an exit code alone.
+            json(outcome.build ? { ...outcome.response, build: outcome.build } : outcome.response);
+            return outcome.exitCode;
+        }
+        if (typeof outcome.response?.segmentId === "string") {
+            // A record-log document's segment export (#4310).
+            if (outcome.build) {
+                for (const [label, value] of segmentRows(outcome.build))
+                    printResult(label, value);
+            }
+            else {
+                printResult("Segment", outcome.response.segmentId);
+                printResult("State", outcome.response.state);
+                printResult("Log number", outcome.response.lsn);
+            }
+            return outcome.exitCode;
+        }
+        printResult("Build", outcome.response?.buildId);
+        return outcome.exitCode;
+    };
+    let code = 1;
+    try {
+        code = await run();
+    }
+    catch (err) {
+        // The server's own sentence, plus the code a script branches on
+        // (#3403) — a refused loop that only says "too young to seal" leaves
+        // a caller parsing prose to tell it from a permission refusal.
+        error(err.code ? `${err.message} (${err.code})` : err.message);
+        const retryAfterMs = err.details?.retryAfterMs;
+        if (typeof retryAfterMs === "number") {
+            error(`Ask again in ${Math.ceil(retryAfterMs / 1000)}s.`);
+        }
+        code = 1;
+    }
+    // The result has to reach the pipe before the process ends: stdout to a
+    // pipe is asynchronous and `process.exit` does not wait for it.
+    await flushOutput();
+    process.exit(code);
 }
 //# sourceMappingURL=documents.js.map