@anchrd/intel-contract 0.12.0 → 0.14.0

package/dist/contract/flow.js

@@ -0,0 +1,417 @@
+import { z } from "zod";
+import { IdempotencyKey, IntelId, IsoDateTime, LinkConfiguration } from "./contract.js";
+import { ToolName } from "./tool.js";
+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),
+};
+// 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",
+};
+export const FlowNode = z.discriminatedUnion("kind", [
+    z.strictObject({
+        ...FlowNodeBase,
+        kind: z.literal("trigger"),
+        // ⚠️ `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("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"),
+        configuration: z.strictObject({
+            toolName: ToolName,
+            fingerprint: z
+                .string()
+                .regex(/^[a-f0-9]{64}$/)
+                .nullable()
+                .default(null),
+            arguments: z.record(z.string(), z.unknown()).default({}),
+        }),
+    }),
+    z.strictObject({
+        ...FlowNodeBase,
+        kind: z.literal("condition"),
+        configuration: z.strictObject({
+            mode: z.literal("semantic"),
+            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("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" }),
+        }),
+    }),
+    // ⚠️ 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({}),
+    }),
+]);
+// 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),
+});
+export const FlowGraph = z.strictObject({
+    nodes: z.array(FlowNode).min(2).max(200),
+    edges: z.array(FlowEdge).min(1).max(500),
+});
+export const Flow = z.strictObject({
+    id: IntelId,
+    // 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(),
+    title: z.string().min(1).max(240),
+    description: z.string().max(2_000).nullable(),
+    ownerId: IntelId,
+    currentVersionId: IntelId.nullable(),
+    publishedVersionId: IntelId.nullable(),
+    createdAt: IsoDateTime,
+    updatedAt: IsoDateTime,
+    archivedAt: IsoDateTime.nullable(),
+});
+export const FlowVersion = z.strictObject({
+    id: IntelId,
+    flowId: IntelId,
+    sequence: z.number().int().positive(),
+    graph: FlowGraph,
+    createdBy: IntelId,
+    createdAt: IsoDateTime,
+});
+export const FlowDocument = z.strictObject({
+    flow: Flow,
+    version: FlowVersion.nullable(),
+});
+// 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.describe("Flow the version belongs to. Named alongside the version so access is decided on the flow."),
+    versionId: IntelId.describe("Version to read, from flow_version_list."),
+});
+// 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 ReferencedNode = z.strictObject({
+    id: IntelId,
+    title: z.string().min(1).max(240),
+});
+// 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).
+//
+// ⚠️ `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(),
+    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.
+//
+// ⚠️ 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)
+        .describe("Folder to file the flow in. `null` puts it at the top level."),
+    title: z.string().trim().min(1).max(240).describe("What the flow is called."),
+    description: z
+        .string()
+        .trim()
+        .max(2_000)
+        .nullable()
+        .default(null)
+        .describe("Optional sentence about what the flow is for."),
+    idempotencyKey: IdempotencyKey,
+});
+// 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.describe("Flow to rename or move."),
+    baseUpdatedAt: IsoDateTime.describe("`updatedAt` as flow_get last reported it. A newer value on the server means somebody else changed the flow first and the call is refused."),
+    title: z
+        .string()
+        .trim()
+        .min(1)
+        .max(240)
+        .optional()
+        .describe("New title. Omit to leave it as it is."),
+    description: z
+        .string()
+        .trim()
+        .max(2_000)
+        .nullable()
+        .optional()
+        .describe("New description, or `null` to clear it. Omit to leave it as it is."),
+    parentId: IntelId.nullable()
+        .optional()
+        .describe("Folder to move the flow into, or `null` for the top level. Omit to leave it where it is. Moving touches no version, no published graph and no run."),
+    idempotencyKey: IdempotencyKey,
+})
+    .refine((input) => input.title !== undefined || input.description !== undefined || input.parentId !== undefined, { error: "At least one change is required" });
+// Archiving a flow is the same shape as archiving a document, deliberately: `archived` is a boolean
+// rather than a one-way verb, because an archive nothing returns from is a delete under a friendlier
+// name. Restoring is the same call with `false`.
+export const ArchiveFlowInput = z.strictObject({
+    flowId: IntelId.describe("Flow to archive or restore."),
+    baseUpdatedAt: IsoDateTime.describe("`updatedAt` as flow_get last reported it. A newer value on the server means somebody else changed the flow first and the call is refused."),
+    archived: z
+        .boolean()
+        .describe("`true` archives the flow, `false` restores it. Nothing is deleted and every version stays readable."),
+    idempotencyKey: IdempotencyKey,
+});
+// 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()
+        .describe("Three answers, not two: omit it to list every flow this reader may see, pass `null` for the top level, or a folder id for one level of it."),
+    // The only way back to an archived flow, and the only place that asks for one: the bounded read
+    // 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 `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()
+        .describe("Include archived flows beside the live ones. Absent means without them."),
+    // The same question for flows, and the same override of `parentId` — see `ListNodesInput`.
+    archivedOnly: z
+        .boolean()
+        .optional()
+        .describe("List only archived flows, across the whole tree. Overrides parentId rather than narrowing it."),
+});
+export const GetFlowInput = z.strictObject({
+    flowId: IntelId.describe("Flow to read, from flow_list."),
+});
+export const SaveFlowVersionInput = z.strictObject({
+    flowId: IntelId.describe("Flow to append a version to."),
+    baseVersionId: IntelId.nullable().describe("The version this edit was made against, from flow_get, or `null` for a flow that has none yet. If the flow has moved on since, the call is refused rather than overwriting the newer version."),
+    graph: FlowGraph.describe("The complete graph — nodes and edges — not a patch. It is validated before it is stored, so an unreachable node or a dangling edge is refused here rather than at run time."),
+    idempotencyKey: IdempotencyKey,
+});
+export const PublishFlowInput = z.strictObject({
+    flowId: IntelId.describe("Flow to publish a version of."),
+    versionId: IntelId.describe("Which version becomes the published one. Publishing freezes what it calls: a sub-flow call set to `latest` is pinned to the version current at this moment. flow_publish_preview shows that beforehand."),
+    idempotencyKey: IdempotencyKey,
+});
+// 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.describe("Flow to withdraw. What is withdrawn is whatever is published now — there is no versionId, so there is no race between reading it and revoking it. Versions are untouched."),
+    idempotencyKey: IdempotencyKey,
+});
+export const PreviewFlowPublishInput = z.strictObject({
+    flowId: IntelId.describe("Flow the version belongs to."),
+    versionId: IntelId.describe("The version flow_publish would be called with. Nothing is changed by asking."),
+});
+// 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.describe("What to draw around: one folder — `null` for the whole tree — or one flow."),
+    // 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)
+        .describe("How many nodes the drawing may carry before it is summarized instead. What was left out is reported in `omitted` rather than swallowed."),
+});
+// ⚠️ 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(),
+});