@anchrd/intel 0.59.0

package/src/contract/flow.ts

@@ -0,0 +1,675 @@
+import { z } from "zod";
+import {
+  baseVersion,
+  IdempotencyKey,
+  IntelId,
+  IsoDateTime,
+  LinkConfiguration,
+  PromptName,
+} from "./contract.ts";
+import { NodeKind } from "./node.ts";
+import { serverOf, ToolName, ToolServerHandle } from "./tool.ts";
+
+export const FlowNodeId = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_-]{0,99}$/);
+export const FlowPosition = z.strictObject({ x: z.number().finite(), y: z.number().finite() });
+// A node has a title and nothing else to write in prose (#39). A second free text beside it was
+// kept half up to date on both sides, and for an instruction the same sentence already belongs in
+// the instruction itself.
+const FlowNodeBase = {
+  id: FlowNodeId,
+  position: FlowPosition,
+  label: z.string().trim().min(1).max(160),
+};
+
+// Which version of the callee a sub-flow call takes (ADR-0004 §5). Three states rather than an
+// optional identifier, because the difference between them is a decision and has to be readable:
+//
+// - `latest`   the draft default. Nobody should have to version things while building, and
+//              publishing turns this into `pinned` — visibly, before the author publishes.
+// - `follows`  "always latest", chosen on purpose. The call rides along with the callee, so a
+//              change to the building block changes this flow too. Publishing leaves it alone.
+// - `pinned`   one immutable version, whatever is published elsewhere.
+//
+// ⚠️ Without the freeze a change to a building block would silently change the behavior of every
+// published flow using it, which contradicts the immutable versions and pinned schema fingerprints
+// Intel otherwise guarantees. That is why `latest` cannot survive publishing.
+export const SubflowVersionMode = z.enum(["latest", "follows", "pinned"]);
+export type SubflowVersionMode = z.infer<typeof SubflowVersionMode>;
+
+export const SubflowVersion = z.discriminatedUnion("mode", [
+  z.strictObject({ mode: z.literal("latest") }),
+  z.strictObject({ mode: z.literal("follows") }),
+  z.strictObject({ mode: z.literal("pinned"), versionId: IntelId }),
+]);
+export type SubflowVersion = z.infer<typeof SubflowVersion>;
+
+// The three layers a node can belong to (D25). Which one a kind is in decides what it may carry and
+// where it may sit, and both rules are enforced in `compileFlow` rather than only drawn in the
+// editor — a graph arrives over MCP as readily as from the canvas.
+//
+// ⚠️ A LINK never stands in the chain. It hangs off a step on a `context` edge, and that is the
+// distinction the graph has drawn since #37 without anyone enforcing it — which is exactly how a
+// start with an attachment once began its run at the attachment (the "flow edges only" comments in
+// `flows.ts`). Marker and step keep the chain; a link is what a step works with.
+export const FlowNodeLayer = z.enum(["marker", "step", "link"]);
+export type FlowNodeLayer = z.infer<typeof FlowNodeLayer>;
+
+export const flowNodeLayer = {
+  trigger: "marker",
+  output: "marker",
+  instruction: "step",
+  condition: "step",
+  subflow: "step",
+  folder: "link",
+  document: "link",
+  upload: "link",
+  table: "link",
+  tool: "link",
+} as const satisfies Record<string, FlowNodeLayer>;
+
+export const FlowNode = z.discriminatedUnion("kind", [
+  z.strictObject({
+    ...FlowNodeBase,
+    kind: z.literal("trigger"),
+    // ⚠️ `manual` is the only mode there is. `webhook` and `schedule` stood here and fired nothing:
+    // a flow is carried out by an external agent that brings its own schedule, which is what the
+    // code does rather than what it intends — `step()` hands back the current node, `completeStep`
+    // takes the result from outside, and the Cloudflare workflow waits rather than drives. #32 was
+    // closed on that basis, and a mode nothing triggers is a promise nobody keeps.
+    configuration: z.strictObject({ mode: z.literal("manual") }),
+  }),
+  z.strictObject({
+    ...FlowNodeBase,
+    kind: z.literal("instruction"),
+    configuration: z.strictObject({ prompt: z.string().min(1).max(50_000) }),
+  }),
+  // The four link kinds that name something in the shared tree. They are separate kinds rather than
+  // one with a `kind` field so the canvas, the palette and the picker can each say what they mean
+  // without reading into a configuration — and so a stored graph says it too.
+  z.strictObject({ ...FlowNodeBase, kind: z.literal("folder"), configuration: LinkConfiguration }),
+  z.strictObject({
+    ...FlowNodeBase,
+    kind: z.literal("document"),
+    configuration: LinkConfiguration,
+  }),
+  z.strictObject({ ...FlowNodeBase, kind: z.literal("upload"), configuration: LinkConfiguration }),
+  z.strictObject({ ...FlowNodeBase, kind: z.literal("table"), configuration: LinkConfiguration }),
+  /**
+   * A tool step names a SERVER, and optionally the functions of it that this step may use.
+   *
+   * ⚠️ It named a single function until #489, together with a raw argument object the author had to
+   * write as JSON. That modelled the protocol instead of the intent: an author gives a step access
+   * to Notion; WHICH of Notion's 28 functions runs, and with which arguments, follows from the
+   * step's instruction and can only be known while the flow runs.
+   *
+   * `allow: null` means every function of that server. A list narrows it, and every entry has to
+   * belong to `server` — checked below, because a name from another server would make the step ask
+   * for something the portal routes somewhere else entirely.
+   *
+   * ⚠️ `allow` is an INSTRUCTION to the agent, not a boundary Intel enforces (#518). Intel is a
+   * library: it says what is to be done, it does not execute. A flow is carried out by an agent
+   * that reaches the portal with its OWN token, and that agent may call the portal directly —
+   * Intel never sees the call. What bounds it is the agent's own portal grant, checked by the
+   * portal on every call; what `allow` does is tell the agent which of those functions this step
+   * is meant to use, the same way an instruction step tells it what to write.
+   *
+   * That is not a gap to be closed by adding a check here. Enforcing it would mean routing every
+   * call through Intel and making it the executor — the one thing this product is not.
+   *
+   * ⚠️ There is deliberately no `arguments` field any more. Arguments are produced at run time and
+   * validated against the tool's own `inputSchema` from a live `tools/list`; a stored copy would be
+   * a second source for something the far side already defines, and it would go stale silently.
+   */
+  z.strictObject({
+    ...FlowNodeBase,
+    kind: z.literal("tool"),
+    configuration: z
+      .strictObject({
+        server: ToolServerHandle,
+        allow: z.array(ToolName).nullable().default(null),
+        fingerprint: z
+          .string()
+          .regex(/^[a-f0-9]{64}$/)
+          .nullable()
+          .default(null),
+      })
+      .check((ctx) => {
+        const { server, allow } = ctx.value;
+        if (allow === null) return;
+        // The prefix rule is the contract's own (`serverOf`), so a step cannot claim a function
+        // that the portal would route somewhere else entirely.
+        for (const name of allow) {
+          if (serverOf(name, [server]) === null) {
+            ctx.issues.push({
+              code: "custom",
+              input: name,
+              message: `An allowed function has to belong to the step's server: ${name} is not a function of ${server}`,
+            });
+          }
+        }
+      }),
+  }),
+  z.strictObject({
+    ...FlowNodeBase,
+    kind: z.literal("condition"),
+    configuration: z.strictObject({
+      mode: z.literal("semantic"),
+      instruction: z.string().min(1).max(10_000),
+    }),
+  }),
+  // ⚠️ There is no `approval` kind, and adding one back is a product decision rather than a schema
+  // addition (#73). It waited on a named person with a deadline, which needs a queue, a
+  // notification, a stand-in and an answer to "the deadline passed" — none of which exist. Without
+  // it, D24 holds without exception: nothing in Intel waits. A stored graph that still carries one
+  // is rewritten to a `condition` by migration 0007, because the question it asked is one the agent
+  // can answer.
+  //
+  // The seventh kind: one flow calls another (ADR-0004 §3). A schema addition, not hidden behavior
+  // in a generic code node — which flow is called has to be readable from the graph, or neither the
+  // publish-time call rule nor the sidebar could see it.
+  z.strictObject({
+    ...FlowNodeBase,
+    kind: z.literal("subflow"),
+    // What the called flow is given travels through `StartFlowRunInput.input` — the schema every run
+    // already uses. A second, static input here would be a promise the execution does not keep.
+    configuration: z.strictObject({
+      flowId: IntelId,
+      version: SubflowVersion.default({ mode: "latest" }),
+    }),
+  }),
+  // ⚠️ The end marks, it does not make. It used to carry a `template` that nothing ever read, and a
+  // node called "Result" that appeared to produce one is what everybody read it as. The result of a
+  // run is what the last step before it hands in (D25) — `completeStep` carries that forward.
+  z.strictObject({
+    ...FlowNodeBase,
+    kind: z.literal("output"),
+    configuration: z.strictObject({}),
+  }),
+]);
+export type FlowNode = z.infer<typeof FlowNode>;
+
+// The two things an edge can mean (#37). `flow` is the order of work — "and then". `context` is what
+// a step works with: a document consulted in exactly this step, an approval obtained in exactly this
+// step, or, at the output, the table a result is written to.
+//
+// ⚠️ `flow` is the default, and that is the whole of the migration: every edge stored before this
+// existed parses into the meaning it already had. Nothing about saved graphs has to be rewritten.
+export const FlowEdgeKind = z.enum(["flow", "context"]);
+export type FlowEdgeKind = z.infer<typeof FlowEdgeKind>;
+
+export const FlowEdge = z.strictObject({
+  id: FlowNodeId,
+  source: FlowNodeId,
+  target: FlowNodeId,
+  kind: FlowEdgeKind.default("flow"),
+  label: z.string().trim().min(1).max(120).nullable().default(null),
+  sourceHandle: z.string().trim().min(1).max(120).nullable().default(null),
+});
+export type FlowEdge = z.infer<typeof FlowEdge>;
+
+export const FlowGraph = z.strictObject({
+  nodes: z.array(FlowNode).min(2).max(200),
+  edges: z.array(FlowEdge).min(1).max(500),
+});
+export type FlowGraph = z.infer<typeof FlowGraph>;
+
+export const Flow = z.strictObject({
+  id: IntelId,
+  // The one thing a Flow shares with a document: its place in the shared folder tree (ADR-0004).
+  // Everything else stays apart — versions, R2 body and Vectorize belong to the document, the graph,
+  // runs and approvals to the flow. `null` is the root of that same tree.
+  parentId: IntelId.nullable(),
+  title: z.string().min(1).max(240),
+  description: z.string().max(2_000).nullable(),
+  ownerId: IntelId,
+  currentVersionId: IntelId.nullable(),
+  publishedVersionId: IntelId.nullable(),
+  createdAt: IsoDateTime,
+  updatedAt: IsoDateTime,
+  archivedAt: IsoDateTime.nullable(),
+  // The slash command this flow is offered under, or `null` (#775). It is set at `flow_publish`
+  // and nowhere else: publishing is already the decision that this flow is for other people, and a
+  // second switch beside it would ask the same question twice.
+  //
+  // ⚠️ It SURVIVES `flow_unpublish`, and that is deliberate. Withdrawing a publication takes the
+  // flow out of `prompts/list` — the name it keeps is what makes republishing it the same command
+  // rather than a new one, and a client that stored the old one is not left pointing at a name that
+  // now means somebody else's flow. The name stays taken while the flow is withdrawn, and whoever
+  // asks for it is told which flow holds it.
+  promptName: PromptName.nullable(),
+});
+export type Flow = z.infer<typeof Flow>;
+
+export const FlowVersion = z.strictObject({
+  id: IntelId,
+  flowId: IntelId,
+  sequence: z.number().int().positive(),
+  graph: FlowGraph,
+  createdBy: IntelId,
+  createdAt: IsoDateTime,
+});
+export type FlowVersion = z.infer<typeof FlowVersion>;
+
+export const FlowDocument = z.strictObject({
+  flow: Flow,
+  version: FlowVersion.nullable(),
+});
+export type FlowDocument = z.infer<typeof FlowDocument>;
+
+// One version as the history shows it: the metadata without the graph it carries. A flow's history
+// is as long as its edits, and a list that shipped every graph would pay for drawings nobody asked
+// for — whoever needs one asks for that one version.
+export const FlowVersionSummary = z.strictObject({
+  id: IntelId,
+  flowId: IntelId,
+  sequence: z.number().int().positive(),
+  createdBy: IntelId,
+  createdAt: IsoDateTime,
+  // Whether this is the version the flow currently publishes. Derived from the flow row when the
+  // list is read, never stored on the version: a version is immutable and "published" is not a
+  // property of it — it is the flow's choice, revocable without touching the version.
+  published: z.boolean(),
+});
+export type FlowVersionSummary = z.infer<typeof FlowVersionSummary>;
+
+export const FlowVersionList = z.strictObject({
+  flowId: IntelId,
+  items: z.array(FlowVersionSummary),
+});
+export type FlowVersionList = z.infer<typeof FlowVersionList>;
+
+// Both identifiers, deliberately: a version ID alone would resolve whatever version carries it,
+// whichever flow it belongs to, and the ACL is answered on the flow. The pair makes a foreign
+// version a 404 rather than a read.
+export const GetFlowVersionInput = z.strictObject({
+  flowId: IntelId.describe(
+    "Flow the version belongs to. Named alongside the version so access is decided on the flow.",
+  ),
+  versionId: IntelId.describe("Version to read, from flow_version_list."),
+});
+export type GetFlowVersionInput = z.infer<typeof GetFlowVersionInput>;
+// The same for flows: which of them call another flow that this reader may also see (#59). An
+// expand arrow on a flow whose calls are all hidden promises content that expanding it cannot
+// deliver.
+export const FlowList = z.strictObject({
+  items: z.array(Flow),
+  withCalls: z.array(IntelId).default([]),
+});
+export type FlowList = z.infer<typeof FlowList>;
+
+export const ReferencedNode = z.strictObject({
+  id: IntelId,
+  title: z.string().min(1).max(240),
+});
+export type ReferencedNode = z.infer<typeof ReferencedNode>;
+
+// What a flow touches: the documents its tree links name and the tools its Tool steps call,
+// read straight out of the graph. Deliberately not a conflict report — there is no arithmetic here
+// and nothing that can go stale, because the graph is the answer. Whether a given person may reach
+// any of it is decided where it can be decided honestly: when the folder is shared, and at runtime
+// (ADR-0004 §4). For tools it can only ever be the latter, because the catalog is a live query with
+// the requesting user's own token (ADR-0003).
+//
+// ⚠️ `nodes` names only what the asking user may see. The rest falls into TWO fields, and keeping
+// them apart is the whole of #509: `invalidNodes` are references that name nothing at all any more,
+// `hiddenNodes` is a count of the ones that exist and are out of this reader's reach.
+//
+// ⚠️ They used to be one number, and the number was read out as "you cannot see it" — a sentence
+// about a PERMISSION, in front of a broken link. The two states suggest opposite actions and only
+// one of them helps: with a permission one asks for access and waits, with a dead reference the step
+// has to be replaced before the flow can run at all. #492 decided that such a reference is marked
+// visibly invalid rather than left silently pointed at an id nothing answers.
+//
+// ⚠️ `invalidNodes` carries IDS, never titles, and that is not the same concession `hiddenNodes`
+// makes. There is nothing left to name — the row is gone — and the id is one the caller sent us out
+// of a graph they may already read, so it discloses nothing they did not write themselves.
+export const FlowRequirements = z.strictObject({
+  flowId: IntelId,
+  versionId: IntelId.nullable(),
+  nodes: z.array(ReferencedNode),
+  invalidNodes: z.array(IntelId),
+  hiddenNodes: z.number().int().nonnegative(),
+  servers: z.array(ToolServerHandle),
+});
+export type FlowRequirements = z.infer<typeof FlowRequirements>;
+
+// What stands between this flow and a run, asked on demand and answered for the person asking.
+//
+// ⚠️ A snapshot, and it says so. The tool catalog is a live query with the requesting user's own
+// token (ADR-0003), so what is reachable now can be different tomorrow, and the same flow answers
+// differently for two people. That is why this is a question one asks rather than a badge on the
+// flow: a standing "this flow has conflicts" would be wrong for tools by construction (#72, D24).
+export const FlowValidation = z.strictObject({
+  flowId: IntelId,
+  versionId: IntelId.nullable(),
+  // Empty means it would start now — for this person, at this moment.
+  problems: z.array(
+    z.strictObject({
+      code: z.string().min(1).max(80),
+      detail: z.string().min(1).max(2_000),
+    }),
+  ),
+  checkedAt: IsoDateTime,
+});
+export type FlowValidation = z.infer<typeof FlowValidation>;
+
+export const CreateFlowInput = z.strictObject({
+  parentId: IntelId.nullable()
+    .default(null)
+    .describe("Folder to file the flow in. `null` puts it at the top level."),
+  title: z.string().trim().min(1).max(240).describe("What the flow is called."),
+  description: z
+    .string()
+    .trim()
+    .max(2_000)
+    .nullable()
+    .default(null)
+    .describe("Optional sentence about what the flow is for."),
+  idempotencyKey: IdempotencyKey,
+});
+export type CreateFlowInput = z.infer<typeof CreateFlowInput>;
+
+// Renaming and moving a flow. Both are organization and nothing else: they touch no version, no
+// published graph and no run, because organization has to stay free of consequence or nobody dares
+// to reorganize (ADR-0004).
+export const UpdateFlowInput = z
+  .strictObject({
+    flowId: IntelId.describe("Flow to rename or move."),
+    baseUpdatedAt: IsoDateTime.describe(
+      "`updatedAt` as flow_get last reported it. A newer value on the server means somebody else changed the flow first and the call is refused.",
+    ),
+    title: z
+      .string()
+      .trim()
+      .min(1)
+      .max(240)
+      .optional()
+      .describe("New title. Omit to leave it as it is."),
+    description: z
+      .string()
+      .trim()
+      .max(2_000)
+      .nullable()
+      .optional()
+      .describe("New description, or `null` to clear it. Omit to leave it as it is."),
+    parentId: IntelId.nullable()
+      .optional()
+      .describe(
+        "Folder to move the flow into, or `null` for the top level. Omit to leave it where it is. Moving touches no version, no published graph and no run.",
+      ),
+    idempotencyKey: IdempotencyKey,
+  })
+  .refine(
+    (input) =>
+      input.title !== undefined || input.description !== undefined || input.parentId !== undefined,
+    { error: "At least one change is required" },
+  );
+export type UpdateFlowInput = z.infer<typeof UpdateFlowInput>;
+
+// Archiving a flow is the same shape as archiving a document, deliberately: `archived` is a boolean
+// rather than a one-way verb, because an archive nothing returns from is a delete under a friendlier
+// name. Restoring is the same call with `false`.
+export const ArchiveFlowInput = z.strictObject({
+  flowId: IntelId.describe("Flow to archive or restore."),
+  baseUpdatedAt: IsoDateTime.describe(
+    "`updatedAt` as flow_get last reported it. A newer value on the server means somebody else changed the flow first and the call is refused.",
+  ),
+  archived: z
+    .boolean()
+    .describe(
+      "`true` archives the flow, `false` restores it. Nothing is deleted and every version stays readable.",
+    ),
+  idempotencyKey: IdempotencyKey,
+});
+export type ArchiveFlowInput = z.infer<typeof ArchiveFlowInput>;
+
+// ⚠️ The flow half of the one irreversible act in Intel (#457). No `baseUpdatedAt`, no
+// `idempotencyKey`, for the same two reasons the node's has neither: an archived flow is not being
+// edited, and a replay has nothing to replay — deleting twice deletes once and then answers 404.
+export const PurgeFlowInput = z.strictObject({
+  flowId: IntelId.describe(
+    "Flow to delete for good. It must already be archived — a living flow has no path into nothing.",
+  ),
+});
+export type PurgeFlowInput = z.infer<typeof PurgeFlowInput>;
+
+export const PurgeFlowResult = z.strictObject({
+  purged: z.literal(true),
+  title: z.string(),
+});
+export type PurgeFlowResult = z.infer<typeof PurgeFlowResult>;
+
+// Three answers, not two: an absent `parentId` lists every visible flow (the search dialog asks
+// that), `null` lists the root of the shared tree and an ID lists one folder (the sidebar tree asks
+// per level, which is what keeps the tree off the N+1 it used to load with).
+export const ListFlowsInput = z.strictObject({
+  parentId: IntelId.nullable()
+    .optional()
+    .describe(
+      "Three answers, not two: omit it to list every flow this reader may see, pass `null` for the top level, or a folder id for one level of it.",
+    ),
+  // The only way back to an archived flow, and the only place that asks for one: the bounded read
+  // behind the relation graph has no such flag on purpose (#30). A drawing that includes what was
+  // archived says the tidying up never happened.
+  //
+  // ⚠️ `.optional()` rather than `.default(false)`, unlike `ListNodesInput`. This schema is
+  // the argument type of `listFlows` on three layers, and a default makes the field required in the
+  // *parsed* type — every existing caller that lists a folder would have to spell out the answer to
+  // a question it is not asking. Absent means "without the archive" everywhere it is read.
+  includeArchived: z
+    .boolean()
+    .optional()
+    .describe("Include archived flows beside the live ones. Absent means without them."),
+  // The same question for flows, and the same override of `parentId` — see `ListNodesInput`.
+  archivedOnly: z
+    .boolean()
+    .optional()
+    .describe(
+      "List only archived flows, across the whole tree. Overrides parentId rather than narrowing it.",
+    ),
+});
+export type ListFlowsInput = z.infer<typeof ListFlowsInput>;
+
+export const GetFlowInput = z.strictObject({
+  flowId: IntelId.describe("Flow to read, from flow_list."),
+});
+export type GetFlowInput = z.infer<typeof GetFlowInput>;
+export const SaveFlowVersionInput = z.strictObject({
+  flowId: IntelId.describe("Flow to append a version to."),
+  // ⚠️ `baseVersion`, not `IntelId.nullable()` (#459). The field is required-nullable either way;
+  // what changes is what a caller who left it out is told. Zod's own `expected string, received
+  // undefined` reads as "this needs an id" to somebody holding a flow created one call earlier —
+  // whose `currentVersionId` is `null` and can be nothing else. That reading cost a session at
+  // #437, and this was the third field carrying it.
+  baseVersionId: baseVersion(
+    "baseVersionId takes the `currentVersionId` from flow_get, or null when the flow has no version yet — and it has to be sent.",
+  ).describe(
+    "The version this edit was made against, from flow_get, or `null` for a flow that has none yet. If the flow has moved on since, the call is refused rather than overwriting the newer version.",
+  ),
+  graph: FlowGraph.describe(
+    "The complete graph — nodes and edges — not a patch. It is validated before it is stored, so an unreachable node or a dangling edge is refused here rather than at run time.",
+  ),
+  idempotencyKey: IdempotencyKey,
+});
+export type SaveFlowVersionInput = z.infer<typeof SaveFlowVersionInput>;
+export const PublishFlowInput = z.strictObject({
+  flowId: IntelId.describe("Flow to publish a version of."),
+  versionId: IntelId.describe(
+    "Which version becomes the published one. Publishing freezes what it calls: a sub-flow call set to `latest` is pinned to the version current at this moment. flow_publish_preview shows that beforehand.",
+  ),
+  // ⚠️ Optional, and its absence means "leave the name as it is" rather than "no name". Publishing
+  // a second version of a flow that is already offered must not silently withdraw its command, and
+  // that is what a required-nullable field here would do to every caller who republishes without
+  // thinking about prompts (#775). `null` is how a name is actually given up.
+  promptName: PromptName.nullable()
+    .optional()
+    .describe(
+      "Offer this flow as a slash command under this name, or `null` to stop offering it. Omit to keep whatever name it has — republishing a flow does not withdraw its command.",
+    ),
+  idempotencyKey: IdempotencyKey,
+});
+export type PublishFlowInput = z.infer<typeof PublishFlowInput>;
+
+// The way back out of a publication (#146). No versionId: what is withdrawn is whatever is
+// published now, and naming one would invite a race between reading it and revoking it. Versions
+// are untouched — republishing any of them is one `publish` away.
+export const UnpublishFlowInput = z.strictObject({
+  flowId: IntelId.describe(
+    "Flow to withdraw. What is withdrawn is whatever is published now — there is no versionId, so there is no race between reading it and revoking it. Versions are untouched.",
+  ),
+  idempotencyKey: IdempotencyKey,
+});
+export type UnpublishFlowInput = z.infer<typeof UnpublishFlowInput>;
+
+export const PreviewFlowPublishInput = z.strictObject({
+  flowId: IntelId.describe("Flow the version belongs to."),
+  versionId: IntelId.describe(
+    "The version flow_publish would be called with. Nothing is changed by asking.",
+  ),
+});
+export type PreviewFlowPublishInput = z.infer<typeof PreviewFlowPublishInput>;
+
+// One sub-flow call as publishing will leave it (ADR-0004 §5). `freezes` is the whole point of the
+// preview: it marks the calls whose `latest` publishing turns into `versionId`, so the author reads
+// the decision before making it rather than after.
+//
+// ⚠️ Only callees the asking actor may reach are listed at all. A call whose callee they cannot see
+// is left out rather than named, because a title is the thing an unreachable flow must not hand out.
+export const FlowPublishCall = z.strictObject({
+  nodeId: FlowNodeId,
+  nodeLabel: z.string().min(1).max(160),
+  calleeId: IntelId,
+  calleeTitle: z.string().min(1).max(240),
+  mode: SubflowVersionMode,
+  // The version this call will take once published. `null` when it follows the callee, which is the
+  // one case where the answer is only known at run time.
+  versionId: IntelId.nullable(),
+  versionSequence: z.number().int().positive().nullable(),
+  freezes: z.boolean(),
+  // The callee has a published version to be called at all. `false` is what publishing will refuse.
+  available: z.boolean(),
+});
+export type FlowPublishCall = z.infer<typeof FlowPublishCall>;
+
+/**
+ * What a tool step will be allowed to reach once this version is published (#517).
+ *
+ * ⚠️ It is in the preview because publishing FREEZES it: from that moment the step's surface is
+ * pinned, and a function the provider adds later is not inherited. An author who cannot see the
+ * surface before confirming is asked to freeze something they were never shown.
+ */
+export const FlowPublishTool = z.strictObject({
+  nodeId: FlowNodeId,
+  nodeLabel: z.string().min(1).max(160),
+  server: ToolServerHandle,
+  // `null` is "every function of that server". A list is what the step narrowed itself to, and it
+  // is spelled out rather than counted: the whole point of the preview is that a human can read it.
+  allow: z.array(ToolName).nullable(),
+  // The server is reachable for the person publishing. `false` is what publishing will refuse.
+  available: z.boolean(),
+});
+export type FlowPublishTool = z.infer<typeof FlowPublishTool>;
+
+export const FlowPublishPreview = z.strictObject({
+  flowId: IntelId,
+  versionId: IntelId,
+  calls: z.array(FlowPublishCall),
+  tools: z.array(FlowPublishTool),
+});
+export type FlowPublishPreview = z.infer<typeof FlowPublishPreview>;
+// A flow's own sharing schemas live in `share.ts` beside the node's (#530): `ShareFlowInput`,
+// `RevokeFlowGrantInput`, `ListFlowGrantsInput`. They are there rather than here because a grant is
+// one subject with two kinds of target, not two features — and `ShareResult` answers for both.
+
+// What accesses what, for one level of the shared tree (#19). A folder answers it for its contents,
+// a single flow for itself. Documents and flows are two kinds of thing that share one tree
+// (ADR-0004 §1), so the graph carries both and says which of them it is.
+//
+// ⚠️ **DERIVED from `NodeKind`, not written out beside it** (#376). It was a hand-kept copy until
+// D66 added two kinds, and the copy did not follow — the graph would have gone on answering about
+// four kinds while the tree held six, and nothing would have said so. That is the same failure
+// `check:boundaries` refuses elsewhere; here the extra member `flow` had kept it out of the
+// checker's reach.
+export const RelationNodeKind = z.enum([...NodeKind.options, "flow"]);
+export type RelationNodeKind = z.infer<typeof RelationNodeKind>;
+
+export const RelationNode = z.strictObject({
+  id: IntelId,
+  kind: RelationNodeKind,
+  title: z.string().min(1).max(240),
+  // Inside the level being shown, rather than something it reaches out to. A flow reading a policy
+  // document from another folder pulls that document in, and the difference should be legible.
+  inScope: z.boolean(),
+  // ⚠️ The radial tree's own structure (#825), and deliberately not an edge: a "belongs" relation
+  // would duplicate what `parentId` already says and give two places for the two to drift.
+  // `depth` is the ring this node sits on, counted from the folder or flow being viewed (depth 0).
+  // A node reached only through a `reads`/`calls` edge — never part of the tree itself — carries the
+  // depth of whichever in-tree node reached it and a `null` parent, so the renderer knows not to
+  // draw a membership arc for it.
+  parentId: IntelId.nullable(),
+  depth: z.number().int().nonnegative(),
+});
+export type RelationNode = z.infer<typeof RelationNode>;
+
+export const RelationEdge = z.strictObject({
+  id: z.string().min(1).max(400),
+  source: IntelId,
+  target: IntelId,
+  relation: z.enum(["reads", "calls"]),
+});
+export type RelationEdge = z.infer<typeof RelationEdge>;
+
+// A user who may reach a node the viewer is looking at, and only ever THAT (#825). No name here on
+// purpose: `id` is resolved through the same directory lookup every other screen already uses
+// (`ResolvedNamesProvider`), so a name that later changes does not have to be threaded through this
+// schema as well.
+export const RelationUser = z.strictObject({ id: IntelId });
+export type RelationUser = z.infer<typeof RelationUser>;
+
+// ⚠️ Drawn only from a node the viewer holds `share` on (#825, `nodes.ts:1537`). `node_effective_access_list`
+// refuses a caller without `share` with a `403` — a graph that drew this edge anyway would hand out,
+// for every node in it, an answer the tool right next to it refuses to give.
+export const RelationAccessEdge = z.strictObject({ userId: IntelId, nodeId: IntelId });
+export type RelationAccessEdge = z.infer<typeof RelationAccessEdge>;
+
+export const RelationGraphScope = z.discriminatedUnion("of", [
+  z.strictObject({ of: z.literal("folder"), folderId: IntelId.nullable() }),
+  z.strictObject({ of: z.literal("flow"), flowId: IntelId }),
+]);
+export type RelationGraphScope = z.infer<typeof RelationGraphScope>;
+
+export const RelationGraphInput = z.strictObject({
+  scope: RelationGraphScope.describe(
+    "What to draw around: one folder — `null` for the whole tree — or one flow.",
+  ),
+  // How much is drawn before the answer is summarized instead. A big folder has to stay usable, and
+  // the cut-off is reported rather than swallowed.
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(300)
+    .default(60)
+    .describe(
+      "How many nodes the drawing may carry before it is summarized instead. What was left out is reported in `omitted` rather than swallowed.",
+    ),
+});
+export type RelationGraphInput = z.infer<typeof RelationGraphInput>;
+
+// ⚠️ Only what the asking user may see is in here. A node they may not reach is absent, not greyed
+// out and not counted: an edge to a placeholder would already tell them the thing exists, which is
+// the leak this schema has to make impossible to write by accident. `omitted` is about the size
+// limit alone, never about permissions.
+export const RelationGraph = z.strictObject({
+  scope: RelationGraphScope,
+  nodes: z.array(RelationNode),
+  edges: z.array(RelationEdge),
+  // The outer ring (#825). `users` is the distinct set `access` points at — never every member of
+  // the organization, and never a user reachable only through an `email` or `organization` grant,
+  // because neither names a single account this drawing could point a line at.
+  users: z.array(RelationUser),
+  access: z.array(RelationAccessEdge),
+  omitted: z.number().int().nonnegative(),
+  limit: z.number().int().positive(),
+});
+export type RelationGraph = z.infer<typeof RelationGraph>;