@anchrd/intel 0.59.0

package/src/contract/node.ts

@@ -0,0 +1,583 @@
+import { z } from "zod";
+import { baseVersion, IdempotencyKey, IntelId, IsoDateTime, PromptName } from "./contract.ts";
+
+// What this installation is equipped to do — deployment facts, never the caller's permissions
+// (those stay behind each door, where `/session` deliberately does not carry them). `agentRuntime`
+// says whether an agent Worker is bound at all (#190): without it the UI offers no "New agent" and
+// an agent node explains itself instead of rendering views that could only end in a 503.
+// The fourth kind is `table` (#40); `board` and `task` are the fifth and sixth (**D66**, #376).
+// Each is a kind of node, not a kind of thing: it hangs in the same folder tree, inherits the same
+// folder grants, carries the same immutable versions and the same R2 body as a document
+// (ADR-0004 §1). Only the media type and the operations below differ. `agent` is NOT among them —
+// D65 moved agents out of Intel entirely (ADR-0007).
+//
+// ⚠️ **The sentence that stood here said the opposite, and it was right for its day.** Until
+// 2026-08-20 this comment read *"a board is one node carrying its tasks and not a folder that only
+// tasks may live in (#285)"*. D66 reverses it, and the reason is not taste:
+//
+//   * **The tree has to hide `task` on EVERY level query.** As a kind that is a condition on a
+//     column already in the statement; as a `document` plus a side-table row it would be a join on
+//     the hottest path. And with tasks hidden a board has no visible children, so the chevron falls
+//     away with no rule of its own.
+//   * **`audit_list` exists since #620.** A task that is a node makes "task assigned to Paul" an
+//     event `anchrd/signals` can pick up. Inside one board's content every change looks the same
+//     from outside — "the board changed" — and nothing can act on it.
+//
+// ⚠️ What did NOT change: `status`, `assignee`, the dates and the ordering live in `board_tasks`,
+// not on the node. They are filter columns and would stand empty on every other kind.
+export const NodeKind = z.enum(["folder", "document", "attachment", "table", "board", "task"]);
+export type NodeKind = z.infer<typeof NodeKind>;
+
+export const Node = z.strictObject({
+  id: IntelId,
+  parentId: IntelId.nullable(),
+  kind: NodeKind,
+  title: z.string().min(1).max(240),
+  description: z.string().max(2_000).nullable(),
+  ownerId: IntelId,
+  currentVersionId: IntelId.nullable(),
+  createdAt: IsoDateTime,
+  updatedAt: IsoDateTime,
+  archivedAt: IsoDateTime.nullable(),
+  // The slash command this document is offered under, or `null` for the overwhelming majority that
+  // are not offered at all (#775).
+  //
+  // ⚠️ Required-and-nullable rather than optional, and every reader of a node pays one field for
+  // it. The alternative — filling it in only where a surface needs it — is the shape that answers
+  // `undefined` on the query which forgot its join, and then "not offered" and "nobody asked" are
+  // the same value. Only a `document` can carry one; the other five kinds are held to `null` by a
+  // CHECK in `0028`, not merely by habit.
+  promptName: PromptName.nullable(),
+});
+export type Node = z.infer<typeof Node>;
+
+// What one table version carries (#135). An `append` holds only the rows one write added; a
+// `snapshot` holds the complete table — header and every row — so reading starts at the newest
+// snapshot and everything before it is history rather than content. Defining a table writes the
+// first snapshot; updating, deleting, and redefining write the later ones. Documents and
+// attachments carry `null`: each of their versions is complete by construction, and the word would
+// say nothing about them.
+export const NodeVersionSegment = z.enum(["append", "snapshot"]);
+export type NodeVersionSegment = z.infer<typeof NodeVersionSegment>;
+
+export const NodeVersion = z.strictObject({
+  id: IntelId,
+  nodeId: IntelId,
+  sequence: z.number().int().positive(),
+  contentKey: z.string().min(1),
+  mediaType: z.string().min(1).max(160),
+  contentHash: z.string().regex(/^[a-f0-9]{64}$/),
+  size: z.number().int().nonnegative(),
+  segment: NodeVersionSegment.nullable(),
+  createdBy: IntelId,
+  createdAt: IsoDateTime,
+});
+export type NodeVersion = z.infer<typeof NodeVersion>;
+
+export const ListNodesInput = z.strictObject({
+  parentId: IntelId.nullable()
+    .default(null)
+    .describe("Folder to list the direct children of. `null` lists the top level."),
+  includeArchived: z
+    .boolean()
+    .default(false)
+    .describe("Include archived nodes beside the live ones instead of hiding them."),
+  // ⚠️ Overrides `parentId` rather than narrowing beside it: what is archived is asked for across
+  // the whole tree, because that is the only useful question. Somebody looking for what they threw
+  // away does not know which folder it was in — if they did, they would not be looking (#113).
+  // A separate flag rather than a third state on `includeArchived`, so no existing caller changes
+  // meaning — and `.optional()` rather than `.default(false)` for the same reason `ListFlowsInput`
+  // carries it that way: a default makes the field required in the PARSED type, and every existing
+  // caller would have to answer a question it is not asking.
+  archivedOnly: z
+    .boolean()
+    .optional()
+    .describe(
+      "List only archived nodes, across the whole tree. Overrides parentId rather than narrowing it: somebody looking for what they threw away does not know which folder it was in.",
+    ),
+});
+export type ListNodesInput = z.infer<typeof ListNodesInput>;
+
+export const GetNodeInput = z.strictObject({
+  nodeId: IntelId.describe("Node to read, from node_list or search."),
+});
+export type GetNodeInput = z.infer<typeof GetNodeInput>;
+
+/**
+ * An attachment, with the option of its bytes.
+ *
+ * ⚠️ One tool rather than a second one beside `node_attachment_get`, because the grammar in
+ * `packages/intel/CLAUDE.md` gives one verb one meaning: `get` reads one, and metadata and bytes are
+ * two halves of the same one. It mirrors HTTP, where `GET /nodes/:nodeId/attachment` and its
+ * `/meta` sibling have always been the same tool.
+ *
+ * ⚠️ The default is `false` on purpose. The bytes travel as base64 in the answer, so asking for
+ * them by accident would put a whole file into a model's context; a caller that wants the file says
+ * so. `SaveAttachmentInput` has carried bytes the other way since the beginning — this closes the
+ * asymmetry that let a model upload a PDF it could never read back (#773).
+ */
+export const GetAttachmentInput = z.strictObject({
+  nodeId: IntelId.describe("Attachment node to read, from node_list or search."),
+  includeContent: z
+    .boolean()
+    .default(false)
+    .describe(
+      "Return the file itself beside its metadata. Default false answers metadata only. Files above 10 MB are refused here and take the HTTP door, which streams.",
+    ),
+});
+export type GetAttachmentInput = z.infer<typeof GetAttachmentInput>;
+
+// One pinned version of one node (#147). Both IDs, always: a version ID alone would let anyone
+// holding an ID read content whose node-level ACL they never passed, and a citation names both.
+export const GetNodeVersionInput = z.strictObject({
+  nodeId: IntelId.describe(
+    "Node the version belongs to. Required even though the version id is unique: access is decided on the node.",
+  ),
+  versionId: IntelId.describe("Version to read, from node_version_list or a search citation."),
+});
+export type GetNodeVersionInput = z.infer<typeof GetNodeVersionInput>;
+
+export const CreateNodeInput = z.strictObject({
+  parentId: IntelId.nullable()
+    .default(null)
+    .describe("Folder to file the new node in. `null` puts it at the top level."),
+  kind: NodeKind.describe(
+    "What the node is. A folder and a board hold others and have no content of their own; document, task, attachment and table each carry their own body, written afterwards by node_version_create (document and task), node_attachment_create or node_table_create. A task created under a board lands on that board.",
+  ),
+  title: z
+    .string()
+    .trim()
+    .min(1)
+    .max(240)
+    .describe(
+      "What the node is called. Shown in the tree and searched. ⚠️ `index` inside a folder is reserved: a document of that name (`index`, `Index` or `index.md`) is the TEXT OF THAT FOLDER, and a browser shows it in the folder's details rather than as a row under it. Naming a document that for another reason changes how its folder reads.",
+    ),
+  description: z
+    .string()
+    .trim()
+    .max(2_000)
+    .nullable()
+    .default(null)
+    .describe("Optional sentence about the node, for readers rather than for search ranking."),
+  idempotencyKey: IdempotencyKey,
+});
+export type CreateNodeInput = z.infer<typeof CreateNodeInput>;
+
+export const SaveNodeVersionInput = z.strictObject({
+  nodeId: IntelId.describe(
+    "Document or board card to append a version to. A card's text is a node version like any other, so this is how a ticket gets its context, steps and definition of done instead of a one-line description. Folders, boards, attachments and tables carry their content another way and refuse.",
+  ),
+  baseVersionId: baseVersion(
+    "baseVersionId takes the `currentVersionId` from node_get, or null when the node has no version yet — and it has to be sent.",
+  ).describe(
+    "The version this edit was made against — `currentVersionId` from node_get. If the node has moved on since, the call is refused rather than overwriting the newer version; pass `null` only for a node that has no version yet.",
+  ),
+  content: z
+    .string()
+    .max(10_000_000)
+    .describe("The complete new content. Versions are whole documents, not patches."),
+  mediaType: z
+    .string()
+    .min(1)
+    .max(160)
+    .default("text/markdown")
+    .describe("Media type of `content`. Leave at text/markdown unless writing another format."),
+  idempotencyKey: IdempotencyKey,
+});
+export type SaveNodeVersionInput = z.infer<typeof SaveNodeVersionInput>;
+
+export const SaveAttachmentInput = z.strictObject({
+  nodeId: IntelId.describe("Attachment node to append bytes to."),
+  baseVersionId: baseVersion(
+    "baseVersionId takes the `currentVersionId` from node_get, or null for the first upload — and it has to be sent.",
+  ).describe(
+    "The version these bytes replace — `currentVersionId` from node_get, or `null` for the first upload. A stale value is refused rather than overwriting.",
+  ),
+  contentBase64: z
+    .string()
+    .min(1)
+    .max(20_000_000)
+    .describe(
+      "The file, base64-encoded — around 15 MB of bytes at most. Encoding grows a file by a third and this door holds the whole of it in memory, encoded and decoded at once. A bigger file goes to `POST /nodes/:nodeId/attachment/bytes`, whose body IS the file and which streams it to storage.",
+    ),
+  mediaType: z
+    .string()
+    .min(1)
+    .max(160)
+    .describe("Media type of the decoded bytes, e.g. application/pdf."),
+  idempotencyKey: IdempotencyKey,
+});
+export type SaveAttachmentInput = z.infer<typeof SaveAttachmentInput>;
+
+/**
+ * How many bytes an attachment may carry through the streaming door (#821).
+ *
+ * ⚠️ **This is our number, not the platform's.** A Worker refuses a request body over 100 MB on the
+ * Free and Pro plans (200 MB on Business, 500 MB on Enterprise by default), and the isolate that
+ * receives it has 128 MB of memory for everything it does at once. 50 MB is the presentation and
+ * PDF size this was raised for, and it leaves the hard ceiling a factor of two away — which is what
+ * makes a file over the limit a sentence the reader gets rather than a connection that drops.
+ *
+ * ⚠️ It is not the limit of the base64 door beside it. That one stays where it was, because there
+ * the file exists twice in memory before a single byte is stored; `contentBase64` says so.
+ */
+/**
+ * The name a document takes to become the TEXT OF ITS FOLDER (#824).
+ *
+ * ⚠️ It is a convention that already existed: nearly every folder in this installation holds a
+ * document called `index` describing what is in it, and every person had to be told so. A surface
+ * that serves the convention makes the telling unnecessary — and nothing about the model changes:
+ * the document stays a document, in full text and in the vectors, with its versions, without a
+ * length limit and with version-pinned citations.
+ *
+ * ⚠️ **The comparison is case-insensitive, and `index.md` counts too.** The three spellings the
+ * decision names — `index`, `Index`, `index.md` — are all covered by it, and so are the ones nobody
+ * thought of. A list of exact spellings would make `INDEX` a different document from `index` for no
+ * reason a reader could guess.
+ *
+ * ⚠️ It lives in the contract because three surfaces need the same answer: the browser hides the
+ * row, the MCP tool description explains the name to a model, and neither may disagree with the
+ * other about what counts.
+ */
+export function isFolderIndexTitle(title: string): boolean {
+  const name = title.trim().toLowerCase();
+  return name === "index" || name === "index.md";
+}
+
+export const MaxAttachmentBytes = 50_000_000;
+
+/**
+ * The largest attachment whose CONTENTS are read and converted for the index (#821).
+ *
+ * ⚠️ A bigger file is stored, opened and downloaded exactly like any other; what it does not get is
+ * a search over its text. The indexing pass reads an attachment into memory whole and hands it to
+ * the converter as a blob beside it, so at 50 MB it would meet the isolate's 128 MB — and an upload
+ * that succeeds and then dies while being indexed is the worst of both: the file is filed and
+ * cannot be found.
+ *
+ * ⚠️ The number is 15 MB because that is what the old upload limit was. Every file that could be
+ * uploaded before this ticket therefore behaves exactly as it did; only the sizes that were
+ * impossible until now fall into the new case. Raising it is a measurement, not a decision to take
+ * in passing.
+ */
+export const MaxIndexedAttachmentBytes = 15_000_000;
+
+/**
+ * The streaming door for one attachment: everything ABOUT the bytes, while the bytes are the
+ * request body (#821).
+ *
+ * ⚠️ It has no MCP twin, and that is the one place where "every capability has an MCP equivalent"
+ * is answered by the door beside it instead: MCP carries JSON, so a tool cannot hand over a body.
+ * `SaveAttachmentInput` IS the MCP form of this capability, and the size is what separates them.
+ *
+ * ⚠️ `mediaType` travels as the request's own `content-type`, and `size` as its `content-length`.
+ * Both are read from the headers rather than invented here, because the body they describe is the
+ * body being sent; a second, hand-written statement about the same bytes is a second truth.
+ */
+export const SaveAttachmentBytesInput = z.strictObject({
+  nodeId: IntelId.describe("Attachment node to append bytes to."),
+  baseVersionId: baseVersion(
+    "baseVersionId takes the `currentVersionId` from node_get, or null for the first upload — and it has to be sent.",
+  ),
+  mediaType: z.string().min(1).max(160),
+  size: z
+    .number()
+    .int()
+    .positive()
+    .max(MaxAttachmentBytes)
+    .describe("Length of the body in bytes, as `content-length` announces it."),
+  idempotencyKey: IdempotencyKey,
+});
+export type SaveAttachmentBytesInput = z.infer<typeof SaveAttachmentBytesInput>;
+
+export const UpdateNodeInput = z
+  .strictObject({
+    nodeId: IntelId.describe("Node to change."),
+    baseUpdatedAt: IsoDateTime.describe(
+      "`updatedAt` as node_get last reported it. A newer value on the server means somebody else changed the node 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 node into, or `null` for the top level. Omit to leave it where it is.",
+      ),
+    // ⚠️ Three states, and all three are used: a name offers the document, `null` withdraws it, and
+    // omitting the field leaves whatever is there. A `promptEnabled` boolean beside a name would
+    // have a fourth — on, without a name — and `prompts/list` could not answer it (#775).
+    promptName: PromptName.nullable()
+      .optional()
+      .describe(
+        "Offer this document as a slash command under this name, or `null` to stop offering it. Omit to leave it as it is. Only a `document` can be offered: a folder, table, attachment, board or task is refused rather than quietly ignored.",
+      ),
+    idempotencyKey: IdempotencyKey,
+  })
+  .refine(
+    (input) =>
+      input.title !== undefined ||
+      input.description !== undefined ||
+      input.parentId !== undefined ||
+      input.promptName !== undefined,
+    { message: "At least one change is required" },
+  );
+export type UpdateNodeInput = z.infer<typeof UpdateNodeInput>;
+
+export const ArchiveNodeInput = z.strictObject({
+  nodeId: IntelId.describe("Node to archive or restore."),
+  baseUpdatedAt: IsoDateTime.describe(
+    "`updatedAt` as node_get last reported it. A newer value on the server means somebody else changed the node first and the call is refused.",
+  ),
+  archived: z
+    .boolean()
+    .describe(
+      "`true` archives the node, `false` restores it. Archiving hides a node from listings and search; nothing is deleted and every version stays readable.",
+    ),
+  idempotencyKey: IdempotencyKey,
+});
+export type ArchiveNodeInput = z.infer<typeof ArchiveNodeInput>;
+
+// ⚠️ The one input in this contract that describes an IRREVERSIBLE act (#457). Everything else
+// called "delete" in Intel means `archived_at`.
+//
+// It carries no `baseUpdatedAt` and no `idempotencyKey`, and both absences are decisions:
+//   · There is nothing to conflict with. The node must already be archived — an archived node is
+//     not being edited by anybody, and a restore between the read and the call is caught by the
+//     statement itself rather than by a timestamp the caller had to carry.
+//   · A replay has nothing to replay. Deleting twice is deleting once and then a 404, which is the
+//     honest answer: the second caller really did not delete anything.
+export const PurgeNodeInput = z.strictObject({
+  nodeId: IntelId.describe(
+    "Node to delete for good. It must already be archived — a living node has no path into nothing.",
+  ),
+  idempotencyKey: IdempotencyKey,
+});
+export type PurgeNodeInput = z.infer<typeof PurgeNodeInput>;
+
+// The question `PurgeNodeInput` cannot be asked afterwards: what goes with it, while it is all
+// still there to be counted. Described since #586, because the count reached MCP that day — and a
+// surface that may delete without being able to look first is the state `destructive.md` calls a
+// confirmation that cannot name what disappears.
+export const PurgeNodePreviewInput = z.strictObject({
+  nodeId: IntelId.describe(
+    "Archived node a purge would delete. Answers how many items would go with it and how many documents link to it from outside, and changes nothing. A node that is not archived is refused here for the same reason node_purge refuses it.",
+  ),
+});
+export type PurgeNodePreviewInput = z.infer<typeof PurgeNodePreviewInput>;
+
+/**
+ * ⚠️ **A count is not an answer before a deletion that cannot be undone** (D71, #733). `totalItems`
+ * alone reads as "82 items" for a folder holding somebody's whole memory, and `destructive.md` asks
+ * for the number to be named BEFORE the confirmation — one step more precise is the difference
+ * between a number and something a person can decide on.
+ *
+ * `items` is capped, and the cap is visible rather than silent: `totalItems` keeps counting past it,
+ * so a caller can always say "and 40 more". A list of ten thousand rows would be an answer nobody
+ * reads and a response nobody can render.
+ */
+export const PurgeNodePreview = z.strictObject({
+  inboundLinks: z.number().int().nonnegative(),
+  totalItems: z.number().int().positive(),
+  // ⚠️ `flow` beside the node kinds, because a flow filed in the folder goes with it and is counted
+  // in `totalItems`. Naming everything except flows would leave out the one thing the cascade had to
+  // be widened for (#733).
+  items: z.array(
+    z.strictObject({
+      id: IntelId,
+      kind: z.union([NodeKind, z.literal("flow")]),
+      title: z.string(),
+    }),
+  ),
+});
+export type PurgeNodePreview = z.infer<typeof PurgeNodePreview>;
+
+// The title travels back because after this call nothing can look it up any more — not the row, not
+// a version, not the index. A caller that wants to say what it just deleted has this one chance.
+export const PurgeNodeResult = z.strictObject({
+  purged: z.literal(true),
+  title: z.string(),
+});
+export type PurgeNodeResult = z.infer<typeof PurgeNodeResult>;
+
+// ⚠️ `withChildren` belongs to the LEVEL, not to the node (#59). Whether something has children
+// THIS reader may see is not a property of the thing — two readers get different answers. As a
+// field on the node, every other place that returns a node would have to compute it as well or
+// lie; as a list beside the entries it costs only the one answer that needs it.
+export const NodeList = z.strictObject({
+  items: z.array(Node),
+  withChildren: z.array(IntelId).default([]),
+});
+export type NodeList = z.infer<typeof NodeList>;
+
+export const NodeVersionList = z.strictObject({ items: z.array(NodeVersion) });
+export type NodeVersionList = z.infer<typeof NodeVersionList>;
+
+export const NodeDocument = z.strictObject({
+  node: Node,
+  version: NodeVersion.nullable(),
+  content: z.string().nullable(),
+});
+export type NodeDocument = z.infer<typeof NodeDocument>;
+
+export const NodeAttachment = z.strictObject({
+  node: Node,
+  version: NodeVersion,
+  resourceUri: z.string().regex(/^intel:\/\/nodes\/[^/]+\/attachment$/),
+});
+export type NodeAttachment = z.infer<typeof NodeAttachment>;
+
+// The table as a grid rather than as text: the server owns the one CSV reader, so no surface has to
+// grow a second one that would disagree with it about quoting.
+export const NodeTable = z.strictObject({
+  node: Node,
+  columns: z.array(z.string()),
+  rows: z.array(z.array(z.string())),
+  // The newest append, or `null` while the table has no header yet.
+  versionId: IntelId.nullable(),
+});
+export type NodeTable = z.infer<typeof NodeTable>;
+
+export const NodeLinkRelation = z.enum(["references", "related", "depends_on", "implements"]);
+export type NodeLinkRelation = z.infer<typeof NodeLinkRelation>;
+
+// Where the link came from. `text` links are derived from a document's content and are rewritten
+// whenever it is saved; `manual` links were made in the dialog #41 removed and are now history.
+//
+// ⚠️ This is provenance, never a second sort of relationship. Nothing offers the reader a choice
+// between them, and nothing may start writing `manual` again — that would be the two ways of saying
+// one thing that #41 exists to end. It exists so that saving a document cannot delete a link
+// somebody made before there was another way to make one.
+export const NodeLinkOrigin = z.enum(["text", "manual"]);
+export type NodeLinkOrigin = z.infer<typeof NodeLinkOrigin>;
+
+export const NodeLink = z.strictObject({
+  id: IntelId,
+  sourceNodeId: IntelId,
+  targetNodeId: IntelId,
+  relation: NodeLinkRelation,
+  origin: NodeLinkOrigin,
+  label: z.string().trim().min(1).max(120).nullable(),
+  createdBy: IntelId,
+  createdAt: IsoDateTime,
+});
+export type NodeLink = z.infer<typeof NodeLink>;
+
+export const NodeLinkList = z.strictObject({ items: z.array(NodeLink) });
+export type NodeLinkList = z.infer<typeof NodeLinkList>;
+
+// The inline element a document link is, inside a BlockNote document (#41).
+//
+// ⚠️ The ID and nothing else. No title and no path travel with it: a stored title would go stale
+// the moment the target is renamed, a stored path the moment it is moved — and either one would
+// put a name the reader may not see into a document they may.
+export const DocumentLinkInlineType = "documentLink";
+
+export const ResolveNodeLinksInput = z.strictObject({
+  nodeIds: z
+    .array(IntelId)
+    .min(1)
+    .max(200)
+    .describe(
+      "The link targets to name, as found in a document's documentLink elements. Unreachable and deleted targets are simply absent from the answer, so a shorter list than asked for is normal.",
+    ),
+});
+export type ResolveNodeLinksInput = z.infer<typeof ResolveNodeLinksInput>;
+
+export const ResolvedNodeLink = z.strictObject({
+  nodeId: IntelId,
+  title: z.string().min(1).max(240),
+});
+export type ResolvedNodeLink = z.infer<typeof ResolvedNodeLink>;
+
+// ⚠️ Only what the asking reader may see is in here, and an unreachable target is simply absent —
+// never a row with an empty title, never a count, never a "restricted" marker. The list is what one
+// side of a document link is drawn from, and an entry that says "something is here" is exactly the
+// leak this schema has to make impossible to write by accident. Deleted and unreadable therefore
+// look identical from the outside, which is the point.
+export const ResolveNodeLinksResult = z.strictObject({
+  items: z.array(ResolvedNodeLink),
+});
+export type ResolveNodeLinksResult = z.infer<typeof ResolveNodeLinksResult>;
+
+export const NodeGraphInput = z.strictObject({
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(500)
+    .default(250)
+    .describe("How many nodes the graph may carry. The links returned are the ones between them."),
+});
+export type NodeGraphInput = z.infer<typeof NodeGraphInput>;
+
+export const NodeGraph = z.strictObject({
+  nodes: z.array(Node),
+  links: z.array(NodeLink),
+});
+export type NodeGraph = z.infer<typeof NodeGraph>;
+
+export const BlockNoteMediaType = "application/vnd.anchrd.intel.blocknote+json";
+export const BlockNoteDocument = z.strictObject({
+  format: z.literal("blocknote"),
+  schemaVersion: z.literal(1),
+  blocks: z.array(z.record(z.string(), z.unknown())),
+  markdown: z.string(),
+});
+export type BlockNoteDocument = z.infer<typeof BlockNoteDocument>;
+
+// `scopeId` is a cut, never a grant (#126): it narrows an answer the actor is already entitled to
+// and can only ever remove rows. Without it the search stays global over everything visible, which
+// is why it is optional rather than nullable — an absent field and `null` would otherwise be two
+// spellings of the same request.
+export const SearchInput = z.strictObject({
+  query: z
+    .string()
+    .trim()
+    .min(1)
+    .max(500)
+    .describe(
+      "What to look for, in the reader's own words. Matched both lexically and semantically, so a question works as well as keywords.",
+    ),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(50)
+    .default(10)
+    .describe("How many citations to return, best first."),
+  scopeId: IntelId.optional().describe(
+    "Optional folder node id. When given, only nodes filed in that folder or beneath it are searched.",
+  ),
+});
+export type SearchInput = z.infer<typeof SearchInput>;
+
+export const NodeCitation = z.strictObject({
+  nodeId: IntelId,
+  versionId: IntelId,
+  title: z.string(),
+  passage: z.string(),
+  source: z.string(),
+  freshness: IsoDateTime,
+  score: z.number().min(0).max(1),
+  match: z.enum(["lexical", "semantic", "hybrid"]),
+});
+export type NodeCitation = z.infer<typeof NodeCitation>;
+
+export const SearchResult = z.strictObject({
+  items: z.array(NodeCitation),
+});
+export type SearchResult = z.infer<typeof SearchResult>;
+export const ReindexResult = z.strictObject({ queued: z.number().int().nonnegative() });
+export type ReindexResult = z.infer<typeof ReindexResult>;