@anchrd/intel-contract 0.2.0 → 0.2.2

package/dist/contract/contract.js

@@ -9,9 +9,21 @@ export const ProblemDetails = z.strictObject({
     instance: z.string().optional(),
     code: z.string().optional(),
 });
-export const KnowledgeNodeKind = z.enum(["folder", "document", "attachment"]);
+// Who the caller is, as Gate resolved it from the bearer. Deliberately identity only: no
+// capabilities, no token, nothing a surface could mistake for a permission.
+export const SessionUser = z.strictObject({
+    id: IntelId,
+    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"]);
 export const ContextPolicy = z.enum(["pinned", "relevant", "explicit"]);
-export const ResourceRole = z.enum(["viewer", "commenter", "editor", "manager"]);
+// 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() }),
@@ -101,32 +113,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),
@@ -146,7 +220,7 @@ export const ResourceGrant = z.strictObject({
     id: IntelId,
     resourceId: IntelId,
     principal: SharePrincipal,
-    role: ResourceRole,
+    verb: ResourceVerb,
     expiresAt: IsoDateTime.nullable(),
     createdBy: IntelId,
     createdAt: IsoDateTime,
@@ -154,7 +228,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),
 });
@@ -163,7 +237,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),
@@ -183,7 +280,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 ||
@@ -265,21 +361,42 @@ 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 }),
+]);
 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,
@@ -324,16 +441,37 @@ export const FlowNode = z.discriminatedUnion("kind", [
             timeout: z.string().regex(/^\d+\s+(minute|minutes|hour|hours|day|days)$/),
         }),
     }),
+    // The eighth kind: one flow calls another (ADR-0004 §3). A schema addition, not hidden behavior in
+    // a generic code node — which flow is called has to be readable from the graph, or neither the
+    // publish-time call rule nor the sidebar could see it.
+    z.strictObject({
+        ...FlowNodeBase,
+        kind: z.literal("subflow"),
+        // What the called flow is given travels through `StartFlowRunInput.input` — the schema every run
+        // already uses. A second, static input here would be a promise the execution does not keep.
+        configuration: z.strictObject({
+            flowId: IntelId,
+            version: SubflowVersion.default({ mode: "latest" }),
+        }),
+    }),
     z.strictObject({
         ...FlowNodeBase,
         kind: z.literal("output"),
         configuration: z.strictObject({ template: z.string().max(50_000).default("") }),
     }),
 ]);
+// 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),
 });
@@ -343,6 +481,10 @@ 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).
+    // Everything else stays apart — versions, R2 body and Vectorize belong to the document, the graph,
+    // runs and approvals to the flow. `null` is the root of that same tree.
+    parentId: IntelId.nullable(),
     title: z.string().min(1).max(240),
     description: z.string().max(2_000).nullable(),
     ownerId: IntelId,
@@ -365,11 +507,50 @@ 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),
+});
 export const CreateFlowInput = 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),
     idempotencyKey: z.string().min(8).max(200),
 });
+// Renaming and moving a flow. Both are organization and nothing else: they touch no version, no
+// published graph and no run, because organization has to stay free of consequence or nobody dares
+// to reorganize (ADR-0004).
+export const UpdateFlowInput = z
+    .strictObject({
+    flowId: IntelId,
+    baseUpdatedAt: IsoDateTime,
+    title: z.string().trim().min(1).max(240).optional(),
+    description: z.string().trim().max(2_000).nullable().optional(),
+    parentId: IntelId.nullable().optional(),
+    idempotencyKey: z.string().min(8).max(200),
+})
+    .refine((input) => input.title !== undefined || input.description !== undefined || input.parentId !== undefined, { error: "At least one change is required" });
+// Three answers, not two: an absent `parentId` lists every visible flow (the search dialog asks
+// that), `null` lists the root of the shared tree and an ID lists one folder (the sidebar tree asks
+// per level, which is what keeps the tree off the N+1 it used to load with).
+export const ListFlowsInput = z.strictObject({
+    parentId: IntelId.nullable().optional(),
+});
 export const GetFlowInput = z.strictObject({ flowId: IntelId });
 export const SaveFlowVersionInput = z.strictObject({
     flowId: IntelId,
@@ -382,18 +563,73 @@ 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 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(),
 });
 export const FlowRunStatus = z.enum([
     "queued",
@@ -413,14 +649,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 });
@@ -433,3 +691,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.0",
+  "version": "0.2.2",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {