primitive-admin 1.1.0-alpha.9 → 1.1.0

package/dist/src/commands/documents.js

@@ -1,22 +1,1633 @@
+import { snapshotBuildRows } from "../lib/snapshot-build-rows.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 { resolveAppId } from "../lib/config.js";
-import { success, error, info, formatTable, formatDate, json, } from "../lib/output.js";
+import { success, error, info, formatTable, formatId, formatDate, json, keyValue, result as printResult, warn, flushOutput, } from "../lib/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 { 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 { 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 { ulid } from "ulid";
+import * as fs from "fs";
+import * as path from "path";
+/**
+ * One bulk-load session as rows (#3434, #3435, #3598).
+ *
+ * Shared by `documents ingests get` and by `documents ingest`'s own terminal
+ * report, so an operator reads the same thing however they arrived at it. The
+ * rows themselves are decided in `document-ingest-rows`, where they can be
+ * checked without a live server holding a session in the right state.
+ */
+function printIngestSession(session) {
+    for (const [label, value] of ingestSessionRows(session)) {
+        printResult(label, value);
+    }
+}
+/**
+ * One refused records call, as one line for an operator (#3764).
+ *
+ * The same composition `describeBulkFailure` makes for the atomic blob, on the
+ * verbs that have no `--json` envelope to fill: the server's sentence, the
+ * stable code a script branches on, and the status. `statusCode` FIRST —
+ * `cli/src/lib/api-client.ts`'s `ApiError` is where the status lives, and a
+ * reader that asks for `status` alone prints nothing at all (#3597 paid for
+ * that once already).
+ */
+export function describeRecordsFailure(err) {
+    const message = (typeof err?.message === "string" && err.message) || String(err);
+    const code = typeof err?.code === "string" && err.code ? err.code : undefined;
+    const raw = err?.statusCode ?? err?.status;
+    const status = Number.isFinite(Number(raw)) ? Number(raw) : undefined;
+    return `${message}${code ? ` [${code}]` : ""}${status !== undefined ? ` (${status})` : ""}`;
+}
+/**
+ * Report a document's format (#2816) — but only when it is a large document.
+ *
+ * The format is chosen at creation and never migrated, so an operator has to
+ * be able to read it back: `--large` that the server ignored would otherwise
+ * hand back an ordinary-looking document. A legacy document says nothing at
+ * all, so its output is byte-for-byte what it has always been, however the
+ * stored row spells the format (absent, null or 1).
+ */
+function printDocumentFormat(doc) {
+    if (Number(doc?.documentFormat) === 2) {
+        keyValue("Format", "2 (large document)");
+    }
+}
+/**
+ * The `--document-format` an operator stated, or the refusal (#3764, E10).
+ *
+ * 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.
+ */
+export function parseDocumentFormatOption(value) {
+    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).`);
+}
+/** 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 " +
+    "with the platform's own answer is refused with DOCUMENT_FORMAT_MISMATCH " +
+    "rather than answered out of the wrong tables";
+/**
+ * What `documents records bulk` reports when the write is refused (#3619).
+ *
+ * The command used to catch every failure with `error(err.message)` while
+ * `ApiError` carried the code and the status on separate fields, so the stable
+ * code the server answers never reached the output and `--json` handled
+ * successes only. An operator driving a multi-hour load had to read human text
+ * to tell "ask again" from "somebody look at the log" (finding 3619-SO-04).
+ *
+ * The status is read from `statusCode` FIRST: that is where
+ * `cli/src/lib/api-client.ts`'s `ApiError` keeps it, and a reader that asks for
+ * `status` alone sees `undefined` on every error the client raises and prints
+ * nothing at all — #3597 paid for that once already. `status` is the fallback,
+ * for an error that came from somewhere else.
+ *
+ * Its own function so both surfaces are composed once and can be graded
+ * without spawning a process: the human line and the `--json` envelope must
+ * agree about which failure happened.
+ */
+export function describeBulkFailure(err) {
+    const message = (typeof err?.message === "string" && err.message) || String(err);
+    const code = typeof err?.code === "string" && err.code ? err.code : undefined;
+    const raw = err?.statusCode ?? err?.status;
+    const status = Number.isFinite(Number(raw)) ? Number(raw) : undefined;
+    return {
+        line: `${message}${code ? ` [${code}]` : ""}${status !== undefined ? ` (${status})` : ""}`,
+        envelope: {
+            ok: false,
+            ...(code ? { code } : {}),
+            ...(status !== undefined ? { status } : {}),
+            error: message,
+        },
+    };
+}
+/**
+ * A document's tags as a list, from whatever the wire handed back (#3644).
+ *
+ * `tags` is absent when the document has none — the server's presence rule,
+ * shared by the app API's list shape and the admin inventory — so every
+ * reader here has to cope with `undefined`. A stray non-array (an older
+ * server, a hand-edited fixture) is read as "no tags" rather than printed
+ * raw.
+ */
+function documentTagList(tags) {
+    return Array.isArray(tags)
+        ? tags.filter((tag) => typeof tag === "string" && tag !== "")
+        : [];
+}
+/**
+ * Tag text a terminal prints rather than obeys (#3644).
+ *
+ * A tag is app-user text. The write-side validator
+ * (`validateTag` in `src/app-api/controllers/documents-controller.ts`) trims
+ * it, caps it at 48 characters and refuses dynamo-bao's key separator, but
+ * every other byte survives — including the escape character. Printed raw
+ * into an operator's terminal, a 15-character tag such as
+ * `\x1b[2J\x1b[Hrestored` clears the screen and homes the cursor while
+ * the listing is being written, so a member with write access to one document
+ * could hide or falsify what `documents list` and `documents get` appear to
+ * report about the rest. The C0 range, DEL and the C1 range are therefore
+ * rendered as their `\uXXXX` source escapes: readable, one line and one cell
+ * per tag, and inert. Ordinary text — accents, CJK, emoji — is untouched.
+ */
+function escapeForTerminal(tag) {
+    return tag.replace(/[\x00-\x1f\x7f-\x9f]/g, (ch) => `\\u${ch.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+/**
+ * A document's tags as printable text, in the order the wire reported them.
+ *
+ * Only the plain-text surfaces come through here: `--json` on both commands
+ * returns the server's object untouched, so a migration diffing tags against
+ * what it wrote still reads the stored bytes.
+ */
+export function displayTags(tags) {
+    return documentTagList(tags).map(escapeForTerminal);
+}
+/** The tags cell of a documents table: comma-joined, or `-` when there are none. */
+export function formatTags(tags) {
+    const list = displayTags(tags);
+    return list.length > 0 ? list.join(", ") : "-";
+}
 export function registerDocumentsCommands(program) {
     const documents = program
         .command("documents")
         .description("Manage documents within an app")
         .addHelpText("after", `
 Examples:
+  $ primitive documents list --user-id <user-id>
+  $ primitive documents get <document-id>
+  $ primitive documents create "My Doc"
+  $ primitive documents create "My Doc" --owner user@example.com
+  $ primitive documents delete <document-id> -y
+  $ primitive documents permissions list <document-id>
+  $ primitive documents permissions grant <document-id> --user-id <user-id> --permission reader
+  $ primitive documents permissions revoke <document-id> <user-id>
+  $ 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 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}'
+  $ primitive documents records delete <document-id> <model-name> <record-id> -y
+  $ primitive documents records aggregate <document-id> <model-name> --op avg --field price
+  $ primitive documents records bulk <document-id> --data-file ops.json -y
+  $ primitive documents dump <document-id>
+  $ primitive documents stats <document-id>
   $ primitive documents transfer-owner <document-id> <new-owner-id>
   $ primitive documents group-permissions list <document-id>
 `);
+    // ---- List a user's documents ----
+    // No app-wide enumeration: `--user-id` is required (the admin token has no
+    // "self"). Reads the per-user permission partition via the admin endpoint.
+    documents
+        .command("list")
+        .description("List a user's documents")
+        .requiredOption("--user-id <id>", "User ID whose documents to list")
+        .option("--app <app-id>", "App ID")
+        .addOption(pageLimitOption())
+        .addOption(pageCursorOption())
+        .option("--json", "Output as JSON")
+        .action(async (options) => {
+        const limit = parsePageLimit(options.limit);
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const page = normalizeCliListEnvelope(await client.listAdminDocumentsPage(resolvedAppId, options.userId, {
+                limit,
+                cursor: options.cursor,
+            }));
+            const list = page.items;
+            if (options.json) {
+                json(page);
+                return;
+            }
+            if (list.length === 0) {
+                printEmptyPage(page, "documents");
+                return;
+            }
+            console.log(formatTable(list, [
+                { header: "DOCUMENT_ID", key: "documentId", format: formatId },
+                { header: "TITLE", key: "title", flex: true },
+                // #3644 — the tags the route now reports. An app migration that
+                // regenerates tags on import verifies them from here; a document
+                // with none shows `-` rather than an empty cell.
+                { header: "TAGS", key: "tags", format: formatTags },
+                { header: "PERMISSION", key: "permission" },
+                { header: "GRANTED", key: "grantedAt", format: formatDate },
+            ]));
+            printPageHint(page);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ---- Get a single document's metadata ----
+    documents
+        .command("get")
+        .description("Show a document's metadata and the caller's access to it")
+        .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 doc = await client.getDocument(resolvedAppId, documentId);
+            if (options.json) {
+                json(doc);
+                return;
+            }
+            keyValue("Document ID", doc.documentId);
+            keyValue("Title", doc.title);
+            keyValue("Created By", doc.createdBy);
+            keyValue("Created", formatDate(doc.createdAt));
+            keyValue("Modified", formatDate(doc.modifiedAt ?? doc.lastModified));
+            printDocumentFormat(doc);
+            // #3644 — tags, when the document has any. The endpoint has returned
+            // them since #3096 but only `--json` showed them, so a migration
+            // verifying restored tags had to parse JSON to see its own work.
+            // Printed only when present, by the same rule the response uses: an
+            // untagged document's output is unchanged, and escaped the same way
+            // the table's cell is so a crafted tag cannot drive the terminal.
+            const tags = displayTags(doc.tags);
+            if (tags.length > 0)
+                keyValue("Tags", tags.join(", "));
+            // `GET documents/:id` reports the caller's own access, not the
+            // document's grant/alias/collection inventory — printing counts for
+            // fields the endpoint never returns read as a definitive "0" for
+            // documents that demonstrably have them. Use
+            // `documents permissions list` for the grant list.
+            if (doc.permission)
+                keyValue("Your Permission", doc.permission);
+            if (doc.accessSource)
+                keyValue("Access Source", doc.accessSource);
+            if (doc.linkAccess)
+                keyValue("Link Access", doc.linkAccess);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ---- Create a document ----
+    // The same `POST /documents` every client uses (#2763). Who ends up owning
+    // the document is the server's call, decided from the token's identity —
+    // the help below states that matrix rather than the CLI guessing at a role.
+    documents
+        .command("create")
+        .description("Create a document")
+        .argument("<title>", "Document title")
+        .option("--app <app-id>", "App ID")
+        .option("--owner <userId-or-email>", "User ID or email to own the document (super-admin or assigned-console-admin tokens only)")
+        .option("--large", "Create a large document (format 2): base snapshots + epoch overlays, for documents that outgrow a single in-memory Y.Doc")
+        .option("--json", "Output as JSON")
+        .addHelpText("after", `
+Ownership:
+  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.
+  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
+  created; a user who is not in the app fails the command without creating a
+  document.
+`)
+        .action(async (title, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        let ownerUserId;
+        if (options.owner) {
+            try {
+                ownerUserId = await resolveOwnerUserId(client, resolvedAppId, options.owner);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
+        }
+        try {
+            const result = await client.createDocument(resolvedAppId, {
+                title,
+                ...(ownerUserId ? { createdBy: ownerUserId } : {}),
+                // Opt-in only: without --large nothing is sent, so the document is
+                // created in the legacy format exactly as before (#2816).
+                ...(options.large ? { documentFormat: 2 } : {}),
+            });
+            if (options.json) {
+                json(result);
+                return;
+            }
+            success("Document created.");
+            keyValue("Document ID", result.documentId);
+            keyValue("Title", result.title);
+            keyValue("Owner", result.createdBy);
+            // Read back from the RESPONSE, not from `--large`: what the server
+            // created is what the document will be for the rest of its life.
+            printDocumentFormat(result);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ---- Delete a document ----
+    // The runtime-resource delete verb (#2756): the server endpoint cascades
+    // through records, Yjs history, blobs, aliases and permissions, so an
+    // operator resetting an app's data no longer needs a one-off SDK script.
+    // Who may run it is the server's decision, so the help below states that
+    // model (#2763) rather than leaving it to be discovered from a 403.
+    documents
+        .command("delete")
+        .description("Delete a document and all its data (records, history, blobs, aliases, permissions)")
+        .argument("<document-id>", "Document ID")
+        .option("--app <app-id>", "App ID")
+        .option("-y, --yes", "Skip confirmation prompt")
+        .option("--json", "Output as JSON")
+        .addHelpText("after", `
+Permissions (enforced by the server, not the CLI):
+  The document's owner, the app owner, and super-admin or assigned-console-admin
+  tokens — which act with app-owner authority — delete directly.
+  Everyone else, including app-role admins, can delete only when a containing
+  collection's document.delete rule allows it: an app admin cannot delete a
+  standalone document (one in no collection) they do not own.
+  The app's root document cannot be deleted.
+`)
+        .action(async (documentId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        if (!options.yes) {
+            let confirm;
+            try {
+                confirm = await confirmPrompt(`Delete document ${documentId}? This permanently deletes its records, ` +
+                    `update history, blobs, aliases, and permissions. This cannot be undone.`);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
+            if (!confirm) {
+                info("Cancelled.");
+                return;
+            }
+        }
+        const client = new ApiClient();
+        try {
+            const result = await client.deleteDocument(resolvedAppId, documentId);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            success(`Document ${documentId} deleted.`);
+        }
+        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);
+            process.exit(1);
+        }
+    });
+    // ---- User-level permissions subcommand group ----
+    const permissions = documents
+        .command("permissions")
+        .description("Manage user-level permissions on a document");
+    // List user-level permissions
+    permissions
+        .command("list")
+        .description("List user-level permissions for a document")
+        .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.listDocumentPermissions(resolvedAppId, documentId);
+            const list = Array.isArray(result) ? result : result?.permissions ?? [];
+            if (options.json) {
+                json(wholeListEnvelope(list));
+                return;
+            }
+            if (list.length === 0) {
+                info("No permissions found.");
+                return;
+            }
+            console.log(formatTable(list, [
+                { header: "USER_ID", key: "userId", format: formatId },
+                { header: "EMAIL", key: "email", flex: true },
+                { header: "PERMISSION", key: "permission" },
+                { header: "GRANTED", key: "grantedAt", format: formatDate },
+            ]));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Grant (or update) a user-level permission
+    permissions
+        .command("grant")
+        .description("Grant or update a user's permission on a document")
+        .argument("<document-id>", "Document ID")
+        .option("--user-id <id>", "User ID to grant the permission to")
+        .option("--email <email>", "Email of the user to grant the permission to")
+        .requiredOption("--permission <permission>", "Permission level: reader or read-write")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (documentId, options) => {
+        if (!options.userId && !options.email) {
+            error("Either --user-id or --email is required.");
+            process.exit(1);
+        }
+        if (options.userId && options.email) {
+            error("Provide only one of --user-id or --email, not both.");
+            process.exit(1);
+        }
+        if (!["reader", "read-write"].includes(options.permission)) {
+            error("Invalid --permission. Must be 'reader' or 'read-write'.");
+            process.exit(1);
+        }
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const entry = options.userId
+                ? { userId: options.userId, permission: options.permission }
+                : { email: options.email, permission: options.permission };
+            const result = await client.grantDocumentPermission(resolvedAppId, documentId, [entry]);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            const target = options.userId ? options.userId : options.email;
+            success(`Permission '${options.permission}' granted to ${target}.`);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Revoke a user-level permission
+    permissions
+        .command("revoke")
+        .description("Revoke a user's permission on a document")
+        .argument("<document-id>", "Document ID")
+        .argument("[user-id]", "User ID to revoke (or use --email)")
+        .option("--email <email>", "Email of the user to revoke (alternative to <user-id>)")
+        .option("--app <app-id>", "App ID")
+        .option("-y, --yes", "Skip confirmation prompt")
+        .action(async (documentId, userId, options) => {
+        if (!userId && !options.email) {
+            error("Either a <user-id> argument or --email is required.");
+            process.exit(1);
+        }
+        if (userId && options.email) {
+            error("Provide only one of <user-id> or --email, not both.");
+            process.exit(1);
+        }
+        const target = userId ?? options.email;
+        const resolvedAppId = resolveAppId(undefined, options);
+        if (!options.yes) {
+            let confirm;
+            try {
+                confirm = await confirmPrompt(`Revoke permission for ${target} on document ${documentId}?`);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
+            if (!confirm) {
+                info("Cancelled.");
+                return;
+            }
+        }
+        const client = new ApiClient();
+        try {
+            await client.revokeDocumentPermission(resolvedAppId, documentId, {
+                userId,
+                email: options.email,
+            });
+            success(`Permission revoked for ${target}.`);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ---- Records introspection subcommand group ----
+    const records = documents
+        .command("records")
+        .description("Inspect a document's models and records");
+    // List model names
+    records
+        .command("models")
+        .description("List model names in a document")
+        .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.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);
+        }
+    });
+    // Describe a model's fields and indexes
+    records
+        .command("describe")
+        .description("Show a model's fields and indexes")
+        .argument("<document-id>", "Document ID")
+        .argument("<model-name>", "Model name")
+        .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);
+        }
+    });
+    // Query records in a document model
+    records
+        .command("query")
+        .description("Query records in a document model")
+        .argument("<document-id>", "Document ID")
+        .argument("<model-name>", "Model name to query")
+        .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(DOCUMENT_FORMAT_FLAG, DOCUMENT_FORMAT_HELP)
+        .option("--json", "Output as JSON")
+        .action(async (documentId, modelName, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        let documentFormat;
+        try {
+            documentFormat = parseDocumentFormatOption(options.documentFormat);
+        }
+        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);
+        }
+        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);
+        }
+    });
+    // Get a single record by id (mirrors `databases records get`, issue #2357).
+    records
+        .command("get")
+        .description("Get a single record by id from a document model")
+        .argument("<document-id>", "Document ID")
+        .argument("<model-name>", "Model name")
+        .argument("<record-id>", "Record ID")
+        .option("--app <app-id>", "App ID")
+        .option(DOCUMENT_FORMAT_FLAG, DOCUMENT_FORMAT_HELP)
+        .option("--json", "Output as JSON")
+        .action(async (documentId, modelName, recordId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        let documentFormat;
+        try {
+            documentFormat = parseDocumentFormatOption(options.documentFormat);
+        }
+        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);
+        }
+        const client = new ApiClient();
+        try {
+            // A single-record fetch is a query filtered by primary-key id (there is
+            // no dedicated get endpoint — reuse queryDocumentRecords, exactly as
+            // the `databases records get` twin reuses queryDatabaseRecords).
+            const result = await client.queryDocumentRecords(resolvedAppId, documentId, modelName, { filter: { id: recordId }, limit: 1, documentFormat });
+            const record = result.items[0];
+            if (options.json) {
+                json(record ?? null);
+                return;
+            }
+            if (!record) {
+                info(`No record found with id ${recordId} in ${modelName}.`);
+                return;
+            }
+            // `get` is a data command, so its fields go to stdout via `result()`
+            // — the #711 split (`result()` = the data the caller asked for,
+            // `keyValue()` = a post-action diagnostic summary). Issue #2437; the
+            // databases twin renders identically.
+            for (const [key, value] of Object.entries(record)) {
+                const rendered = value === null || value === undefined
+                    ? "—"
+                    : typeof value === "object"
+                        ? JSON.stringify(value)
+                        : String(value);
+                printResult(key, rendered);
+            }
+        }
+        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);
+        }
+    });
+    // Count records in a document model
+    records
+        .command("count")
+        .description("Count records in a document model")
+        .argument("<document-id>", "Document ID")
+        .argument("<model-name>", "Model name to count")
+        .option("--app <app-id>", "App ID")
+        .option("--filter <json>", "Filter as JSON (e.g. '{\"status\":\"open\"}')")
+        .option(DOCUMENT_FORMAT_FLAG, DOCUMENT_FORMAT_HELP)
+        .option("--filter-file <path>", "Read filter from a JSON or TOML file")
+        .option("--json", "Output as JSON")
+        .action(async (documentId, modelName, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        let documentFormat;
+        try {
+            documentFormat = parseDocumentFormatOption(options.documentFormat);
+        }
+        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);
+        }
+        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);
+        }
+    });
+    // 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)")
+        .argument("<document-id>", "Document ID")
+        .argument("<model-name>", "Model name")
+        .option("--app <app-id>", "App ID")
+        .requiredOption("--op <operation>", `Aggregate operation: ${AGGREGATE_OPS.join("|")}`)
+        .option("--field <field>", "Field to aggregate (required for sum/avg/min/max)")
+        .option("--group-by <field>", "Group results by this plain field (repeatable; StringSet fields are not supported)", (value, previous = []) => previous.concat(value), [])
+        .option("--filter <json>", "Filter as JSON")
+        .option("--filter-file <path>", "Read filter from a JSON or TOML file")
+        .option(DOCUMENT_FORMAT_FLAG, DOCUMENT_FORMAT_HELP)
+        .option("--json", "Output as JSON")
+        .action(async (documentId, modelName, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        let documentFormat;
+        try {
+            documentFormat = parseDocumentFormatOption(options.documentFormat);
+        }
+        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);
+        }
+        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);
+        }
+    });
+    // ---- Record writes (#1964 Phase 4) ----
+    // Server-side writes through the document facade: Yjs-first, CRDT-safe,
+    // broadcast to connected clients. Requires read-write or higher on the
+    // document (or an admin token). `--data` / `--data-file` are validated
+    // CLI-side before any request is sent.
+    // `--data`/`--data-file` parsing (including the object-shape check and the
+    // both-flags rule) is the shared `parseDataOption` helper, so these verbs
+    // behave and diagnose identically to `metadata` and `databases records`.
+    // Create or replace a record
+    records
+        .command("save")
+        .description("Create or replace a record in a document model")
+        .argument("<document-id>", "Document ID")
+        .argument("<model-name>", "Model name to write to")
+        .option("--app <app-id>", "App ID")
+        .option("--id <record-id>", "Record ID (a ULID is generated when omitted)")
+        .option("--data <json>", "Record fields as JSON (e.g. '{\"qty\":10}')")
+        .option("--data-file <file>", "Read record fields from a JSON file")
+        .option("--upsert-on <field>", "Update the record whose <field> matches instead of creating")
+        .option(DOCUMENT_FORMAT_FLAG, DOCUMENT_FORMAT_HELP)
+        .option("--json", "Output as JSON")
+        .action(async (documentId, modelName, options) => {
+        const data = parseDataOption(options, "record fields");
+        const resolvedAppId = resolveAppId(undefined, options);
+        let documentFormat;
+        try {
+            documentFormat = parseDocumentFormatOption(options.documentFormat);
+        }
+        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);
+        }
+        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);
+        }
+    });
+    // Merge fields into an existing record
+    records
+        .command("patch")
+        .description("Merge fields into an existing record in a document model")
+        .argument("<document-id>", "Document ID")
+        .argument("<model-name>", "Model name")
+        .argument("<record-id>", "Record ID to patch")
+        .option("--app <app-id>", "App ID")
+        .option("--data <json>", "Fields to merge as JSON (e.g. '{\"status\":\"closed\"}')")
+        .option(DOCUMENT_FORMAT_FLAG, DOCUMENT_FORMAT_HELP)
+        .option("--data-file <file>", "Read fields from a JSON file")
+        .option("--json", "Output as JSON")
+        .action(async (documentId, modelName, recordId, options) => {
+        const data = parseDataOption(options, "fields to merge");
+        const resolvedAppId = resolveAppId(undefined, options);
+        let documentFormat;
+        try {
+            documentFormat = parseDocumentFormatOption(options.documentFormat);
+        }
+        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);
+        }
+        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);
+        }
+    });
+    // Delete a record
+    records
+        .command("delete")
+        .description("Delete a record from a document model")
+        .argument("<document-id>", "Document ID")
+        .argument("<model-name>", "Model name")
+        .argument("<record-id>", "Record ID to delete")
+        .option("--app <app-id>", "App ID")
+        .option(DOCUMENT_FORMAT_FLAG, DOCUMENT_FORMAT_HELP)
+        .option("-y, --yes", "Skip confirmation prompt")
+        .option("--json", "Output as JSON")
+        .action(async (documentId, modelName, recordId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        let documentFormat;
+        try {
+            documentFormat = parseDocumentFormatOption(options.documentFormat);
+        }
+        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);
+        }
+        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);
+        }
+    });
+    // Apply an atomic multi-model operations blob
+    records
+        .command("bulk")
+        .description("Apply an atomic create/patch/delete 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")
+        .option("--app <app-id>", "App ID")
+        .option(DOCUMENT_FORMAT_FLAG, DOCUMENT_FORMAT_HELP)
+        .option("-y, --yes", "Skip confirmation prompt")
+        .option("--json", "Output as JSON")
+        .action(async (documentId, options) => {
+        let documentFormat;
+        try {
+            documentFormat = parseDocumentFormatOption(options.documentFormat);
+        }
+        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);
+        }
+        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);
+        }
+    });
+    // Dump a document's records grouped by model (CLI-side composition)
+    documents
+        .command("dump")
+        .description("Dump a document's records grouped by model as JSON")
+        .argument("<document-id>", "Document ID")
+        .option("--app <app-id>", "App ID")
+        .option("--output <file>", "Write the JSON dump to a file instead of stdout")
+        .option("--json", "Output as JSON (default)")
+        .action(async (documentId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            // Model names come from the schema; records are assembled from paged
+            // reads per model (not a single atomic snapshot — the paged path is
+            // the contract, same pattern as `databases export`).
+            const schema = await client.getDocumentSchema(resolvedAppId, documentId);
+            const modelNames = schema?.modelNames ?? Object.keys(schema?.schema?.models ?? {});
+            const grouped = {};
+            for (const modelName of modelNames) {
+                const records = [];
+                let cursor;
+                do {
+                    const page = await client.queryDocumentRecords(resolvedAppId, documentId, modelName, { limit: 100, cursor });
+                    records.push(...page.items);
+                    cursor = page.nextCursor;
+                } while (cursor);
+                grouped[modelName] = records;
+            }
+            const output = JSON.stringify(grouped, null, 2);
+            if (options.output) {
+                fs.writeFileSync(options.output, output);
+                success(`Document dump written to ${options.output}`);
+                return;
+            }
+            console.log(output);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Document statistics (platform-vocabulary projection)
+    documents
+        .command("stats")
+        .description("Show a document's record/model/blob counts and approximate 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);
+        }
+    });
+    // The action verb (#3435, criterion 9): a directory of records becomes a
+    // chunked, digested, uploaded artifact and one atomic swap of the
+    // document's tables. `documents ingests list|get` below is how an operator
+    // watches one afterwards.
+    //
+    // Destructive by nature — a bulk load deletes and overwrites records in a
+    // live document with no undo — so it confirms unless `-y`, which is what
+    // `docs/cli-design.md` reserves the destructive default for.
+    documents
+        .command("ingest")
+        .description("Bulk-load records into a large document from a directory")
+        .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("-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);
+    });
+    // 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.
+    const ingests = documents
+        .command("ingests")
+        .description("Inspect a large document's bulk-load sessions");
+    ingests
+        .command("list")
+        .description("List a large document's bulk-load sessions, newest first")
+        .argument("<document-id>", "Document ID")
+        .option("--app <app-id>", "App ID")
+        .option("--limit <n>", "Page size (1–100)", "20")
+        .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);
+        }
+    });
+    ingests
+        .command("get")
+        .description("Show one bulk-load session, its progress and why it stopped")
+        .argument("<document-id>", "Document ID")
+        .argument("<session-id>", "Session ID")
+        .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);
+        }
+    });
+    // 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");
+    snapshots
+        .command("list")
+        .description("List a large document's snapshot builds, newest first")
+        .argument("<document-id>", "Document ID")
+        .option("--app <app-id>", "App ID")
+        .option("--limit <n>", "Page size (1–100)", "20")
+        .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);
+        }
+    });
+    snapshots
+        .command("get")
+        .description("Show one snapshot build, its verification result and where its time went")
+        .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);
+        }
+    });
+    // #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
+    // codes are `documents ingest`'s, as `docs/cli-design.md` records them, and
+    // for the same reason: giving up on WATCHING a build is not the build
+    // failing.
+    //
+    // Not destructive, so it does not confirm: a seal rotates the overlay the
+    // room is writing to and loses nothing, which is what the size trigger does
+    // on its own several times a day.
+    snapshots
+        .command("build")
+        .description("Snapshot a large document now: seal the open epoch and build a base")
+        .argument("<document-id>", "Document ID")
+        .option("--app <app-id>", "App ID")
+        .option("--wait", "Poll until the build has verified 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);
+    });
     // Transfer document ownership
     documents
         .command("transfer-owner")
         .description("Transfer document ownership to another user")
