@anchrd/intel-contract 0.2.1 → 0.3.0

package/dist/contract/contract.js

@@ -16,9 +16,19 @@ export const SessionUser = z.strictObject({
     email: z.email(),
     name: z.string().min(1).max(240).nullable(),
 });
-export const KnowledgeNodeKind = z.enum(["folder", "document", "attachment"]);
-export const ContextPolicy = z.enum(["pinned", "relevant", "explicit"]);
-export const ResourceRole = z.enum(["viewer", "commenter", "editor", "manager"]);
+// 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"]);
+// ⚠️ 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
+// fetches what it needs (D24), so nothing here could ever have read it, and nothing did.
+//
+// Semantic search stays: as an MCP tool the agent calls, over everything or over one area.
+// One verb per grant, granted independently (ADR-0004 §2). Not a ladder: seeing a process must be
+// separable from being allowed to start it, and `execute` is meaningful only where a flow can live.
+export const ResourceVerb = z.enum(["read", "write", "execute", "share"]);
 export const SharePrincipal = z.discriminatedUnion("type", [
     z.strictObject({ type: z.literal("user"), id: IntelId }),
     z.strictObject({ type: z.literal("email"), email: z.email() }),
@@ -30,7 +40,6 @@ export const KnowledgeNode = z.strictObject({
     kind: KnowledgeNodeKind,
     title: z.string().min(1).max(240),
     description: z.string().max(2_000).nullable(),
-    contextPolicy: ContextPolicy,
     ownerId: IntelId,
     currentVersionId: IntelId.nullable(),
     createdAt: IsoDateTime,
@@ -59,7 +68,6 @@ export const CreateKnowledgeNodeInput = z.strictObject({
     kind: KnowledgeNodeKind,
     title: z.string().trim().min(1).max(240),
     description: z.string().trim().max(2_000).nullable().default(null),
-    contextPolicy: ContextPolicy.default("relevant"),
     idempotencyKey: z.string().min(8).max(200),
 });
 export const SaveKnowledgeVersionInput = z.strictObject({
@@ -82,14 +90,10 @@ export const UpdateKnowledgeNodeInput = z
     baseUpdatedAt: IsoDateTime,
     title: z.string().trim().min(1).max(240).optional(),
     description: z.string().trim().max(2_000).nullable().optional(),
-    contextPolicy: ContextPolicy.optional(),
     parentId: IntelId.nullable().optional(),
     idempotencyKey: z.string().min(8).max(200),
 })
-    .refine((input) => input.title !== undefined ||
-    input.description !== undefined ||
-    input.contextPolicy !== undefined ||
-    input.parentId !== undefined, { message: "At least one change is required" });
+    .refine((input) => input.title !== undefined || input.description !== undefined || input.parentId !== undefined, { message: "At least one change is required" });
 export const ArchiveKnowledgeNodeInput = z.strictObject({
     nodeId: IntelId,
     baseUpdatedAt: IsoDateTime,
@@ -108,32 +112,94 @@ export const KnowledgeAttachment = z.strictObject({
     version: KnowledgeVersion,
     resourceUri: z.string().regex(/^intel:\/\/knowledge\/[^/]+\/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).
+export const TableMediaType = "text/csv";
+// A column name is the contract between the table and everyone who appends to it, so it is trimmed,
+// non-empty and bounded like a title. Cells are not: a cell is text, and text is what CSV carries.
+export const TableColumn = z.string().trim().min(1).max(120);
+export const TableCell = z.string().max(4_000);
+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({
+    nodeId: IntelId,
+    columns: z
+        .array(TableColumn)
+        .min(1)
+        .max(64)
+        .refine((columns) => new Set(columns.map((column) => column.toLowerCase())).size === columns.length, { error: "Column names must be distinct" }),
+    idempotencyKey: z.string().min(8).max(200),
+});
+// ⚠️ No `baseVersionId`, and that absence is the feature. A document replaces its content and needs
+// 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({
+    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 });
+// 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,
+    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,
+    appended: z.number().int().positive(),
+});
+// ⚠️ 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"]);
+// 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 KnowledgeLinkOrigin = z.enum(["text", "manual"]);
 export const KnowledgeLink = z.strictObject({
     id: IntelId,
     sourceNodeId: IntelId,
     targetNodeId: IntelId,
     relation: KnowledgeLinkRelation,
+    origin: KnowledgeLinkOrigin,
     label: z.string().trim().min(1).max(120).nullable(),
     createdBy: IntelId,
     createdAt: IsoDateTime,
 });
 export const KnowledgeLinkList = z.strictObject({ items: z.array(KnowledgeLink) });
-export const CreateKnowledgeLinkInput = z
-    .strictObject({
-    sourceNodeId: IntelId,
-    targetNodeId: IntelId,
-    relation: KnowledgeLinkRelation,
-    label: z.string().trim().min(1).max(120).nullable().default(null),
-    idempotencyKey: z.string().min(8).max(200),
-})
-    .refine((input) => input.sourceNodeId !== input.targetNodeId, {
-    message: "Knowledge cannot link to itself",
+// 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({
+    nodeIds: z.array(IntelId).min(1).max(200),
+});
+export const ResolvedKnowledgeLink = z.strictObject({
+    nodeId: IntelId,
+    title: z.string().min(1).max(240),
 });
-export const DeleteKnowledgeLinkInput = z.strictObject({
-    sourceNodeId: IntelId,
-    linkId: IntelId,
-    idempotencyKey: z.string().min(8).max(200),
+// ⚠️ 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 ResolveKnowledgeLinksResult = z.strictObject({
+    items: z.array(ResolvedKnowledgeLink),
 });
 export const KnowledgeGraphInput = z.strictObject({
     limit: z.number().int().min(1).max(500).default(250),
@@ -153,7 +219,7 @@ export const ResourceGrant = z.strictObject({
     id: IntelId,
     resourceId: IntelId,
     principal: SharePrincipal,
-    role: ResourceRole,
+    verb: ResourceVerb,
     expiresAt: IsoDateTime.nullable(),
     createdBy: IntelId,
     createdAt: IsoDateTime,
@@ -161,7 +227,7 @@ export const ResourceGrant = z.strictObject({
 export const ShareKnowledgeInput = z.strictObject({
     resourceId: IntelId,
     principal: SharePrincipal,
-    role: ResourceRole,
+    verb: ResourceVerb,
     expiresAt: IsoDateTime.nullable().default(null),
     idempotencyKey: z.string().min(8).max(200),
 });
@@ -170,7 +236,30 @@ export const RevokeKnowledgeGrantInput = z.strictObject({
     grantId: IntelId,
     idempotencyKey: z.string().min(8).max(200),
 });
-export const ResourceGrantList = z.strictObject({ items: z.array(ResourceGrant) });
+// What a grant does not cover, reported to whoever just made it. A flow in the shared folder may
+// read a document outside it, and the run is re-authorized against the person running it — so the
+// grant can be complete and the flow still stop for them (ADR-0004 §4).
+//
+// ⚠️ `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({
+    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({
+    grant: ResourceGrant,
+    unreadable: UnreadableKnowledge,
+});
+// `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).
+export const ResourceGrantList = z.strictObject({
+    resourceId: IntelId,
+    applicableVerbs: z.array(ResourceVerb).min(1),
+    items: z.array(ResourceGrant),
+});
 export const SearchKnowledgeInput = z.strictObject({
     query: z.string().trim().min(1).max(500),
     limit: z.number().int().min(1).max(50).default(10),
@@ -190,7 +279,6 @@ export const SearchKnowledgeResult = z.strictObject({
 });
 export const ReindexKnowledgeResult = z.strictObject({ queued: z.number().int().nonnegative() });
 export const RevokeGrantResult = z.strictObject({ revoked: z.boolean() });
-export const DeleteKnowledgeLinkResult = z.strictObject({ deleted: z.boolean() });
 function isPrivateIpv4(hostname) {
     const parts = hostname.split(".").map(Number);
     if (parts.length !== 4 ||
@@ -272,36 +360,86 @@ export const ToolTestResult = z.strictObject({
 });
 export const FlowNodeId = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_-]{0,99}$/);
 export const FlowPosition = z.strictObject({ x: z.number().finite(), y: z.number().finite() });
+// A node has a title and nothing else to write in prose (#39). A second free text beside it was
+// kept half up to date on both sides, and for an instruction the same sentence already belongs in
+// the instruction itself.
 const FlowNodeBase = {
     id: FlowNodeId,
     position: FlowPosition,
     label: z.string().trim().min(1).max(160),
-    description: z.string().trim().max(2_000).nullable().default(null),
 };
+// Which version of the callee a sub-flow call takes (ADR-0004 §5). Three states rather than an
+// optional identifier, because the difference between them is a decision and has to be readable:
+//
+// - `latest`   the draft default. Nobody should have to version things while building, and
+//              publishing turns this into `pinned` — visibly, before the author publishes.
+// - `follows`  "always latest", chosen on purpose. The call rides along with the callee, so a
+//              change to the building block changes this flow too. Publishing leaves it alone.
+// - `pinned`   one immutable version, whatever is published elsewhere.
+//
+// ⚠️ Without the freeze a change to a building block would silently change the behavior of every
+// published flow using it, which contradicts the immutable versions and pinned schema fingerprints
+// Intel otherwise guarantees. That is why `latest` cannot survive publishing.
+export const SubflowVersionMode = z.enum(["latest", "follows", "pinned"]);
+export const SubflowVersion = z.discriminatedUnion("mode", [
+    z.strictObject({ mode: z.literal("latest") }),
+    z.strictObject({ mode: z.literal("follows") }),
+    z.strictObject({ mode: z.literal("pinned"), versionId: IntelId }),
+]);
+// The three layers a node can belong to (D25). Which one a kind is in decides what it may carry and
+// where it may sit, and both rules are enforced in `compileFlow` rather than only drawn in the
+// editor — a graph arrives over MCP as readily as from the canvas.
+//
+// ⚠️ A LINK never stands in the chain. It hangs off a step on a `context` edge, and that is the
+// distinction the graph has drawn since #37 without anyone enforcing it — which is exactly how a
+// start with an attachment once began its run at the attachment (the "flow edges only" comments in
+// `flows.ts`). Marker and step keep the chain; a link is what a step works with.
+export const FlowNodeLayer = z.enum(["marker", "step", "link"]);
+export const flowNodeLayer = {
+    trigger: "marker",
+    output: "marker",
+    instruction: "step",
+    condition: "step",
+    subflow: "step",
+    folder: "link",
+    document: "link",
+    upload: "link",
+    table: "link",
+    tool: "link",
+};
+// One reference, never a list. The old `knowledge` node carried up to a hundred, plus a retrieval
+// mode and a query that nothing read — three things in one, and the last two describing a retrieval
+// Intel does not perform (D24: the agent fetches, Intel does not put anything into a context).
+// Splitting by kind is what makes "exactly one" sayable at all, and it lets the editor filter the
+// picker by what the node is for.
+const LinkConfiguration = z.strictObject({ resourceId: IntelId });
 export const FlowNode = z.discriminatedUnion("kind", [
     z.strictObject({
         ...FlowNodeBase,
         kind: z.literal("trigger"),
-        configuration: z.discriminatedUnion("mode", [
-            z.strictObject({ mode: z.literal("manual") }),
-            z.strictObject({ mode: z.literal("webhook"), event: z.string().min(1).max(120) }),
-            z.strictObject({ mode: z.literal("schedule"), cron: z.string().min(5).max(120) }),
-        ]),
+        // ⚠️ `manual` is the only mode there is. `webhook` and `schedule` stood here and fired nothing:
+        // a flow is carried out by an external agent that brings its own schedule, which is what the
+        // code does rather than what it intends — `step()` hands back the current node, `completeStep`
+        // takes the result from outside, and the Cloudflare workflow waits rather than drives. #32 was
+        // closed on that basis, and a mode nothing triggers is a promise nobody keeps.
+        configuration: z.strictObject({ mode: z.literal("manual") }),
     }),
     z.strictObject({
         ...FlowNodeBase,
         kind: z.literal("instruction"),
         configuration: z.strictObject({ prompt: z.string().min(1).max(50_000) }),
     }),
+    // The four link kinds that name something in the shared tree. They are separate kinds rather than
+    // one with a `kind` field so the canvas, the palette and the picker can each say what they mean
+    // without reading into a configuration — and so a stored graph says it too.
+    z.strictObject({ ...FlowNodeBase, kind: z.literal("folder"), configuration: LinkConfiguration }),
     z.strictObject({
         ...FlowNodeBase,
-        kind: z.literal("knowledge"),
-        configuration: z.strictObject({
-            resourceIds: z.array(IntelId).min(1).max(100),
-            mode: z.enum(["full", "relevant"]),
-            query: z.string().max(1_000).nullable().default(null),
-        }),
+        kind: z.literal("document"),
+        configuration: LinkConfiguration,
     }),
+    z.strictObject({ ...FlowNodeBase, kind: z.literal("upload"), configuration: LinkConfiguration }),
+    z.strictObject({ ...FlowNodeBase, kind: z.literal("table"), configuration: LinkConfiguration }),
     z.strictObject({
         ...FlowNodeBase,
         kind: z.literal("tool"),
@@ -323,24 +461,47 @@ export const FlowNode = z.discriminatedUnion("kind", [
             instruction: z.string().min(1).max(10_000),
         }),
     }),
+    // ⚠️ There is no `approval` kind, and adding one back is a product decision rather than a schema
+    // addition (#73). It waited on a named person with a deadline, which needs a queue, a
+    // notification, a stand-in and an answer to "the deadline passed" — none of which exist. Without
+    // it, D24 holds without exception: nothing in Intel waits. A stored graph that still carries one
+    // is rewritten to a `condition` by migration 0007, because the question it asked is one the agent
+    // can answer.
+    //
+    // The seventh kind: one flow calls another (ADR-0004 §3). A schema addition, not hidden behavior
+    // in a generic code node — which flow is called has to be readable from the graph, or neither the
+    // publish-time call rule nor the sidebar could see it.
     z.strictObject({
         ...FlowNodeBase,
-        kind: z.literal("approval"),
+        kind: z.literal("subflow"),
+        // What the called flow is given travels through `StartFlowRunInput.input` — the schema every run
+        // already uses. A second, static input here would be a promise the execution does not keep.
         configuration: z.strictObject({
-            prompt: z.string().min(1).max(10_000),
-            timeout: z.string().regex(/^\d+\s+(minute|minutes|hour|hours|day|days)$/),
+            flowId: IntelId,
+            version: SubflowVersion.default({ mode: "latest" }),
         }),
     }),
+    // ⚠️ The end marks, it does not make. It used to carry a `template` that nothing ever read, and a
+    // node called "Result" that appeared to produce one is what everybody read it as. The result of a
+    // run is what the last step before it hands in (D25) — `completeStep` carries that forward.
     z.strictObject({
         ...FlowNodeBase,
         kind: z.literal("output"),
-        configuration: z.strictObject({ template: z.string().max(50_000).default("") }),
+        configuration: z.strictObject({}),
     }),
 ]);
+// The two things an edge can mean (#37). `flow` is the order of work — "and then". `context` is what
+// a step works with: a document consulted in exactly this step, an approval obtained in exactly this
+// step, or, at the output, the table a result is written to.
+//
+// ⚠️ `flow` is the default, and that is the whole of the migration: every edge stored before this
+// existed parses into the meaning it already had. Nothing about saved graphs has to be rewritten.
+export const FlowEdgeKind = z.enum(["flow", "context"]);
 export const FlowEdge = z.strictObject({
     id: FlowNodeId,
     source: FlowNodeId,
     target: FlowNodeId,
+    kind: FlowEdgeKind.default("flow"),
     label: z.string().trim().min(1).max(120).nullable().default(null),
     sourceHandle: z.string().trim().min(1).max(120).nullable().default(null),
 });
@@ -376,6 +537,41 @@ export const FlowDocument = z.strictObject({
     version: FlowVersion.nullable(),
 });
 export const FlowList = z.strictObject({ items: z.array(Flow) });
+export const FlowKnowledgeReference = 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,
+// 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.
+export const FlowRequirements = z.strictObject({
+    flowId: IntelId,
+    versionId: IntelId.nullable(),
+    knowledge: z.array(FlowKnowledgeReference),
+    hiddenKnowledge: 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.
+//
+// ⚠️ A snapshot, and it says so. The tool catalog is a live query with the requesting user's own
+// token (ADR-0003), so what is reachable now can be different tomorrow, and the same flow answers
+// differently for two people. That is why this is a question one asks rather than a badge on the
+// flow: a standing "this flow has conflicts" would be wrong for tools by construction (#72, D24).
+export const FlowValidation = z.strictObject({
+    flowId: IntelId,
+    versionId: IntelId.nullable(),
+    // Empty means it would start now — for this person, at this moment.
+    problems: z.array(z.strictObject({
+        code: z.string().min(1).max(80),
+        detail: z.string().min(1).max(2_000),
+    })),
+    checkedAt: IsoDateTime,
+});
 export const CreateFlowInput = z.strictObject({
     parentId: IntelId.nullable().default(null),
     title: z.string().trim().min(1).max(240),
@@ -413,27 +609,80 @@ export const PublishFlowInput = z.strictObject({
     versionId: IntelId,
     idempotencyKey: z.string().min(8).max(200),
 });
-export const ListFlowGrantsInput = z.strictObject({ resourceId: IntelId });
-export const ShareFlowInput = z.strictObject({
-    resourceId: IntelId,
-    principal: SharePrincipal,
-    role: ResourceRole,
-    expiresAt: IsoDateTime.nullable().default(null),
-    idempotencyKey: z.string().min(8).max(200),
-});
-export const RevokeFlowGrantInput = z.strictObject({
-    resourceId: IntelId,
-    grantId: IntelId,
-    idempotencyKey: z.string().min(8).max(200),
-});
-export const FlowRunStatus = z.enum([
-    "queued",
-    "running",
-    "waiting",
-    "completed",
-    "failed",
-    "cancelled",
+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
+// the decision before making it rather than after.
+//
+// ⚠️ Only callees the asking actor may reach are listed at all. A call whose callee they cannot see
+// is left out rather than named, because a title is the thing an unreachable flow must not hand out.
+export const FlowPublishCall = z.strictObject({
+    nodeId: FlowNodeId,
+    nodeLabel: z.string().min(1).max(160),
+    calleeId: IntelId,
+    calleeTitle: z.string().min(1).max(240),
+    mode: SubflowVersionMode,
+    // The version this call will take once published. `null` when it follows the callee, which is the
+    // one case where the answer is only known at run time.
+    versionId: IntelId.nullable(),
+    versionSequence: z.number().int().positive().nullable(),
+    freezes: z.boolean(),
+    // The callee has a published version to be called at all. `false` is what publishing will refuse.
+    available: z.boolean(),
+});
+export const FlowPublishPreview = z.strictObject({
+    flowId: IntelId,
+    versionId: IntelId,
+    calls: z.array(FlowPublishCall),
+});
+// A flow has no share schema of its own. A grant sits on the folder a flow is filed in and inherits
+// down from there (ADR-0004 §2); a narrower grant beside it would destroy the subtree guarantee
+// section 3 rests on, so per-flow grants were removed rather than deprecated.
+// 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 RelationNode = z.strictObject({
+    id: IntelId,
+    kind: RelationNodeKind,
+    title: z.string().min(1).max(240),
+    // Inside the level being shown, rather than something it reaches out to. A flow reading a policy
+    // document from another folder pulls that document in, and the difference should be legible.
+    inScope: z.boolean(),
+});
+export const RelationEdge = z.strictObject({
+    id: z.string().min(1).max(400),
+    source: IntelId,
+    target: IntelId,
+    relation: z.enum(["reads", "calls"]),
+});
+export const RelationGraphScope = z.discriminatedUnion("of", [
+    z.strictObject({ of: z.literal("folder"), folderId: IntelId.nullable() }),
+    z.strictObject({ of: z.literal("flow"), flowId: IntelId }),
 ]);
+export const RelationGraphInput = z.strictObject({
+    scope: RelationGraphScope,
+    // How much is drawn before the answer is summarized instead. A big folder has to stay usable, and
+    // the cut-off is reported rather than swallowed.
+    limit: z.number().int().min(1).max(300).default(60),
+});
+// ⚠️ Only what the asking user may see is in here. A node they may not reach is absent, not greyed
+// out and not counted: an edge to a placeholder would already tell them the thing exists, which is
+// the leak this schema has to make impossible to write by accident. `omitted` is about the size
+// limit alone, never about permissions.
+export const RelationGraph = z.strictObject({
+    scope: RelationGraphScope,
+    nodes: z.array(RelationNode),
+    edges: z.array(RelationEdge),
+    omitted: z.number().int().nonnegative(),
+    limit: z.number().int().positive(),
+});
+// ⚠️ No `waiting`. It was written for the approval node and never set by anything — the two places
+// that tested for it only ever saw `running` (#73). The column's CHECK constraint still allows the
+// value, deliberately: rewriting it means rebuilding the table in D1 for a value nothing writes,
+// and migration 0007 turns any row that somehow carries it into `failed` rather than leave a status
+// the contract cannot parse.
+export const FlowRunStatus = z.enum(["queued", "running", "completed", "failed", "cancelled"]);
 export const FlowRun = z.strictObject({
     id: IntelId,
     flowId: IntelId,
@@ -444,14 +693,36 @@ export const FlowRun = z.strictObject({
     output: z.unknown().nullable(),
     error: z.string().max(2_000).nullable(),
     initiatedBy: IntelId,
+    // The subflow node this run was called from, and the run that node belongs to. A called run is a
+    // run of its own: it has its own version, its own steps and its own authorization, and only these
+    // two fields say where its result goes back to.
+    parentRunId: IntelId.nullable().default(null),
+    parentNodeId: FlowNodeId.nullable().default(null),
     createdAt: IsoDateTime,
     updatedAt: IsoDateTime,
     completedAt: IsoDateTime.nullable(),
 });
-export const FlowRunStep = z.strictObject({ run: FlowRun, node: FlowNode.nullable() });
+// Which step of which flow is running, outermost caller first. Readable rather than reconstructed
+// from `parentRunId` by whoever is looking (#17).
+export const FlowRunTrailEntry = z.strictObject({
+    runId: IntelId,
+    flowId: IntelId,
+    flowTitle: z.string().min(1).max(240),
+    nodeId: FlowNodeId.nullable(),
+    nodeLabel: z.string().max(160).nullable(),
+});
+export const FlowRunStep = z.strictObject({
+    run: FlowRun,
+    node: FlowNode.nullable(),
+    trail: z.array(FlowRunTrailEntry).default([]),
+});
 export const StartFlowRunInput = z.strictObject({
     flowId: IntelId,
     input: z.record(z.string(), z.unknown()).default({}),
+    // Present when this run is the call a subflow node makes. It names a place, never a permission:
+    // the callee's `execute` is asked of the user exactly as it is for a run they start themselves,
+    // and the parent run must be the caller's own and standing on that very node.
+    parent: z.strictObject({ runId: IntelId, nodeId: FlowNodeId }).nullable().default(null),
     idempotencyKey: z.string().min(8).max(200),
 });
 export const GetFlowRunInput = z.strictObject({ runId: IntelId });
@@ -464,3 +735,81 @@ export const CompleteFlowRunStepInput = z.strictObject({
     error: z.string().max(2_000).nullable().default(null),
     idempotencyKey: z.string().min(8).max(200),
 });
+// Why a run started. Derived when it is read and deliberately not a column: `subflow` when the run
+// is the call another run made, otherwise the mode of the trigger node in the immutable version the
+// run took. A stored copy would be a second answer that could disagree with the graph that ran.
+//
+// ⚠️ `webhook` and `schedule` stood here until #39 took them out of the trigger node. Being derived
+// rather than stored is exactly what makes that safe: no run carries a trigger of its own, so once
+// the 0005 migration has rewritten every stored trigger to `manual`, there is nowhere left for the
+// old values to come from. Had this been a column, the enum would have had to keep reading them or
+// every old run would have failed to parse the moment somebody opened the list.
+export const FlowRunTrigger = z.enum(["manual", "subflow"]);
+// Which step ended a run, and why, in the words the failure already used (#20).
+//
+// ⚠️ A call that failed carries its reason in the *called* run, and that run is a run of its own
+// with its own authorization. `calledRunId` is therefore filled only when the asking user may see
+// that run through the very rule every other run answer uses; otherwise the failure is named by the
+// calling step alone — the caller's own label — and `detail` says no more than that it did not
+// finish. Naming a callee's step or document here would be the leak #17, #19 and #20 each closed.
+export const FlowRunFailure = z.strictObject({
+    nodeId: FlowNodeId,
+    nodeLabel: z.string().max(160),
+    detail: z.string().max(2_000),
+    calledRunId: IntelId.nullable(),
+});
+// 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
+// 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.
+export const FlowRunSummary = z.strictObject({
+    id: IntelId,
+    flowId: IntelId,
+    // The version the run took. Together with the run's stored input it is what a later "run this
+    // again with the old data" would need; replaying is a separate ticket, this only keeps it possible.
+    versionId: IntelId,
+    status: FlowRunStatus,
+    trigger: FlowRunTrigger,
+    startedAt: IsoDateTime,
+    completedAt: IsoDateTime.nullable(),
+    durationMs: z.number().int().nonnegative().nullable(),
+    initiatedBy: IntelId,
+    parentRunId: IntelId.nullable(),
+    failure: FlowRunFailure.nullable(),
+});
+// One filter and nothing else: "only the failed ones" is the question asked in almost every case,
+// and every further facet is a report rather than a search for a fault.
+export const ListFlowRunsInput = z.strictObject({
+    flowId: IntelId,
+    failedOnly: z.boolean().default(false),
+    limit: z.number().int().min(1).max(50).default(20),
+    // The `nextCursor` of the previous page. Keyset rather than an offset, because runs arrive while
+    // someone reads and an offset would skip or repeat rows exactly when a flow is busy.
+    cursor: z.string().min(1).max(400).nullable().default(null),
+});
+export const FlowRunList = z.strictObject({
+    items: z.array(FlowRunSummary),
+    nextCursor: z.string().max(400).nullable(),
+});
+// One completed step of one run. `detail` is the step's own error text; an output is absent for the
+// same reason it is absent from the summary.
+export const FlowRunStepRecord = z.strictObject({
+    nodeId: FlowNodeId,
+    nodeLabel: z.string().max(160),
+    outcome: z.enum(["completed", "failed"]),
+    branch: z.string().max(120).nullable(),
+    detail: z.string().max(2_000).nullable(),
+    calledRunId: IntelId.nullable(),
+    completedAt: IsoDateTime,
+});
+// What one run did, step by step, oldest first, with the call chain it belongs to (#17). The trail
+// is what makes a nested run readable: which step of which flow this run is.
+export const FlowRunHistory = z.strictObject({
+    runId: IntelId,
+    flowId: IntelId,
+    status: FlowRunStatus,
+    steps: z.array(FlowRunStepRecord),
+    trail: z.array(FlowRunTrailEntry),
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-contract",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {