@anchrd/intel 0.59.0

package/dist/bundle/bundle.js

@@ -0,0 +1,1194 @@
+import { Unzip, UnzipInflate, Zip, ZipDeflate, ZipPassThrough } from "fflate";
+import { BundleImportResult, BundleManifest, BundleManifestFilename, } from "../contract/bundle.js";
+import { FlowGraph } from "../contract/flow.js";
+import { BlockNoteMediaType, DocumentLinkInlineType, } from "../contract/node.js";
+import { TableMediaType } from "../contract/table.js";
+import { documentLinkTargets } from "../nodes/document-links/document-links.js";
+import { parseCsv } from "../shared/csv/csv.js";
+import { IntelError } from "../shared/intel-error/intel-error.js";
+import { plainTitle } from "../shared/plain-title/plain-title.js";
+/**
+ * What every bundle leaves out, by decision rather than by accident (#136, ADR-0006). The manifest
+ * says so, because a backup that is silent about what it does not hold will be trusted with exactly
+ * that.
+ *
+ * ⚠️ ONE list, read by both halves of the round trip: the export writes it into `manifest.json`,
+ * and the import answers with it in `BundleImportResult.excluded` (#433). The import does NOT read
+ * the word back out of the manifest it was handed — a bundle claiming `excluded: []` would
+ * otherwise make the import report that nothing was left behind, and a naked folder carries no
+ * manifest to ask at all. Every one of the five holds for every import this build performs: a node
+ * arrives with `sequence: 1` and nothing older, an import mints no grants, it starts no runs,
+ * nothing it creates is archived, and a published flow's graph is the one that was published.
+ *
+ * ⚠️ `unpublished-flow-changes` is a CONSTANT of the build like the other four, not a report about
+ * this particular bundle (#585). It says what a bundle never carries — the edits made to a flow
+ * after it was published — in the same way `version-history` says so for a node with a single
+ * version. A list that named only the losses this one export happens to suffer would be a different
+ * kind of statement, and the import could not make it at all: it answers before it knows what is in
+ * the zip, and from a naked folder it never finds out.
+ */
+const Excluded = [
+    "version-history",
+    "grants",
+    "flow-runs",
+    "archived-nodes",
+    "unpublished-flow-changes",
+];
+/**
+ * A title as a file name. Titles are free text and zip paths are not: a separator would move the
+ * entry, a control character corrupts the archive listing, and a trailing dot breaks extraction on
+ * Windows. What cannot be kept is replaced rather than refused — an export must not fail because of
+ * how something was named.
+ */
+function sanitizeName(title) {
+    const cleaned = title
+        // biome-ignore lint/suspicious/noControlCharactersInRegex: control characters are exactly what has to go
+        .replace(/[\u0000-\u001f\u007f]/g, "")
+        .replace(/[/\\]/g, "-")
+        .trim()
+        .replace(/^\.+/, "")
+        .replace(/[. ]+$/, "")
+        .slice(0, 150);
+    return cleaned.length > 0 ? cleaned : "untitled";
+}
+// A name that is free in this directory. Case-insensitive, because the zip will be extracted onto
+// filesystems where "Notes.md" and "notes.md" are the same file and the second would overwrite the
+// first without a word.
+function uniqueName(used, base, extension) {
+    const candidate = base.toLowerCase().endsWith(extension.toLowerCase())
+        ? base.slice(0, base.length - extension.length)
+        : base;
+    const first = `${candidate}${extension}`;
+    if (!used.has(first.toLowerCase())) {
+        used.add(first.toLowerCase());
+        return first;
+    }
+    for (let counter = 2;; counter++) {
+        const next = `${candidate} (${counter})${extension}`;
+        if (!used.has(next.toLowerCase())) {
+            used.add(next.toLowerCase());
+            return next;
+        }
+    }
+}
+// ── Import (#137) ───────────────────────────────────────────────────────────────────────────────
+// The import limits, explicit rather than discovered (#137). The zip stream and the unpacked total
+// are both bounded because the Worker holds an entry in memory while it lands: a bundle is parsed
+// where it arrives, and an isolate has 128 MB for everything. The old 15 MB base64 door stays for
+// single attachments; these carry a real bundle several times that size.
+export const MaxImportZipBytes = 64 * 1024 * 1024;
+export const MaxImportEntryBytes = 48 * 1024 * 1024;
+const MaxImportTotalBytes = 96 * 1024 * 1024;
+const MaxImportEntries = 1000;
+// The same key shape `nodes.ts` writes: keys are stored, never derived back, so agreeing on the
+// format costs nothing while a second format would split the bucket for no reason.
+function contentKeyFor(nodeId, versionId) {
+    return `nodes/${nodeId}/versions/${versionId}`;
+}
+// Files archivers add that nobody filed: importing them would put macOS bookkeeping into the tree.
+const JunkNames = new Set([".DS_Store", "Thumbs.db"]);
+function isJunkPath(path) {
+    const segments = path.replace(/\/$/, "").split("/");
+    return segments[0] === "__MACOSX" || JunkNames.has(segments[segments.length - 1] ?? "");
+}
+// A zip entry name is attacker-controlled text, and "../" in one is how an archive writes outside
+// its directory. Nothing here touches a filesystem, but a traversal segment would still corrupt
+// the parent lookup, so the path is refused rather than interpreted.
+function requireSafePath(path) {
+    if (path.includes("\\") || path.startsWith("/")) {
+        throw new IntelError(400, "import_invalid_path", `Bundle path is not usable: ${path}`);
+    }
+    for (const segment of path.replace(/\/$/, "").split("/")) {
+        if (segment === "" || segment === "." || segment === "..") {
+            throw new IntelError(400, "import_invalid_path", `Bundle path is not usable: ${path}`);
+        }
+    }
+}
+function concatChunks(chunks, size) {
+    const joined = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        joined.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return joined;
+}
+/**
+ * The whole zip, read incrementally: the compressed stream is fed chunk by chunk and every entry
+ * is collected as it completes, so the peak cost is the unpacked entries — bounded above — and
+ * never compressed-plus-unpacked at once.
+ *
+ * ⚠️ A truncated archive does not fail loudly in fflate: entries simply never finish. The open
+ * counter turns that silence into the refusal it is — a bundle that ends mid-entry imports
+ * nothing (#137, Abbruch-Test).
+ */
+async function readZip(source) {
+    const files = new Map();
+    const directories = new Set();
+    let failure = null;
+    let unpackedTotal = 0;
+    let entryCount = 0;
+    let openEntries = 0;
+    const invalid = () => new IntelError(400, "import_invalid_bundle", "The zip archive could not be read");
+    const unzip = new Unzip((file) => {
+        if (failure)
+            return;
+        const name = file.name;
+        if (name.endsWith("/")) {
+            directories.add(name);
+            return;
+        }
+        entryCount += 1;
+        if (entryCount > MaxImportEntries) {
+            failure = new IntelError(413, "import_too_many_entries", `The bundle exceeds ${MaxImportEntries} entries`);
+            return;
+        }
+        openEntries += 1;
+        const chunks = [];
+        let size = 0;
+        file.ondata = (error, chunk, final) => {
+            if (failure)
+                return;
+            if (error) {
+                failure = invalid();
+                return;
+            }
+            if (chunk) {
+                size += chunk.length;
+                unpackedTotal += chunk.length;
+                if (size > MaxImportEntryBytes) {
+                    failure = new IntelError(413, "import_entry_too_large", `A bundle entry exceeds ${MaxImportEntryBytes} bytes unpacked: ${name}`);
+                    return;
+                }
+                if (unpackedTotal > MaxImportTotalBytes) {
+                    failure = new IntelError(413, "import_too_large", `The bundle exceeds ${MaxImportTotalBytes} bytes unpacked`);
+                    return;
+                }
+                chunks.push(chunk);
+            }
+            if (final) {
+                openEntries -= 1;
+                files.set(name, concatChunks(chunks, size));
+            }
+        };
+        try {
+            file.start();
+        }
+        catch {
+            failure = invalid();
+        }
+    });
+    unzip.register(UnzipInflate);
+    const push = (chunk, final) => {
+        try {
+            unzip.push(chunk, final);
+        }
+        catch {
+            failure = failure ?? invalid();
+        }
+    };
+    if (source instanceof Uint8Array) {
+        if (source.length > MaxImportZipBytes) {
+            throw new IntelError(413, "import_too_large", `The zip exceeds ${MaxImportZipBytes} bytes`);
+        }
+        push(source, true);
+    }
+    else {
+        const reader = source.getReader();
+        let compressed = 0;
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            compressed += value.length;
+            if (compressed > MaxImportZipBytes) {
+                throw new IntelError(413, "import_too_large", `The zip exceeds ${MaxImportZipBytes} bytes`);
+            }
+            push(value, false);
+            if (failure)
+                throw failure;
+        }
+        push(new Uint8Array(0), true);
+    }
+    if (failure)
+        throw failure;
+    if (openEntries > 0 || (files.size === 0 && directories.size === 0))
+        throw invalid();
+    return { files, directories };
+}
+const decoder = new TextDecoder("utf-8", { fatal: true });
+function decodeText(body, path) {
+    try {
+        return decoder.decode(body);
+    }
+    catch {
+        throw new IntelError(400, "import_invalid_text", `Bundle entry is not UTF-8: ${path}`);
+    }
+}
+function depthOf(path) {
+    return path.replace(/\/$/, "").split("/").length;
+}
+function directoryOf(path) {
+    const trimmed = path.replace(/\/$/, "");
+    const cut = trimmed.lastIndexOf("/");
+    return cut === -1 ? "" : trimmed.slice(0, cut + 1);
+}
+// What a file extension says a naked upload is (#137): the three kinds a name can carry, and
+// attachment for everything else. Only used without a manifest — a manifest already says.
+function nakedKindOf(name) {
+    const lower = name.toLowerCase();
+    if (lower.endsWith(".md")) {
+        return { kind: "document", mediaType: "text/markdown", title: name.slice(0, -3) };
+    }
+    if (lower.endsWith(".csv")) {
+        return { kind: "table", mediaType: TableMediaType, title: name.slice(0, -4) };
+    }
+    // ⚠️ `.board.json` had its own rule here until #390 and deliberately does not any more. This is
+    // the NAKED-folder path — a directory somebody picked, with no manifest — so a file called
+    // `plan.board.json` is a JSON file on a disk, and keeping it as an attachment preserves it. A
+    // real export is a different matter: its manifest declares the kind, and that is where such an
+    // entry is refused by name.
+    return { kind: "attachment", mediaType: guessedMediaType(lower), title: name };
+}
+const KnownMediaTypes = {
+    ".pdf": "application/pdf",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".svg": "image/svg+xml",
+    ".txt": "text/plain",
+    ".json": "application/json",
+    ".zip": "application/zip",
+};
+function guessedMediaType(lowerName) {
+    const dot = lowerName.lastIndexOf(".");
+    return ((dot === -1 ? undefined : KnownMediaTypes[lowerName.slice(dot)]) ?? "application/octet-stream");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+// The link rewrite of #137: every `documentLink` inline element whose target the bundle carried is
+// pointed at the node the import just made; a link to a node outside the bundle stays as written.
+// Tolerant like `documentLinkTargets`: what is not recognised is carried over unchanged.
+function remapDocumentLinks(content, idMap) {
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch {
+        return content;
+    }
+    function walk(value) {
+        if (Array.isArray(value)) {
+            for (const entry of value)
+                walk(entry);
+            return;
+        }
+        if (!isRecord(value))
+            return;
+        if (value.type === DocumentLinkInlineType && isRecord(value.props)) {
+            const target = value.props.nodeId;
+            if (typeof target === "string" && idMap.has(target)) {
+                value.props.nodeId = idMap.get(target);
+            }
+        }
+        // `blocks` is the document's own top level; `content` and `children` are where a block hides
+        // inline elements — the same three places `documentLinkTargets` reads.
+        walk(value.blocks);
+        walk(value.content);
+        walk(value.children);
+    }
+    walk(parsed);
+    return JSON.stringify(parsed);
+}
+/**
+ * The graph rewrite of #137: link nodes point at the imported copies of what they named, a subflow
+ * calls the imported copy of its callee. References to things outside the bundle stay untouched.
+ *
+ * ⚠️ A `pinned` sub-flow version cannot survive the remap of its callee: the pinned ID names a row
+ * of the OLD installation's history, which this import deliberately does not recreate. The call
+ * falls back to `latest` — the draft default — and publishing will pin it anew.
+ */
+function remapFlowGraph(graph, idMap) {
+    return {
+        ...graph,
+        nodes: graph.nodes.map((node) => {
+            if ((node.kind === "folder" ||
+                node.kind === "document" ||
+                node.kind === "upload" ||
+                node.kind === "table") &&
+                idMap.has(node.configuration.resourceId)) {
+                return {
+                    ...node,
+                    configuration: {
+                        ...node.configuration,
+                        resourceId: idMap.get(node.configuration.resourceId),
+                    },
+                };
+            }
+            if (node.kind === "subflow" && idMap.has(node.configuration.flowId)) {
+                return {
+                    ...node,
+                    configuration: {
+                        flowId: idMap.get(node.configuration.flowId),
+                        version: node.configuration.version.mode === "pinned"
+                            ? { mode: "latest" }
+                            : node.configuration.version,
+                    },
+                };
+            }
+            return node;
+        }),
+    };
+}
+function flowGraphJson(version) {
+    // A flow that was never saved has no graph; its entry is an empty file rather than an invented
+    // graph, and the import creates the same empty flow back.
+    return version === undefined ? "" : JSON.stringify(version.graph, null, 2);
+}
+export function createBundle(deps) {
+    // Flow visibility is the flow repository's question and takes its actor shape. `canRun` gates
+    // starting runs, which no export does, so it is answered with the conservative constant.
+    function asFlowActor(actor) {
+        return {
+            id: actor.id,
+            email: actor.email,
+            canRun: false,
+            ...(actor.isAdmin === undefined ? {} : { isAdmin: actor.isAdmin }),
+        };
+    }
+    async function tableCsv(nodeId) {
+        const keys = await deps.repository.listVersionContentKeys(nodeId);
+        // ⚠️ `some` on an empty list is false, so no segments at all used to walk past the guard below
+        // and return `[].join("")` — the empty string, written into the zip as a file of zero bytes
+        // (#534). A table that has never been defined no longer reaches this function at all: it has no
+        // current version, and `plannedNode` marks it absent instead. An empty list HERE therefore means
+        // something else — a current version whose segments are gone — which is the loss the guard below
+        // already names, and it deserves the same answer rather than a silently empty file.
+        if (keys.length === 0) {
+            throw new IntelError(500, "content_missing", "Version content is missing");
+        }
+        const segments = await Promise.all(keys.map(async (key) => await deps.content.get(key)));
+        if (segments.some((segment) => segment === null)) {
+            throw new IntelError(500, "content_missing", "Version content is missing");
+        }
+        return segments.join("");
+    }
+    function textLoader(contentKey) {
+        return async () => {
+            const body = await deps.content.get(contentKey);
+            if (body === null) {
+                throw new IntelError(500, "content_missing", "Version content is missing");
+            }
+            return body;
+        };
+    }
+    /**
+     * The bytes of an attachment version, or the same refusal the text path has always given (#560).
+     *
+     * ⚠️ A `contentKey` in the row and nothing behind it in R2 is data LOSS, and the attachment path
+     * was the one path that answered it with silence: `getStream` returned `null`, the zip got a file
+     * of zero bytes, and the export reported success. Whoever filed that zip away as a backup learns
+     * what it holds when they restore it — the one moment nothing can be done about it any more.
+     *
+     * This is deliberately NOT the `absence` answer. "Never uploaded" is a state of the node and
+     * travels in the manifest; "the object is gone" is a broken installation, and a bundle must not
+     * be able to describe it as if it were fine. Same distinction as `textLoader` and `tableCsv`.
+     */
+    function streamLoader(contentKey) {
+        return async () => {
+            const stream = await deps.content.getStream(contentKey);
+            if (stream === null) {
+                throw new IntelError(500, "content_missing", "Version content is missing");
+            }
+            return stream;
+        };
+    }
+    function plannedNode(row, directory, used) {
+        const { node, version } = row;
+        const base = sanitizeName(node.title);
+        if (node.kind === "folder") {
+            const name = uniqueName(used, base, "");
+            const path = `${directory}${name}/`;
+            return {
+                manifest: {
+                    id: node.id,
+                    kind: "folder",
+                    title: node.title,
+                    description: node.description,
+                    mediaType: null,
+                    path,
+                },
+                content: { type: "folder" },
+            };
+        }
+        if (node.kind === "table") {
+            const path = `${directory}${uniqueName(used, base, ".csv")}`;
+            // ⚠️ A table with no current version has never been given a header, and for a table the
+            // canonical content IS the CSV: there is nothing to write. It used to travel as a file of zero
+            // bytes, which the holder of the zip cannot tell apart from a table whose content was lost on
+            // the way — the very case `tableCsv` refuses as `content_missing`. One file, two meanings, no
+            // way to read which (#534).
+            //
+            // ⚠️ The entry STAYS in the manifest, and that is the half that matters: dropping it would
+            // take the node's title, its description and its place in the tree out of the backup too, and
+            // the import would recreate a subtree with a node missing from it without anybody noticing.
+            // What travels instead is the node without bytes, plus the word for what is not there.
+            if (version === null) {
+                return {
+                    manifest: {
+                        id: node.id,
+                        kind: "table",
+                        title: node.title,
+                        description: node.description,
+                        mediaType: TableMediaType,
+                        path,
+                        absence: "no-content",
+                    },
+                    content: { type: "absent" },
+                };
+            }
+            return {
+                manifest: {
+                    id: node.id,
+                    kind: "table",
+                    title: node.title,
+                    description: node.description,
+                    mediaType: TableMediaType,
+                    path,
+                },
+                content: { type: "text", load: async () => await tableCsv(node.id) },
+            };
+        }
+        if (node.kind === "attachment") {
+            // Original bytes under the original name: an attachment's title IS its file name, so no
+            // extension is imposed on it.
+            const path = `${directory}${uniqueName(used, base, "")}`;
+            // ⚠️ An attachment with no current version was created and never uploaded to, and for an
+            // attachment the canonical content IS the bytes: there is nothing to write. It used to travel
+            // as a file of zero bytes — the same one file with two meanings the table branch above
+            // refuses, and here the second meaning is a lost R2 object (#560).
+            //
+            // ⚠️ The entry STAYS in the manifest for the same reason it does for a table: dropping it
+            // would take the node's title, its description and its place in the tree out of the backup,
+            // and the import would rebuild a subtree with a node missing from it and say nothing.
+            if (version === null) {
+                return {
+                    manifest: {
+                        id: node.id,
+                        kind: "attachment",
+                        title: node.title,
+                        description: node.description,
+                        mediaType: "application/octet-stream",
+                        path,
+                        absence: "no-content",
+                    },
+                    content: { type: "absent" },
+                };
+            }
+            return {
+                manifest: {
+                    id: node.id,
+                    kind: "attachment",
+                    title: node.title,
+                    description: node.description,
+                    mediaType: version.mediaType ?? "application/octet-stream",
+                    path,
+                },
+                content: { type: "stream", load: streamLoader(version.contentKey) },
+            };
+        }
+        // ⚠️ A row of a kind this build no longer makes — an `agent` or a `board` written before #390
+        // — falls through to the document branch and travels as its raw body. Deliberately forgiving:
+        // refusing here would make one leftover row enough to stop a whole subtree from being exported,
+        // and the file it produces is exactly the bytes that were stored. The IMPORT is where such a
+        // bundle is turned away, by name.
+        // A document: markdown stays `.md`, a BlockNote body is JSON and says so with its name.
+        const mediaType = version?.mediaType ?? "text/markdown";
+        const extension = mediaType === BlockNoteMediaType ? ".json" : ".md";
+        const path = `${directory}${uniqueName(used, base, extension)}`;
+        return {
+            manifest: {
+                id: node.id,
+                kind: "document",
+                title: node.title,
+                description: node.description,
+                mediaType,
+                path,
+            },
+            content: version === null
+                ? { type: "text", load: async () => "" }
+                : { type: "text", load: textLoader(version.contentKey) },
+        };
+    }
+    /**
+     * Which graph of a flow travels: the PUBLISHED one when the flow has one, the draft otherwise.
+     * Three call sites read it through this function rather than spelling the fallback out, because
+     * it is one decision and not three (#585).
+     *
+     * ⚠️ For a flow that was published and edited afterwards, this deliberately leaves the newer draft
+     * behind — and that is NOT the `version-history` case, which is why `Excluded` names it with a
+     * word of its own. The draft is the newest state there is; what decides against it is that the
+     * import cannot carry both. It creates rather than restores (ADR-0006): every flow arrives as a
+     * draft with one version and `publishedVersionId: null`, so "published v1 plus draft v2" has no
+     * shape on the far side, and carrying both would be flow version history — the thing that ADR
+     * refuses for exactly the reasons it lists.
+     *
+     * Of the two single answers the published one wins because it is the one that was IN EFFECT. A
+     * draft need never have been validated — publishing is what checks a graph — so moving the draft
+     * instead would replace a running process with somebody's unfinished edit, silently, at the one
+     * moment nobody can compare against the source any more.
+     */
+    function exportedVersionId(flow) {
+        return flow.publishedVersionId ?? flow.currentVersionId;
+    }
+    function plannedFlow(flow, version, directory, used) {
+        const path = `${directory}${uniqueName(used, sanitizeName(flow.title), ".json")}`;
+        return {
+            manifest: {
+                id: flow.id,
+                kind: "flow",
+                title: flow.title,
+                description: flow.description,
+                mediaType: "application/json",
+                path,
+            },
+            content: { type: "text", load: async () => flowGraphJson(version) },
+        };
+    }
+    /**
+     * The plan of one export: every entry with its path, parents before children.
+     *
+     * The tree is walked from the chosen root through what `listVisibleSubtree` answered — one
+     * statement carrying the same `allowed` predicate every other read uses, so a node without read
+     * is neither in the zip nor mentioned in the manifest (#136). Flows ride along by the folder they
+     * are filed in, only when the caller holds `flows/read` at all, and their graph is the published
+     * version when there is one — the frozen state — falling back to the current draft.
+     */
+    async function plan(actor, rootId) {
+        if (rootId !== null) {
+            const root = await deps.repository.getVisible(actor, rootId);
+            // An archived node is out of every bundle by decision, and "archived" must not be
+            // distinguishable from "absent" through this door either.
+            if (!root || root.archivedAt !== null) {
+                throw new IntelError(404, "node_not_found", "Node was not found");
+            }
+        }
+        const rows = await deps.repository.listVisibleSubtree(actor, rootId);
+        const byParent = new Map();
+        const included = new Set(rows.map((row) => row.node.id));
+        for (const row of rows) {
+            // The export root's own parent is outside the bundle; it anchors at the zip root.
+            const key = row.node.id === rootId || !row.node.parentId || !included.has(row.node.parentId)
+                ? null
+                : row.node.parentId;
+            const level = byParent.get(key) ?? [];
+            level.push(row);
+            byParent.set(key, level);
+        }
+        const flowsByParent = new Map();
+        const flowVersions = new Map();
+        if (actor.canReadFlows) {
+            const folderIds = new Set(rows.filter((row) => row.node.kind === "folder").map((row) => row.node.id));
+            const visible = (await deps.flows.listVisible(asFlowActor(actor))).filter((flow) => flow.parentId === null ? rootId === null : folderIds.has(flow.parentId));
+            const versionIds = visible.map(exportedVersionId).filter((id) => id !== null);
+            for (const version of await deps.flows.getVersions(versionIds)) {
+                flowVersions.set(version.id, version);
+            }
+            for (const flow of visible) {
+                const level = flowsByParent.get(flow.parentId) ?? [];
+                level.push(flow);
+                flowsByParent.set(flow.parentId, level);
+            }
+        }
+        const entries = [];
+        // Folders first, then titles, the order the tree itself draws — so the zip listing reads like
+        // the sidebar. Ties fall back to the id to stay deterministic.
+        function walk(parentKey, directory) {
+            const level = [
+                ...(byParent.get(parentKey) ?? []).map((row) => ({ row, flow: null })),
+                ...(flowsByParent.get(parentKey) ?? []).map((flow) => ({
+                    row: null,
+                    flow,
+                })),
+            ].sort((left, right) => {
+                const leftFolder = left.row?.node.kind === "folder" ? 0 : 1;
+                const rightFolder = right.row?.node.kind === "folder" ? 0 : 1;
+                const leftTitle = left.row?.node.title ?? left.flow?.title ?? "";
+                const rightTitle = right.row?.node.title ?? right.flow?.title ?? "";
+                const leftId = left.row?.node.id ?? left.flow?.id ?? "";
+                const rightId = right.row?.node.id ?? right.flow?.id ?? "";
+                return (leftFolder - rightFolder ||
+                    leftTitle.toLowerCase().localeCompare(rightTitle.toLowerCase()) ||
+                    leftId.localeCompare(rightId));
+            });
+            const used = new Set();
+            for (const item of level) {
+                if (item.row !== null) {
+                    const entry = plannedNode(item.row, directory, used);
+                    entries.push(entry);
+                    if (item.row.node.kind === "folder") {
+                        walk(item.row.node.id, entry.manifest.path);
+                    }
+                    continue;
+                }
+                if (item.flow !== null) {
+                    const versionId = exportedVersionId(item.flow);
+                    entries.push(plannedFlow(item.flow, versionId === null ? undefined : flowVersions.get(versionId), directory, used));
+                }
+            }
+        }
+        walk(null, "");
+        return entries;
+    }
+    function manifestOf(rootId, entries) {
+        return {
+            version: 1,
+            exportedAt: deps.now().toISOString(),
+            rootId,
+            entries: entries.map((entry) => entry.manifest),
+            excluded: Excluded,
+        };
+    }
+    /**
+     * The zip as a stream. fflate writes into a TransformStream whose readable side is the response
+     * body; the pump pushes one entry at a time and waits for `writer.ready` between chunks, so the
+     * memory in flight stays one chunk deep however large an attachment is — the whole point of
+     * streaming rather than assembling (#136).
+     */
+    function zipStream(manifest, entries) {
+        const { readable, writable } = new TransformStream();
+        const writer = writable.getWriter();
+        const zip = new Zip((error, chunk, final) => {
+            if (error) {
+                void writer.abort(error).catch(() => undefined);
+                return;
+            }
+            void writer.write(chunk).catch(() => undefined);
+            if (final)
+                void writer.close().catch(() => undefined);
+        });
+        const encoder = new TextEncoder();
+        async function pushText(name, text) {
+            // Text bodies deflate well and are bounded by the save limit; attachments go through the
+            // store path below instead, because recompressing archives and images buys nothing.
+            const file = new ZipDeflate(name, { level: 6 });
+            zip.add(file);
+            file.push(encoder.encode(text), true);
+            await writer.ready;
+        }
+        async function pump() {
+            // The manifest goes first so a streaming reader — the import — knows what it is walking into
+            // before the first content byte.
+            await pushText(BundleManifestFilename, JSON.stringify(manifest, null, 2));
+            for (const entry of entries) {
+                if (entry.content.type === "folder") {
+                    const folder = new ZipPassThrough(entry.manifest.path);
+                    zip.add(folder);
+                    folder.push(new Uint8Array(0), true);
+                    await writer.ready;
+                    continue;
+                }
+                // Nothing is written for it — not even an empty file, which is the whole point (#534). The
+                // manifest carries the node and says why its path is unoccupied.
+                if (entry.content.type === "absent")
+                    continue;
+                if (entry.content.type === "text") {
+                    await pushText(entry.manifest.path, await entry.content.load());
+                    continue;
+                }
+                // ⚠️ No `null` branch here any more, and its removal is the repair (#560): it wrote a file
+                // of zero bytes for "the loader has nothing", which was true both for an attachment nobody
+                // ever uploaded to and for one whose object had left R2. The first is now `absent` above
+                // and never reaches this loop; the second throws out of `load()` and aborts the whole zip,
+                // which is what a backup that cannot be written is supposed to do.
+                //
+                // The loader runs BEFORE the entry is added, so a refusal leaves no half-opened file
+                // behind in the zip that nothing will ever terminate.
+                const stream = await entry.content.load();
+                const file = new ZipPassThrough(entry.manifest.path);
+                zip.add(file);
+                const reader = stream.getReader();
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    file.push(value);
+                    await writer.ready;
+                }
+                file.push(new Uint8Array(0), true);
+                await writer.ready;
+            }
+            zip.end();
+        }
+        pump().catch((error) => {
+            void writer.abort(error).catch(() => undefined);
+        });
+        return readable;
+    }
+    // The manifest, when the zip carries one. A file that merely wears the name — a naked folder
+    // with somebody's own manifest.json in it — is left to the naked path; a file that clearly
+    // means to be a bundle manifest but does not parse is a broken bundle and refuses the import.
+    function readImportManifest(files) {
+        const raw = files.get(BundleManifestFilename);
+        if (raw === undefined)
+            return { manifest: null, text: null };
+        let json;
+        let text;
+        try {
+            text = decodeText(raw, BundleManifestFilename);
+            json = JSON.parse(text);
+        }
+        catch {
+            return { manifest: null, text: null };
+        }
+        if (!isRecord(json) || json.version === undefined || json.entries === undefined) {
+            return { manifest: null, text: null };
+        }
+        const parsed = BundleManifest.safeParse(json);
+        if (!parsed.success) {
+            throw new IntelError(400, "import_invalid_manifest", "manifest.json does not match the bundle manifest contract");
+        }
+        return { manifest: parsed.data, text };
+    }
+    // The plan a manifest dictates: kinds and titles from its entries, hierarchy from its paths.
+    // Sorted by path depth so a parent folder's new ID exists before its children ask for it — the
+    // same order the atomic insert needs (see `importTree`).
+    function importPlanFromManifest(manifest, files) {
+        const sorted = [...manifest.entries].sort((left, right) => depthOf(left.path) - depthOf(right.path));
+        const folderIdByPath = new Map();
+        const entries = [];
+        for (const entry of sorted) {
+            requireSafePath(entry.path);
+            const isFolder = entry.kind === "folder";
+            const parentPath = directoryOf(entry.path);
+            const parentNewId = parentPath === "" ? null : (folderIdByPath.get(parentPath) ?? null);
+            if (parentPath !== "" && parentNewId === null) {
+                throw new IntelError(400, "import_bundle_incomplete", `The manifest names no folder for: ${entry.path}`);
+            }
+            const newId = deps.id();
+            if (isFolder)
+                folderIdByPath.set(entry.path.endsWith("/") ? entry.path : `${entry.path}/`, newId);
+            let body = null;
+            // ⚠️ An entry that declares an `absence` names a path with nothing at it ON PURPOSE, so the
+            // zip is complete rather than broken (#534). Without this the export written by this very
+            // build would refuse its own import — and the node it describes arrives the way it left: a
+            // table with a title, a place in the tree and no content.
+            if (!isFolder && entry.absence === undefined) {
+                const found = files.get(entry.path);
+                if (found === undefined) {
+                    throw new IntelError(400, "import_bundle_incomplete", `The manifest names a file the zip does not carry: ${entry.path}`);
+                }
+                body = found;
+            }
+            entries.push({
+                kind: entry.kind,
+                oldId: entry.id,
+                newId,
+                parentNewId,
+                title: entry.title,
+                description: entry.description,
+                mediaType: entry.mediaType,
+                body,
+                path: entry.path,
+            });
+        }
+        return entries;
+    }
+    // The plan a naked folder allows: hierarchy from the paths, kinds from the extensions (#137),
+    // no IDs and therefore nothing to remap. Directories a zip only implies — a file three levels
+    // deep without its folders spelled out — are created all the same.
+    function importPlanNaked(contents) {
+        const folderPaths = new Set();
+        const filePaths = [];
+        for (const directory of contents.directories) {
+            if (isJunkPath(directory))
+                continue;
+            requireSafePath(directory);
+            folderPaths.add(directory.endsWith("/") ? directory : `${directory}/`);
+        }
+        for (const path of contents.files.keys()) {
+            if (isJunkPath(path))
+                continue;
+            requireSafePath(path);
+            filePaths.push(path);
+        }
+        for (const path of [...folderPaths, ...filePaths]) {
+            const segments = path.replace(/\/$/, "").split("/");
+            for (let depth = 1; depth < segments.length; depth++) {
+                folderPaths.add(`${segments.slice(0, depth).join("/")}/`);
+            }
+        }
+        const folderIdByPath = new Map();
+        const entries = [];
+        for (const path of [...folderPaths].sort((left, right) => depthOf(left) - depthOf(right))) {
+            const newId = deps.id();
+            folderIdByPath.set(path, newId);
+            const segments = path.replace(/\/$/, "").split("/");
+            entries.push({
+                kind: "folder",
+                oldId: null,
+                newId,
+                parentNewId: segments.length === 1
+                    ? null
+                    : folderIdByPath.get(`${segments.slice(0, -1).join("/")}/`),
+                title: segments[segments.length - 1],
+                description: null,
+                mediaType: null,
+                body: null,
+                path,
+            });
+        }
+        for (const path of filePaths.sort((left, right) => depthOf(left) - depthOf(right))) {
+            const segments = path.split("/");
+            const name = segments[segments.length - 1];
+            const derived = nakedKindOf(name);
+            entries.push({
+                kind: derived.kind,
+                oldId: null,
+                newId: deps.id(),
+                parentNewId: segments.length === 1
+                    ? null
+                    : folderIdByPath.get(`${segments.slice(0, -1).join("/")}/`),
+                title: derived.title.length > 0 ? derived.title.slice(0, 240) : name.slice(0, 240),
+                description: null,
+                mediaType: derived.mediaType,
+                body: contents.files.get(path) ?? null,
+                path,
+            });
+        }
+        return entries;
+    }
+    function replayResult(metadata) {
+        return BundleImportResult.parse({
+            nodes: typeof metadata.nodes === "number" ? metadata.nodes : 0,
+            flows: typeof metadata.flows === "number" ? metadata.flows : 0,
+            rootNodeIds: Array.isArray(metadata.rootNodeIds) ? metadata.rootNodeIds : [],
+            replayed: true,
+            // Not read out of the stored metadata: a replay answers for an import this build performed,
+            // and the list is what this build leaves behind rather than something an earlier row said.
+            excluded: Excluded,
+        });
+    }
+    return {
+        async exportSubtree(actor, rootId) {
+            const entries = await plan(actor, rootId);
+            const manifest = manifestOf(rootId, entries);
+            const rootEntry = rootId === null ? null : entries.find((entry) => entry.manifest.id === rootId);
+            const filename = rootEntry === null || rootEntry === undefined
+                ? "intel-export.zip"
+                : `${sanitizeName(rootEntry.manifest.title)}.zip`;
+            return { filename, stream: zipStream(manifest, entries) };
+        },
+        async exportFlow(actor, flowId) {
+            const flow = await deps.flows.getVisible(asFlowActor(actor), flowId);
+            if (!flow || flow.archivedAt !== null) {
+                throw new IntelError(404, "flow_not_found", "Flow was not found");
+            }
+            const versionId = exportedVersionId(flow);
+            const version = versionId === null ? undefined : (await deps.flows.getVersions([versionId]))[0];
+            const entries = [plannedFlow(flow, version, "", new Set())];
+            // A single flow's bundle is rooted at the flow itself: the manifest names it as the root the
+            // same way a single node export does.
+            const manifest = manifestOf(flow.id, entries);
+            return { filename: `${sanitizeName(flow.title)}.zip`, stream: zipStream(manifest, entries) };
+        },
+        async manifest(actor, rootId) {
+            return manifestOf(rootId, await plan(actor, rootId));
+        },
+        /**
+         * One bundle in, one new subtree out (#137, phase 1): always new nodes, never a merge, never
+         * an overwrite — a second import of the same bundle is a second subtree, and only the
+         * idempotency key makes a RETRY of the same request not be one.
+         *
+         * The order of operations is the whole safety story: authorize, parse and decide everything,
+         * write the R2 bodies, then land every row in ONE `db.batch`. The batch is a transaction, so a
+         * half-imported tree cannot exist; R2 objects written for a batch that refused are deleted
+         * again, exactly as `save` treats its single object.
+         */
+        async importBundle(actor, input) {
+            const earlier = await deps.repository.findImportReplay(actor.id, input.idempotencyKey);
+            if (earlier !== null)
+                return replayResult(earlier);
+            if (input.targetNodeId !== null) {
+                const target = await deps.repository.getVisible(actor, input.targetNodeId);
+                if (!target || target.archivedAt !== null) {
+                    throw new IntelError(404, "node_not_found", "Node was not found");
+                }
+                if (target.kind !== "folder") {
+                    throw new IntelError(409, "import_target_not_folder", "Imports land in a folder");
+                }
+                if (!(await deps.repository.can(actor, target.id, "write"))) {
+                    throw new IntelError(403, "node_forbidden", "Target folder cannot be edited");
+                }
+            }
+            const contents = await readZip(input.zip);
+            const { manifest, text: manifestText } = readImportManifest(contents.files);
+            if (manifest !== null)
+                contents.files.delete(BundleManifestFilename);
+            const entries = manifest !== null
+                ? importPlanFromManifest(manifest, contents.files)
+                : importPlanNaked(contents);
+            if (entries.length === 0) {
+                throw new IntelError(400, "import_invalid_bundle", "The bundle holds nothing to import");
+            }
+            if (entries.some((entry) => entry.kind === "flow") && actor.canCreateFlows !== true) {
+                throw new IntelError(403, "permission_required", "Importing a bundle that carries flows needs the flows/create permission");
+            }
+            const idMap = new Map();
+            for (const entry of entries) {
+                if (entry.oldId !== null)
+                    idMap.set(entry.oldId, entry.newId);
+            }
+            const occurredAt = deps.now().toISOString();
+            const nodes = [];
+            const versions = [];
+            const flows = [];
+            const flowVersions = [];
+            // Text bodies and media types per new node, kept for the link pass below.
+            const documentBodies = new Map();
+            const pendingWrites = [];
+            function versionRowFor(entry, content, mediaType, contentHash, segment) {
+                const versionId = deps.id();
+                const contentKey = contentKeyFor(entry.newId, versionId);
+                pendingWrites.push({ key: contentKey, mediaType, body: content });
+                return {
+                    id: versionId,
+                    nodeId: entry.newId,
+                    sequence: 1,
+                    contentKey,
+                    mediaType,
+                    contentHash,
+                    size: typeof content === "string"
+                        ? new TextEncoder().encode(content).byteLength
+                        : content.byteLength,
+                    segment,
+                    createdBy: actor.id,
+                    createdAt: occurredAt,
+                };
+            }
+            for (const entry of entries) {
+                const parentId = entry.parentNewId ?? input.targetNodeId;
+                if (entry.kind === "flow") {
+                    const text = entry.body === null ? "" : decodeText(entry.body, entry.path);
+                    let versionId = null;
+                    if (text.trim().length > 0) {
+                        let graph;
+                        try {
+                            graph = remapFlowGraph(FlowGraph.parse(JSON.parse(text)), idMap);
+                        }
+                        catch {
+                            throw new IntelError(400, "import_invalid_flow", `Bundle entry is not a flow graph: ${entry.path}`);
+                        }
+                        versionId = deps.id();
+                        flowVersions.push({
+                            id: versionId,
+                            flowId: entry.newId,
+                            sequence: 1,
+                            graph,
+                            createdBy: actor.id,
+                            createdAt: occurredAt,
+                        });
+                    }
+                    flows.push({
+                        /**
+                         * ⚠️ **An import never carries a slash command over, and that is not a gap** (#775). A
+                         * prompt name is unique across the whole installation the bundle lands IN, and the
+                         * bundle knows nothing about it: importing a flow offered as `/billing` into a tree
+                         * that already has one would fail the whole import over a name nobody chose here. The
+                         * import brings the content; offering it is a decision somebody makes afterwards, in
+                         * the installation that has to live with the name.
+                         */
+                        promptName: null,
+                        id: entry.newId,
+                        parentId,
+                        title: plainTitle(entry.title),
+                        description: entry.description,
+                        ownerId: actor.id,
+                        currentVersionId: versionId,
+                        // Publishing froze a decision in the OLD installation; the import hands over a draft
+                        // and whoever owns the new tree publishes it anew.
+                        publishedVersionId: null,
+                        createdAt: occurredAt,
+                        updatedAt: occurredAt,
+                        archivedAt: null,
+                    });
+                    continue;
+                }
+                let version = null;
+                if (entry.kind === "document") {
+                    let text = entry.body === null ? "" : decodeText(entry.body, entry.path);
+                    const mediaType = entry.mediaType ?? "text/markdown";
+                    if (text.length > 0 && mediaType === BlockNoteMediaType) {
+                        text = remapDocumentLinks(text, idMap);
+                    }
+                    if (text.length > 0) {
+                        version = versionRowFor(entry, text, mediaType, await deps.hash(text), null);
+                        documentBodies.set(entry.newId, { mediaType, content: text });
+                    }
+                }
+                else if (entry.kind === "table") {
+                    const text = entry.body === null ? "" : decodeText(entry.body, entry.path);
+                    if (text.trim().length > 0) {
+                        const header = parseCsv(text)[0] ?? [];
+                        if (header.length === 0 || header.every((column) => column.trim().length === 0)) {
+                            throw new IntelError(400, "import_invalid_table", `Bundle entry is not a table with a header row: ${entry.path}`);
+                        }
+                        // ⚠️ Distinct column names, read the same way `DefineTableInput` and
+                        // `RedefineTableInput` read them — case-insensitively (#322). Both refuse a duplicate,
+                        // and the import used to walk past both: a table could only enter the tree this way
+                        // with two columns of one name.
+                        //
+                        // The consumer assumes the opposite and says so. `packages/intel/ui/src/node-table` keys its
+                        // header cells and every row cell with the column name and carries the comment
+                        // "Column names are distinct by contract (`DefineTableInput`)" — true for the two write
+                        // paths, and false for this one. Two equal names are two React keys with one value, in
+                        // the header AND in every row.
+                        const seen = new Set(header.map((column) => column.trim().toLowerCase()));
+                        if (seen.size !== header.length) {
+                            throw new IntelError(400, "import_invalid_table", `Bundle entry has two columns of the same name: ${entry.path}`);
+                        }
+                        // The whole file as one snapshot: the same shape a definition or a redefine writes
+                        // (#135), so reading starts here and nothing older is expected to exist.
+                        version = versionRowFor(entry, text, TableMediaType, await deps.hash(text), "snapshot");
+                    }
+                }
+                else if (entry.kind === "board" || entry.kind === "agent") {
+                    /**
+                     * ⚠️ Refused by name, and the name says WHY rather than what the parser tripped over.
+                     *
+                     * Agents and Boards were parked with #385; nothing in this build can hold either kind.
+                     * A bundle that carries one is not malformed — it is a correct export of an installation
+                     * that still had the feature, and the person holding it is usually moving a tree between
+                     * two installations rather than the author of the file. Left to the schema they would get
+                     * `unexpected enum value`, look for a broken file, and find nothing wrong with it.
+                     *
+                     * The refusal names the entry, the kind and the branch the feature is parked on, so the
+                     * answer to "where did my board go" is in the message and not in somebody's memory.
+                     *
+                     * ⚠️ Only a MANIFEST can reach this, because only a manifest declares a kind. A naked
+                     * folder holding a `plan.board.json` imports it as an attachment — see `kindOfFile`.
+                     */
+                    throw new IntelError(400, "import_kind_parked", `Bundle entry “${entry.path}” is a ${entry.kind}, and ${entry.kind}s are not part of this installation any more (anchrd/intel#385). The bundle was exported from a version that still had them; the code is on the branch parked/agents-and-board. Remove the entry from the bundle to import the rest.`);
+                }
+                else if (entry.kind === "attachment" && entry.body !== null) {
+                    // ⚠️ `entry.body === null` reaches here only for a manifest entry that declared an
+                    // absence — a naked folder always has the bytes of the file it names. It used to be read
+                    // as `new Uint8Array(0)` and given a version of zero bytes, which is a DIFFERENT node
+                    // from the one that was exported: the export said "never uploaded to", and the import
+                    // would answer with an upload of nothing. No version is what came out of that
+                    // installation and no version is what goes back in (#560).
+                    version = versionRowFor(entry, entry.body, entry.mediaType ?? "application/octet-stream", await deps.hash(entry.body), null);
+                }
+                if (version !== null)
+                    versions.push(version);
+                nodes.push({
+                    // Not carried over, for the reason the flow half above spells out: the catalogue belongs
+                    // to the installation, not to the bundle (#775).
+                    promptName: null,
+                    id: entry.newId,
+                    parentId,
+                    // Flows took the `continue` above; what reaches here is one of the six node kinds.
+                    kind: entry.kind,
+                    // A manifest title and a file name are both somebody else's text, and an export written
+                    // by an escaping chain carries the entity in both (#202).
+                    title: plainTitle(entry.title),
+                    description: entry.description,
+                    ownerId: actor.id,
+                    currentVersionId: version?.id ?? null,
+                    createdAt: occurredAt,
+                    updatedAt: occurredAt,
+                    archivedAt: null,
+                });
+            }
+            // The link pass: what the imported texts now point at. Targets inside the import are linked
+            // as written — they exist by the same transaction. Targets outside go through the same
+            // visibility question a save asks, so an import cannot mint a link into a part of the tree
+            // its author may not see.
+            const links = [];
+            const importedIds = new Set(nodes.map((node) => node.id));
+            const outsideTargets = new Set();
+            for (const [sourceId, body] of documentBodies) {
+                for (const target of documentLinkTargets(body.mediaType, body.content)) {
+                    if (target === sourceId)
+                        continue;
+                    if (!importedIds.has(target))
+                        outsideTargets.add(target);
+                }
+            }
+            const visibleOutside = new Set(outsideTargets.size === 0
+                ? []
+                : (await deps.repository.resolveVisibleTitles(actor, [...outsideTargets])).map((row) => row.nodeId));
+            for (const [sourceId, body] of documentBodies) {
+                for (const target of documentLinkTargets(body.mediaType, body.content)) {
+                    if (target === sourceId)
+                        continue;
+                    if (importedIds.has(target) || visibleOutside.has(target)) {
+                        links.push({ id: deps.id(), sourceNodeId: sourceId, targetNodeId: target });
+                    }
+                }
+            }
+            const rootNodeIds = nodes
+                .filter((node) => node.parentId === input.targetNodeId)
+                .map((node) => node.id);
+            const metadata = {
+                manifestHash: await deps.hash(manifestText ?? [...contents.files.keys()].sort().join("\n")),
+                nodes: nodes.length,
+                flows: flows.length,
+                rootNodeIds,
+            };
+            // R2 first, rows second, cleanup on refusal — the same discipline every single-version
+            // write in `nodes.ts` follows, over many objects at once.
+            const written = [];
+            try {
+                for (const write of pendingWrites) {
+                    if (typeof write.body === "string") {
+                        await deps.content.put(write.key, write.body, write.mediaType);
+                    }
+                    else {
+                        const copy = new Uint8Array(write.body.byteLength);
+                        copy.set(write.body);
+                        await deps.content.putBytes(write.key, copy.buffer, write.mediaType);
+                    }
+                    written.push(write.key);
+                }
+                const outcome = await deps.repository.importTree({
+                    nodes,
+                    versions,
+                    links,
+                    flows,
+                    flowVersions,
+                    actorId: actor.id,
+                    idempotencyKey: input.idempotencyKey,
+                    auditId: deps.id(),
+                    auditResourceId: input.targetNodeId ?? "root",
+                    metadata,
+                    occurredAt,
+                });
+                if (outcome === "replayed") {
+                    // A racing retry landed first; these objects belong to nobody's rows.
+                    await Promise.all(written.map(async (key) => await deps.content.delete(key).catch(() => undefined)));
+                    const stored = await deps.repository.findImportReplay(actor.id, input.idempotencyKey);
+                    return replayResult(stored ?? {});
+                }
+            }
+            catch (error) {
+                await Promise.all(written.map(async (key) => await deps.content.delete(key).catch(() => undefined)));
+                throw error;
+            }
+            // Derived indexes only after the canonical write stands (#137): the queue reads D1 and R2,
+            // and both now hold what it will find.
+            for (const version of versions) {
+                await deps.indexing.enqueue(version.id);
+            }
+            return {
+                nodes: nodes.length,
+                flows: flows.length,
+                rootNodeIds,
+                replayed: false,
+                excluded: Excluded,
+            };
+        },
+    };
+}