primitive-admin 1.2.0-alpha.3 → 1.2.0-alpha.5

package/dist/src/commands/documents.js

@@ -1,9 +1,11 @@
-import { snapshotBuildRows } from "../lib/snapshot-build-rows.js";
+import { segmentRows, snapshotBuildRows } from "../lib/snapshot-build-rows.js";
+import { exportRecordLogDocument } from "../lib/document-export-record-log.js";
 import { driveSnapshotBuild } from "../lib/snapshot-build.js";
 import { ingestClientRows, ingestSessionRows, } from "../lib/document-ingest-rows.js";
 import { ApiClient } from "../lib/api-client.js";
 import { resolveAppId } from "../lib/config.js";
 import { success, error, info, formatTable, formatId, formatDate, json, keyValue, result as printResult, warn, flushOutput, } from "../lib/output.js";
+import { renderAggregateResult } from "../lib/aggregate-output.js";
 import { confirmPrompt } from "../lib/confirm-prompt.js";
 import { resolveOwnerUserId } from "../lib/resolve-owner.js";
 import { pageCursorOption, pageLimitOption, parsePageLimit, printEmptyPage, printPageHint, } from "../lib/list-options.js";
@@ -12,14 +14,9 @@ import { parseDataOption } from "../lib/data-input.js";
 import { parseFilterOptions } from "../lib/record-filter.js";
 import { buildPermissionsExport, PENDING_INVITATIONS_ABSENT_STATUSES, } from "../lib/document-export-permissions.js";
 import { readExportLookup } from "../lib/document-export-lookups.js";
-import { chunkAddressOf, renumberManifestForExport, } from "../lib/snapshot-manifest-layout.js";
-import { validateSnapshotManifest } from "js-bao";
-import { auditSnapshotChain, } from "../lib/snapshot-audit.js";
-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 { driveDocumentIngest, summariseIngestPlan, assertIngestConfirmable, ingestCreateBody, parseIngestFlags, } from "../lib/document-ingest.js";
 import { withTransientRetry } from "../lib/transient-retry.js";
 import { ulid } from "ulid";
 import * as Y from "yjs";
@@ -39,6 +36,17 @@ function printIngestSession(session) {
         printResult(label, value);
     }
 }
+/**
+ * One refused document call, as one line for an operator: the server's
+ * sentence and, when it sent one, the stable code a script branches on — a
+ * large document's refusal names `DOCUMENT_FORMAT_UNSUPPORTED` on every verb
+ * that reaches its data (#4313).
+ */
+export function describeDocumentFailure(err) {
+    const message = (typeof err?.message === "string" && err.message) || String(err);
+    const code = typeof err?.code === "string" && err.code ? err.code : undefined;
+    return code && !message.includes(code) ? `${message} [${code}]` : message;
+}
 /**
  * One refused records call, as one line for an operator (#3764).
  *
@@ -57,7 +65,8 @@ export function describeRecordsFailure(err) {
     return `${message}${code ? ` [${code}]` : ""}${status !== undefined ? ` (${status})` : ""}`;
 }
 /**
- * Report a document's format (#2816) — but only when it is a large document.
+ * Report a document's format (#2816) — but only when it is a large (2) or a
+ * record-log (3, #4306) document.
  *
  * The format is chosen at creation and never migrated, so an operator has to
  * be able to read it back: `--large` that the server ignored would otherwise
@@ -66,9 +75,13 @@ export function describeRecordsFailure(err) {
  * stored row spells the format (absent, null or 1).
  */
 function printDocumentFormat(doc) {
-    if (Number(doc?.documentFormat) === 2) {
+    const format = Number(doc?.documentFormat);
+    if (format === 2) {
         keyValue("Format", "2 (large document)");
     }
+    else if (format === 3) {
+        keyValue("Format", "3 (record log)");
+    }
 }
 /**
  * The `--document-format` an operator stated, or the refusal (#3764, E10).
@@ -76,22 +89,53 @@ function printDocumentFormat(doc) {
  * Refused HERE rather than by the server, because an operator CAN act on it
  * (principle 6) and a round trip to be told what they typed wrong is a round
  * trip they do not need to spend. Commander hands the raw string over, so the
- * digits are what is read; an unset flag states nothing.
+ * digits are what is read; an unset flag states nothing. `flag` names the
+ * option in the refusal: `documents create` reads its `--format` here too.
+ *
+ * `2` — a large document, which the platform no longer serves — is refused
+ * with `DOCUMENT_FORMAT_UNSUPPORTED` named, as the server would refuse it.
  */
-export function parseDocumentFormatOption(value) {
+export function parseDocumentFormatOption(value, flag = "--document-format") {
     if (value === undefined || value === null)
         return undefined;
     const text = String(value).trim();
     if (text === "1")
         return 1;
-    if (text === "2")
-        return 2;
-    throw new Error(`Invalid --document-format "${String(value)}". Expected 1 (an ordinary ` +
-        `document) or 2 (a large document).`);
+    if (text === "3")
+        return 3;
+    if (text === "2") {
+        throw new Error(`documentFormat 2 (large document) is no longer served; use ${flag} 3 (DOCUMENT_FORMAT_UNSUPPORTED)`);
+    }
+    throw new Error(`Invalid ${flag} "${String(value)}". Expected 1 (an ordinary ` +
+        `document) or 3 (a record-log document).`);
 }
-/** The `--document-format <1|2>` flag, said once for every records verb. */
-const DOCUMENT_FORMAT_FLAG = "--document-format <1|2>";
-const DOCUMENT_FORMAT_HELP = "The document format you expect: 1 (ordinary) or 2 (large). A disagreement " +
+/**
+ * The `documentFormat` a `documents create` sends, from its two flags.
+ *
+ * `--format` is read by {@link parseDocumentFormatOption}, so a value outside
+ * 1 and 3 is refused before any request with the same sentence every records
+ * verb uses, and 2 with `DOCUMENT_FORMAT_UNSUPPORTED`. `--large` is
+ * `--format 3`: alone it sends 3, beside `--format 3` it changes nothing, and
+ * beside `--format 1` the two disagree and the command is refused rather than
+ * guessing which one was meant. Neither flag sends nothing, so the server's
+ * default stands.
+ *
+ * @param flags - The raw `--format` value and whether `--large` was given.
+ * @returns The format to send, or `undefined` to send none.
+ * @throws Error when `--format` is not 1 or 3, or disagrees with `--large`.
+ */
+export function documentFormatForCreate(flags) {
+    const format = parseDocumentFormatOption(flags.format, "--format");
+    if (!flags.large)
+        return format;
+    if (format !== undefined && format !== 3) {
+        throw new Error("--large is --format 3; pass one of them");
+    }
+    return 3;
+}
+/** The `--document-format <1|3>` flag, said once for every records verb. */
+const DOCUMENT_FORMAT_FLAG = "--document-format <1|3>";
+const DOCUMENT_FORMAT_HELP = "The document format you expect: 1 (ordinary) or 3 (record log). A disagreement " +
     "with the platform's own answer is refused with DOCUMENT_FORMAT_MISMATCH " +
     "rather than answered out of the wrong tables";
 /**
@@ -211,6 +255,7 @@ Examples:
   $ primitive documents get <document-id>
   $ primitive documents create "My Doc"
   $ primitive documents create "My Doc" --owner user@example.com
+  $ primitive documents create "Ledger" --format 3
   $ primitive documents delete <document-id> -y
   $ primitive documents permissions list <document-id>
   $ primitive documents permissions grant <document-id> --user-id <user-id> --permission reader
@@ -333,7 +378,8 @@ Examples:
         .argument("<title>", "Document title")
         .option("--app <app-id>", "App ID")
         .option("--owner <userId-or-email>", "User ID or email to own the document (super-admin or assigned-console-admin tokens only)")
-        .option("--large", "Create a large document (format 2): base snapshots + epoch overlays, for documents that outgrow a single in-memory Y.Doc")
+        .option("--format <n>", "Document format: 1 (ordinary) or 3 (record log). Chosen at creation and never changed")
+        .option("--large", "Create a record-log document (format 3), for documents that outgrow a single in-memory Y.Doc. The same as --format 3")
         .option("--json", "Output as JSON")
         .addHelpText("after", `
 Ownership:
@@ -349,6 +395,20 @@ Ownership:
   document.
 `)
         .action(async (title, options) => {
+        // Decided before anything else: a format the operator mistyped, one that
+        // disagrees with --large, or 2 (a large document, no longer served) is
+        // refused without a request (#4308, #4313).
+        let documentFormat;
+        try {
+            documentFormat = documentFormatForCreate({
+                format: options.format,
+                large: options.large === true,
+            });
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         let ownerUserId;
@@ -365,9 +425,9 @@ Ownership:
             const result = await client.createDocument(resolvedAppId, {
                 title,
                 ...(ownerUserId ? { createdBy: ownerUserId } : {}),
-                // Opt-in only: without --large nothing is sent, so the document is
-                // created in the legacy format exactly as before (#2816).
-                ...(options.large ? { documentFormat: 2 } : {}),
+                // Opt-in only: without --format or --large nothing is sent, so the
+                // document is created in the legacy format exactly as before (#2816).
+                ...(documentFormat !== undefined ? { documentFormat } : {}),
             });
             if (options.json) {
                 json(result);
@@ -377,7 +437,7 @@ Ownership:
             keyValue("Document ID", result.documentId);
             keyValue("Title", result.title);
             keyValue("Owner", result.createdBy);
-            // Read back from the RESPONSE, not from `--large`: what the server
+            // Read back from the RESPONSE, not from the flags: what the server
             // created is what the document will be for the rest of its life.
             printDocumentFormat(result);
         }
@@ -437,7 +497,7 @@ Permissions (enforced by the server, not the CLI):
         catch (err) {
             // Server refusals (404 not found, 403 root document / owner-only, the
             // non-owner fail-closed 503) are printed verbatim, never swallowed.
-            error(err.message);
+            error(describeDocumentFailure(err));
             process.exit(1);
         }
     });
@@ -882,35 +942,18 @@ Permissions (enforced by the server, not the CLI):
                 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" },
-                ]));
+            // The route answers rows (#4265): one key/value line when
+            // ungrouped, a table with one column per group key when grouped.
+            const rendered = renderAggregateResult(response?.result, {
+                groupBy,
+                op: options.op,
+                field: options.field,
+            });
+            if (rendered.kind === "scalar") {
+                keyValue(rendered.label, rendered.value);
             }
             else {
-                console.log(JSON.stringify(aggregated ?? {}, null, 2));
+                console.log(rendered.text);
             }
         }
         catch (err) {
@@ -1153,7 +1196,7 @@ Permissions (enforced by the server, not the CLI):
             console.log(output);
         }
         catch (err) {
-            error(err.message);
+            error(describeDocumentFailure(err));
             process.exit(1);
         }
     });
@@ -1185,7 +1228,98 @@ Permissions (enforced by the server, not the CLI):
             keyValue("Last modified", result.lastModifiedAt ? formatDate(result.lastModifiedAt) : "—");
         }
         catch (err) {
-            error(err.message);
+            error(describeDocumentFailure(err));
+            process.exit(1);
+        }
+    });
+    // #4306 — a record-log document's room: the inspection route's payload.
+    documents
+        .command("inspect")
+        .description("Show a record-log document's room: epochs, log number, floors, writers, the bulk load in progress and checkpoint")
+        .argument("<document-id>", "Document ID")
+        .option("--app <app-id>", "App ID")
+        .option("--refused <session-id>", "Print every row that bulk load refused, with its code, instead")
+        .option("--limit <n>", "With --refused: rows per page read (1–100)", "100")
+        .option("--json", "Output as JSON")
+        .action(async (documentId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            if (options.refused !== undefined) {
+                // Every page, in order: the room keeps each refused row with its code.
+                const items = [];
+                let cursor;
+                do {
+                    const page = await client.getDocumentRoom(resolvedAppId, documentId, {
+                        refused: options.refused,
+                        limit: Number(options.limit),
+                        cursor,
+                    });
+                    items.push(...page.refused.items);
+                    cursor = page.refused.hasMore ? page.refused.nextCursor : undefined;
+                } while (cursor);
+                if (options.json) {
+                    json({ documentId, sessionId: options.refused, items });
+                    return;
+                }
+                keyValue("Document ID", documentId);
+                keyValue("Session", options.refused);
+                keyValue("Refused rows", items.length);
+                for (const row of items) {
+                    const conflicting = row.conflicting ? ` (held by ${row.conflicting.model} ${row.conflicting.id})` : "";
+                    keyValue(`  ${row.model} ${row.id}`, `${row.code}${row.constraint ? ` ${row.constraint}` : ""}${conflicting}`);
+                }
+                return;
+            }
+            const result = await client.getDocumentRoom(resolvedAppId, documentId);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            keyValue("Document ID", result.documentId);
+            printDocumentFormat(result);
+            const room = result.room;
+            if (!room) {
+                keyValue("Room", `no record room (format ${result.documentFormat ?? 1})`);
+                return;
+            }
+            keyValue("Log number", room.lsn);
+            keyValue("Epochs", `current ${room.epochs.current}, next ${room.epochs.next}, high ${room.epochs.high}`);
+            keyValue("Epoch floor", room.epochs.floor);
+            keyValue("Cursor floor", room.cursorFloor);
+            keyValue("Entries since rotation", room.epochs.entriesSinceRotation);
+            keyValue("Rotated", room.epochs.rotatedAt ? formatDate(room.epochs.rotatedAt) : "—");
+            keyValue("Writers", `${room.writers.count} (${room.writers.connected} connected)`);
+            keyValue("Subscribers", room.subscribers);
+            keyValue("Held entries", room.held.entries);
+            const load = room.load;
+            keyValue("Load", load
+                ? `${load.sessionId} ${load.state} (${load.mode}, epoch reserved at ${load.reserveEpoch}` +
+                    (load.epoch !== null ? `: epoch ${load.epoch} from log number ${load.k}` : "") +
+                    `), ${load.chunksApplied}/${load.chunks} chunks, ${load.rowsApplied} rows applied, ` +
+                    `${load.refusedRows} refused, ${load.touched} keys touched`
+                : "none");
+            const loads = Array.isArray(room.loads) ? room.loads : [];
+            keyValue("Loads", loads.length
+                ? loads
+                    .map((l) => `${l.sessionId} (${l.mode}, log numbers ${l.firstLsn ?? "—"}–${l.lastLsn ?? "—"}, ${l.rows} rows, ${l.touched} keys touched)`)
+                    .join("; ")
+                : "none kept");
+            const segmentLine = (s) => `${s.segmentId} ${s.state} (log number ${s.lsn}` +
+                (s.completedLsn !== null && s.completedLsn !== undefined ? `, completed at ${s.completedLsn}` : "") +
+                `, ${s.rows} rows, ${s.chunks} chunks)`;
+            keyValue("Segment", room.segment ? segmentLine(room.segment) : "none");
+            keyValue("Segment export", room.segmentExport ? segmentLine(room.segmentExport) : "none");
+            keyValue("Last checkpoint", room.checkpoint
+                ? `${formatDate(room.checkpoint.at)} (${room.checkpoint.durationMs} ms, ` +
+                    `${room.checkpoint.pruned} pruned, ${room.checkpoint.dropped} dropped, ` +
+                    `${room.checkpoint.writersDropped} writers dropped)`
+                : "none yet");
+            keyValue("Next alarm", room.nextAlarmAt ? formatDate(room.nextAlarmAt) : "—");
+            keyValue("Storage (bytes)", room.storage?.databaseSize ?? "—");
+        }
+        catch (err) {
+            error(describeDocumentFailure(err));
             process.exit(1);
         }
     });
@@ -1203,6 +1337,8 @@ Permissions (enforced by the server, not the CLI):
         .argument("<document-id>", "Document ID")
         .requiredOption("--input <dir>", "Directory of <model>.ndjson[.gz] files, or a `documents export` output")
         .option("--app <app-id>", "App ID")
+        .option("--reserve-epoch <when>", "Record-log (format 3) documents: reserve the load's epoch at session open (open, the default) or at commit")
+        .option("--mode <mode>", "Record-log (format 3) documents: merge the rows (merge, the default), or refresh: also delete every record of the input's models that no row names")
         .option("-y, --yes", "Skip the confirmation prompt")
         .option("--no-wait", "Exit once the session is committed")
         .option("--timeout <seconds>", "Give up waiting after this many seconds")
@@ -1217,6 +1353,8 @@ Permissions (enforced by the server, not the CLI):
         // artifact — up to the whole input, gzipped — in the OS temp directory
         // on every run, successful or not (finding 3435-FROZEN-05).
         const run = async () => {
+            // A flag's value is checked before any request.
+            const flags = parseIngestFlags({ reserveEpoch: options.reserveEpoch, mode: options.mode });
             // The preflight, in this order and before a byte is read from disk:
             // the schema read says whether this caller may see the document's
             // declarations at all and hands over the ones the lines are checked
@@ -1227,15 +1365,19 @@ Permissions (enforced by the server, not the CLI):
             const introspection = await client.getDocumentSchema(resolvedAppId, documentId);
             await client.listDocumentIngests(resolvedAppId, documentId, { limit: 1 });
             const schema = ingestSchemaFromIntrospection(introspection);
+            // A record-log (format 3) document takes models and fields it does
+            // not declare, as its writes do (#4310); its schema read says so.
+            const recordLog = Number(introspection?.documentFormat) === 3;
             const input = discoverIngestInput(options.input, documentId);
             for (const ignored of input.ignored) {
                 info(`Ignoring ${ignored}: a bulk load reads the snapshot only.`);
             }
+            const body = ingestCreateBody(flags, input.sources.map((source) => source.model));
             // #3598 — reading, checking, sorting, cutting and gzipping is this
             // side's biggest phase on a large input, and it used to be invisible
             // inside one wall-clock number that also covered the platform's work.
             const buildStartedAt = Date.now();
-            plan = await buildIngestArtifact({ input, schema });
+            plan = await buildIngestArtifact({ input, schema, open: recordLog });
             const buildMs = Date.now() - buildStartedAt;
             info(`Built artifact in ${(buildMs / 1000).toFixed(1)}s.`);
             for (const line of summariseIngestPlan(plan))
@@ -1263,7 +1405,7 @@ Permissions (enforced by the server, not the CLI):
             try {
                 outcome = await driveDocumentIngest({
                     client: {
-                        createIngest: (id) => client.createDocumentIngest(resolvedAppId, id),
+                        createIngest: (id) => client.createDocumentIngest(resolvedAppId, id, body),
                         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),
@@ -1311,7 +1453,7 @@ Permissions (enforced by the server, not the CLI):
             code = await run();
         }
         catch (err) {
-            error(err.message);
+            error(describeDocumentFailure(err));
             code = 1;
         }
         finally {
@@ -1371,7 +1513,7 @@ Permissions (enforced by the server, not the CLI):
             }
         }
         catch (err) {
-            error(err.message);
+            error(describeDocumentFailure(err));
             process.exit(1);
         }
     });
@@ -1394,7 +1536,7 @@ Permissions (enforced by the server, not the CLI):
             printIngestSession(session);
         }
         catch (err) {
-            error(err.message);
+            error(describeDocumentFailure(err));
             process.exit(1);
         }
     });
@@ -1429,6 +1571,20 @@ Permissions (enforced by the server, not the CLI):
                 info("No snapshot builds yet.");
                 return;
             }
+            // A record-log (format 3) document's are its segments (#4310).
+            if (page.items.some((item) => typeof item?.segmentId === "string")) {
+                console.log(formatTable(page.items, [
+                    { header: "SEGMENT", key: "segmentId" },
+                    { header: "LOG NUMBER", key: "lsn" },
+                    { header: "COMPLETED AT LOG NUMBER", key: "completedLsn", format: (v) => (v === null || v === undefined ? "-" : String(v)) },
+                    { header: "STATE", key: "state" },
+                    { header: "ROWS", key: "rows" },
+                    { header: "CHUNKS", key: "chunks" },
+                    { header: "STARTED", key: "startedAt", format: formatDate },
+                    { header: "COMPLETED", key: "completedAt", format: formatDate },
+                ]));
+                return;
+            }
             console.log(formatTable(page.items, [
                 { header: "BUILD", key: "buildId" },
                 { header: "EPOCH", key: "epoch" },
@@ -1453,7 +1609,7 @@ Permissions (enforced by the server, not the CLI):
             }
         }
         catch (err) {
-            error(err.message);
+            error(describeDocumentFailure(err));
             process.exit(1);
         }
     });
@@ -1475,13 +1631,14 @@ Permissions (enforced by the server, not the CLI):
             }
             // 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)) {
+            // owns the printing. A record-log document's build is a segment (#4310).
+            const rows = typeof build?.segmentId === "string" ? segmentRows(build) : snapshotBuildRows(build);
+            for (const [label, value] of rows) {
                 printResult(label, value);
             }
         }
         catch (err) {
-            error(err.message);
+            error(describeDocumentFailure(err));
             process.exit(1);
         }
     });
@@ -1539,20 +1696,20 @@ Permissions (enforced by the server, not the CLI):
                 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);
+            if (typeof outcome.response?.segmentId === "string") {
+                // A record-log document's segment export (#4310).
+                if (outcome.build) {
+                    for (const [label, value] of segmentRows(outcome.build))
+                        printResult(label, value);
+                }
+                else {
+                    printResult("Segment", outcome.response.segmentId);
+                    printResult("State", outcome.response.state);
+                    printResult("Log number", outcome.response.lsn);
                 }
+                return outcome.exitCode;
             }
+            printResult("Build", outcome.response?.buildId);
             return outcome.exitCode;
         };
         let code = 1;
@@ -1575,74 +1732,6 @@ Permissions (enforced by the server, not the CLI):
         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")
@@ -1936,7 +2025,7 @@ Permissions (enforced by the server, not the CLI):
             await exportSingleDocument(client, resolvedAppId, documentId, options.output, options.blobs !== false ? true : false, options.json);
         }
         catch (err) {
-            error(err.message);
+            error(describeDocumentFailure(err));
             process.exit(1);
         }
     });
@@ -2043,9 +2132,8 @@ Permissions (enforced by the server, not the CLI):
         // `--overwrite` has never replaced a document: the import path issues no
         // delete and calls `import/state`, whose room handler merges the exported
         // state into the document with `Y.applyUpdate`. The description says so
-        // (#3135), and names the one id remapping on top of it — plus the one
-        // format that is installed rather than merged.
-        .option("--overwrite", "Merge the exported state into a document that already exists (a root document export is merged into the target user's root document; a large-document export is installed, so it needs a document that holds nothing yet)")
+        // (#3135), and names the one id remapping on top of it.
+        .option("--overwrite", "Merge the exported state into a document that already exists (a root document export is merged into the target user's root document)")
         .option("--dry-run", "Show what would be imported without making changes")
         .option("--owner <userId-or-email>", "User ID or email to set as document owner (admin only)")
         .option("--json", "Output as JSON")
@@ -2111,6 +2199,30 @@ Permissions (enforced by the server, not the CLI):
                 info("No documents to import.");
                 return;
             }
+            // A record-log (format 3) export is a document's rows at one log
+            // number, not a state to install (#4310): it is loaded with a bulk
+            // load. Refused before any request, naming the way in.
+            // A large-document (format 2) export cannot be installed: the platform
+            // no longer serves the format. Its snapshot row chunks are the way
+            // across, loaded into a record-log document. Refused before any write.
+            const largeDocumentExports = docDirs.filter((docDir) => isLargeDocumentExport(docDir));
+            if (largeDocumentExports.length > 0) {
+                for (const docDir of largeDocumentExports) {
+                    error(`${docDir}: this export is a large document (format 2), which the platform no longer serves; ` +
+                        `create a record-log document and run \`primitive documents ingest <document-id> --input ${docDir}\` to load its row chunks`);
+                }
+                await flushOutput();
+                process.exit(1);
+            }
+            const recordLogExports = docDirs.filter((docDir) => Number(readExportMetadata(docDir)?.documentFormat) === 3);
+            if (recordLogExports.length > 0) {
+                for (const docDir of recordLogExports) {
+                    error(`${docDir} is a record-log (format 3) export; \`documents import\` does not install one. ` +
+                        `Load its rows into a format-3 document with \`documents ingest <document-id> --input ${docDir}\`.`);
+                }
+                await flushOutput();
+                process.exit(1);
+            }
             const summary = {
                 created: 0,
                 updated: 0,
@@ -2126,28 +2238,6 @@ Permissions (enforced by the server, not the CLI):
             // 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 vouched for only when
-            // its plan installs it (#4195): a refused or skipped root export is
-            // never read past `metadata.json`, so a broken chain in it cannot
-            // fail the run.
-            for (const docDir of docDirs) {
-                const rootPlan = rootPlans.get(docDir);
-                if (rootPlan) {
-                    if (rootPlan.mode === "install") {
-                        readChainArtifact(docDir, rootPlan.exportedDocumentId);
-                    }
-                    continue;
-                }
-                if (!largeDocumentArtifactAt(docDir))
-                    continue;
-                const metadataPath = path.join(docDir, "metadata.json");
-                const documentId = fs.existsSync(metadataPath)
-                    ? JSON.parse(fs.readFileSync(metadataPath, "utf-8")).documentId
-                    : path.basename(docDir);
-                readChainArtifact(docDir, documentId);
-            }
             // One document failing does not stop the run (#4148): it is recorded
             // by id, the rest are imported, and the run exits non-zero at the end.
             for (const docDir of docDirs) {
@@ -2250,97 +2340,6 @@ Permissions (enforced by the server, not the CLI):
         }
     });
 }
-// ============================================
-// Helper functions for export/import
-// ============================================
-/**
- * Write a large document's export chain into `docDir` (#2816, behavior 20).
- *
- * The layout mirrors the chain and is applied in that order on import:
- *
- * ```
- *   chain.json          what this artifact is, and the order to apply it in
- *   snapshot/           manifest.json + {model}/{n}.ndjson.gz, when there is a base
- *   epochs/{E}.yjs      each sealed overlay after the base's epoch, oldest first
- *   current.yjs         the open epoch's overlay
- * ```
- *
- * The server refuses a chain it cannot vouch for, so nothing here has to guess
- * whether an artifact is complete; what this function must not do is write a
- * PARTIAL one, which is why `chain.json` — the file that says "this is a
- * complete v2 export" — is written last.
- *
- * Returns the bytes written, which is what `--json` reports as the document's
- * size: for a large document that is the artifact, not one Yjs update.
- */
-async function exportLargeDocumentChain(client, appId, documentId, docDir) {
-    const chain = await client.exportDocumentChain(appId, documentId);
-    let bytes = 0;
-    // The open epoch's overlay travels inline: the rotation threshold bounds it.
-    const current = Buffer.from(chain.current.update, "base64");
-    fs.writeFileSync(path.join(docDir, "current.yjs"), current);
-    bytes += current.byteLength;
-    const overlays = [];
-    if (Array.isArray(chain.overlays) && chain.overlays.length > 0) {
-        const epochsDir = path.join(docDir, "epochs");
-        fs.mkdirSync(epochsDir, { recursive: true });
-        for (const overlay of chain.overlays) {
-            const archive = await client.downloadDocumentArtifact(appId, overlay.download.path);
-            fs.writeFileSync(path.join(epochsDir, `${overlay.epoch}.yjs`), archive);
-            bytes += archive.byteLength;
-            overlays.push({ epoch: overlay.epoch, sealedAt: overlay.sealedAt ?? null });
-        }
-    }
-    let base = null;
-    if (chain.base) {
-        const snapshotDir = path.join(docDir, "snapshot");
-        fs.mkdirSync(snapshotDir, { recursive: true });
-        const manifestBytes = await client.downloadDocumentArtifact(appId, chain.base.download.path);
-        const downloaded = JSON.parse(manifestBytes.toString("utf-8"));
-        // Addressed within the granted build by each entry's `path` — the
-        // own-build `{model}/{n}` or the `{epoch}-{buildId}/{model}/{n}` of a
-        // chunk reused from an earlier build — never by key (#3432). On disk the
-        // chunks are renumbered per model into the own-build form and the stored
-        // manifest says so, which is the one layout `documents import` reads.
-        const { manifest, files } = renumberManifestForExport(downloaded);
-        for (const file of files) {
-            const body = await client.downloadDocumentArtifact(appId, `${chain.base.download.path}/${file.download}`);
-            const target = path.join(snapshotDir, file.file);
-            fs.mkdirSync(path.dirname(target), { recursive: true });
-            fs.writeFileSync(target, body);
-            bytes += body.byteLength;
-        }
-        fs.writeFileSync(path.join(snapshotDir, "manifest.json"), JSON.stringify(manifest, null, 2));
-        base = {
-            epoch: chain.base.epoch,
-            buildId: chain.base.buildId,
-            rows: chain.base.rows,
-        };
-    }
-    // Last, and without the signatures: a grant is this run's read of the
-    // document, and an artifact that outlives it must not carry one.
-    fs.writeFileSync(path.join(docDir, "chain.json"), JSON.stringify({
-        version: 2,
-        documentFormat: 2,
-        documentId,
-        epoch: chain.epoch,
-        base,
-        overlays,
-        current: { epoch: chain.current.epoch, file: "current.yjs" },
-    }, null, 2));
-    return bytes;
-}
-/**
- * Where a stored manifest entry's chunk is on disk: `snapshot/{model}/{n}`.
- *
- * An exported manifest is in the own-build form (renumbered per model), so
- * the entry's `path` — or, for an artifact written before the field existed,
- * its key — names the file directly.
- */
-function chunkFileOf(chunk) {
-    const address = chunkAddressOf(chunk);
-    return { model: address.model, index: address.index };
-}
 async function exportSingleDocument(client, appId, documentId, outputDir, includeBlobs, jsonOutput) {
     const docDir = path.join(outputDir, "documents", documentId);
     fs.mkdirSync(docDir, { recursive: true });
@@ -2352,13 +2351,26 @@ async function exportSingleDocument(client, appId, documentId, outputDir, includ
     fs.rmSync(path.join(docDir, "metadata.json"), { force: true });
     // 1. Fetch document metadata
     const docMeta = await client.getDocument(appId, documentId);
-    // 2. Export the document's state. A legacy document is one blob; a large
-    //    one (#2816) is the chain — snapshot, sealed overlays, open epoch —
-    //    because the blob is exactly the whole-document-in-memory cost format 2
-    //    exists to avoid.
+    // 2. Export the document's state. A legacy document is one blob; a
+    //    record-log document is its rows at one log number. A large document
+    //    (format 2) is no longer served, and the server refuses its export.
     let stateBytes;
-    if (Number(docMeta?.documentFormat) === 2) {
-        stateBytes = await exportLargeDocumentChain(client, appId, documentId, docDir);
+    if (Number(docMeta?.documentFormat) === 3) {
+        // A record-log document (#4310): its current segment, with the rows
+        // written while it exported merged in, so the directory is the document
+        // at one log number.
+        const exported = await exportRecordLogDocument({
+            client: {
+                requestSegment: () => client.requestDocumentSnapshot(appId, documentId),
+                getSegment: (segmentId) => client.getDocumentSnapshot(appId, documentId, segmentId),
+                listSegments: () => client.listDocumentSnapshots(appId, documentId, { limit: 100 }),
+                exportChain: () => client.exportDocumentChain(appId, documentId),
+                download: (artifactPath) => client.downloadDocumentArtifact(appId, artifactPath),
+            },
+            documentId,
+            docDir,
+        });
+        stateBytes = exported.bytes;
     }
     else {
         const stateResult = await client.exportDocumentState(appId, documentId);
@@ -2391,15 +2403,16 @@ async function exportSingleDocument(client, appId, documentId, outputDir, includ
     fs.writeFileSync(path.join(docDir, "permissions.json"), JSON.stringify(permissionsExport, null, 2));
     // 5. Aliases (user-scoped only)
     const aliases = (Array.isArray(aliasResult) ? aliasResult : aliasResult?.aliases || []).filter((a) => (a.scope || a.aliasScope) === "user");
-    // 6. Write metadata. A large document says so here as well as in
-    //    `chain.json`: the format decides how the artifact has to be installed,
-    //    and an import that reads only `metadata.json` must not mistake one for
-    //    a legacy document (#2816).
+    // 6. Write metadata. A large or record-log document says so here as well
+    //    as in `chain.json`: the format decides how the artifact has to be
+    //    installed, and an import that reads only `metadata.json` must not
+    //    mistake one for a legacy document (#2816, #4310).
     const metadata = {
         documentId: docMeta.documentId || documentId,
         title: docMeta.title,
         tags: docMeta.tags || [],
         ...(Number(docMeta?.documentFormat) === 2 ? { documentFormat: 2 } : {}),
+        ...(Number(docMeta?.documentFormat) === 3 ? { documentFormat: 3 } : {}),
         createdAt: docMeta.createdAt,
         createdBy: docMeta.createdByEmail || docMeta.createdBy,
         aliases: aliases.map((a) => ({
@@ -2476,135 +2489,6 @@ async function readExportBlobList(client, appId, documentId) {
     } while (cursor);
     return blobs;
 }
-/**
- * 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");
-}
 /**
  * One idempotent write of an import, retried through a transient failure
  * (#4148): a blob PUT, a state merge, an artifact upload or an install read.
@@ -2614,109 +2498,21 @@ function retryingImportStep(what, attempt) {
     return withTransientRetry(attempt, (failure, delayMs) => warn(`${what} failed (${failure?.message || "no reason given"}); ` +
         `retrying in ${delayMs / 1000}s`));
 }
-/** Upload one chain artifact; the server stores it under a fixed key. */
-function uploadChainArtifact(client, appId, documentId, query, body) {
-    const what = query.kind === "chunk"
-        ? `chunk ${query.index} of ${query.model}`
-        : query.kind === "overlay"
-            ? `the overlay of epoch ${query.epoch}`
-            : "the base snapshot's manifest";
-    return retryingImportStep(`Uploading ${what} of ${documentId}`, () => client.uploadDocumentChainArtifact(appId, documentId, query, body));
-}
-/** How long an install is waited on before the CLI gives up on it. */
-const CHAIN_INSTALL_TIMEOUT_MS = 60 * 60 * 1000;
-/** How often the install's progress is asked for. */
-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);
-    await uploadAndInstallChain(client, appId, docDir, documentId, chain);
-    await awaitChainInstall(client, appId, documentId);
-}
-/** Upload every artifact of the chain, then start installing it. */
-async function uploadAndInstallChain(client, appId, docDir, documentId, chain) {
-    // The base's manifest and chunks. The manifest names the chunks, so nothing
-    // here has to walk the directory and guess what belongs to the build.
-    if (chain.base) {
-        const manifestPath = path.join(docDir, "snapshot", "manifest.json");
-        const manifestBytes = fs.readFileSync(manifestPath);
-        await uploadChainArtifact(client, 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 uploadChainArtifact(client, 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 uploadChainArtifact(client, appId, documentId, { kind: "overlay", epoch: overlay.epoch }, fs.readFileSync(path.join(docDir, "epochs", `${overlay.epoch}.yjs`)));
-    }
-    await uploadChainArtifact(client, appId, documentId, { kind: "overlay", epoch: chain.epoch }, fs.readFileSync(path.join(docDir, "current.yjs")));
-    await client.installDocumentChain(appId, documentId, {
-        base: chain.base
-            ? { epoch: chain.base.epoch, buildId: chain.base.buildId }
-            : null,
-        overlays: chain.overlays.map((overlay) => overlay.epoch),
-        currentEpoch: chain.epoch,
-    });
-}
-/**
- * Wait for the document's chain install to finish.
- *
- * The install runs on the document's alarm, a bounded tick at a time, so it
- * is waited on rather than awaited: reporting "imported" while the records
- * are still arriving is the failure this whole path exists to avoid.
- */
-async function awaitChainInstall(client, appId, documentId) {
-    const deadline = Date.now() + CHAIN_INSTALL_TIMEOUT_MS;
-    for (;;) {
-        const status = await retryingImportStep(`Reading the chain install of ${documentId}`, () => client.getDocumentChainInstall(appId, documentId));
-        const install = status?.install;
-        if (install?.state === "complete")
-            return;
-        if (install?.state === "failed") {
-            throw new Error(`Document ${documentId}: installing its chain failed — ` +
-                `${install.error || "no reason given"}. The document is incomplete; ` +
-                `re-run the import to install it again.`);
-        }
-        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);
 }
+/**
+ * Whether `docDir` holds a large document's (format 2) export: the
+ * `chain.json` its export wrote last, or a `metadata.json` naming format 2.
+ */
+function isLargeDocumentExport(docDir) {
+    if (fs.existsSync(path.join(docDir, "chain.json")))
+        return true;
+    return Number(readExportMetadata(docDir)?.documentFormat) === 2;
+}
 /** Read an export directory's `metadata.json`, or null when it has none. */
 function readExportMetadata(docDir) {
     const metadataPath = path.join(docDir, "metadata.json");
@@ -2930,20 +2726,10 @@ async function importSingleDocument(client, appId, docDir, overwrite, aliasMode,
     // A root-marked export is never restored under its exported id: that id is
     // the SOURCE user's root document. It goes to the target user's own root
     // instead, per the plan made before this run wrote anything (#3135).
-    //
-    // Decided BEFORE the chain artifact below is read: a root export's chain is
-    // installed into the target user's root, never under its exported id, and
-    // only when the plan says so (#4195) — reading it here would fail the whole
-    // run over an artifact a refused or skipped plan never touches.
     if (isRootDocumentExport(metadata.tags)) {
         await importRootDocument(client, appId, docDir, metadata, rootPlan, overwrite, aliasMode, dryRun, summary, progress);
         return;
     }
-    // A large document's data is the chain, not `document.yjs` (#2816), and it
-    // is installed rather than replayed. Vouched for before anything is created.
-    const isLargeDocument = largeDocumentArtifactAt(docDir);
-    if (isLargeDocument)
-        readChainArtifact(docDir, documentId);
     // `--dry-run` decides from the same facts the real run does (#3096), so a
     // preview never promises a skip that the run turns into a merge: it looks
     // the document up as well, and only the writes below are withheld.
@@ -2952,16 +2738,6 @@ async function importSingleDocument(client, appId, docDir, overwrite, aliasMode,
     progress.exists = exists;
     const wouldSkip = dryRun ? "[dry-run] Would skip" : "Skipping";
     if (exists && !overwrite) {
-        // A same-id document of the other format is not one this import created:
-        // the format is decided at creation and never migrated. It is skipped
-        // before any read of what it lacks, which its format's endpoints refuse.
-        if ((Number(existing?.documentFormat) === 2) !== isLargeDocument) {
-            warn(`${wouldSkip} ${documentId}: already exists as a ` +
-                `${isLargeDocument ? "legacy" : "large"} document, and the export ` +
-                `is a ${isLargeDocument ? "large" : "legacy"} one`);
-            summary.skipped++;
-            return;
-        }
         // A document an earlier run created and did not finish is completed, not
         // skipped (#4148): what it lacks of the export is read from the server,
         // and only that is written. A document that lacks nothing, or that holds
@@ -2969,24 +2745,9 @@ async function importSingleDocument(client, appId, docDir, overwrite, aliasMode,
         // re-uploads to one already imported, nor writes to one it did not start.
         // With an owner named, the export's user aliases are among what it can
         // lack.
-        const gaps = await findImportGaps(client, appId, docDir, documentId, isLargeDocument, ownerUserId
+        const gaps = await findImportGaps(client, appId, docDir, documentId, ownerUserId
             ? { userId: ownerUserId, aliasMode, exported: metadata.aliases }
             : undefined);
-        // Never installed and not empty: a document of its own, which the server
-        // would refuse to install into.
-        const skipHoldingRecords = (held = "holds records of its own") => {
-            warn(`${wouldSkip} ${documentId}: already exists and ${held}, so its ` +
-                `large-document export cannot be installed into it`);
-            summary.skipped++;
-        };
-        if (gaps === "holds-records") {
-            skipHoldingRecords();
-            return;
-        }
-        if (gaps === "rotated-epoch") {
-            skipHoldingRecords("has rotated an epoch of its own");
-            return;
-        }
         if (gaps) {
             if (dryRun) {
                 info(`[dry-run] Would complete document ${documentId} ` +
@@ -2996,22 +2757,6 @@ async function importSingleDocument(client, appId, docDir, overwrite, aliasMode,
             }
             if (gaps.state)
                 await importExportedState(client, appId, docDir, documentId);
-            if (gaps.chain === "install") {
-                try {
-                    await uploadAndInstallChain(client, appId, docDir, documentId, readChainArtifact(docDir, documentId));
-                }
-                catch (refusal) {
-                    // The server's own check, at the first artifact and before it
-                    // stores anything: it decides when the document changed after the
-                    // reads above.
-                    if (refusal?.code !== "DOCUMENT_NOT_IMPORTABLE")
-                        throw refusal;
-                    skipHoldingRecords();
-                    return;
-                }
-            }
-            if (gaps.chain)
-                await awaitChainInstall(client, appId, documentId);
             await uploadExportedBlobs(client, appId, documentId, docDir, gaps.blobs, summary);
             await restoreExportedAliases(client, appId, documentId, ownerUserId ? { ...metadata, aliases: gaps.aliases } : metadata, ownerUserId, aliasMode, summary);
             summary.completed++;
@@ -3019,17 +2764,8 @@ async function importSingleDocument(client, appId, docDir, overwrite, aliasMode,
                 `imported ${describeImportGaps(gaps)}`);
             return;
         }
-        // `--overwrite` merges a legacy document's state — but a large document is
-        // INSTALLED, and the server refuses to install a chain into a document
-        // that already holds records (`assertDocumentIsImportable`), so the remedy
-        // 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)`);
+        warn(`${wouldSkip} ${documentId}: already exists (use --overwrite to merge ` +
+            `the exported state into it)`);
         summary.skipped++;
         return;
     }
@@ -3042,8 +2778,7 @@ async function importSingleDocument(client, appId, docDir, overwrite, aliasMode,
             summary.created++;
         return;
     }
-    // Create document if it doesn't exist. The format is decided at creation and
-    // never migrated, so a large document has to be created as one (#2816).
+    // Create document if it doesn't exist.
     //
     // Tags go back exactly as `metadata.json` recorded them (#3096): an export
     // is a faithful record of what the document is, and editing the list on the
@@ -3053,7 +2788,6 @@ async function importSingleDocument(client, appId, docDir, overwrite, aliasMode,
             title: metadata.title || "Imported Document",
             documentId,
             tags: metadata.tags,
-            ...(isLargeDocument ? { documentFormat: 2 } : {}),
             ...(ownerUserId ? { createdBy: ownerUserId } : {}),
         });
         progress.exists = true;
@@ -3062,14 +2796,7 @@ async function importSingleDocument(client, appId, docDir, overwrite, aliasMode,
     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 {
-        await importExportedState(client, appId, docDir, documentId);
-    }
+    await importExportedState(client, appId, docDir, documentId);
     await uploadExportedBlobs(client, appId, documentId, docDir, exportedBlobsOf(docDir), summary);
     // Permissions are exported for reference but not restored during import.
     // The importing admin is the new owner; sharing is managed in the target app.
@@ -3136,10 +2863,6 @@ function describeImportGaps(gaps) {
     const parts = [];
     if (gaps.state)
         parts.push("its state");
-    if (gaps.chain === "install")
-        parts.push("its chain");
-    if (gaps.chain === "await")
-        parts.push("its chain (installing)");
     if (gaps.blobs.length > 0) {
         parts.push(`${gaps.blobs.length} blob${gaps.blobs.length === 1 ? "" : "s"}`);
     }
@@ -3182,76 +2905,36 @@ function holdsYjsUpdate(held, exported) {
     return Y.equalSnapshots(before, Y.snapshot(doc));
 }
 /**
- * Read what an existing document lacks of its export (#4148): the gaps, null
- * when there is nothing a re-run may write, or `"holds-records"` /
- * `"rotated-epoch"` for a large document that was never imported into and
- * holds records or has rotated an epoch of its own.
+ * Read what an existing document lacks of its export (#4148): the gaps, or
+ * null when there is nothing a re-run may write.
  *
- * A legacy document is only completed when it is the one an earlier run
- * started: it holds no state at all — what `createDocument` leaves, and what a
- * failed `import/state` leaves, since the server stores the merge before it
- * applies it — or it already holds the exported state, and then only its
- * blobs can be missing. A document holding state of its own is not written
- * to at all, neither merged into nor given blobs or aliases: that is
- * `--overwrite`'s decision, not a re-run's. A large document's chain is
- * missing unless its install completed; the server takes a new install over a
- * failed one, but never one into a document with records and no install
- * behind them. Blobs are compared by id against every page the document
- * lists. When `aliasOwner` is given, the export's user aliases are read as
- * well: one the owner holds for another document counts as missing only when
- * the alias mode would move it.
+ * A document is only completed when it is the one an earlier run started: it
+ * holds no state at all — what `createDocument` leaves, and what a failed
+ * `import/state` leaves, since the server stores the merge before it applies
+ * it — or it already holds the exported state, and then only its blobs can be
+ * missing. A document holding state of its own is not written to at all,
+ * neither merged into nor given blobs or aliases: that is `--overwrite`'s
+ * decision, not a re-run's. Blobs are compared by id against every page the
+ * document lists. When `aliasOwner` is given, the export's user aliases are
+ * read as well: one the owner holds for another document counts as missing
+ * only when the alias mode would move it.
  */
-async function findImportGaps(client, appId, docDir, documentId, isLargeDocument, aliasOwner) {
+async function findImportGaps(client, appId, docDir, documentId, aliasOwner) {
     let state = false;
-    let chain = null;
     const exported = exportedBlobsOf(docDir);
-    if (isLargeDocument) {
-        const status = await retryingImportStep(`Reading the chain install of ${documentId}`, () => client.getDocumentChainInstall(appId, documentId));
-        const installState = status?.install?.state;
-        if (installState === "installing")
-            chain = "await";
-        else if (installState !== "complete")
-            chain = "install";
-        // Read, not discovered by the first artifact upload, so `--dry-run`
-        // reaches the same decision the run does.
-        // `tableModels` is every model the document's records table holds.
-        if (chain === "install" && !status?.install) {
-            const schema = await retryingImportStep(`Reading the records of ${documentId}`, () => client.getDocumentSchema(appId, documentId));
-            if (Array.isArray(schema?.tableModels) && schema.tableModels.length > 0) {
-                return "holds-records";
-            }
-            // The server refuses one past its first epoch as well. Its open epoch is
-            // the one its chain ends on; a chain it cannot describe has sealed an
-            // epoch, which only a rotation does.
-            let openEpoch;
-            try {
-                const described = await retryingImportStep(`Reading the epoch of ${documentId}`, () => client.exportDocumentChain(appId, documentId));
-                openEpoch = Number(described?.epoch);
-            }
-            catch (refusal) {
-                if (refusal?.code !== "EXPORT_CHAIN_INCOMPLETE")
-                    throw refusal;
-                return "rotated-epoch";
-            }
-            if (openEpoch !== 1)
-                return "rotated-epoch";
-        }
+    const exportedState = exportedStateOf(docDir);
+    // An export with no state and no blobs can still carry a root's aliases.
+    const exportsUserAliases = (Array.isArray(aliasOwner?.exported) ? aliasOwner.exported : [])
+        .some((alias) => alias?.aliasScope === "user");
+    if (!exportedState && exported.length === 0 && !exportsUserAliases)
+        return null;
+    const held = await retryingImportStep(`Reading the state of ${documentId}`, () => client.exportDocumentState(appId, documentId));
+    const heldState = Buffer.from(String(held?.state ?? ""), "base64");
+    if (isEmptyYjsUpdate(heldState)) {
+        state = exportedState !== null;
     }
-    else {
-        const exportedState = exportedStateOf(docDir);
-        // An export with no state and no blobs can still carry a root's aliases.
-        const exportsUserAliases = (Array.isArray(aliasOwner?.exported) ? aliasOwner.exported : [])
-            .some((alias) => alias?.aliasScope === "user");
-        if (!exportedState && exported.length === 0 && !exportsUserAliases)
-            return null;
-        const held = await retryingImportStep(`Reading the state of ${documentId}`, () => client.exportDocumentState(appId, documentId));
-        const heldState = Buffer.from(String(held?.state ?? ""), "base64");
-        if (isEmptyYjsUpdate(heldState)) {
-            state = exportedState !== null;
-        }
-        else if (!exportedState || !holdsYjsUpdate(heldState, exportedState)) {
-            return null;
-        }
+    else if (!exportedState || !holdsYjsUpdate(heldState, exportedState)) {
+        return null;
     }
     let blobs = [];
     if (exported.length > 0) {
@@ -3261,8 +2944,8 @@ async function findImportGaps(client, appId, docDir, documentId, isLargeDocument
     const aliases = aliasOwner
         ? await findMissingAliases(client, appId, documentId, aliasOwner)
         : [];
-    return state || chain || blobs.length > 0 || aliases.length > 0
-        ? { state, chain, blobs, aliases }
+    return state || blobs.length > 0 || aliases.length > 0
+        ? { state, blobs, aliases }
         : null;
 }
 /** The form the server stores an alias key in. */
@@ -3314,8 +2997,7 @@ async function listedBlobIds(client, appId, documentId) {
 }
 /**
  * Restore a root-marked export into the target user's own root document
- * (#3135), by format (#4195): a legacy export's state is merged into a legacy
- * root, a large-document export's chain is installed into a large root.
+ * (#3135): its state is merged into the target user's root.
  *
  * The exported id is never created and never looked up: it is the source
  * user's root id, which means nothing in this app. Everything — the Yjs state,
@@ -3342,7 +3024,6 @@ async function importRootDocument(client, appId, docDir, metadata, plan, overwri
             ...(targetRootDocId ? { targetRootDocId } : {}),
             action,
             ...(reason ? { reason } : {}),
-            ...(targetFormat === 2 ? { documentFormat: 2 } : {}),
         });
     };
     if (!plan || plan.action === "refused") {
@@ -3358,21 +3039,17 @@ async function importRootDocument(client, appId, docDir, metadata, plan, overwri
     // What a root an earlier run started still lacks (#4148), when completing it.
     let gaps = null;
     if (plan.action === "skip") {
-        // The root exists and `--overwrite` was not given. A legacy root an
-        // earlier run started and did not finish is completed, by the same rule
-        // as any legacy document: it holds no state, or already holds the
-        // exported state. A root holding state of its own — its user's — is never
-        // merged into. A large root is skipped as before: a chain is installed
-        // only into a root that holds nothing, which `--overwrite` asks for.
+        // The root exists and `--overwrite` was not given. A root an earlier run
+        // started and did not finish is completed, by the same rule as any
+        // document: it holds no state, or already holds the exported state. A
+        // root holding state of its own — its user's — is never merged into.
         progress.exists = true;
-        const found = plan.targetFormat === 2
-            ? null
-            : await findImportGaps(client, appId, docDir, targetRootDocId, false, {
-                userId: plan.targetUserId,
-                aliasMode,
-                exported: metadata.aliases,
-            });
-        if (!found || typeof found === "string") {
+        const found = await findImportGaps(client, appId, docDir, targetRootDocId, {
+            userId: plan.targetUserId,
+            aliasMode,
+            exported: metadata.aliases,
+        });
+        if (!found) {
             const reason = plan.reason ||
                 `the root document of ${plan.owner} already exists ` +
                     `(${targetRootDocId}); use --overwrite to merge the exported ` +
@@ -3384,7 +3061,6 @@ async function importRootDocument(client, appId, docDir, metadata, plan, overwri
         }
         gaps = found;
     }
-    const install = plan.mode === "install";
     if (dryRun) {
         if (gaps) {
             info(`[dry-run] Would complete root document export ${exportedDocumentId} ` +
@@ -3394,19 +3070,14 @@ async function importRootDocument(client, appId, docDir, metadata, plan, overwri
             report("completed", targetRootDocId);
         }
         else if (plan.action === "create") {
-            info(install
-                ? `[dry-run] Would create the root document (large) for ` +
-                    `${plan.owner} and install root document export ` +
-                    `${exportedDocumentId} into it`
-                : `[dry-run] Would create the root document for ${plan.owner} and ` +
-                    `apply root document export ${exportedDocumentId} to it`);
+            info(`[dry-run] Would create the root document for ${plan.owner} and ` +
+                `apply root document export ${exportedDocumentId} to it`);
             summary.created++;
             report("created", undefined, undefined, plan.targetFormat);
         }
         else {
-            info(`[dry-run] Would ${install ? "install" : "apply"} root document ` +
-                `export ${exportedDocumentId} ${install ? "into" : "to"} ` +
-                `${plan.owner}'s root document ${plan.targetRootDocId}`);
+            info(`[dry-run] Would apply root document export ${exportedDocumentId} ` +
+                `to ${plan.owner}'s root document ${plan.targetRootDocId}`);
             summary.updated++;
             report("applied", plan.targetRootDocId, undefined, plan.targetFormat);
         }
@@ -3448,8 +3119,7 @@ async function importRootDocument(client, appId, docDir, metadata, plan, overwri
         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 ${install ? "install" : "merge"} the exported ` +
-                `content into it`;
+                `--overwrite to merge the exported content into it`;
             warn(`Skipping ${exportedDocumentId}: ${reason}`);
             summary.skipped++;
             report("skipped", targetRootDocId, reason, minted.targetFormat);
@@ -3459,13 +3129,7 @@ async function importRootDocument(client, appId, docDir, metadata, plan, overwri
     progress.exists = true;
     // Only content moves. The target root keeps its own id, title, tags and
     // permissions — the ensure path already granted the owner read-write.
-    if (install) {
-        // A large root's content is its chain, installed — the server refuses a
-        // root that already holds records or has rotated, as it does for any
-        // large document (#4195).
-        await importLargeDocumentChain(client, appId, docDir, targetRootDocId);
-    }
-    else if (!gaps || gaps.state) {
+    if (!gaps || gaps.state) {
         await importExportedState(client, appId, docDir, targetRootDocId);
     }
     // The blobId is preserved: a document's own references travel by blobId,
@@ -3475,7 +3139,6 @@ async function importRootDocument(client, appId, docDir, metadata, plan, overwri
     // so they are restored without `--owner` — the target user is already known.
     // A completion restores only the ones the root is missing.
     await restoreExportedAliases(client, appId, targetRootDocId, gaps ? { ...metadata, aliases: gaps.aliases } : metadata, plan.targetUserId, aliasMode, summary);
-    const verb = install ? "installed" : "applied";
     if (gaps) {
         summary.completed++;
         report("completed", targetRootDocId);
@@ -3486,44 +3149,14 @@ async function importRootDocument(client, appId, docDir, metadata, plan, overwri
     else if (created) {
         summary.created++;
         report("created", targetRootDocId, undefined, plan.targetFormat);
-        info(`Created root document ${targetRootDocId} for ${plan.owner} and ${verb} ` +
-            `root document export ${exportedDocumentId} ${install ? "into" : "to"} it`);
+        info(`Created root document ${targetRootDocId} for ${plan.owner} and applied ` +
+            `root document export ${exportedDocumentId} to it`);
     }
     else {
         summary.updated++;
         report("applied", targetRootDocId, undefined, plan.targetFormat);
-        info(`${install ? "Installed" : "Applied"} root document export ` +
-            `${exportedDocumentId} ${install ? "into" : "to"} ${plan.owner}'s ` +
-            `root document ${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