@anchrd/intel-ui 0.19.0 → 0.21.0

package/README.md

@@ -43,6 +43,39 @@ Point `intel.json` at your files:
 Missing assets, non-SVG branding and incomplete language catalogs fail the build rather than
 silently producing a half-branded application.
 
+## What an empty screen means
+
+Most "the UI is broken" reports are one of four situations, and the application distinguishes them
+rather than showing one blank page for all of them. The full explanation of the two permission
+layers is in the
+[`@anchrd/intel-api` README](https://www.npmjs.com/package/@anchrd/intel-api); what follows is what
+each one looks like here.
+
+| On screen | What it is |
+|---|---|
+| "You do not have permission to see this." | The Gate capability is missing — `nodes.read` and friends |
+| An empty tree, no error | Nothing has been shared with this person yet |
+| "This is not available to you. It may not exist, or it may no longer be shared with you." | A node that was reachable and is not any more, or never existed — Intel deliberately does not say which |
+| Skeletons that never resolve | Should no longer happen: a refusal ends the loading state on the first answer, and no button offers a retry that cannot change anything |
+
+A node somebody shares appears in the recipient's sidebar on its own, at the top level, without
+naming the folders above it. Nobody needs to be sent a link.
+
+The sharing dialog grants to an email address or to the whole organization. It never shows a raw
+user id: where Intel cannot name an account it says so. ⚠️ Choosing **execute for the whole
+organization** on a folder makes that folder a library that flows from anywhere may call into, and
+withdrawing it is refused while a caller remains — the dialog says so before the click.
+
+The Tools screen tells four situations apart — refused, expired, broken, and started-but-never-
+answered — and offers a second attempt everywhere a second attempt could change the answer.
+
+The editor answers "Nothing to save" rather than "Saved" when the write produced no new version.
+The two are different outcomes and only one of them means the text is safe to walk away from.
+
+⚠️ The editor opens **empty** on content it cannot parse. Documents written over HTTP or MCP have to
+carry the BlockNote media type to be editable in the browser; see the
+[`@anchrd/intel-contract` README](https://www.npmjs.com/package/@anchrd/intel-contract).
+
 ## What is inside
 
 Vite, React, TanStack Router and Query, with shadcn components. The node editor uses BlockNote

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-ui",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {
@@ -33,7 +33,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@anchrd/intel-contract": "^0.13.0",
+    "@anchrd/intel-contract": "^0.15.0",
     "@blocknote/core": "^0.52.1",
     "@blocknote/react": "^0.52.1",
     "@blocknote/shadcn": "^0.52.1",

package/src/app/app-tree/app-tree.tsx

@@ -1,3 +1,4 @@
+import type { NodeKind } from "@anchrd/intel-contract/node";
 import { useMutation, useQueries, useQueryClient } from "@tanstack/react-query";
 import { useNavigate, useRouterState } from "@tanstack/react-router";
 import {
@@ -34,6 +35,7 @@ import {
 } from "@/components/ui/sidebar";
 import { flowEntry } from "@/data/intel-data-provider/intel-data-provider.ts";
 import type { TreeEntry } from "@/data/intel-data-provider/intel-data-provider.types.ts";
+import { refusalOf } from "@/data/request-refusal/request-refusal.ts";
 import { useI18n } from "@/i18n/i18n-context.tsx";
 import { type ImportKind, useBundleImport } from "@/import-bundle/import-bundle.tsx";
 import { kindIcons } from "@/kind-icon.ts";
@@ -41,7 +43,15 @@ import { Modal } from "@/modal/modal.tsx";
 import { useIntelRouterContext } from "@/router/router-context.ts";
 import { selectedFrom } from "@/router/selection-search.ts";
 
-type NewKind = "folder" | "document" | "table" | "flow";
+/**
+ * What the plus can MAKE — derived from `NodeKind`, never written out again (#395).
+ *
+ * ⚠️ `attachment` is excluded because an attachment is uploaded rather than created, and `flow` is
+ * added because a flow shares the tree without being a node (ADR-0004 §1). Both are decisions about
+ * this menu; the LIST of node kinds is not, and a copy of it here goes stale in the direction that
+ * already bit us — the parked kinds stood in such a union long after nothing could make one.
+ */
+type NewKind = Exclude<NodeKind, "attachment"> | "flow";
 type Creating = { parentId: string | null; kind: NewKind };
 
 // Attachments are inlined as base64, so the browser holds the file twice while it uploads.
@@ -328,6 +338,19 @@ export function AppTree() {
         </SidebarMenu>
       );
     }
+    // ⚠️ A refusal, not a failure (#430). While this branch did not exist, a reader whose share had
+    // been revoked — or who holds no `intel.nodes.read` at all — watched the three skeleton bars
+    // above for as long as the retries lasted, and the retries are paused whenever the tab is not
+    // in front. Neither of those two cases is worth trying again, so what stands here is a sentence
+    // and no button.
+    const refusal = refusalOf(level.error);
+    if (refusal) {
+      return (
+        <p role="status" className="px-2 py-1.5 text-sm text-muted-foreground">
+          {i18n.t(refusal === "no-permission" ? "common.noPermission" : "common.noAccess")}
+        </p>
+      );
+    }
     if (level.isError) {
       return (
         <div role="alert" className="space-y-2 px-2 py-1.5 text-sm">
@@ -367,15 +390,16 @@ export function AppTree() {
     }
     return (
       <SidebarMenu aria-label={label}>
-        {entries.map((entry) => renderRow(entry, ancestors, parent.type === "flow"))}
+        {entries.map((entry) => renderRow(entry, parent, ancestors))}
       </SidebarMenu>
     );
   }
 
-  // ⚠️ `derived` is the level under a flow: its rows are that flow's calls, read out of its graph
+  // ⚠️ A level under a FLOW is derived: its rows are that flow's calls, read out of its graph
   // (ADR-0004 §3, `levelKey`). Nothing there has a `parent_id` to rewrite, so those rows are neither
   // dragged nor dropped on — a move made there would silently be a move of the shared flow itself.
-  function renderRow(entry: TreeEntry, ancestors: ReadonlySet<string>, derived: boolean) {
+  function renderRow(entry: TreeEntry, parent: Level, ancestors: ReadonlySet<string>) {
+    const derived = parent.type === "flow";
     const isFolder = entry.kind === "folder";
     // ⚠️ A flow expands too, and what appears under it is what it calls — read from its graph, not
     // from `parent_id`. A flow reused by three callers therefore shows up under all three, which is
@@ -391,7 +415,23 @@ export function AppTree() {
     const area = entry.type === "flow" ? "/flows" : "/nodes";
     const isActive = location.select === entry.id && location.pathname === area;
     // A row's plus files into that row's place: inside a folder, beside anything else.
-    const target = isFolder ? entry.id : parentOf(entry);
+    //
+    // ⚠️ "Beside it" is the level this row is shown IN, not the parent its own record names. Since
+    // #429 the root level also carries rows whose `parentId` points at a folder this reader may not
+    // see — a shared document is filed inside the sharer's folder, and only the share reaches down
+    // to it. Filing beside such a row through that id would try to write into a folder the reader
+    // cannot even open, and the refusal would arrive as a bare "could not be created".
+    //
+    // ⚠️ A derived level is the exception, because it has no folder to be filed in: what a flow
+    // calls is read from its graph, so the record's own parent is the only answer available there.
+    //
+    // ⚠️ It is the only one, not a safe one. A called flow may be a LIBRARY flow — `execute` without
+    // `read`, which ADR-0004 §2/§3 allows on purpose — and its folder is then one this reader may
+    // not open at all. The plus there can still be refused, exactly as the plus on any read-only
+    // folder row elsewhere in the tree has always been able to be. That is the older question of
+    // what a plus should do where writing is not allowed, and it is not this ticket's: what #429
+    // changed is a plus pointing at a folder that is not even the level being shown.
+    const target = isFolder ? entry.id : derived ? parentOf(entry) : parent.id;
     // Only a folder takes a drop, and only on a level that owns its rows. Everything else keeps the
     // default cursor while a drag is in progress, which is the answer "not here" without a word.
     const drop =

package/src/app/header-search/header-search.tsx

@@ -1,4 +1,5 @@
-import type { Flow, ToolCapability } from "@anchrd/intel-contract";
+import type { Flow } from "@anchrd/intel-contract/flow";
+import type { ToolCapability } from "@anchrd/intel-contract/tool";
 import { useQuery } from "@tanstack/react-query";
 import { useNavigate } from "@tanstack/react-router";
 import { FileText, Search, Workflow, Wrench } from "lucide-react";

package/src/app/reindex-dialog/reindex-dialog.tsx

@@ -0,0 +1,79 @@
+import { useMutation } from "@tanstack/react-query";
+import { Button } from "@/components/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { useI18n } from "@/i18n/i18n-context.tsx";
+import { useIntelRouterContext } from "@/router/router-context.ts";
+
+/**
+ * Rebuilding the search index, asked for before it happens (#416).
+ *
+ * ⚠️ Two clicks, not one, and the reason is not that it is dangerous — nothing is lost, the index is
+ * derived from D1 and R2 and can always be built again. It is that it is EXPENSIVE and invisible:
+ * every node is read and embedded again, which costs money and minutes, and the screen looks exactly
+ * the same afterwards. A one-click button next to "Preferences" invites a second press when the
+ * first one seems to have done nothing.
+ *
+ * ⚠️ It reports what was QUEUED, never "done". The answer comes back the moment the work is handed
+ * to the queue, and the index catches up behind it — writing "finished" here would be a sentence
+ * about something this screen cannot see. The number is the honest part: it says how much was
+ * accepted, so a repeat press can be compared against it.
+ *
+ * The dialog is opened from outside, like the settings one: its trigger is a `DropdownMenuItem`, and
+ * Radix unmounts the menu content in the same frame the item is chosen.
+ */
+interface ReindexDialogProps {
+  open: boolean;
+  onOpenChange(open: boolean): void;
+}
+
+export function ReindexDialog({ open, onOpenChange }: ReindexDialogProps) {
+  const i18n = useI18n();
+  const { data } = useIntelRouterContext();
+  const reindex = useMutation({ mutationFn: () => data.reindexNodes() });
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(next) => {
+        // Closing forgets the last answer, so re-opening never shows a count from an earlier run as
+        // if it were this one's.
+        if (!next) reindex.reset();
+        onOpenChange(next);
+      }}
+    >
+      <DialogContent className="sm:max-w-md">
+        <DialogHeader>
+          <DialogTitle>{i18n.t("reindex.title")}</DialogTitle>
+          <DialogDescription>{i18n.t("reindex.description")}</DialogDescription>
+        </DialogHeader>
+        {reindex.isSuccess ? (
+          <p role="status" className="text-sm">
+            {i18n.t("reindex.queued", { count: reindex.data.queued })}
+          </p>
+        ) : null}
+        {reindex.isError ? (
+          <p role="alert" className="text-sm text-destructive">
+            {i18n.t("reindex.failed")}
+          </p>
+        ) : null}
+        <DialogFooter>
+          <Button variant="outline" onClick={() => onOpenChange(false)}>
+            {i18n.t(reindex.isSuccess ? "reindex.close" : "reindex.cancel")}
+          </Button>
+          {reindex.isSuccess ? null : (
+            <Button disabled={reindex.isPending} onClick={() => reindex.mutate()}>
+              {i18n.t(reindex.isPending ? "reindex.running" : "reindex.confirm")}
+            </Button>
+          )}
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}

package/src/app/user-footer/user-footer.tsx

@@ -4,6 +4,7 @@ import {
   Archive as ArchiveIcon,
   ChevronsUpDown,
   LogOut,
+  RefreshCw,
   Settings,
   User,
   Wrench,
@@ -20,6 +21,7 @@ import { SidebarMenu, SidebarMenuItem } from "@/components/ui/sidebar";
 import { loginPath } from "@/data/intel-data-provider/intel-data-provider.ts";
 import { useI18n } from "@/i18n/i18n-context.tsx";
 import { useIntelRouterContext } from "@/router/router-context.ts";
+import { ReindexDialog } from "../reindex-dialog/reindex-dialog.tsx";
 import { SettingsDialog } from "../settings-dialog/settings-dialog.tsx";
 
 /**
@@ -41,6 +43,7 @@ export function UserFooter() {
   // The state lives here, not in the dialog: its trigger is a DropdownMenuItem, and Radix unmounts
   // the menu content when an item is chosen — a dialog nested in there would go with it.
   const [settingsOpen, setSettingsOpen] = useState(false);
+  const [reindexOpen, setReindexOpen] = useState(false);
   const session = useQuery({ queryKey: ["session"], queryFn: () => data.getSession() });
   const logout = useMutation({
     mutationFn: () => data.logout(),
@@ -103,6 +106,20 @@ export function UserFooter() {
               <Settings aria-hidden="true" />
               {i18n.t("settings.title")}
             </DropdownMenuItem>
+            {/* ⚠️ Drawn only for an administrator, and that is a DRAWING decision — `POST
+                /nodes/reindex` asks Gate for `intel/admin` itself and would refuse this row's press
+                just the same (#416). Hiding it is not the check; it is not offering everybody a
+                door they cannot open. Its own separator, because the rows above belong to the
+                person and this one belongs to the installation. */}
+            {session.data?.isAdmin ? (
+              <>
+                <DropdownMenuSeparator />
+                <DropdownMenuItem onSelect={() => setReindexOpen(true)}>
+                  <RefreshCw aria-hidden="true" />
+                  {i18n.t("reindex.title")}
+                </DropdownMenuItem>
+              </>
+            ) : null}
             <DropdownMenuSeparator />
             <DropdownMenuItem
               disabled={logout.isPending}
@@ -116,6 +133,8 @@ export function UserFooter() {
         </DropdownMenu>
         {/* ⚠️ Outside the DropdownMenu on purpose — see the state above. */}
         <SettingsDialog open={settingsOpen} onOpenChange={setSettingsOpen} />
+        {/* ⚠️ Outside the DropdownMenu for the same reason as the settings dialog. */}
+        <ReindexDialog open={reindexOpen} onOpenChange={setReindexOpen} />
       </SidebarMenuItem>
       {/* ⚠️ Outside the menu on purpose. Choosing sign-out closes the popup, so a refusal rendered
           inside it would be gone in the same frame it was written — the one message that must

package/src/archive/archive.tsx

@@ -1,4 +1,5 @@
-import type { Flow, Node } from "@anchrd/intel-contract";
+import type { Flow } from "@anchrd/intel-contract/flow";
+import type { Node } from "@anchrd/intel-contract/node";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { ArchiveRestore } from "lucide-react";
 import { useI18n } from "@/i18n/i18n-context.tsx";

package/src/data/intel-data-provider/intel-data-provider.ts

@@ -1,24 +1,33 @@
+import { ProblemDetails, SessionUser } from "@anchrd/intel-contract";
+import { BundleImportResult } from "@anchrd/intel-contract/bundle";
 import {
-  AppendTableRowsInput,
-  AppendTableRowsResult,
   ArchiveFlowInput,
-  ArchiveNodeInput,
-  BundleImportResult,
-  CompleteFlowRunStepInput,
   CreateFlowInput,
-  CreateNodeInput,
-  DefineTableInput,
   Flow,
   FlowDocument,
   FlowList,
   FlowPublishPreview,
   FlowRequirements,
+  FlowValidation,
+  ListFlowsInput,
+  PreviewFlowPublishInput,
+  PublishFlowInput,
+  RelationGraph,
+  RelationGraphInput,
+  SaveFlowVersionInput,
+  UpdateFlowInput,
+} from "@anchrd/intel-contract/flow";
+import {
+  CompleteFlowRunStepInput,
   FlowRunHistory,
   FlowRunList,
   FlowRunStep,
-  FlowValidation,
   ListFlowRunsInput,
-  ListFlowsInput,
+  StartFlowRunInput,
+} from "@anchrd/intel-contract/flow-run";
+import {
+  ArchiveNodeInput,
+  CreateNodeInput,
   ListNodesInput,
   Node,
   NodeDocument,
@@ -27,30 +36,28 @@ import {
   NodeList,
   NodeTable,
   NodeVersionList,
-  PreviewFlowPublishInput,
-  ProblemDetails,
-  PublishFlowInput,
-  RelationGraph,
-  RelationGraphInput,
+  ReindexResult,
   ResolveNodeLinksInput,
   ResolveNodeLinksResult,
-  ResourceGrantList,
-  RevokeGrantInput,
-  RevokeGrantResult,
   SaveAttachmentInput,
-  SaveFlowVersionInput,
   SaveNodeVersionInput,
   SearchInput,
   SearchResult,
-  SessionUser,
+  UpdateNodeInput,
+} from "@anchrd/intel-contract/node";
+import {
+  ResourceGrantList,
+  RevokeGrantInput,
+  RevokeGrantResult,
   ShareInput,
   ShareResult,
-  StartFlowRunInput,
-  ToolCatalog,
-  ToolServerCatalog,
-  UpdateFlowInput,
-  UpdateNodeInput,
-} from "@anchrd/intel-contract";
+} from "@anchrd/intel-contract/share";
+import {
+  AppendTableRowsInput,
+  AppendTableRowsResult,
+  DefineTableInput,
+} from "@anchrd/intel-contract/table";
+import { ToolCatalog, ToolServerCatalog } from "@anchrd/intel-contract/tool";
 import type { z } from "zod";
 import { createBrowserSignIn } from "@/data/sign-in/sign-in.ts";
 import type { IntelDataProvider, TreeEntry } from "./intel-data-provider.types.ts";
@@ -187,6 +194,9 @@ export function createIntelDataProvider(
     async getSession() {
       return await request("/session", SessionUser);
     },
+    async reindexNodes() {
+      return await request("/nodes/reindex", ReindexResult, { method: "POST", body: "{}" });
+    },
     listNodes,
     async listTreeChildren(parentId) {
       // Both sides of one folder, asked for in parallel and merged here rather than on the server:
@@ -439,10 +449,14 @@ export function createIntelDataProvider(
     },
     async completeFlowStep(input) {
       const parsed = CompleteFlowRunStepInput.parse(input);
-      return await request(`/flow-runs/${encodeURIComponent(parsed.runId)}/complete`, FlowRunStep, {
-        method: "POST",
-        body: JSON.stringify(parsed),
-      });
+      return await request(
+        `/flow-runs/${encodeURIComponent(parsed.runId)}/steps/complete`,
+        FlowRunStep,
+        {
+          method: "POST",
+          body: JSON.stringify(parsed),
+        },
+      );
     },
     async listTools() {
       return await request("/tools", ToolCatalog);

package/src/data/intel-data-provider/intel-data-provider.types.ts

@@ -1,24 +1,33 @@
+import type { SessionUser } from "@anchrd/intel-contract";
+import type { BundleImportResult } from "@anchrd/intel-contract/bundle";
 import type {
-  AppendTableRowsInput,
-  AppendTableRowsResult,
   ArchiveFlowInput,
-  ArchiveNodeInput,
-  BundleImportResult,
-  CompleteFlowRunStepInput,
   CreateFlowInput,
-  CreateNodeInput,
-  DefineTableInput,
   Flow,
   FlowDocument,
   FlowList,
   FlowPublishPreview,
   FlowRequirements,
+  FlowValidation,
+  ListFlowsInput,
+  PreviewFlowPublishInput,
+  PublishFlowInput,
+  RelationGraph,
+  RelationGraphScope,
+  SaveFlowVersionInput,
+  UpdateFlowInput,
+} from "@anchrd/intel-contract/flow";
+import type {
+  CompleteFlowRunStepInput,
   FlowRunHistory,
   FlowRunList,
   FlowRunStep,
-  FlowValidation,
   ListFlowRunsInput,
-  ListFlowsInput,
+  StartFlowRunInput,
+} from "@anchrd/intel-contract/flow-run";
+import type {
+  ArchiveNodeInput,
+  CreateNodeInput,
   ListNodesInput,
   Node,
   NodeDocument,
@@ -28,29 +37,28 @@ import type {
   NodeList,
   NodeTable,
   NodeVersionList,
-  PreviewFlowPublishInput,
-  PublishFlowInput,
-  RelationGraph,
-  RelationGraphScope,
+  ReindexResult,
   ResolveNodeLinksInput,
   ResolveNodeLinksResult,
-  ResourceGrantList,
-  RevokeGrantInput,
-  RevokeGrantResult,
   SaveAttachmentInput,
-  SaveFlowVersionInput,
   SaveNodeVersionInput,
   SearchInput,
   SearchResult,
-  SessionUser,
+  UpdateNodeInput,
+} from "@anchrd/intel-contract/node";
+import type {
+  ResourceGrantList,
+  RevokeGrantInput,
+  RevokeGrantResult,
   ShareInput,
   ShareResult,
-  StartFlowRunInput,
-  ToolCatalog,
-  ToolServerCatalog,
-  UpdateFlowInput,
-  UpdateNodeInput,
-} from "@anchrd/intel-contract";
+} from "@anchrd/intel-contract/share";
+import type {
+  AppendTableRowsInput,
+  AppendTableRowsResult,
+  DefineTableInput,
+} from "@anchrd/intel-contract/table";
+import type { ToolCatalog, ToolServerCatalog } from "@anchrd/intel-contract/tool";
 
 // One row of the shared tree. Nodes and Flows share the folder, not their nature (ADR-0004), so
 // this is a union that keeps each side's record whole — never a merged "node" that is a bit of both.
@@ -70,6 +78,14 @@ export type TreeEntry =
 
 export interface IntelDataProvider {
   getSession(): Promise<SessionUser>;
+  /**
+   * Rebuild the whole search index (`intel/admin`).
+   *
+   * ⚠️ Answers as soon as the work is QUEUED, not when it is done — `queued` counts the nodes that
+   * will be read again, and the index catches up behind it. A screen that said "finished" here
+   * would be reporting the wrong thing.
+   */
+  reindexNodes(): Promise<ReindexResult>;
   listNodes(input?: Partial<ListNodesInput>): Promise<NodeList>;
   // One level of the shared tree: the documents and the flows filed in the same folder, in one
   // sorted list. Per level rather than recursive, so opening a folder is what costs a request.

package/src/data/query-client.ts

@@ -0,0 +1,18 @@
+import { QueryClient } from "@tanstack/react-query";
+import { retryRequest } from "@/data/request-refusal/request-refusal.ts";
+
+/**
+ * The one query client the application runs on.
+ *
+ * ⚠️ It exists as a function rather than as the literal `new QueryClient()` that stood in `main.tsx`
+ * so the policy in it can be exercised by a test (#430). A default nothing renders under is a
+ * default nothing checks, and this one decides how long a screen stays on "Loading…".
+ *
+ * ⚠️ Flat, and without a `.unit.ts` of its own on purpose: the only thing to assert here is that the
+ * returned client carries `retryRequest`, and what that predicate DOES is already covered next door
+ * in `request-refusal.unit.ts` — twice over, because two screen tests render against this very
+ * client. A test that restated the wiring would be the "pure wiring" the repository rules exclude.
+ */
+export function createIntelQueryClient(): QueryClient {
+  return new QueryClient({ defaultOptions: { queries: { retry: retryRequest } } });
+}

package/src/data/request-refusal/request-refusal.ts

@@ -0,0 +1,51 @@
+import { IntelRequestError } from "@/data/intel-data-provider/intel-data-provider.ts";
+
+/**
+ * What a failed request already settles, as opposed to what it might answer differently next time.
+ *
+ * - `not-available` is Intel's `404`. It is deliberately the same answer for "there is no such node"
+ *   and "you may not reach this node" — `requireVisible` in `packages/api/src/nodes/nodes.ts`, held
+ *   in place by "answers 404 for a foreign version and for an unreadable node" in `nodes.int.ts`.
+ *   A screen must therefore not guess between them either: one sentence covers both, and that is why
+ *   `no-permission` is a separate value rather than prose that could be shown for a `404` by mistake.
+ * - `no-permission` is a `403`. The server said the word itself, so repeating it reveals nothing.
+ * - `null` is everything else: a timeout, a `502`, a network that came back. Those are worth trying
+ *   again, and the screen keeps its retry button for them.
+ */
+export type Refusal = "not-available" | "no-permission";
+
+/** The HTTP status the data provider recorded, or `null` where the failure carried none. */
+export function statusOf(error: unknown): number | null {
+  return error instanceof IntelRequestError ? error.status : null;
+}
+
+export function refusalOf(error: unknown): Refusal | null {
+  switch (statusOf(error)) {
+    case 403:
+      return "no-permission";
+    case 404:
+      return "not-available";
+    default:
+      return null;
+  }
+}
+
+/**
+ * The retry policy every query in Intel runs under.
+ *
+ * ⚠️ A refusal is deterministic, and repeating it is what left the screen on "Loading…" after a
+ * share was revoked (#430). React Query's default is three retries with a growing delay, so a `404`
+ * kept the reader in front of a moving loading state for seconds — and a retry is **paused while
+ * the tab is unfocused** (`packages/ui/CLAUDE.md`, #212), so "seconds" has no upper bound whenever
+ * the person looked somewhere else. The answer was there the whole time.
+ *
+ * ⚠️ `408` and `429` are the two `4xx` that DO change on their own — a timeout and a rate limit both
+ * say "not now" rather than "not you" — so they keep the retries. Everything else in the range is
+ * about this request as it was made, and making it again cannot alter that.
+ */
+export function retryRequest(failureCount: number, error: unknown): boolean {
+  const status = statusOf(error);
+  const deterministic =
+    status !== null && status >= 400 && status < 500 && status !== 408 && status !== 429;
+  return !deterministic && failureCount < 3;
+}

package/src/document-link/document-link.tsx

@@ -1,4 +1,4 @@
-import { DocumentLinkInlineType } from "@anchrd/intel-contract";
+import { DocumentLinkInlineType } from "@anchrd/intel-contract/node";
 import { BlockNoteSchema } from "@blocknote/core";
 import { createReactInlineContentSpec } from "@blocknote/react";
 import { FileText, Link2Off } from "lucide-react";

package/src/entry-picker/entry-picker.tsx

@@ -1,4 +1,4 @@
-import type { NodeKind } from "@anchrd/intel-contract";
+import type { NodeKind } from "@anchrd/intel-contract/node";
 import { useQuery } from "@tanstack/react-query";
 import { ChevronRight, Folder, Search } from "lucide-react";
 import { useMemo, useState } from "react";

package/src/flow-runs/flow-runs.tsx

@@ -1,4 +1,4 @@
-import type { FlowRunSummary } from "@anchrd/intel-contract";
+import type { FlowRunSummary } from "@anchrd/intel-contract/flow-run";
 import { useInfiniteQuery, useQuery } from "@tanstack/react-query";
 import { ChevronDown, ChevronRight, CornerDownRight } from "lucide-react";
 import { useState } from "react";

package/src/flows/flows.tsx

@@ -1,5 +1,6 @@
-import type { Flow, FlowGraph, FlowNode, Node } from "@anchrd/intel-contract";
-import { flowNodeLayer } from "@anchrd/intel-contract";
+import type { Flow, FlowGraph, FlowNode } from "@anchrd/intel-contract/flow";
+import { flowNodeLayer } from "@anchrd/intel-contract/flow";
+import type { Node } from "@anchrd/intel-contract/node";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { useNavigate, useRouterState } from "@tanstack/react-router";
 import {
@@ -758,7 +759,14 @@ function FlowTitle({
           <TooltipContent>{publishLabel}</TooltipContent>
         </Tooltip>
       </TooltipProvider>
-      <SaveButton dirty={dirty && canMutate} saving={saving} onSave={onSave} />
+      {/* A draft that was never saved has no version, and the button says so rather than claiming
+          one (#432) — the same distinction the publish button next to it already draws. */}
+      <SaveButton
+        dirty={dirty && canMutate}
+        saving={saving}
+        stored={flow.currentVersionId !== null}
+        onSave={onSave}
+      />
     </TitleRow>
   );
 }

package/src/flows/node-icon/node-icon.ts

@@ -1,4 +1,4 @@
-import type { FlowNode } from "@anchrd/intel-contract";
+import type { FlowNode } from "@anchrd/intel-contract/flow";
 import {
   CircleDot,
   CirclePlay,

package/src/flows/node-palette/node-palette.tsx

@@ -1,4 +1,4 @@
-import { flowNodeLayer } from "@anchrd/intel-contract";
+import { flowNodeLayer } from "@anchrd/intel-contract/flow";
 import { Plus, X } from "lucide-react";
 import { Fragment, useId, useRef, useState } from "react";
 import { type NodeIcon, nodeIcon } from "@/flows/node-icon/node-icon.ts";

package/src/flows/node-palette/node-palette.types.ts

@@ -1,4 +1,4 @@
-import type { FlowNode } from "@anchrd/intel-contract";
+import type { FlowNode } from "@anchrd/intel-contract/flow";
 
 export type PaletteKind = FlowNode["kind"];