+        // Every positional is declared optional and the action decides which is
+        // which (#3645). A required positional AFTER an optional one makes the
+        // optional one mandatory: commander binds the first value it sees to
+        // `[app-id]` and then reports the required argument missing, so
+        // `transfer-owner <document-id> <new-owner-id>` never reached the action.
+        // What each slot actually requires is enforced below, where the shift is
+        // already known.
         .argument("[app-id]", "App ID (uses current app if not specified)")
-        .argument("<document-id>", "Document ID")
-        .argument("<new-owner-id>", "User ID of the new owner")
+        .argument("[document-id]", "Document ID (required)")
+        .argument("[new-owner-id]", "User ID of the new owner (required)")
         .option("--app <app-id>", "App ID")
         .option("-y, --yes", "Skip confirmation prompt")
         .option("--json", "Output as JSON")
@@ -43,15 +1654,14 @@ Examples:
             process.exit(1);
         }
         if (!options.yes) {
-            const inquirer = await import("inquirer");
-            const { confirm } = await inquirer.default.prompt([
-                {
-                    type: "confirm",
-                    name: "confirm",
-                    message: `Transfer ownership of document ${documentId} to user ${newOwnerId}? This cannot be undone.`,
-                    default: false,
-                },
-            ]);
+            let confirm;
+            try {
+                confirm = await confirmPrompt(`Transfer ownership of document ${documentId} to user ${newOwnerId}? This cannot be undone.`);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
             if (!confirm) {
                 info("Cancelled.");
                 return;
@@ -89,7 +1699,7 @@ Examples:
             const result = await client.listDocumentGroupPermissions(resolvedAppId, documentId);
             const list = Array.isArray(result) ? result : result?.permissions ?? [];
             if (options.json) {
-                json(list);
+                json(wholeListEnvelope(list));
                 return;
             }
             if (list.length === 0) {
@@ -138,6 +1748,381 @@ Examples:
             process.exit(1);
         }
     });
+    // ---- Effective access for a named user (#3658) ----
+    const access = documents
+        .command("access")
+        .description("Read a user's effective access to a document");
+    access
+        .command("get")
+        .description("Show what a user may do with a document, across direct, group, " +
+        "collection and link access")
+        .argument("<document-id>", "Document ID")
+        .requiredOption("--user <user-id>", "The user whose access to resolve")
+        .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.validateDocumentAccessForUser(resolvedAppId, documentId, options.user);
+            const row = {
+                documentId,
+                userId: options.user,
+                hasAccess: result?.hasAccess === true,
+                permission: result?.permission ?? null,
+                accessSource: result?.accessSource ?? null,
+                appRole: result?.appRole ?? null,
+            };
+            if (options.json) {
+                json(row);
+                return;
+            }
+            console.log(formatTable([row], [
+                { header: "DOCUMENT", key: "documentId" },
+                { header: "USER", key: "userId" },
+                { header: "ACCESS", key: "hasAccess" },
+                { header: "PERMISSION", key: "permission" },
+                { header: "SOURCE", key: "accessSource" },
+                { header: "APP_ROLE", key: "appRole" },
+            ]));
+            if (!row.hasAccess) {
+                // The role is not a grant: only the tag routes admit an
+                // administrator without one, so an operator reading "admin" here
+                // should not conclude the user may write content.
+                info("No document grant. An app role admits tag changes only, never a content write.");
+            }
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ---- Link access ("anyone with the link") ----
+    const linkAccess = documents
+        .command("link-access")
+        .description('Manage "anyone with the link" access on a document');
+    linkAccess
+        .command("get")
+        .description("Show the current link-access level for a document")
+        .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 state = await client.getDocumentLinkAccess(resolvedAppId, documentId);
+            const level = state?.linkAccess ?? null;
+            if (options.json) {
+                json({ documentId, linkAccess: level });
+                return;
+            }
+            if (!level) {
+                info("Link access is off for this document.");
+                return;
+            }
+            keyValue("Document", documentId);
+            keyValue("Link access", level);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    linkAccess
+        .command("set")
+        .description("Turn on link access at a given level")
+        .argument("<document-id>", "Document ID")
+        .requiredOption("--level <level>", "Link access level: reader or read-write")
+        .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.setDocumentLinkAccess(resolvedAppId, documentId, options.level);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            success(`Link access set to '${options.level}' for document ${documentId}.`);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    linkAccess
+        .command("clear")
+        .description("Turn off link access")
+        .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.clearDocumentLinkAccess(resolvedAppId, documentId);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            success(`Link access turned off for document ${documentId}.`);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ---- Export / Import commands ----
+    documents
+        .command("export")
+        .description("Export a document (Yjs state, blobs, permissions, aliases)")
+        // Optional in commander, required in the action (#3645) — see
+        // `transfer-owner` above for why a `<...>` here would make `[app-id]`
+        // mandatory.
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .argument("[document-id]", "Document ID to export (required)")
+        .option("--app <app-id>", "App ID")
+        .option("--output <dir>", "Output directory", "./primitive-export")
+        .option("--no-blobs", "Skip blob data")
+        .option("--json", "Output as JSON")
+        .action(async (first, second, options) => {
+        let resolvedAppId;
+        let documentId;
+        if (second && !second.startsWith("-")) {
+            resolvedAppId = resolveAppId(first, options);
+            documentId = second;
+        }
+        else {
+            resolvedAppId = resolveAppId(undefined, options);
+            documentId = first;
+        }
+        if (!documentId) {
+            error("Document ID is required.");
+            process.exit(1);
+        }
+        const client = new ApiClient();
+        try {
+            await exportSingleDocument(client, resolvedAppId, documentId, options.output, options.blobs !== false ? true : false, options.json);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    documents
+        .command("export-all")
+        .description("Export all documents for a user")
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .requiredOption("--user-id <id>", "User ID to export documents for")
+        .option("--app <app-id>", "App ID")
+        .option("--owned-only", "Only export documents owned by the user")
+        .option("--output <dir>", "Output directory", "./primitive-export")
+        .option("--no-blobs", "Skip blob data")
+        .option("--json", "Output as JSON")
+        .action(async (appIdArg, options) => {
+        const resolvedAppId = resolveAppId(appIdArg, options);
+        const client = new ApiClient();
+        const includeBlobs = options.blobs !== false;
+        try {
+            const documents = await client.listAdminDocuments(resolvedAppId, options.userId);
+            let docList = Array.isArray(documents) ? documents : [];
+            if (options.ownedOnly) {
+                docList = docList.filter((d) => d.permission === "owner");
+            }
+            if (docList.length === 0) {
+                info("No documents found.");
+                return;
+            }
+            info(`Exporting ${docList.length} document(s)...`);
+            const exportedIds = [];
+            for (const doc of docList) {
+                const docId = doc.documentId || doc.id;
+                try {
+                    await exportSingleDocument(client, resolvedAppId, docId, options.output, includeBlobs, false);
+                    exportedIds.push(docId);
+                }
+                catch (err) {
+                    warn(`Failed to export ${docId}: ${err.message}`);
+                }
+            }
+            // Write manifest. `export-all` is per-user, and each run REPLACES the
+            // manifest with its own ids — so exporting a second user into the same
+            // directory leaves the first user's documents on disk but unreachable
+            // through the manifest an import reads. The supported migration is one
+            // directory per user; a run that would drop ids says so (#3135).
+            const manifestPath = path.join(options.output, "manifest.json");
+            if (fs.existsSync(manifestPath)) {
+                try {
+                    const existing = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+                    const dropped = (Array.isArray(existing?.documents) ? existing.documents : []).filter((id) => !exportedIds.includes(id));
+                    if (dropped.length > 0) {
+                        warn(`The manifest already in ${options.output} lists ` +
+                            `${dropped.length} document(s) this export does not: ` +
+                            `${dropped.join(", ")}. Replacing it leaves them on disk but ` +
+                            `no longer reachable through the manifest an import reads — ` +
+                            `export each user into their own directory.`);
+                    }
+                }
+                catch {
+                    // An unreadable manifest is not a reason to refuse the export.
+                }
+            }
+            const manifest = {
+                version: 1,
+                exportedAt: new Date().toISOString(),
+                sourceAppId: resolvedAppId,
+                documentCount: exportedIds.length,
+                documents: exportedIds,
+            };
+            fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+            fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+            if (options.json) {
+                json(manifest);
+            }
+            else {
+                success(`Exported ${exportedIds.length} document(s) to ${options.output}`);
+            }
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    documents
+        .command("import")
+        .description("Import documents from an export directory")
+        // Optional in commander, required in the action (#3645).
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .argument("[path]", "Path to export directory or single document directory (required)")
+        .option("--app <app-id>", "App ID")
+        .option("--aliases <mode>", "Alias conflict handling: overwrite or skip", "skip")
+        // `--overwrite` has never replaced a document: the import path issues no
+        // delete and calls `import/state`, whose room handler merges the exported
+        // state into the document with `Y.applyUpdate`. The description says so
+        // (#3135), and names the one id remapping on top of it — plus the one
+        // format that is installed rather than merged.
+        .option("--overwrite", "Merge the exported state into a document that already exists (a root document export is merged into the target user's root document; a large-document export is installed, so it needs a document that holds nothing yet)")
+        .option("--dry-run", "Show what would be imported without making changes")
+        .option("--owner <userId-or-email>", "User ID or email to set as document owner (admin only)")
+        .option("--json", "Output as JSON")
+        .action(async (first, second, options) => {
+        let resolvedAppId;
+        let importPath;
+        if (second && !second.startsWith("-")) {
+            resolvedAppId = resolveAppId(first, options);
+            importPath = second;
+        }
+        else {
+            resolvedAppId = resolveAppId(undefined, options);
+            importPath = first;
+        }
+        if (!importPath) {
+            error("Import path is required.");
+            process.exit(1);
+        }
+        const client = new ApiClient();
+        // Resolve --owner to a userId through the one shared lookup (#2763).
+        let ownerUserId;
+        if (options.owner) {
+            try {
+                ownerUserId = await resolveOwnerUserId(client, resolvedAppId, options.owner);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
+        }
+        try {
+            // Determine if this is a manifest-based export or a single document
+            const manifestPath = path.join(importPath, "manifest.json");
+            let docDirs = [];
+            if (fs.existsSync(manifestPath)) {
+                const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+                for (const docId of manifest.documents) {
+                    const docDir = path.join(importPath, "documents", docId);
+                    if (fs.existsSync(docDir)) {
+                        docDirs.push(docDir);
+                    }
+                }
+            }
+            else if (fs.existsSync(path.join(importPath, "metadata.json"))) {
+                // Single document directory
+                docDirs = [importPath];
+            }
+            else if (fs.existsSync(path.join(importPath, "documents"))) {
+                // Export directory without manifest — discover documents
+                const entries = fs.readdirSync(path.join(importPath, "documents"), { withFileTypes: true });
+                for (const entry of entries) {
+                    if (entry.isDirectory()) {
+                        docDirs.push(path.join(importPath, "documents", entry.name));
+                    }
+                }
+            }
+            else {
+                error("No valid export data found at the specified path.");
+                process.exit(1);
+            }
+            if (docDirs.length === 0) {
+                info("No documents to import.");
+                return;
+            }
+            const summary = {
+                created: 0,
+                updated: 0,
+                skipped: 0,
+                blobsUploaded: 0,
+                aliasesSet: 0,
+                aliasesSkipped: 0,
+                rootDocuments: [],
+            };
+            // Where every root-marked export in this run lands, decided from reads
+            // alone and before any write (#3135): a refusal, or two exports
+            // competing for one user's root document, is reported up front.
+            const rootPlans = await planRootImports(client, resolvedAppId, docDirs, options.owner, ownerUserId, options.overwrite || false);
+            // Nothing is created until every artifact is one this CLI can install:
+            // a refusal halfway through a multi-document import would leave the
+            // app half-populated (#2816). A root export is never installed as a
+            // chain — `planRootImports` has already refused a format-2 one — so it
+            // is not vouched for here.
+            for (const docDir of docDirs) {
+                if (rootPlans.has(docDir))
+                    continue;
+                if (!largeDocumentArtifactAt(docDir))
+                    continue;
+                const metadataPath = path.join(docDir, "metadata.json");
+                const documentId = fs.existsSync(metadataPath)
+                    ? JSON.parse(fs.readFileSync(metadataPath, "utf-8")).documentId
+                    : path.basename(docDir);
+                readChainArtifact(docDir, documentId);
+            }
+            for (const docDir of docDirs) {
+                await importSingleDocument(client, resolvedAppId, docDir, options.overwrite || false, options.aliases || "skip", options.dryRun || false, summary, ownerUserId, rootPlans.get(docDir));
+            }
+            if (options.json) {
+                json(summary);
+            }
+            else {
+                success(`Import complete:`);
+                keyValue("  Documents created", String(summary.created));
+                if (summary.updated > 0)
+                    keyValue("  Documents updated", String(summary.updated));
+                if (summary.skipped > 0)
+                    keyValue("  Documents skipped", String(summary.skipped));
+                if (summary.blobsUploaded > 0)
+                    keyValue("  Blobs uploaded", String(summary.blobsUploaded));
+                if (summary.aliasesSet > 0)
+                    keyValue("  Aliases set", String(summary.aliasesSet));
+                if (summary.aliasesSkipped > 0)
+                    keyValue("  Aliases skipped", String(summary.aliasesSkipped));
+            }
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
     // Revoke group permission
     groupPermissions
         .command("revoke")
@@ -150,15 +2135,14 @@ Examples:
         .action(async (documentId, groupType, groupId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         if (!options.yes) {
-            const inquirer = await import("inquirer");
-            const { confirm } = await inquirer.default.prompt([
-                {
-                    type: "confirm",
-                    name: "confirm",
-                    message: `Revoke permission for group ${groupType}/${groupId} on document ${documentId}?`,
-                    default: false,
-                },
-            ]);
+            let confirm;
+            try {
+                confirm = await confirmPrompt(`Revoke permission for group ${groupType}/${groupId} on document ${documentId}?`);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
             if (!confirm) {
                 info("Cancelled.");
                 return;
@@ -175,4 +2159,886 @@ Examples:
         }
     });
 }
+// ============================================
+// 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 });
+    // 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.
+    let stateBytes;
+    if (Number(docMeta?.documentFormat) === 2) {
+        stateBytes = await exportLargeDocumentChain(client, appId, documentId, docDir);
+    }
+    else {
+        const stateResult = await client.exportDocumentState(appId, documentId);
+        fs.writeFileSync(path.join(docDir, "document.yjs"), Buffer.from(stateResult.state, "base64"));
+        stateBytes = stateResult.byteLength;
+    }
+    // 3. Fetch permissions
+    let 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
+    }
+    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).
+    const metadata = {
+        documentId: docMeta.documentId || documentId,
+        title: docMeta.title,
+        tags: docMeta.tags || [],
+        ...(Number(docMeta?.documentFormat) === 2 ? { documentFormat: 2 } : {}),
+        createdAt: docMeta.createdAt,
+        createdBy: docMeta.createdByEmail || docMeta.createdBy,
+        aliases: aliases.map((a) => ({
+            aliasScope: a.scope || a.aliasScope,
+            aliasKey: a.aliasKey,
+        })),
+    };
+    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 });
+            const blobIndex = blobs.map((b) => ({
+                blobId: b.blobId,
+                filename: b.filename,
+                contentType: b.contentType,
+                sha256: b.sha256,
+                numBytes: b.numBytes,
+            }));
+            fs.writeFileSync(path.join(blobsDir, "index.json"), JSON.stringify(blobIndex, null, 2));
+            // Download blobs (sequentially to avoid overwhelming the server)
+            for (const blob of blobs) {
+                const data = await client.downloadBlob(appId, documentId, blob.blobId);
+                fs.writeFileSync(path.join(blobsDir, `${blob.blobId}.bin`), data);
+            }
+        }
+    }
+    if (jsonOutput) {
+        json({
+            documentId,
+            title: metadata.title,
+            stateBytes,
+            permissions: permissionsExport.length,
+            aliases: aliases.length,
+            exportPath: docDir,
+        });
+    }
+    else {
+        success(`Exported document ${documentId} (${metadata.title || "untitled"}) to ${docDir}`);
+    }
+}
+/**
+ * Whether `docDir` holds a large document's export (#2816, behavior 20).
+ *
+ * Either marker is enough: `chain.json` is what the chain export writes last,
+ * and `metadata.json` carries the format for artifacts inspected on their own.
+ */
+function largeDocumentArtifactAt(docDir) {
+    if (fs.existsSync(path.join(docDir, "chain.json")))
+        return true;
+    const metadataPath = path.join(docDir, "metadata.json");
+    if (!fs.existsSync(metadataPath))
+        return false;
+    try {
+        const metadata = JSON.parse(fs.readFileSync(metadataPath, "utf-8"));
+        return Number(metadata?.documentFormat) === 2;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read (and vouch for) a large document's chain artifact.
+ *
+ * `chain.json` is what the export writes LAST, so its absence means the
+ * artifact is partial — a directory recognizable as a large document with no
+ * description of what to install. Importing that as a legacy document would
+ * read a `document.yjs` that is not there, create an empty document, and
+ * report success: total data loss from the operator's point of view, since the
+ * export is the only copy they were told they had. Refusing is the honest
+ * answer, and it happens before anything is created.
+ */
+function readChainArtifact(docDir, documentId) {
+    const chainPath = path.join(docDir, "chain.json");
+    if (!fs.existsSync(chainPath)) {
+        throw new Error(`Document ${documentId} was exported as a large document (documentFormat 2), ` +
+            `but ${chainPath} is missing, so this artifact is incomplete. A large document's ` +
+            `data IS its chain — a base snapshot, the sealed overlays after it, and the open ` +
+            `epoch — and importing this directory as a legacy document would create an EMPTY ` +
+            `document. Nothing was imported.`);
+    }
+    let chain;
+    try {
+        chain = JSON.parse(fs.readFileSync(chainPath, "utf-8"));
+    }
+    catch (parseError) {
+        throw new Error(`Document ${documentId}: ${chainPath} is not readable as a chain description ` +
+            `(${parseError.message}), so nothing was imported.`);
+    }
+    if (!Number.isSafeInteger(Number(chain?.epoch))) {
+        throw new Error(`Document ${documentId}: ${chainPath} names no open epoch, so nothing was imported.`);
+    }
+    const artifact = {
+        epoch: Number(chain.epoch),
+        base: chain.base
+            ? {
+                epoch: Number(chain.base.epoch),
+                buildId: String(chain.base.buildId),
+                rows: Number(chain.base.rows ?? 0),
+            }
+            : null,
+        overlays: (Array.isArray(chain.overlays) ? chain.overlays : []).map((overlay) => ({ epoch: Number(overlay.epoch) })),
+    };
+    verifyChainArtifact(docDir, documentId, artifact);
+    return artifact;
+}
+/**
+ * Check that the directory holds every file the chain names, and that the
+ * chain is one.
+ *
+ * `chain.json` being present says the export finished writing; it does not say
+ * the files are there, and until this check the first missing chunk was found
+ * AFTER the destination document had been created — leaving an empty document
+ * behind, and in a multi-document import an app half-populated. The chain's
+ * shape is checked here too, for the same reason the server checks it: a
+ * chain with an epoch missing from the middle installs cleanly and is missing
+ * everything that epoch held.
+ */
+function verifyChainArtifact(docDir, documentId, chain) {
+    const refuse = (reason) => {
+        throw new Error(`Document ${documentId}: its large-document export ${reason}, so nothing was imported.`);
+    };
+    const from = chain.base ? chain.base.epoch : 1;
+    const expected = [];
+    for (let epoch = from; epoch < chain.epoch; epoch++)
+        expected.push(epoch);
+    const named = chain.overlays
+        .map((overlay) => overlay.epoch)
+        .sort((left, right) => left - right);
+    if (named.length !== expected.length ||
+        named.some((epoch, index) => epoch !== expected[index])) {
+        refuse(`describes sealed overlays [${named.join(", ")}] where the chain from ` +
+            (chain.base ? `its base at epoch ${chain.base.epoch}` : "epoch 1") +
+            ` to its open epoch ${chain.epoch} is [${expected.join(", ")}]`);
+    }
+    const require = (file, what) => {
+        if (!fs.existsSync(file))
+            refuse(`is missing ${what} (${file})`);
+    };
+    if (chain.base) {
+        const manifestPath = path.join(docDir, "snapshot", "manifest.json");
+        require(manifestPath, "its base snapshot's manifest");
+        let manifest;
+        try {
+            manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+        }
+        catch (parseError) {
+            refuse(`has a base snapshot manifest that is not readable ` +
+                `(${parseError.message})`);
+        }
+        // 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");
+}
+/** How long an install is waited on before the CLI gives up on it. */
+const CHAIN_INSTALL_TIMEOUT_MS = 60 * 60 * 1000;
+/** How often the install's progress is asked for. */
+const CHAIN_INSTALL_POLL_MS = 1000;
+/**
+ * Install a large document's chain export into a freshly created document
+ * (#2816, behavior 20).
+ *
+ * Every artifact is uploaded byte-for-byte into the new document's own prefix
+ * — the manifest's digests are over the STORED bytes, so re-encoding a chunk
+ * here would fail its own verification on install — and then the server
+ * streams them into the document's `records` table a tick at a time. The full
+ * document is never built as a Y.Doc on either side, which is what makes
+ * importing a multi-hundred-MB artifact possible at all; it is also the
+ * efficient way to bulk-seed a new large document.
+ */
+async function importLargeDocumentChain(client, appId, docDir, documentId) {
+    const chain = readChainArtifact(docDir, documentId);
+    // The base's manifest and chunks. The manifest names the chunks, so nothing
+    // here has to walk the directory and guess what belongs to the build.
+    if (chain.base) {
+        const manifestPath = path.join(docDir, "snapshot", "manifest.json");
+        const manifestBytes = fs.readFileSync(manifestPath);
+        await client.uploadDocumentChainArtifact(appId, documentId, {
+            kind: "manifest",
+            epoch: chain.base.epoch,
+            buildId: chain.base.buildId,
+        }, manifestBytes);
+        const manifest = JSON.parse(manifestBytes.toString("utf-8"));
+        for (const chunk of manifest.chunks ?? []) {
+            // 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));
+    }
+}
+/** Mirrors `ROOT_DOCUMENT_TAG` in `src/config/constants.ts`. */
+const ROOT_DOCUMENT_TAG = "__ROOT_TAG__";
+/** Does this `metadata.json` describe somebody's root document? */
+function isRootDocumentExport(tags) {
+    return Array.isArray(tags) && tags.includes(ROOT_DOCUMENT_TAG);
+}
+/**
+ * Why a large-document root export is refused (#3135, contract 7).
+ *
+ * A format-2 export is a chain installed wholesale into a freshly created
+ * format-2 document — a replace, not a merge, and not something that can be
+ * done to a root document, which the server only ever mints as a legacy
+ * document. Refusing says so rather than installing a chain somewhere it does
+ * not belong.
+ */
+const ROOT_LARGE_DOCUMENT_REFUSAL = "it is a root document exported as a large document (documentFormat 2). A " +
+    "root document is minted as a legacy document and a chain is installed " +
+    "wholesale into a new format-2 document, so the export cannot be applied " +
+    "to the target user's root. Nothing was imported for it.";
+/** Read an export directory's `metadata.json`, or null when it has none. */
+function readExportMetadata(docDir) {
+    const metadataPath = path.join(docDir, "metadata.json");
+    if (!fs.existsSync(metadataPath))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(metadataPath, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Decide what each root-marked export in this run resolves to (#3135).
+ *
+ * A root document is a per-user singleton the server owns: the exported id is
+ * the SOURCE user's root and means nothing here, so the export is mapped to
+ * the TARGET user's root document instead. The target is `--owner` when given,
+ * otherwise the owner `metadata.json` recorded — an email since #3135, which
+ * is the only owner identity that survives a move between environments.
+ *
+ * Only a definitive answer reads as absence: `exists: false` from the email
+ * lookup, or a 404 from the root-document read. Anything else (an expired
+ * login, a lost permission, a server fault) fails the run, exactly as the
+ * document-existence check does (#3096) — a failed read must never turn into a
+ * confident create.
+ */
+async function planRootImports(client, appId, docDirs, explicitOwner, explicitOwnerUserId, overwrite) {
+    const plans = new Map();
+    for (const docDir of docDirs) {
+        const metadata = readExportMetadata(docDir);
+        if (!metadata || !isRootDocumentExport(metadata.tags))
+            continue;
+        const exportedDocumentId = metadata.documentId || path.basename(docDir);
+        const owner = String(explicitOwner || metadata.createdBy || "");
+        const plan = {
+            docDir,
+            exportedDocumentId,
+            owner,
+            action: "refused",
+        };
+        const refuse = (reason) => {
+            plan.action = "refused";
+            plan.reason = reason;
+            plans.set(docDir, plan);
+        };
+        if (Number(metadata.documentFormat) === 2) {
+            refuse(ROOT_LARGE_DOCUMENT_REFUSAL);
+            continue;
+        }
+        if (!owner) {
+            refuse(`it is a root document export that records no owner, so there is no ` +
+                `user in ${appId} to restore it into. Pass --owner <userId-or-email>.`);
+            continue;
+        }
+        // Resolve the target user. An explicit `--owner` was already resolved,
+        // command-level, before anything was read.
+        let targetUserId = explicitOwnerUserId;
+        if (!targetUserId) {
+            if (owner.includes("@")) {
+                // Absence is what the lookup ANSWERS with — `exists: false` on a 200.
+                // A thrown lookup is a failed read (an expired login, a lost
+                // permission, a proxy), and a failed read must never pass for "no such
+                // user": it fails the run instead (#3096).
+                let lookup;
+                try {
+                    lookup = await client.lookupUserByEmail(appId, owner);
+                }
+                catch (error) {
+                    throw new Error(`Document ${exportedDocumentId}: looking up its recorded owner ` +
+                        `"${owner}" failed — ${error?.message || "no reason given"}. ` +
+                        `Nothing was imported.`);
+                }
+                if (!lookup?.exists || !lookup.user) {
+                    refuse(unresolvableRootOwner(appId, owner));
+                    continue;
+                }
+                targetUserId = lookup.user.userId;
+            }
+            else {
+                targetUserId = owner;
+            }
+        }
+        plan.targetUserId = targetUserId;
+        let assignment;
+        try {
+            assignment = await client.getUserRootDocument(appId, targetUserId);
+        }
+        catch (error) {
+            if (error?.statusCode !== 404) {
+                throw new Error(`Document ${exportedDocumentId}: reading the root document of ` +
+                    `"${owner}" failed — ${error?.message || "no reason given"}. ` +
+                    `Nothing was imported.`);
+            }
+            refuse(unresolvableRootOwner(appId, owner));
+            continue;
+        }
+        const rootDocId = assignment?.rootDocId || null;
+        if (!rootDocId) {
+            plan.action = "create";
+        }
+        else {
+            plan.targetRootDocId = rootDocId;
+            plan.action = overwrite ? "apply" : "skip";
+        }
+        plans.set(docDir, plan);
+    }
+    assertDistinctRootTargets(plans);
+    return plans;
+}
+/** Why a recorded owner cannot be restored into, and what to do about it. */
+function unresolvableRootOwner(appId, owner) {
+    return (`it is a root document export whose owner "${owner}" is not a user of ` +
+        `app ${appId}. A root document is restored into one specific user's own ` +
+        `root document, so name the target user with --owner <userId-or-email>, ` +
+        `or re-export so the owner's email is recorded.`);
+}
+/**
+ * Refuse a run in which two root exports would land in one user's root
+ * document (#3135, contract 5).
+ *
+ * The supported migration is one `export-all --user-id` directory per user,
+ * imported one directory per run. A hand-assembled directory holding two
+ * users' roots — or `--owner` given for a run containing more than one root
+ * export — would merge both sources into a single root and lose one of them,
+ * so it fails before anything is created rather than half-way through.
+ */
+function assertDistinctRootTargets(plans) {
+    const byUser = new Map();
+    for (const plan of plans.values()) {
+        if (plan.action === "refused" || !plan.targetUserId)
+            continue;
+        const seen = byUser.get(plan.targetUserId) ?? [];
+        seen.push(plan.exportedDocumentId);
+        byUser.set(plan.targetUserId, seen);
+    }
+    for (const [userId, documents] of byUser) {
+        if (documents.length > 1) {
+            throw new Error(`Root document exports ${documents.join(", ")} all resolve to user ` +
+                `${userId}, and a user has exactly one root document — importing ` +
+                `them would merge them into each other. Export one user per ` +
+                `directory and import one directory per run. Nothing was imported.`);
+        }
+    }
+}
+/**
+ * Does the target app already hold this document?
+ *
+ * Only an explicit 404 answers "no" (#3096). An expired login (401), a lost
+ * permission (403), a server fault or a transport failure says nothing about
+ * the document, and reading those as absence turns a failed lookup into a
+ * confident create — or, for a root-marked export, into a reported skip that
+ * silently omits the overwrite the operator asked for. Those propagate, and
+ * `documents import` fails the run.
+ */
+async function documentExists(client, appId, documentId) {
+    try {
+        await client.getDocument(appId, documentId);
+        return true;
+    }
+    catch (error) {
+        if (error?.statusCode === 404)
+            return false;
+        throw new Error(`Document ${documentId}: checking whether it already exists failed — ` +
+            `${error?.message || "no reason given"}. Nothing was imported for it.`);
+    }
+}
+async function importSingleDocument(client, appId, docDir, overwrite, aliasMode, dryRun, summary, ownerUserId, rootPlan) {
+    const metadataPath = path.join(docDir, "metadata.json");
+    if (!fs.existsSync(metadataPath)) {
+        warn(`Skipping ${docDir}: no metadata.json found`);
+        summary.skipped++;
+        return;
+    }
+    const metadata = JSON.parse(fs.readFileSync(metadataPath, "utf-8"));
+    const documentId = metadata.documentId;
+    // A root-marked export is never restored under its exported id: that id is
+    // the SOURCE user's root document. It goes to the target user's own root
+    // instead, per the plan made before this run wrote anything (#3135).
+    //
+    // Decided BEFORE the chain artifact below is read, because a root export is
+    // never installed as a chain: a large-document root is refused by the plan,
+    // and reading its chain here would fail the whole run over an artifact this
+    // run has already decided not to touch.
+    if (isRootDocumentExport(metadata.tags)) {
+        await importRootDocument(client, appId, docDir, metadata, rootPlan, overwrite, aliasMode, dryRun, summary);
+        return;
+    }
+    // A large document's data is the chain, not `document.yjs` (#2816), and it
+    // is installed rather than replayed. Vouched for before anything is created.
+    const isLargeDocument = largeDocumentArtifactAt(docDir);
+    if (isLargeDocument)
+        readChainArtifact(docDir, documentId);
+    // `--dry-run` decides from the same facts the real run does (#3096), so a
+    // preview never promises a skip that the run turns into a merge: it looks
+    // the document up as well, and only the writes below are withheld.
+    const exists = await documentExists(client, appId, documentId);
+    const wouldSkip = dryRun ? "[dry-run] Would skip" : "Skipping";
+    if (exists && !overwrite) {
+        // `--overwrite` merges a legacy document's state — but a large document is
+        // INSTALLED, and the server refuses to install a chain into a document
+        // that already holds records (`assertDocumentIsImportable`), so the remedy
+        // is only honest for the format the state path handles.
+        warn(isLargeDocument
+            ? `${wouldSkip} ${documentId}: already exists, and ` +
+                `a large-document export is installed rather than merged — ` +
+                `--overwrite can only install it into a document that holds ` +
+                `nothing yet`
+            : `${wouldSkip} ${documentId}: already exists (use --overwrite to merge ` +
+                `the exported state into it)`);
+        summary.skipped++;
+        return;
+    }
+    if (dryRun) {
+        info(`[dry-run] Would ${exists ? "update" : "import"} document ${documentId} ` +
+            `(${metadata.title || "untitled"})`);
+        if (exists)
+            summary.updated++;
+        else
+            summary.created++;
+        return;
+    }
+    // Create document if it doesn't exist. The format is decided at creation and
+    // never migrated, so a large document has to be created as one (#2816).
+    //
+    // Tags go back exactly as `metadata.json` recorded them (#3096): an export
+    // is a faithful record of what the document is, and editing the list on the
+    // way back in loses that.
+    if (!exists) {
+        await client.createDocument(appId, {
+            title: metadata.title || "Imported Document",
+            documentId,
+            tags: metadata.tags,
+            ...(isLargeDocument ? { documentFormat: 2 } : {}),
+            ...(ownerUserId ? { createdBy: ownerUserId } : {}),
+        });
+        summary.created++;
+    }
+    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);
+    }
+    else {
+        // Import Yjs state
+        const yjsPath = path.join(docDir, "document.yjs");
+        if (fs.existsSync(yjsPath)) {
+            const stateBuffer = fs.readFileSync(yjsPath);
+            const stateBase64 = stateBuffer.toString("base64");
+            await client.importDocumentState(appId, documentId, stateBase64);
+        }
+    }
+    // Upload blobs
+    const blobIndexPath = path.join(docDir, "blobs", "index.json");
+    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++;
+            }
+        }
+    }
+    // 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++;
+            }
+        }
+    }
+    info(`Imported document ${documentId} (${metadata.title || "untitled"})`);
+}
+/**
+ * Restore a root-marked export into the target user's own root document
+ * (#3135).
+ *
+ * The exported id is never created and never looked up: it is the source
+ * user's root id, which means nothing in this app. Everything — the Yjs state,
+ * the blobs, the user-scoped aliases — is written against the target user's
+ * root document id instead, so blob references inside the document still
+ * resolve and the app still holds exactly one root document per user.
+ *
+ * "Apply" is the merge `import/state` has always performed: keys only one side
+ * holds survive, and a key both sides set resolves by Yjs's own conflict rule,
+ * which guarantees neither source-wins nor target-wins. That is why merging
+ * into an existing root needs `--overwrite` — the default must not quietly
+ * rewrite a user's live preferences.
+ */
+async function importRootDocument(client, appId, docDir, metadata, plan, overwrite, aliasMode, dryRun, summary) {
+    const exportedDocumentId = metadata.documentId || path.basename(docDir);
+    const wouldSkip = dryRun ? "[dry-run] Would skip" : "Skipping";
+    const report = (action, targetRootDocId, reason) => {
+        summary.rootDocuments.push({
+            exportedDocumentId,
+            owner: plan?.owner ?? "",
+            ...(targetRootDocId ? { targetRootDocId } : {}),
+            action,
+            ...(reason ? { reason } : {}),
+        });
+    };
+    if (!plan || plan.action === "refused") {
+        const reason = plan?.reason ||
+            `it is a root document export this run could not resolve to a user in ` +
+                `app ${appId}. Pass --owner <userId-or-email>.`;
+        warn(`${wouldSkip} ${exportedDocumentId}: ${reason}`);
+        summary.skipped++;
+        report("refused", undefined, reason);
+        return;
+    }
+    if (plan.action === "skip") {
+        const reason = `the root document of ${plan.owner} already exists ` +
+            `(${plan.targetRootDocId}); use --overwrite to merge the exported ` +
+            `content into it`;
+        warn(`${wouldSkip} ${exportedDocumentId}: ${reason}`);
+        summary.skipped++;
+        report("skipped", plan.targetRootDocId, reason);
+        return;
+    }
+    if (dryRun) {
+        if (plan.action === "create") {
+            info(`[dry-run] Would create the root document for ${plan.owner} and ` +
+                `apply root document export ${exportedDocumentId} to it`);
+            summary.created++;
+            report("created");
+        }
+        else {
+            info(`[dry-run] Would apply root document export ${exportedDocumentId} to ` +
+                `${plan.owner}'s root document ${plan.targetRootDocId}`);
+            summary.updated++;
+            report("applied", plan.targetRootDocId);
+        }
+        return;
+    }
+    let targetRootDocId = plan.targetRootDocId;
+    let created = false;
+    if (plan.action === "create") {
+        // The server's own get-or-create, and the only place a root document is
+        // ever minted. Its answer — not the preflight read — decides both the id
+        // the content lands in and whether this run created it: a first sign-in
+        // may have minted the root between the read and this call.
+        const ensured = await client.ensureUserRootDocument(appId, plan.targetUserId);
+        targetRootDocId = ensured?.rootDocId;
+        if (!targetRootDocId) {
+            throw new Error(`Document ${exportedDocumentId}: the server returned no root document ` +
+                `for ${plan.owner}, so nothing was imported for it.`);
+        }
+        created = ensured.created === true;
+        if (!created && !overwrite) {
+            const reason = `the root document of ${plan.owner} (${targetRootDocId}) was created ` +
+                `by a concurrent sign-in while this import was running; use ` +
+                `--overwrite to merge the exported content into it`;
+            warn(`Skipping ${exportedDocumentId}: ${reason}`);
+            summary.skipped++;
+            report("skipped", targetRootDocId, reason);
+            return;
+        }
+    }
+    // Only content moves. The target root keeps its own id, title, tags and
+    // permissions — the ensure path already granted the owner read-write.
+    const yjsPath = path.join(docDir, "document.yjs");
+    if (fs.existsSync(yjsPath)) {
+        await client.importDocumentState(appId, targetRootDocId, fs.readFileSync(yjsPath).toString("base64"));
+    }
+    const blobIndexPath = path.join(docDir, "blobs", "index.json");
+    if (fs.existsSync(blobIndexPath)) {
+        const blobIndex = JSON.parse(fs.readFileSync(blobIndexPath, "utf-8"));
+        for (const blob of blobIndex) {
+            const blobPath = path.join(docDir, "blobs", `${blob.blobId}.bin`);
+            if (!fs.existsSync(blobPath))
+                continue;
+            // The blobId is preserved: a document's own references travel by blobId,
+            // so they resolve inside the target root as they did in the source.
+            await client.uploadBlob(appId, targetRootDocId, blob.blobId, fs.readFileSync(blobPath), {
+                filename: blob.filename,
+                contentType: blob.contentType,
+                sha256: blob.sha256,
+            });
+            summary.blobsUploaded++;
+        }
+    }
+    // A root document's user-scoped aliases belong to its owner by definition,
+    // so they are restored without `--owner` — the target user is already known.
+    if (Array.isArray(metadata.aliases)) {
+        for (const alias of metadata.aliases) {
+            if (alias.aliasScope !== "user")
+                continue;
+            try {
+                await client.setDocumentAlias(appId, alias.aliasScope, alias.aliasKey, targetRootDocId, plan.targetUserId, aliasMode === "skip");
+                summary.aliasesSet++;
+            }
+            catch {
+                summary.aliasesSkipped++;
+            }
+        }
+    }
+    if (created) {
+        summary.created++;
+        report("created", targetRootDocId);
+        info(`Created root document ${targetRootDocId} for ${plan.owner} and applied ` +
+            `root document export ${exportedDocumentId} to it`);
+    }
+    else {
+        summary.updated++;
+        report("applied", targetRootDocId);
+        info(`Applied root document export ${exportedDocumentId} to ${plan.owner}'s ` +
+            `root document ${targetRootDocId}`);
+    }
+}
+/**
+ * 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.
+ */
+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,
+    });
+}
 //# sourceMappingURL=documents.js.map