@anchrd/intel-api 0.24.0 → 0.26.0

package/README.md

@@ -75,12 +75,29 @@ values it stops with `Error: GATE_URL and GATE_SERVICE_KEY must be set.` before
 It declares five interfaces — `intel`, `nodes`, `flows`, `tools`, `mcp` — with the functions listed
 under *Permission, layer one* below. It is idempotent and safe to repeat after an upgrade.
 
-⚠️ **`bootstrap` declares interfaces and changes no grant.** It creates the permissions an
-administrator can hand out; it hands out none of them. This is step 8, and it is why a fresh
-installation shows an empty screen to everybody including the person who installed it.
+⚠️ **`bootstrap` hands out no grant, and it takes none away as long as the declared list does not
+change.** It creates the permissions an administrator can hand out; it hands out none of them. This
+is step 8, and it is why a fresh installation shows an empty screen to everybody including the
+person who installed it.
 
-⚠️ It also never revokes. An interface an older version declared stays declared in Gate; that is
-harmless, and removing one is an act in Gate, by hand.
+⚠️ **But a function that falls out of a still-declared interface takes its grants with it.**
+Declaring is an upsert that REPLACES an interface's function list, and Gate deletes every grant on a
+function the new list no longer names. So an upgrade that retires a function also retires every role
+assignment on it — against a running installation that is a change to who may do what, not a
+read. `bootstrap` reads the catalog before it writes and names each one as it goes:
+
+```text
+Removed flows:approve from Gate; every grant on it was deleted with it.
+Declared 5 Intel interfaces in Gate.
+```
+
+A run that dropped nothing says so instead: `No declared function was dropped, so Gate deleted no
+grant.` And if the catalog cannot be read, `bootstrap` writes nothing at all rather than delete
+grants it would then be unable to name.
+
+⚠️ It never revokes a whole **interface**. One an older version declared stays declared in Gate:
+`bootstrap` writes only the handles it names, so an interface outside that list keeps its functions
+and its grants. That is harmless, and removing one is an act in Gate, by hand.
 
 ### 4. Copy the migrations out of `node_modules`
 
