@anchrd/intel-contract 0.12.0 → 0.14.0

package/dist/contract/node.d.ts

@@ -0,0 +1,402 @@
+import { z } from "zod";
+export declare const NodeKind: z.ZodEnum<{
+    folder: "folder";
+    document: "document";
+    table: "table";
+    attachment: "attachment";
+}>;
+export type NodeKind = z.infer<typeof NodeKind>;
+export declare const Node: z.ZodObject<{
+    id: z.ZodString;
+    parentId: z.ZodNullable<z.ZodString>;
+    kind: z.ZodEnum<{
+        folder: "folder";
+        document: "document";
+        table: "table";
+        attachment: "attachment";
+    }>;
+    title: z.ZodString;
+    description: z.ZodNullable<z.ZodString>;
+    ownerId: z.ZodString;
+    currentVersionId: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodISODateTime;
+    updatedAt: z.ZodISODateTime;
+    archivedAt: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strict>;
+export type Node = z.infer<typeof Node>;
+export declare const NodeVersionSegment: z.ZodEnum<{
+    append: "append";
+    snapshot: "snapshot";
+}>;
+export type NodeVersionSegment = z.infer<typeof NodeVersionSegment>;
+export declare const NodeVersion: z.ZodObject<{
+    id: z.ZodString;
+    nodeId: z.ZodString;
+    sequence: z.ZodNumber;
+    contentKey: z.ZodString;
+    mediaType: z.ZodString;
+    contentHash: z.ZodString;
+    size: z.ZodNumber;
+    segment: z.ZodNullable<z.ZodEnum<{
+        append: "append";
+        snapshot: "snapshot";
+    }>>;
+    createdBy: z.ZodString;
+    createdAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export type NodeVersion = z.infer<typeof NodeVersion>;
+export declare const ListNodesInput: z.ZodObject<{
+    parentId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    includeArchived: z.ZodDefault<z.ZodBoolean>;
+    archivedOnly: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type ListNodesInput = z.infer<typeof ListNodesInput>;
+export declare const GetNodeInput: z.ZodObject<{
+    nodeId: z.ZodString;
+}, z.core.$strict>;
+export type GetNodeInput = z.infer<typeof GetNodeInput>;
+export declare const GetNodeVersionInput: z.ZodObject<{
+    nodeId: z.ZodString;
+    versionId: z.ZodString;
+}, z.core.$strict>;
+export type GetNodeVersionInput = z.infer<typeof GetNodeVersionInput>;
+export declare const CreateNodeInput: z.ZodObject<{
+    parentId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    kind: z.ZodEnum<{
+        folder: "folder";
+        document: "document";
+        table: "table";
+        attachment: "attachment";
+    }>;
+    title: z.ZodString;
+    description: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    idempotencyKey: z.ZodString;
+}, z.core.$strict>;
+export type CreateNodeInput = z.infer<typeof CreateNodeInput>;
+export declare const SaveNodeVersionInput: z.ZodObject<{
+    nodeId: z.ZodString;
+    baseVersionId: z.ZodNullable<z.ZodString>;
+    content: z.ZodString;
+    mediaType: z.ZodDefault<z.ZodString>;
+    idempotencyKey: z.ZodString;
+}, z.core.$strict>;
+export type SaveNodeVersionInput = z.infer<typeof SaveNodeVersionInput>;
+export declare const SaveAttachmentInput: z.ZodObject<{
+    nodeId: z.ZodString;
+    baseVersionId: z.ZodNullable<z.ZodString>;
+    contentBase64: z.ZodString;
+    mediaType: z.ZodString;
+    idempotencyKey: z.ZodString;
+}, z.core.$strict>;
+export type SaveAttachmentInput = z.infer<typeof SaveAttachmentInput>;
+export declare const UpdateNodeInput: z.ZodObject<{
+    nodeId: z.ZodString;
+    baseUpdatedAt: z.ZodISODateTime;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    parentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    idempotencyKey: z.ZodString;
+}, z.core.$strict>;
+export type UpdateNodeInput = z.infer<typeof UpdateNodeInput>;
+export declare const ArchiveNodeInput: z.ZodObject<{
+    nodeId: z.ZodString;
+    baseUpdatedAt: z.ZodISODateTime;
+    archived: z.ZodBoolean;
+    idempotencyKey: z.ZodString;
+}, z.core.$strict>;
+export type ArchiveNodeInput = z.infer<typeof ArchiveNodeInput>;
+export declare const NodeList: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        parentId: z.ZodNullable<z.ZodString>;
+        kind: z.ZodEnum<{
+            folder: "folder";
+            document: "document";
+            table: "table";
+            attachment: "attachment";
+        }>;
+        title: z.ZodString;
+        description: z.ZodNullable<z.ZodString>;
+        ownerId: z.ZodString;
+        currentVersionId: z.ZodNullable<z.ZodString>;
+        createdAt: z.ZodISODateTime;
+        updatedAt: z.ZodISODateTime;
+        archivedAt: z.ZodNullable<z.ZodISODateTime>;
+    }, z.core.$strict>>;
+    withChildren: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type NodeList = z.infer<typeof NodeList>;
+export declare const NodeVersionList: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        nodeId: z.ZodString;
+        sequence: z.ZodNumber;
+        contentKey: z.ZodString;
+        mediaType: z.ZodString;
+        contentHash: z.ZodString;
+        size: z.ZodNumber;
+        segment: z.ZodNullable<z.ZodEnum<{
+            append: "append";
+            snapshot: "snapshot";
+        }>>;
+        createdBy: z.ZodString;
+        createdAt: z.ZodISODateTime;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type NodeVersionList = z.infer<typeof NodeVersionList>;
+export declare const NodeDocument: z.ZodObject<{
+    node: z.ZodObject<{
+        id: z.ZodString;
+        parentId: z.ZodNullable<z.ZodString>;
+        kind: z.ZodEnum<{
+            folder: "folder";
+            document: "document";
+            table: "table";
+            attachment: "attachment";
+        }>;
+        title: z.ZodString;
+        description: z.ZodNullable<z.ZodString>;
+        ownerId: z.ZodString;
+        currentVersionId: z.ZodNullable<z.ZodString>;
+        createdAt: z.ZodISODateTime;
+        updatedAt: z.ZodISODateTime;
+        archivedAt: z.ZodNullable<z.ZodISODateTime>;
+    }, z.core.$strict>;
+    version: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        nodeId: z.ZodString;
+        sequence: z.ZodNumber;
+        contentKey: z.ZodString;
+        mediaType: z.ZodString;
+        contentHash: z.ZodString;
+        size: z.ZodNumber;
+        segment: z.ZodNullable<z.ZodEnum<{
+            append: "append";
+            snapshot: "snapshot";
+        }>>;
+        createdBy: z.ZodString;
+        createdAt: z.ZodISODateTime;
+    }, z.core.$strict>>;
+    content: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type NodeDocument = z.infer<typeof NodeDocument>;
+export declare const NodeAttachment: z.ZodObject<{
+    node: z.ZodObject<{
+        id: z.ZodString;
+        parentId: z.ZodNullable<z.ZodString>;
+        kind: z.ZodEnum<{
+            folder: "folder";
+            document: "document";
+            table: "table";
+            attachment: "attachment";
+        }>;
+        title: z.ZodString;
+        description: z.ZodNullable<z.ZodString>;
+        ownerId: z.ZodString;
+        currentVersionId: z.ZodNullable<z.ZodString>;
+        createdAt: z.ZodISODateTime;
+        updatedAt: z.ZodISODateTime;
+        archivedAt: z.ZodNullable<z.ZodISODateTime>;
+    }, z.core.$strict>;
+    version: z.ZodObject<{
+        id: z.ZodString;
+        nodeId: z.ZodString;
+        sequence: z.ZodNumber;
+        contentKey: z.ZodString;
+        mediaType: z.ZodString;
+        contentHash: z.ZodString;
+        size: z.ZodNumber;
+        segment: z.ZodNullable<z.ZodEnum<{
+            append: "append";
+            snapshot: "snapshot";
+        }>>;
+        createdBy: z.ZodString;
+        createdAt: z.ZodISODateTime;
+    }, z.core.$strict>;
+    resourceUri: z.ZodString;
+}, z.core.$strict>;
+export type NodeAttachment = z.infer<typeof NodeAttachment>;
+export declare const NodeTable: z.ZodObject<{
+    node: z.ZodObject<{
+        id: z.ZodString;
+        parentId: z.ZodNullable<z.ZodString>;
+        kind: z.ZodEnum<{
+            folder: "folder";
+            document: "document";
+            table: "table";
+            attachment: "attachment";
+        }>;
+        title: z.ZodString;
+        description: z.ZodNullable<z.ZodString>;
+        ownerId: z.ZodString;
+        currentVersionId: z.ZodNullable<z.ZodString>;
+        createdAt: z.ZodISODateTime;
+        updatedAt: z.ZodISODateTime;
+        archivedAt: z.ZodNullable<z.ZodISODateTime>;
+    }, z.core.$strict>;
+    columns: z.ZodArray<z.ZodString>;
+    rows: z.ZodArray<z.ZodArray<z.ZodString>>;
+    versionId: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type NodeTable = z.infer<typeof NodeTable>;
+export declare const NodeLinkRelation: z.ZodEnum<{
+    references: "references";
+    related: "related";
+    depends_on: "depends_on";
+    implements: "implements";
+}>;
+export type NodeLinkRelation = z.infer<typeof NodeLinkRelation>;
+export declare const NodeLinkOrigin: z.ZodEnum<{
+    manual: "manual";
+    text: "text";
+}>;
+export type NodeLinkOrigin = z.infer<typeof NodeLinkOrigin>;
+export declare const NodeLink: z.ZodObject<{
+    id: z.ZodString;
+    sourceNodeId: z.ZodString;
+    targetNodeId: z.ZodString;
+    relation: z.ZodEnum<{
+        references: "references";
+        related: "related";
+        depends_on: "depends_on";
+        implements: "implements";
+    }>;
+    origin: z.ZodEnum<{
+        manual: "manual";
+        text: "text";
+    }>;
+    label: z.ZodNullable<z.ZodString>;
+    createdBy: z.ZodString;
+    createdAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export type NodeLink = z.infer<typeof NodeLink>;
+export declare const NodeLinkList: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        sourceNodeId: z.ZodString;
+        targetNodeId: z.ZodString;
+        relation: z.ZodEnum<{
+            references: "references";
+            related: "related";
+            depends_on: "depends_on";
+            implements: "implements";
+        }>;
+        origin: z.ZodEnum<{
+            manual: "manual";
+            text: "text";
+        }>;
+        label: z.ZodNullable<z.ZodString>;
+        createdBy: z.ZodString;
+        createdAt: z.ZodISODateTime;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type NodeLinkList = z.infer<typeof NodeLinkList>;
+export declare const DocumentLinkInlineType = "documentLink";
+export declare const ResolveNodeLinksInput: z.ZodObject<{
+    nodeIds: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type ResolveNodeLinksInput = z.infer<typeof ResolveNodeLinksInput>;
+export declare const ResolvedNodeLink: z.ZodObject<{
+    nodeId: z.ZodString;
+    title: z.ZodString;
+}, z.core.$strict>;
+export type ResolvedNodeLink = z.infer<typeof ResolvedNodeLink>;
+export declare const ResolveNodeLinksResult: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        nodeId: z.ZodString;
+        title: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ResolveNodeLinksResult = z.infer<typeof ResolveNodeLinksResult>;
+export declare const NodeGraphInput: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export type NodeGraphInput = z.infer<typeof NodeGraphInput>;
+export declare const NodeGraph: z.ZodObject<{
+    nodes: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        parentId: z.ZodNullable<z.ZodString>;
+        kind: z.ZodEnum<{
+            folder: "folder";
+            document: "document";
+            table: "table";
+            attachment: "attachment";
+        }>;
+        title: z.ZodString;
+        description: z.ZodNullable<z.ZodString>;
+        ownerId: z.ZodString;
+        currentVersionId: z.ZodNullable<z.ZodString>;
+        createdAt: z.ZodISODateTime;
+        updatedAt: z.ZodISODateTime;
+        archivedAt: z.ZodNullable<z.ZodISODateTime>;
+    }, z.core.$strict>>;
+    links: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        sourceNodeId: z.ZodString;
+        targetNodeId: z.ZodString;
+        relation: z.ZodEnum<{
+            references: "references";
+            related: "related";
+            depends_on: "depends_on";
+            implements: "implements";
+        }>;
+        origin: z.ZodEnum<{
+            manual: "manual";
+            text: "text";
+        }>;
+        label: z.ZodNullable<z.ZodString>;
+        createdBy: z.ZodString;
+        createdAt: z.ZodISODateTime;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type NodeGraph = z.infer<typeof NodeGraph>;
+export declare const BlockNoteMediaType = "application/vnd.anchrd.intel.blocknote+json";
+export declare const BlockNoteDocument: z.ZodObject<{
+    format: z.ZodLiteral<"blocknote">;
+    schemaVersion: z.ZodLiteral<1>;
+    blocks: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    markdown: z.ZodString;
+}, z.core.$strict>;
+export type BlockNoteDocument = z.infer<typeof BlockNoteDocument>;
+export declare const SearchInput: z.ZodObject<{
+    query: z.ZodString;
+    limit: z.ZodDefault<z.ZodNumber>;
+    scopeId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type SearchInput = z.infer<typeof SearchInput>;
+export declare const NodeCitation: z.ZodObject<{
+    nodeId: z.ZodString;
+    versionId: z.ZodString;
+    title: z.ZodString;
+    passage: z.ZodString;
+    source: z.ZodString;
+    freshness: z.ZodISODateTime;
+    score: z.ZodNumber;
+    match: z.ZodEnum<{
+        semantic: "semantic";
+        lexical: "lexical";
+        hybrid: "hybrid";
+    }>;
+}, z.core.$strict>;
+export type NodeCitation = z.infer<typeof NodeCitation>;
+export declare const SearchResult: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        nodeId: z.ZodString;
+        versionId: z.ZodString;
+        title: z.ZodString;
+        passage: z.ZodString;
+        source: z.ZodString;
+        freshness: z.ZodISODateTime;
+        score: z.ZodNumber;
+        match: z.ZodEnum<{
+            semantic: "semantic";
+            lexical: "lexical";
+            hybrid: "hybrid";
+        }>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type SearchResult = z.infer<typeof SearchResult>;
+export declare const ReindexResult: z.ZodObject<{
+    queued: z.ZodNumber;
+}, z.core.$strict>;
+export type ReindexResult = z.infer<typeof ReindexResult>;

package/dist/contract/node.js

@@ -0,0 +1,286 @@
+import { z } from "zod";
+import { IdempotencyKey, IntelId, IsoDateTime } from "./contract.js";
+// 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), the fifth is `agent` (#139) and the sixth is `board` (#285).
+// 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, ADR-0005 §1). Only the media type and the operations below differ.
+//
+// ⚠️ `agent` being optional is load-bearing (ADR-0005 §1): an installation without a single agent
+// node is complete, not unfinished, and nothing here asks anyone to classify a document as a skill
+// or a policy in order to file it. The same holds for `board`: it is a file somebody may make, not
+// a place the tree grows a special corner for — which is exactly why a board is one node carrying
+// its tasks and not a folder that only tasks may live in (#285).
+export const NodeKind = z.enum(["folder", "document", "attachment", "table"]);
+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(),
+});
+// 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 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 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 const GetNodeInput = z.strictObject({
+    nodeId: IntelId.describe("Node to read, from node_list or search."),
+});
+// 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 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 holds others and has no content; document, attachment and table each carry their own body, written afterwards by node_version_create, node_attachment_create or node_table_create."),
+    title: z
+        .string()
+        .trim()
+        .min(1)
+        .max(240)
+        .describe("What the node is called. Shown in the tree and searched."),
+    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 const SaveNodeVersionInput = z.strictObject({
+    nodeId: IntelId.describe("Document node to append a version to."),
+    baseVersionId: IntelId.nullable().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 const SaveAttachmentInput = z.strictObject({
+    nodeId: IntelId.describe("Attachment node to append bytes to."),
+    baseVersionId: IntelId.nullable().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; larger files take the HTTP door, which streams."),
+    mediaType: z
+        .string()
+        .min(1)
+        .max(160)
+        .describe("Media type of the decoded bytes, e.g. application/pdf."),
+    idempotencyKey: IdempotencyKey,
+});
+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."),
+    idempotencyKey: IdempotencyKey,
+})
+    .refine((input) => input.title !== undefined || input.description !== undefined || input.parentId !== undefined, { message: "At least one change is required" });
+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,
+});
+// ⚠️ `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 const NodeVersionList = z.strictObject({ items: z.array(NodeVersion) });
+export const NodeDocument = z.strictObject({
+    node: Node,
+    version: NodeVersion.nullable(),
+    content: z.string().nullable(),
+});
+export const NodeAttachment = z.strictObject({
+    node: Node,
+    version: NodeVersion,
+    resourceUri: z.string().regex(/^intel:\/\/nodes\/[^/]+\/attachment$/),
+});
+// 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 const NodeLinkRelation = z.enum(["references", "related", "depends_on", "implements"]);
+// 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 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 const NodeLinkList = z.strictObject({ items: z.array(NodeLink) });
+// 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 const ResolvedNodeLink = z.strictObject({
+    nodeId: IntelId,
+    title: z.string().min(1).max(240),
+});
+// ⚠️ 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 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 const NodeGraph = z.strictObject({
+    nodes: z.array(Node),
+    links: z.array(NodeLink),
+});
+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(),
+});
+// `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 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 const SearchResult = z.strictObject({
+    items: z.array(NodeCitation),
+});
+export const ReindexResult = z.strictObject({ queued: z.number().int().nonnegative() });