@anchrd/intel-contract 0.4.2 → 0.5.0

package/dist/contract/contract.js

@@ -16,10 +16,22 @@ export const SessionUser = z.strictObject({
     email: z.email(),
     name: z.string().min(1).max(240).nullable(),
 });
-// The fourth kind is `table` (#40). It 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 its media type and the one operation below differ.
-export const KnowledgeNodeKind = z.enum(["folder", "document", "attachment", "table"]);
+// 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.
+export const IntelCapabilities = z.strictObject({
+    agentRuntime: z.boolean(),
+});
+// The fourth kind is `table` (#40) and the fifth is `agent` (#139). 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.
+export const NodeKind = z.enum(["folder", "document", "attachment", "table", "agent"]);
 // ⚠️ There is no `ContextPolicy`, and it is not coming back in this shape (#76). It said whether a
 // document should be pinned into a context, be found by relevance, or be named explicitly — an
 // instruction to a retrieval Intel does not perform. Intel hands out references and the agent
@@ -34,10 +46,10 @@ export const SharePrincipal = z.discriminatedUnion("type", [
     z.strictObject({ type: z.literal("email"), email: z.email() }),
     z.strictObject({ type: z.literal("organization") }),
 ]);
-export const KnowledgeNode = z.strictObject({
+export const Node = z.strictObject({
     id: IntelId,
     parentId: IntelId.nullable(),
-    kind: KnowledgeNodeKind,
+    kind: NodeKind,
     title: z.string().min(1).max(240),
     description: z.string().max(2_000).nullable(),
     ownerId: IntelId,
@@ -46,7 +58,14 @@ export const KnowledgeNode = z.strictObject({
     updatedAt: IsoDateTime,
     archivedAt: IsoDateTime.nullable(),
 });
-export const KnowledgeVersion = z.strictObject({
+// 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(),
@@ -54,10 +73,11 @@ export const KnowledgeVersion = z.strictObject({
     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 ListKnowledgeNodesInput = z.strictObject({
+export const ListNodesInput = z.strictObject({
     parentId: IntelId.nullable().default(null),
     includeArchived: z.boolean().default(false),
     // ⚠️ Overrides `parentId` rather than narrowing beside it: what is archived is asked for across
@@ -69,30 +89,33 @@ export const ListKnowledgeNodesInput = z.strictObject({
     // caller would have to answer a question it is not asking.
     archivedOnly: z.boolean().optional(),
 });
-export const GetKnowledgeNodeInput = z.strictObject({ nodeId: IntelId });
-export const ListKnowledgeGrantsInput = z.strictObject({ resourceId: IntelId });
-export const CreateKnowledgeNodeInput = z.strictObject({
+export const GetNodeInput = z.strictObject({ nodeId: IntelId });
+// 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, versionId: IntelId });
+export const ListGrantsInput = z.strictObject({ resourceId: IntelId });
+export const CreateNodeInput = z.strictObject({
     parentId: IntelId.nullable().default(null),
-    kind: KnowledgeNodeKind,
+    kind: NodeKind,
     title: z.string().trim().min(1).max(240),
     description: z.string().trim().max(2_000).nullable().default(null),
     idempotencyKey: z.string().min(8).max(200),
 });
-export const SaveKnowledgeVersionInput = z.strictObject({
+export const SaveNodeVersionInput = z.strictObject({
     nodeId: IntelId,
     baseVersionId: IntelId.nullable(),
     content: z.string().max(10_000_000),
     mediaType: z.string().min(1).max(160).default("text/markdown"),
     idempotencyKey: z.string().min(8).max(200),
 });
-export const SaveKnowledgeAttachmentInput = z.strictObject({
+export const SaveAttachmentInput = z.strictObject({
     nodeId: IntelId,
     baseVersionId: IntelId.nullable(),
     contentBase64: z.string().min(1).max(20_000_000),
     mediaType: z.string().min(1).max(160),
     idempotencyKey: z.string().min(8).max(200),
 });
-export const UpdateKnowledgeNodeInput = z
+export const UpdateNodeInput = z
     .strictObject({
     nodeId: IntelId,
     baseUpdatedAt: IsoDateTime,
@@ -102,30 +125,30 @@ export const UpdateKnowledgeNodeInput = z
     idempotencyKey: z.string().min(8).max(200),
 })
     .refine((input) => input.title !== undefined || input.description !== undefined || input.parentId !== undefined, { message: "At least one change is required" });
-export const ArchiveKnowledgeNodeInput = z.strictObject({
+export const ArchiveNodeInput = z.strictObject({
     nodeId: IntelId,
     baseUpdatedAt: IsoDateTime,
     archived: z.boolean(),
     idempotencyKey: z.string().min(8).max(200),
 });
-// ⚠️ `withChildren` gehört zur EBENE, nicht zum Knoten (#59). Ob etwas Kinder hat, die DIESER
-// Leser sehen darf, ist keine Eigenschaft der Sache — zwei Leser bekommen verschiedene Antworten.
-// Als Feld am Knoten müsste jede andere Stelle, die einen Knoten zurückgibt, es mitberechnen oder
-// lügen; als Liste neben den Einträgen kostet es nur die eine Antwort, die es braucht.
-export const KnowledgeNodeList = z.strictObject({
-    items: z.array(KnowledgeNode),
+// ⚠️ `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 KnowledgeVersionList = z.strictObject({ items: z.array(KnowledgeVersion) });
-export const KnowledgeDocument = z.strictObject({
-    node: KnowledgeNode,
-    version: KnowledgeVersion.nullable(),
+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 KnowledgeAttachment = z.strictObject({
-    node: KnowledgeNode,
-    version: KnowledgeVersion,
-    resourceUri: z.string().regex(/^intel:\/\/knowledge\/[^/]+\/attachment$/),
+export const NodeAttachment = z.strictObject({
+    node: Node,
+    version: NodeVersion,
+    resourceUri: z.string().regex(/^intel:\/\/nodes\/[^/]+\/attachment$/),
 });
 // A table is CSV, and CSV is the whole format: it is what is stored, what is downloaded and what a
 // machine reads. There is no second representation to keep in step with it (#40).
@@ -138,7 +161,7 @@ export const TableRow = z.array(TableCell).min(1).max(64);
 // Writing the header, once. The columns are the contract (#40's comment), which is why this refuses
 // on a table that already has one: changing the header would silently reinterpret every row that
 // was appended under the old one.
-export const DefineKnowledgeTableInput = z.strictObject({
+export const DefineTableInput = z.strictObject({
     nodeId: IntelId,
     columns: z
         .array(TableColumn)
@@ -151,31 +174,233 @@ export const DefineKnowledgeTableInput = z.strictObject({
 // to know which content it replaces; an append adds to the end and cannot collide with a second
 // append, so demanding a base version would invent a conflict that does not exist and force the
 // caller to read the whole table first — the exact cost #40 exists to remove.
-export const AppendKnowledgeTableRowsInput = z.strictObject({
+export const AppendTableRowsInput = z.strictObject({
     nodeId: IntelId,
     rows: z.array(TableRow).min(1).max(1_000),
     idempotencyKey: z.string().min(8).max(200),
 });
-export const GetKnowledgeTableInput = z.strictObject({ nodeId: IntelId });
+export const GetTableInput = z.strictObject({ nodeId: IntelId });
 // 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 KnowledgeTable = z.strictObject({
-    node: KnowledgeNode,
+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 AppendKnowledgeTableRowsResult = z.strictObject({
-    node: KnowledgeNode,
-    version: KnowledgeVersion,
+export const AppendTableRowsResult = z.strictObject({
+    node: Node,
+    version: NodeVersion,
     appended: z.number().int().positive(),
 });
+// A row's address is its position among the table's current rows, counted from zero and without the
+// header. Deliberately not an ID: rows carry no identity of their own (#135, and the same decision
+// the grid documents), so every mutation instead pins the state its positions refer to.
+export const TableRowPosition = z.number().int().nonnegative();
+const distinctPositions = { error: "Row positions must be distinct" };
+// Replacing rows in place (#135). `baseVersionId` is the version the caller read the positions
+// from — required, never nullable, because a position into a table one has not read is a guess.
+// A table that moved on since answers `version_conflict` rather than editing the wrong rows; that
+// is the same optimistic concurrency the document save uses, and the deliberate opposite of
+// `append`, which needs no base because it collides with nothing.
+export const UpdateTableRowsInput = z.strictObject({
+    nodeId: IntelId,
+    baseVersionId: IntelId,
+    updates: z
+        .array(z.strictObject({ position: TableRowPosition, row: TableRow }))
+        .min(1)
+        .max(1_000)
+        .refine((updates) => new Set(updates.map((update) => update.position)).size === updates.length, distinctPositions),
+    idempotencyKey: z.string().min(8).max(200),
+});
+export const UpdateTableRowsResult = z.strictObject({
+    node: Node,
+    version: NodeVersion,
+    updated: z.number().int().positive(),
+});
+export const DeleteTableRowsInput = z.strictObject({
+    nodeId: IntelId,
+    baseVersionId: IntelId,
+    positions: z
+        .array(TableRowPosition)
+        .min(1)
+        .max(1_000)
+        .refine((positions) => new Set(positions).size === positions.length, distinctPositions),
+    idempotencyKey: z.string().min(8).max(200),
+});
+export const DeleteTableRowsResult = z.strictObject({
+    node: Node,
+    version: NodeVersion,
+    deleted: z.number().int().positive(),
+});
+// One entry per column the table will have afterwards, in order. `source` names the current column
+// whose cells fill it; `null` adds an empty column, and a current column no entry names is removed
+// together with its cells. Renaming is naming a source under a new name.
+export const RedefineTableColumn = z.strictObject({
+    name: TableColumn,
+    source: TableColumn.nullable().default(null),
+});
+// Changing the header of a table that has one (#135). The mapping is explicit because it is the
+// whole difference to the blind re-definition `defineTable` keeps refusing: without it a new header
+// would silently reinterpret every stored row under names nobody matched to the old ones.
+export const RedefineTableInput = z.strictObject({
+    nodeId: IntelId,
+    baseVersionId: IntelId,
+    columns: z
+        .array(RedefineTableColumn)
+        .min(1)
+        .max(64)
+        .refine((columns) => new Set(columns.map((column) => column.name.toLowerCase())).size === columns.length, { error: "Column names must be distinct" })
+        .refine((columns) => {
+        const sources = columns.map((column) => column.source).filter((source) => source !== null);
+        return new Set(sources).size === sources.length;
+    }, { error: "A current column can fill only one new column" }),
+    idempotencyKey: z.string().min(8).max(200),
+});
+// ── The agent definition (#139, ADR-0005 §4) ─────────────────────────────────────────────────────
+//
+// An agent's body is a definition, stored as an immutable version in R2 exactly like a document's.
+// Its own media type exists so a reader can tell a definition from prose without parsing it.
+export const AgentMediaType = "application/vnd.anchrd.agent+json";
+// ⚠️ The role lives on the AGENT, never on the node it names, and that is the whole difference to
+// the removed `context_policy` (ADR-0005 §2, #76). The same folder can be the system message for
+// one agent and nothing but search space for another; a node has no opinion about how it is used.
+// Any future field on a node saying how it should be loaded is `context_policy` under a new name.
+//
+//   system-message    prepended verbatim by the runtime
+//   semantic-context  search space; the agent searches it when it decides to
+//   memory            write target — ordinary Knowledge, versioned and readable like everything else
+export const AgentReferenceRole = z.enum(["system-message", "semantic-context", "memory"]);
+export const AgentReference = z.strictObject({ nodeId: IntelId, role: AgentReferenceRole });
+// A `document` target means the content of that document is the instruction — a "skill" somebody
+// wrote as ordinary text; a `flow` target means a run is started through Intel MCP and worked step
+// by step. Both are references, so nothing in here goes stale (ADR-0005 §4).
+//
+// ⚠️ Intel stores a schedule as a declared fact and never fires it. The alarm lives in the runtime
+// (ADR-0005 §3); Intel gains no scheduler, which is D24 confirmed rather than bent.
+export const AgentScheduleTarget = z.strictObject({
+    kind: z.enum(["document", "flow"]),
+    id: IntelId,
+});
+export const AgentSchedule = z.strictObject({
+    cron: z.string().trim().min(1).max(120),
+    target: AgentScheduleTarget,
+});
+export const AgentModel = z.strictObject({
+    provider: z.enum(["workers-ai", "anthropic"]),
+    model: z.string().trim().min(1).max(120),
+});
+/**
+ * ⚠️ No accounts, no secrets, no channels, and no tools — and the reason is mechanical rather than
+ * tidy (ADR-0005 §4): this body is read, shared, exported and put into model context, so a secret
+ * in it is a secret in a citation. Identity is Gate's, accounts are the portal's, channels are
+ * runtime configuration, and the tool catalog is a live `tools/list` that is never mirrored.
+ *
+ * ⚠️ Strict on purpose, and deliberately stricter than the runtime's own reader
+ * (`packages/agent/src/definition/definition.ts`, which is `z.object`). Intel is the writer: an
+ * unknown field here is a caller's mistake and is refused at the boundary. The runtime is the
+ * reader and released separately, so it must keep starting agents when Intel adds a field
+ * tomorrow. The asymmetry is the point, not an oversight.
+ */
+export const AgentDefinition = z.strictObject({
+    references: z.array(AgentReference).max(200).default([]),
+    schedules: z.array(AgentSchedule).max(50).default([]),
+    model: AgentModel,
+});
+export const SaveAgentDefinitionInput = z.strictObject({
+    nodeId: IntelId,
+    baseVersionId: IntelId.nullable(),
+    definition: AgentDefinition,
+    idempotencyKey: z.string().min(8).max(200),
+});
+export const GetAgentInput = z.strictObject({ nodeId: IntelId });
+// Switching an agent off and on again, and starting one run by hand. All three name only the agent
+// and — for a run — which of the targets it already schedules.
+//
+// ⚠️ Intel holds none of this. Whether an agent is paused is state of its Durable Object, not a
+// field of the definition: a definition is versioned, shared and read into model context (ADR-0005
+// §4), so every pause would otherwise be a new version and would tell the agent it is switched off.
+// These inputs are what Intel accepts and passes on, nothing that Intel stores.
+export const PauseAgentInput = z.strictObject({ nodeId: IntelId });
+export const RunAgentNowInput = z.strictObject({
+    nodeId: IntelId,
+    target: AgentScheduleTarget,
+});
+// ⚠️ Three states, not two, and the same three the flow list makes: omitted is the whole tree,
+// `null` is the root level, an ID is that folder. "Which agents may I use" is a question about the
+// tree rather than about one folder, so the useful answer has to be reachable without knowing where
+// somebody filed them.
+export const ListAgentsInput = z.strictObject({
+    parentId: IntelId.nullable().optional(),
+    includeArchived: z.boolean().default(false),
+});
+export const CreateAgentInput = z.strictObject({
+    parentId: IntelId.nullable().default(null),
+    title: z.string().trim().min(1).max(240),
+    description: z.string().trim().max(2_000).nullable().default(null),
+    definition: AgentDefinition,
+    idempotencyKey: z.string().min(8).max(200),
+});
+// The ID of the Gate Application an agent runs as. Deliberately NOT an `IntelId`: it is Better
+// Auth's user ID, minted in Gate and only ever handed back to Gate, so validating it against
+// Intel's own ID shape would be Intel inventing a rule about somebody else's identifier.
+export const GateApplicationId = z.string().min(1).max(255);
+// The definition is `null` exactly while the node exists and no version has been written yet — the
+// same window in which a document's content is `null`.
+//
+// ⚠️ `applicationId` names the machine principal, it does not authenticate it (#182, D27). That is
+// why the ID may be stored, listed and drawn while the key may not: one is a name, the other is the
+// credential, and Gate hands the credential out exactly once and keeps only its hash. `null` means
+// this agent has no Application — an agent node written before #182, restored from a bundle, or
+// imported from another installation. Such an agent is not switched with its node, and giving it a
+// principal is an operator's act in Gate.
+export const NodeAgent = z.strictObject({
+    node: Node,
+    version: NodeVersion.nullable(),
+    definition: AgentDefinition.nullable(),
+    applicationId: GateApplicationId.nullable(),
+});
+/**
+ * The single value in Intel's wire formats that IS a credential (#182, D27).
+ *
+ * ⚠️ It exists for exactly one response — the one that created the agent — and for no other. Gate
+ * returns an Application key once in plain text and stores only its hash, so this is not a value
+ * Intel could fetch again later even if it wanted to; nothing in Intel writes it to D1, to R2, to
+ * an audit event or to a log, and no read surface has a field it could travel in. What the caller
+ * does with it is named in `notice` rather than left to them: it belongs in the agent runtime's
+ * `AGENT_APPLICATION_KEYS` secret, keyed by `agentId`, and nowhere else.
+ *
+ * ⚠️ `agentId` is the Intel node ID and not the Application ID, because that is the key the runtime
+ * looks an entry up by. Writing the Application ID into the runtime's map would produce a
+ * deployment that parses, starts, and then cannot find a single agent.
+ */
+export const AgentApplicationKey = z.strictObject({
+    agentId: IntelId,
+    applicationId: GateApplicationId,
+    key: z.string().min(1),
+    notice: z.string().min(1),
+});
+/**
+ * What `POST /nodes/agents` and `agent_create` answer, and the only shape carrying a key. Every
+ * other agent read answers with the plain `NodeAgent` above.
+ *
+ * ⚠️ `applicationKey` is `null` on a REPLAY, and that is the honest answer rather than a gap. An
+ * idempotency key repeated after the first response was lost still returns the agent that exists —
+ * the promise every create in Intel makes — but the key belonged to the one response that created
+ * it and is gone from Gate. Minting a second principal to fill this field would leave the
+ * installation with two machine accounts for one agent, one of which nobody would ever switch off.
+ * `application_rotate_key` in Gate is the way to a new key, and it is a deliberate act.
+ */
+export const CreatedAgent = NodeAgent.extend({
+    applicationKey: AgentApplicationKey.nullable(),
+});
+export const AgentList = z.strictObject({ items: z.array(Node) });
 // ⚠️ Kept for what is already stored, not for what is written. Relations were picked in a dialog
 // until #41; a link is now made where it is meant — in the text — and every link written from now
 // on is a `references`. Rewriting the old rows would destroy a distinction somebody chose on
 // purpose, and dropping the column would destroy it with them, so both stay readable.
-export const KnowledgeLinkRelation = z.enum(["references", "related", "depends_on", "implements"]);
+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.
 //
@@ -183,28 +408,28 @@ export const KnowledgeLinkRelation = z.enum(["references", "related", "depends_o
 // 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 KnowledgeLinkOrigin = z.enum(["text", "manual"]);
-export const KnowledgeLink = z.strictObject({
+export const NodeLinkOrigin = z.enum(["text", "manual"]);
+export const NodeLink = z.strictObject({
     id: IntelId,
     sourceNodeId: IntelId,
     targetNodeId: IntelId,
-    relation: KnowledgeLinkRelation,
-    origin: KnowledgeLinkOrigin,
+    relation: NodeLinkRelation,
+    origin: NodeLinkOrigin,
     label: z.string().trim().min(1).max(120).nullable(),
     createdBy: IntelId,
     createdAt: IsoDateTime,
 });
-export const KnowledgeLinkList = z.strictObject({ items: z.array(KnowledgeLink) });
+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 ResolveKnowledgeLinksInput = z.strictObject({
+export const ResolveNodeLinksInput = z.strictObject({
     nodeIds: z.array(IntelId).min(1).max(200),
 });
-export const ResolvedKnowledgeLink = z.strictObject({
+export const ResolvedNodeLink = z.strictObject({
     nodeId: IntelId,
     title: z.string().min(1).max(240),
 });
@@ -213,15 +438,15 @@ export const ResolvedKnowledgeLink = z.strictObject({
 // 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 ResolveKnowledgeLinksResult = z.strictObject({
-    items: z.array(ResolvedKnowledgeLink),
+export const ResolveNodeLinksResult = z.strictObject({
+    items: z.array(ResolvedNodeLink),
 });
-export const KnowledgeGraphInput = z.strictObject({
+export const NodeGraphInput = z.strictObject({
     limit: z.number().int().min(1).max(500).default(250),
 });
-export const KnowledgeGraph = z.strictObject({
-    nodes: z.array(KnowledgeNode),
-    links: z.array(KnowledgeLink),
+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({
@@ -239,14 +464,14 @@ export const ResourceGrant = z.strictObject({
     createdBy: IntelId,
     createdAt: IsoDateTime,
 });
-export const ShareKnowledgeInput = z.strictObject({
+export const ShareInput = z.strictObject({
     resourceId: IntelId,
     principal: SharePrincipal,
     verb: ResourceVerb,
     expiresAt: IsoDateTime.nullable().default(null),
     idempotencyKey: z.string().min(8).max(200),
 });
-export const RevokeKnowledgeGrantInput = z.strictObject({
+export const RevokeGrantInput = z.strictObject({
     resourceId: IntelId,
     grantId: IntelId,
     idempotencyKey: z.string().min(8).max(200),
@@ -257,16 +482,16 @@ export const RevokeKnowledgeGrantInput = z.strictObject({
 //
 // ⚠️ `titles` holds only the documents the sharer may see; everything else is in `hidden` as a
 // number. A warning must not become a way of reading titles out of the tree.
-export const UnreadableKnowledge = z.strictObject({
+export const UnreadableNodes = z.strictObject({
     titles: z.array(z.string().min(1).max(240)),
     hidden: z.number().int().nonnegative(),
 });
 // The grant is in the answer, so the warning cannot be mistaken for a refusal: it is written first
 // and described afterwards. Blocking would force everyone who uses a central policy document to
 // duplicate it, which is the opposite of what one tree is for (ADR-0004 §4).
-export const ShareKnowledgeResult = z.strictObject({
+export const ShareResult = z.strictObject({
     grant: ResourceGrant,
-    unreadable: UnreadableKnowledge,
+    unreadable: UnreadableNodes,
 });
 // `applicableVerbs` travels with the list because the answer is the business layer's, not the
 // screen's: a document has nothing to execute, so `execute` is not offered on one (ADR-0004 §2).
@@ -275,11 +500,16 @@ export const ResourceGrantList = z.strictObject({
     applicableVerbs: z.array(ResourceVerb).min(1),
     items: z.array(ResourceGrant),
 });
-export const SearchKnowledgeInput = z.strictObject({
+// `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),
     limit: z.number().int().min(1).max(50).default(10),
+    scopeId: IntelId.optional().describe("Optional folder node id. When given, only nodes filed in that folder or beneath it are searched."),
 });
-export const KnowledgeCitation = z.strictObject({
+export const NodeCitation = z.strictObject({
     nodeId: IntelId,
     versionId: IntelId,
     title: z.string(),
@@ -289,10 +519,10 @@ export const KnowledgeCitation = z.strictObject({
     score: z.number().min(0).max(1),
     match: z.enum(["lexical", "semantic", "hybrid"]),
 });
-export const SearchKnowledgeResult = z.strictObject({
-    items: z.array(KnowledgeCitation),
+export const SearchResult = z.strictObject({
+    items: z.array(NodeCitation),
 });
-export const ReindexKnowledgeResult = z.strictObject({ queued: z.number().int().nonnegative() });
+export const ReindexResult = z.strictObject({ queued: z.number().int().nonnegative() });
 export const RevokeGrantResult = z.strictObject({ revoked: z.boolean() });
 function isPrivateIpv4(hostname) {
     const parts = hostname.split(".").map(Number);
@@ -526,7 +756,7 @@ export const FlowGraph = z.strictObject({
 });
 export const Flow = z.strictObject({
     id: IntelId,
-    // The one thing a Flow shares with a document: its place in the Knowledge folder tree (ADR-0004).
+    // 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(),
@@ -551,30 +781,52 @@ export const FlowDocument = z.strictObject({
     flow: Flow,
     version: FlowVersion.nullable(),
 });
-// Dasselbe für Flows: welche von ihnen einen anderen Flow rufen, den dieser Leser auch sehen darf
-// (#59). Ein Aufklapp-Pfeil an einem Flow, dessen Aufrufe alle verborgen sind, verspricht Inhalt,
-// den das Aufklappen nicht liefern kann.
+// 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 const FlowVersionList = z.strictObject({
+    flowId: IntelId,
+    items: z.array(FlowVersionSummary),
+});
+// 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, versionId: IntelId });
+// 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 const FlowKnowledgeReference = z.strictObject({
+export const ReferencedNode = z.strictObject({
     id: IntelId,
     title: z.string().min(1).max(240),
 });
-// What a flow touches: the documents its Knowledge steps name and the tools its Tool steps call,
+// 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).
 //
-// ⚠️ `knowledge` names only what the asking user may see. The rest is `hiddenKnowledge`, a count.
+// ⚠️ `nodes` names only what the asking user may see. The rest is `hiddenNodes`, a count.
 export const FlowRequirements = z.strictObject({
     flowId: IntelId,
     versionId: IntelId.nullable(),
-    knowledge: z.array(FlowKnowledgeReference),
-    hiddenKnowledge: z.number().int().nonnegative(),
+    nodes: z.array(ReferencedNode),
+    hiddenNodes: z.number().int().nonnegative(),
     tools: z.array(ToolName),
 });
 // What stands between this flow and a run, asked on demand and answered for the person asking.
@@ -630,12 +882,12 @@ export const ListFlowsInput = z.strictObject({
     // 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 `ListKnowledgeNodesInput`. This schema is
+    // ⚠️ `.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(),
-    // The same question for flows, and the same override of `parentId` — see `ListKnowledgeNodesInput`.
+    // The same question for flows, and the same override of `parentId` — see `ListNodesInput`.
     archivedOnly: z.boolean().optional(),
 });
 export const GetFlowInput = z.strictObject({ flowId: IntelId });
@@ -650,6 +902,13 @@ export const PublishFlowInput = z.strictObject({
     versionId: IntelId,
     idempotencyKey: z.string().min(8).max(200),
 });
+// 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,
+    idempotencyKey: z.string().min(8).max(200),
+});
 export const PreviewFlowPublishInput = z.strictObject({ flowId: IntelId, versionId: IntelId });
 // 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
@@ -682,7 +941,14 @@ export const FlowPublishPreview = z.strictObject({
 // 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.
-export const RelationNodeKind = z.enum(["folder", "document", "attachment", "table", "flow"]);
+export const RelationNodeKind = z.enum([
+    "folder",
+    "document",
+    "attachment",
+    "table",
+    "agent",
+    "flow",
+]);
 export const RelationNode = z.strictObject({
     id: IntelId,
     kind: RelationNodeKind,
@@ -767,6 +1033,13 @@ export const StartFlowRunInput = z.strictObject({
     idempotencyKey: z.string().min(8).max(200),
 });
 export const GetFlowRunInput = z.strictObject({ runId: IntelId });
+// Ending a run on purpose (#145). Until this existed the only way off a parked manual step was
+// `completeStep` with `outcome: "failed"` — which recorded a step failure that never happened.
+// Cancelling records nothing into the step history: the run ends, the history stays true.
+export const CancelFlowRunInput = z.strictObject({
+    runId: IntelId,
+    idempotencyKey: z.string().min(8).max(200),
+});
 export const CompleteFlowRunStepInput = z.strictObject({
     runId: IntelId,
     nodeId: FlowNodeId,
@@ -801,7 +1074,7 @@ export const FlowRunFailure = z.strictObject({
 });
 // One run as a list shows it: what it did, never what it produced.
 //
-// ⚠️ Neither `input` nor `output` is in here, on purpose. A run reaches its Knowledge and its tools
+// ⚠️ Neither `input` nor `output` is in here, on purpose. A run reaches its nodes and its tools
 // with the rights of whoever started it, so its result is a way to content the next reader of this
 // list may have no claim to. Whoever wants a result asks for the run itself, where the same rule
 // decides again.
@@ -854,3 +1127,51 @@ export const FlowRunHistory = z.strictObject({
     steps: z.array(FlowRunStepRecord),
     trail: z.array(FlowRunTrailEntry),
 });
+// ── Bundle export (#136) ────────────────────────────────────────────────────────────────────────
+// The one name the importer looks for at the zip root. A different spelling would make a bundle a
+// naked folder, so the constant lives in the contract rather than in each surface.
+export const BundleManifestFilename = "manifest.json";
+// What a bundle entry can be. `flow` joins the five node kinds because a flow shares the folder
+// tree without being a node (ADR-0004), and the bundle mirrors the tree, not the tables.
+export const BundleEntryKind = z.enum([
+    "folder",
+    "document",
+    "table",
+    "attachment",
+    "agent",
+    "flow",
+]);
+// One entry of the manifest: the identity a re-import needs, next to the relative path where the
+// bytes sit in the zip. A folder carries no media type — it has no bytes.
+export const BundleManifestEntry = z.strictObject({
+    id: IntelId,
+    kind: BundleEntryKind,
+    title: z.string().min(1).max(240),
+    description: z.string().max(2_000).nullable(),
+    mediaType: z.string().min(1).max(160).nullable(),
+    // Relative to the zip root, forward slashes, no leading slash. Folders end with a slash so an
+    // empty folder still has an address.
+    path: z.string().min(1).max(4_000),
+});
+// What an export leaves out on purpose, named so a bundle says it rather than a reader guessing:
+// version history, grants/shares, flow runs, and archived nodes are not in any bundle (#136).
+export const BundleExclusion = z.enum(["version-history", "grants", "flow-runs", "archived-nodes"]);
+export const BundleManifest = z.strictObject({
+    version: z.literal(1),
+    exportedAt: IsoDateTime,
+    // The node the export started at; `null` is the root of the tree — the whole installation as the
+    // exporting caller may read it.
+    rootId: IntelId.nullable(),
+    entries: z.array(BundleManifestEntry),
+    excluded: z.array(BundleExclusion),
+});
+// ── Bundle import (#137) ────────────────────────────────────────────────────────────────────────
+// What one import made. Import always creates new nodes — no merge, no overwrite, no restored IDs
+// (#137, phase 1) — so the answer is counts and the new roots, never a diff. `replayed` marks the
+// idempotent second answer to the same key: nothing was created twice.
+export const BundleImportResult = z.strictObject({
+    nodes: z.number().int().nonnegative(),
+    flows: z.number().int().nonnegative(),
+    rootNodeIds: z.array(IntelId),
+    replayed: z.boolean(),
+});