@@ -135,6 +152,19 @@ FAIL TOOL_SOURCE_ORIGINS is missing
 FAIL INTEL_SESSION_SECRET must contain at least 32 bytes
 ```
 
+It also compares the Gate interfaces **in both directions**. A function or a whole interface Gate
+carries that this version of Intel no longer declares is reported as a `NOTE`, never as a `FAIL`:
+nothing is broken by it, and a check one knows red stops being read. Each note names the surplus,
+why it went, and what to do about it:
+
+```text
+NOTE Gate carries flows:approve, which Intel does not declare — the approval node is gone (#73).
+NOTE Gate carries the interface knowledge (read, write), which Intel does not declare — the whole interface became `nodes` (#152, after #125).
+NOTE The next `intel bootstrap` removes a surplus function and every grant on it (#474). Take the grant away in Gate first if anybody should keep it.
+NOTE `bootstrap` never touches an interface Intel does not declare, so a surplus one stays until somebody removes it in Gate by hand — which takes its grants with it.
+OK Intel packages, configuration, and Gate interfaces are ready.
+```
+
 ⚠️ **`doctor` cannot see the Worker's secrets.** It answers about the shell it runs in, so it says
 nothing about whether the deployed Worker is configured. `GET /health` on the deployed Worker
 answers `{"status":"ok"}`; a Worker missing one of the five required variables answers
@@ -255,10 +285,10 @@ grants them.
 
 | Interface | Functions |
 |---|---|
-| `intel` | `use`, `admin` |
+| `intel` | `admin` |
 | `nodes` | `read`, `create`, `write`, `share` |
 | `flows` | `read`, `create`, `write`, `publish`, `run`, `share` |
-| `tools` | `read`, `test`, `execute`, `admin` |
+| `tools` | `read`, `test`, `execute` |
 | `mcp` | `connect` |
 
 A missing capability answers **`403`**, and the screen says a permission is missing.

package/dist/adapters/db/db-flows.js

@@ -607,6 +607,22 @@ export function createFlowRepository(deps) {
                 .all();
             return (result.results ?? []).map((row) => row.resource_id);
         },
+        // ⚠️ No actor and no `archived_at` condition, both on purpose (#509). The question is whether
+        // the row is still there at all, and archiving keeps it — a reference to something archived is
+        // not broken, it is waiting for a restore. The caller has already asked the visibility door for
+        // every one of these ids and reaches this only for the ones it answered nothing for.
+        //
+        // ⚠️ An empty list short-circuits rather than building `IN ()`, which SQLite refuses to parse.
+        async existingNodes(nodeIds) {
+            const wanted = [...new Set(nodeIds)];
+            if (wanted.length === 0)
+                return [];
+            const result = await deps.db
+                .prepare(`SELECT id FROM nodes WHERE id IN (${wanted.map(() => "?").join(", ")}) ORDER BY id`)
+                .bind(...wanted)
+                .all();
+            return (result.results ?? []).map((row) => row.id);
+        },
         async publishedCallees(flowId) {
             const row = await deps.db
                 .prepare(`SELECT flow.title AS title, version.graph_json AS graph_json

package/dist/auth/auth.js

@@ -218,28 +218,55 @@ export function createBrowserAuth(deps) {
                     ? `/auth/connect?returnTo=${encodeURIComponent(pending.returnTo)}`
                     : withConnectError(pending.returnTo));
             }
-            const tokens = await deps.oauth.exchange({
-                issuer: pending.kind === "connection-pending" ? pending.issuer : gateIssuer,
-                clientId: pending.clientId,
-                callbackUrl: requestUrl,
-                redirectUri,
-                resource: pending.kind === "connection-pending" ? pending.resource : deps.resource,
-                codeVerifier: pending.codeVerifier,
-                state: pending.state,
-            });
-            if (pending.kind === "connection-pending") {
-                await deps.portalTokens.write(pending.userId, {
-                    accessToken: tokens.accessToken,
-                    refreshToken: tokens.refreshToken ?? null,
-                    expiresAt: deps.now().getTime() + Math.max(30, tokens.expiresIn) * 1_000,
-                    issuer: pending.issuer,
+            // ⚠️ Everything below runs with the handoff READ, and that is the whole difference between
+            // this catch and the one on the route (#444): here a failure knows where the person was
+            // going, and for a connection handoff it still holds their parked Intel session. The route
+            // can only send somebody to a decided screen, so whatever can be answered here is answered
+            // here — the token exchange, the portal token write and the sealing of the new session all
+            // used to end as a bare 500 in JSON, in the middle of a sign-in.
+            try {
+                const tokens = await deps.oauth.exchange({
+                    issuer: pending.kind === "connection-pending" ? pending.issuer : gateIssuer,
                     clientId: pending.clientId,
-                    resource: pending.resource,
+                    callbackUrl: requestUrl,
+                    redirectUri,
+                    resource: pending.kind === "connection-pending" ? pending.resource : deps.resource,
+                    codeVerifier: pending.codeVerifier,
+                    state: pending.state,
                 });
-                return await restore(pending.user, pending.returnTo, pending.returnTo);
+                if (pending.kind === "connection-pending") {
+                    await deps.portalTokens.write(pending.userId, {
+                        accessToken: tokens.accessToken,
+                        refreshToken: tokens.refreshToken ?? null,
+                        expiresAt: deps.now().getTime() + Math.max(30, tokens.expiresIn) * 1_000,
+                        issuer: pending.issuer,
+                        clientId: pending.clientId,
+                        resource: pending.resource,
+                    });
+                    return await restore(pending.user, pending.returnTo, pending.returnTo);
+                }
+                const session = await userSession(pending.clientId, tokens);
+                return redirect(pending.returnTo, sessionCookie(await deps.sessions.seal(session), secure, (session.expiresAt - deps.now().getTime()) / 1_000));
+            }
+            catch (error) {
+                // The exception is the only thing that still holds the reason: what the reader gets is a
+                // fixed marker, and a marker names a KIND of failure, never its cause (#93).
+                reportUnexpectedError(error);
+                // `portal_sign_in_failed` is the marker `/auth/connect` already writes for exactly this
+                // situation, so nothing new is invented here and no screen has to learn a word. The Tools
+                // screen reads it as "the sign-in is broken", which is true of both handoffs — a Gate login
+                // that could not be exchanged is no more the reader's doing than a portal one.
+                if (pending.kind === "connection-pending") {
+                    // Every other way out of the callback puts the parked Intel session back, and so does
+                    // this one: the portal attempt must never cost somebody their Intel login.
+                    return await restore(pending.user, pending.returnTo, withConnectError(pending.returnTo, "portal_sign_in_failed"));
+                }
+                // A Gate login handoff parks nothing, so there is no session to put back — and the cookie
+                // is spent either way: its verifier belongs to an authorization code that has now been
+                // used. Clearing it is what makes the next attempt start a fresh one instead of replaying
+                // this one.
+                return redirect(withConnectError(pending.returnTo, "portal_sign_in_failed"), sessionCookie("", secure, 0));
             }
-            const session = await userSession(pending.clientId, tokens);
-            return redirect(pending.returnTo, sessionCookie(await deps.sessions.seal(session), secure, (session.expiresAt - deps.now().getTime()) / 1_000));
         },
         logout() {
             return redirect("/", sessionCookie("", secure, 0));

package/dist/build/build.js

@@ -13,6 +13,42 @@ const IntelConfig = z.strictObject({
 const Catalog = z.record(z.string(), z.string());
 const defaultTheme = `/* Generated by \`intel build\`. Intel defaults are active. */\n`;
 const defaultLogo = `export const customLogoUrl: string | null = null;\n`;
+// The `_headers` file of Workers Assets, written INTO THE BUILD OUTPUT (#543, sibling of
+// anchrd/gate#329).
+//
+// Without it every asset answers with the platform default `public, max-age=0, must-revalidate`,
+// and `public` lets a browser store an ERROR answer too. A `403` that appears once during setup is
+// then replayed on every navigation WITHOUT a request leaving the browser — invisible in the worker
+// log, in the Cloudflare Access log, in the firewall and in Cloudflare Analytics, while `curl`
+// against the same address keeps answering `200`. The second rule matters more here than in Gate:
+// the UI ships 1.9 MB of fingerprinted assets that are revalidated on every navigation today.
+//
+// ⚠️ `! Cache-Control` is not decoration, and the naive two-rule form from the ticket is WRONG.
+// A request matching several rules inherits ALL their headers, and a header named twice is joined
+// with a comma. Measured against `wrangler dev` 4.112.0 with both spellings side by side:
+//   without the detach   /assets/app.js → `no-store, public, max-age=31536000, immutable`
+//   with the detach      /assets/app.js → `public, max-age=31536000, immutable`
+// The joined value carries `no-store`, so those 1.9 MB would never be cached at all — the exact
+// opposite of the second rule's purpose.
+//
+// ⚠️ It has to be written into the TEMPORARY directory, before `replaceDir`. The next run's
+// `--emptyOutDir` applies to that directory, so a file placed into the live outDir afterwards
+// survives exactly one build. And `packages/ui/public/` is no way either: the `files` field of
+// @anchrd/intel-ui does not list `public`, so the file would look right in the repository and never
+// reach a customer.
+//
+// The three `cache-control` writes in this package do not contradict it: `auth/auth.ts` (redirect),
+// `http/http.ts` (zipResponse, attachment bytes) all answer `no-store` under `/auth/*` and `/api/*`,
+// which the assets layer never sees. Nothing serves an SPA route under `/assets/`, so the
+// `immutable` rule cannot swallow one.
+const headersFile = `# Generated by \`intel build\` — do not edit by hand.
+/*
+  Cache-Control: no-store
+
+/assets/*
+  ! Cache-Control
+  Cache-Control: public, max-age=31536000, immutable
+`;
 // Customer paths from intel.json are written into generated CSS and TypeScript comments. A path
 // containing `*/` or a newline would close the comment early, leaving broken output or — in
 // custom-logo.ts — customer-controlled text outside the comment and inside the UI bundle.
@@ -130,6 +166,9 @@ export function createBuild(deps) {
                     deps.log(`Error: Intel UI build exited with ${exitCode}.`);
                     return 1;
                 }
+                // Into the temporary directory, not into outDir — see `headersFile`. Vite has just emptied
+                // and refilled this directory; anything written here travels with the swap.
+                await deps.writeTextFile(`${temporaryOutDir}/_headers`, headersFile);
                 await deps.replaceDir(temporaryOutDir, location.outDir);
                 deps.log(`Intel UI built at ${location.outDir}.`);
                 return 0;

package/dist/bundle/bundle.js

@@ -7,9 +7,33 @@ 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). The manifest says so,
-// because a backup that is silent about what it does not hold will be trusted with exactly that.
-const Excluded = ["version-history", "grants", "flow-runs", "archived-nodes"];
+/**
+ * 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
@@ -336,6 +360,15 @@ export function createBundle(deps) {
     }
     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");
@@ -351,6 +384,27 @@ export function createBundle(deps) {
             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);
@@ -371,6 +425,30 @@ export function createBundle(deps) {
         }
         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,
@@ -387,19 +465,38 @@ export function createBundle(deps) {
             // 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",
+                    mediaType: version.mediaType ?? "application/octet-stream",
                     path,
                 },
-                content: {
-                    type: "stream",
-                    load: async () => version === null ? null : await deps.content.getStream(version.contentKey),
-                },
+                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
@@ -425,6 +522,27 @@ export function createBundle(deps) {
                 : { 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 {
@@ -474,9 +592,7 @@ export function createBundle(deps) {
         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((flow) => flow.publishedVersionId ?? flow.currentVersionId)
-                .filter((id) => id !== null);
+            const versionIds = visible.map(exportedVersionId).filter((id) => id !== null);
             for (const version of await deps.flows.getVersions(versionIds)) {
                 flowVersions.set(version.id, version);
             }
@@ -518,7 +634,7 @@ export function createBundle(deps) {
                     continue;
                 }
                 if (item.flow !== null) {
-                    const versionId = item.flow.publishedVersionId ?? item.flow.currentVersionId;
+                    const versionId = exportedVersionId(item.flow);
                     entries.push(plannedFlow(item.flow, versionId === null ? undefined : flowVersions.get(versionId), directory, used));
                 }
             }
@@ -574,18 +690,25 @@ export function createBundle(deps) {
                     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 stream = await entry.content.load();
-                if (stream === null) {
-                    file.push(new Uint8Array(0), true);
-                    await writer.ready;
-                    continue;
-                }
                 const reader = stream.getReader();
                 for (;;) {
                     const { done, value } = await reader.read();
@@ -648,7 +771,11 @@ export function createBundle(deps) {
             if (isFolder)
                 folderIdByPath.set(entry.path.endsWith("/") ? entry.path : `${entry.path}/`, newId);
             let body = null;
-            if (!isFolder) {
+            // ⚠️ 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}`);
@@ -739,6 +866,9 @@ export function createBundle(deps) {
             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 {
@@ -756,7 +886,7 @@ export function createBundle(deps) {
             if (!flow || flow.archivedAt !== null) {
                 throw new IntelError(404, "flow_not_found", "Flow was not found");
             }
-            const versionId = flow.publishedVersionId ?? flow.currentVersionId;
+            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
@@ -933,9 +1063,14 @@ export function createBundle(deps) {
                      */
                     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") {
-                    const bytes = entry.body ?? new Uint8Array(0);
-                    version = versionRowFor(entry, bytes, entry.mediaType ?? "application/octet-stream", await deps.hash(bytes), null);
+                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);
@@ -1035,7 +1170,13 @@ export function createBundle(deps) {
             for (const version of versions) {
                 await deps.indexing.enqueue(version.id);
             }
-            return { nodes: nodes.length, flows: flows.length, rootNodeIds, replayed: false };
+            return {
+                nodes: nodes.length,
+                flows: flows.length,
+                rootNodeIds,
+                replayed: false,
+                excluded: Excluded,
+            };
         },
     };
 }