@calliopelabs/ui 0.7.0 → 0.12.0

package/dist/workflow/definition.d.ts

@@ -0,0 +1,408 @@
+/**
+ * The workflow definition the editor edits: flows of nodes and edges, and the
+ * registry the host supplies beside it. Module-neutral: a step is whatever a
+ * module's preset says it is, a port carries whatever type the module names,
+ * and the run facts, gate kinds and condition operators a definition may use
+ * come from the host. Nothing here assumes tickets, repositories or code.
+ * Pure: no hooks, no browser APIs.
+ */
+import type { WorkflowAvailability, WorkflowModule } from "./model.js";
+/** The definition format this package reads and writes. */
+export declare const WORKFLOW_DEFINITION_VERSION = 1;
+/** Every kind of node a flow is built from. */
+export declare const WORKFLOW_NODE_KINDS: readonly ["step", "subflow", "gate", "condition", "goto", "fanout", "join", "variants", "evaluator", "classifier", "check"];
+export type WorkflowNodeKind = (typeof WORKFLOW_NODE_KINDS)[number];
+/** A choice the host offers in a picker: a role, a member, a model, a harness, an effort. */
+export interface WorkflowOption {
+    id: string;
+    label: string;
+    hint?: string;
+}
+/**
+ * A typed port: what a step takes in or gives out. `type` is a data type id
+ * the registry names ("video", "contract", "form"); `"any"` takes anything.
+ */
+export interface WorkflowPort {
+    id: string;
+    label: string;
+    type: string;
+    /** An input the step can run without. */
+    optional?: boolean;
+}
+/** A data type a module names. `extends` lets a contract go where a document is wanted. */
+export interface WorkflowDataType {
+    id: string;
+    label: string;
+    extends?: readonly string[];
+}
+/** One building block a module offers: a step with its contract. */
+export interface WorkflowStepPreset {
+    /** Unique within its module ("transcode", "redline", "extract-fields"). */
+    id: string;
+    label: string;
+    hint?: string;
+    inputs: readonly WorkflowPort[];
+    outputs: readonly WorkflowPort[];
+    /** Capabilities the destination must have to run it, by display name. */
+    capabilities?: readonly string[];
+    /** Whether the step takes a model, harness and effort (agent work does; a transcode does not). */
+    agent?: boolean;
+}
+/** A module as the registry knows it: its label and version, presets and types. */
+export interface WorkflowModuleSpec extends WorkflowModule {
+    presets: readonly WorkflowStepPreset[];
+    types?: readonly WorkflowDataType[];
+    /** Whether this factory runs the module. Omitted means available. */
+    availability?: WorkflowAvailability;
+}
+export type WorkflowFactType = "string" | "number" | "boolean" | "enum";
+/** A run fact a condition or a loop exit can test, as the host names it. */
+export interface WorkflowFact {
+    id: string;
+    label: string;
+    type: WorkflowFactType;
+    /** An enum's values. */
+    values?: readonly WorkflowOption[];
+    /**
+     * The fact belongs to a node ("score of", "passed"): the condition names one.
+     * `true` takes any node; a list takes only those kinds.
+     */
+    node?: boolean | readonly WorkflowNodeKind[];
+}
+/** A comparison the host's runtime evaluates. */
+export interface WorkflowOperator {
+    id: string;
+    label: string;
+    /** The fact types it applies to. */
+    types: readonly WorkflowFactType[];
+    /** Takes no value ("is set", "is empty"). */
+    unary?: boolean;
+}
+/** What a gate of some kind is configured with. */
+export type WorkflowGateField = "approvers" | "threshold" | "rule" | "timeout";
+/** A kind of gate the host's runtime knows: people approve, a score clears, a window opens. */
+export interface WorkflowGateKind {
+    id: string;
+    label: string;
+    hint?: string;
+    /** The fields the gate needs: `approvers` (roles, members, quorum), a `threshold`, a `rule`, a `timeout`. */
+    fields: readonly WorkflowGateField[];
+    capabilities?: readonly string[];
+    availability?: WorkflowAvailability;
+}
+/**
+ * Everything the host tells the editor about where the definition will run:
+ * the installed modules and their presets, the run facts, operators and gate
+ * kinds the runtime knows, the capabilities present, which node kinds it
+ * runs, and the choices its pickers offer. The library ships none of these.
+ */
+export interface WorkflowRegistry {
+    modules: readonly WorkflowModuleSpec[];
+    facts: readonly WorkflowFact[];
+    operators: readonly WorkflowOperator[];
+    gateKinds: readonly WorkflowGateKind[];
+    /** Data types beyond the modules' own. */
+    types?: readonly WorkflowDataType[];
+    /** Capabilities this destination has. Omitted: capabilities are not checked. */
+    capabilities?: readonly string[];
+    /** Whether the runtime runs each node kind. Omitted kinds are available. */
+    nodeKinds?: Partial<Record<WorkflowNodeKind, WorkflowAvailability>>;
+    roles?: readonly WorkflowOption[];
+    members?: readonly WorkflowOption[];
+    models?: readonly WorkflowOption[];
+    harnesses?: readonly WorkflowOption[];
+    efforts?: readonly WorkflowOption[];
+}
+export interface WorkflowPosition {
+    x: number;
+    y: number;
+}
+/** A comparison on a run fact. */
+export interface WorkflowCondition {
+    fact: string;
+    /** The node the fact belongs to, when the fact is a node's. */
+    node?: string;
+    op: string;
+    value?: string | number | boolean;
+}
+/** Who approves a gate, and how long they have. */
+export interface WorkflowGatePolicy {
+    roles?: readonly string[];
+    members?: readonly string[];
+    /** Approvals needed; one when omitted. */
+    quorum?: number;
+    timeoutHours?: number;
+    onTimeout?: "fail" | "escalate";
+}
+interface NodeBase {
+    id: string;
+    label: string;
+    /** Where it sits on the canvas; laid out when omitted. */
+    at?: WorkflowPosition;
+    note?: string;
+}
+/** One unit of work: a module's preset, or a custom step with its own ports. */
+export interface WorkflowStepNode extends NodeBase {
+    kind: "step";
+    /** The preset, by module and id. */
+    preset?: {
+        module: string;
+        id: string;
+    };
+    /** A custom step's ports; a preset's come from the registry. */
+    inputs?: readonly WorkflowPort[];
+    outputs?: readonly WorkflowPort[];
+    model?: string;
+    harness?: string;
+    effort?: string;
+}
+/** Runs another flow of the definition in its place, once or once per item. */
+export interface WorkflowSubflowNode extends NodeBase {
+    kind: "subflow";
+    flow: string;
+    /** Runs the flow once per item of this input. */
+    each?: string;
+}
+export interface WorkflowGateNode extends NodeBase {
+    kind: "gate";
+    /** A gate kind id from the registry. */
+    gate: string;
+    policy?: WorkflowGatePolicy;
+    /** Pass at or above, 0 to 1. */
+    threshold?: number;
+    rule?: string;
+}
+export interface WorkflowCase {
+    id: string;
+    label: string;
+    when: WorkflowCondition;
+}
+/** If or switch on run facts: each case is an exit, then else. */
+export interface WorkflowConditionNode extends NodeBase {
+    kind: "condition";
+    cases: readonly WorkflowCase[];
+}
+/** Jumps back to a named node, at most `max` times. */
+export interface WorkflowGotoNode extends NodeBase {
+    kind: "goto";
+    target: string;
+    max?: number;
+}
+export interface WorkflowFanoutNode extends NodeBase {
+    kind: "fanout";
+}
+export interface WorkflowJoinNode extends NodeBase {
+    kind: "join";
+    wait: "all" | "any" | "n";
+    n?: number;
+}
+export interface WorkflowVariant {
+    id: string;
+    label: string;
+    model?: string;
+    harness?: string;
+    effort?: string;
+}
+export declare const WORKFLOW_SELECTORS: readonly ["evaluator", "first-passing", "cheapest-passing", "person"];
+export type WorkflowSelector = (typeof WORKFLOW_SELECTORS)[number];
+/** Runs one preset several ways side by side and keeps a winner. */
+export interface WorkflowVariantsNode extends NodeBase {
+    kind: "variants";
+    preset?: {
+        module: string;
+        id: string;
+    };
+    variants: readonly WorkflowVariant[];
+    select?: WorkflowSelector;
+    /** The evaluator whose score picks, when `select` is `evaluator`. */
+    evaluator?: string;
+}
+/** Scores its subject on a rubric; routes on pass and fail when `routes`. */
+export interface WorkflowEvaluatorNode extends NodeBase {
+    kind: "evaluator";
+    question?: string;
+    /** The rubric, lowest level first. */
+    levels: readonly string[];
+    threshold?: number;
+    routes: boolean;
+    /** Below this confidence a person decides. */
+    minConfidence?: number;
+}
+export interface WorkflowClassifierOption {
+    id: string;
+    label: string;
+    description?: string;
+}
+/** Labels its subject; each label is an exit, with `other` and else. */
+export interface WorkflowClassifierNode extends NodeBase {
+    kind: "classifier";
+    question?: string;
+    options: readonly WorkflowClassifierOption[];
+    other: boolean;
+    minConfidence?: number;
+}
+/** A yes or no question about its subject, routed on the answer. */
+export interface WorkflowCheckNode extends NodeBase {
+    kind: "check";
+    question: string;
+    /** Yes at or above this probability. */
+    threshold: number;
+}
+export type WorkflowNode = WorkflowStepNode | WorkflowSubflowNode | WorkflowGateNode | WorkflowConditionNode | WorkflowGotoNode | WorkflowFanoutNode | WorkflowJoinNode | WorkflowVariantsNode | WorkflowEvaluatorNode | WorkflowClassifierNode | WorkflowCheckNode;
+export type WorkflowNodeOf<K extends WorkflowNodeKind> = Extract<WorkflowNode, {
+    kind: K;
+}>;
+/**
+ * `next` carries the run on from an exit (`port`, `out` when omitted) to a
+ * node. `loop` goes back to an earlier node until `until` holds, at most
+ * `max` times. `data` hands an output (`port`) to an input (`input`).
+ */
+export interface WorkflowEdge {
+    kind: "next" | "loop" | "data";
+    from: string;
+    to: string;
+    port?: string;
+    input?: string;
+    label?: string;
+    max?: number;
+    until?: WorkflowCondition;
+}
+export interface WorkflowFlow {
+    label?: string;
+    /** What the flow starts with: a run's inputs for the main flow, the caller's for a sub-flow. */
+    inputs?: readonly WorkflowPort[];
+    /** What a sub-flow hands back to its caller. */
+    outputs?: readonly WorkflowPort[];
+    nodes: readonly WorkflowNode[];
+    edges: readonly WorkflowEdge[];
+}
+/** A whole workflow definition: named flows, one of them the main. */
+export interface WorkflowDefinition {
+    version: typeof WORKFLOW_DEFINITION_VERSION;
+    name: string;
+    description?: string;
+    /** The module it belongs to, by id. */
+    module?: string;
+    main: string;
+    flows: Readonly<Record<string, WorkflowFlow>>;
+}
+export declare function findPreset(registry: WorkflowRegistry, ref: {
+    module: string;
+    id: string;
+} | undefined): {
+    module: WorkflowModuleSpec;
+    preset: WorkflowStepPreset;
+} | null;
+export declare function findFact(registry: WorkflowRegistry, id: string): WorkflowFact | undefined;
+export declare function findGateKind(registry: WorkflowRegistry, id: string): WorkflowGateKind | undefined;
+/** The operators that fit a fact's type. */
+export declare function operatorsFor(registry: WorkflowRegistry, fact: WorkflowFact | undefined): WorkflowOperator[];
+/** Every data type the registry names: the modules' own, then the host's. */
+export declare function dataTypes(registry: WorkflowRegistry): WorkflowDataType[];
+/** Whether a value of type `given` can go where `wanted` is asked for. */
+export declare function typeAccepts(registry: WorkflowRegistry, given: string, wanted: string): boolean;
+/** The judges: nodes that read a subject and route on what they make of it. */
+export type WorkflowJudgeNode = WorkflowEvaluatorNode | WorkflowClassifierNode | WorkflowCheckNode;
+export declare const isJudge: (n: WorkflowNode) => n is WorkflowJudgeNode;
+/**
+ * A node's typed inputs: a preset's, a custom step's own, a sub-flow's
+ * flow's, and a judge's subject (what it reads; the latest output when unbound).
+ */
+export declare function inputsOf(node: WorkflowNode, registry: WorkflowRegistry, definition?: WorkflowDefinition): readonly WorkflowPort[];
+/** A node's typed outputs. Gates, logic and judges pass work on but make nothing. */
+export declare function outputsOf(node: WorkflowNode, registry: WorkflowRegistry, definition?: WorkflowDefinition): readonly WorkflowPort[];
+/** The way on from a node with one exit. */
+export declare const OUT = "out";
+/** The handle a loop leaves from, and the one it comes back into. */
+export declare const LOOP_OUT = "back";
+export declare const LOOP_IN = "back-in";
+/** The handle work comes into. */
+export declare const IN = "in";
+/**
+ * The exits a node offers for `next` edges, in order: a condition's cases and
+ * else, a check's yes and no, a classifier's labels, other and else, a routing
+ * evaluator's pass and fail. A go-to has none: it jumps.
+ */
+export declare function exitsOf(node: WorkflowNode): string[];
+/**
+ * An exit as the node names it: a case's or a label's own words; the fixed
+ * exits (`else`, `yes`, `no`, `other`, `pass`, `fail`, `out`) come back as
+ * themselves for the caller's copy to name.
+ */
+export declare function exitLabel(node: WorkflowNode, exit: string): string;
+export declare const portOf: (e: WorkflowEdge) => string;
+/** A stable id for an edge: its kind, ends and ports. */
+export declare const edgeId: (e: WorkflowEdge) => string;
+/** Ids reachable from `from` over next edges. */
+export declare function downstream(flow: WorkflowFlow, from: string): Set<string>;
+/** Ids with a path of next edges to `to`. */
+export declare function upstream(flow: WorkflowFlow, to: string): Set<string>;
+/** The node a flow starts at: the first with no next edge coming in. */
+export declare function startOf(flow: WorkflowFlow): string | null;
+/**
+ * A drag (or its keyboard equivalent) from a source handle to a target
+ * handle. Source handles: an exit, `back` for a loop, `output:<id>` for data.
+ * Target handles: `in`, `back-in`, `input:<id>`.
+ */
+export interface WorkflowConnection {
+    from: string;
+    source: string;
+    to: string;
+    target: string;
+}
+/** Why a connection is refused. The editor's copy names each one. */
+export type WorkflowConnectReason = "missing-node" | "self" | "loop-target" | "loop-not-back" | "loop-exists" | "next-target" | "no-exit" | "exit-taken" | "exists" | "cycle" | "no-output" | "no-input" | "data-target" | "type-mismatch" | "data-order" | "input-taken";
+export type WorkflowConnectResult = {
+    ok: true;
+    edge: WorkflowEdge;
+} | {
+    ok: false;
+    reason: WorkflowConnectReason;
+    /** What the reason names: the node's label, the exit, the two types. */
+    values: Record<string, string>;
+};
+/**
+ * Whether a connection makes a legal edge, and the edge when it does. Next
+ * edges go from an exit into `in`, one per exit (a fan-out excepted), and
+ * never close a cycle. Loops go from `back` into an earlier node's `back-in`.
+ * Data goes from an output to an input of a type it fits, on a node that runs
+ * after it, one source per input. The canvas only lands what this accepts.
+ */
+export declare function canConnect(flow: WorkflowFlow, c: WorkflowConnection, registry: WorkflowRegistry, definition?: WorkflowDefinition): WorkflowConnectResult;
+/** A fresh node id from a label, not taken. */
+export declare function freshId(label: string, taken: Iterable<string>): string;
+/** What the palette adds: a kind, and for a step or variants a preset, for a gate its kind. */
+export interface WorkflowNodeTemplate {
+    kind: WorkflowNodeKind;
+    preset?: {
+        module: string;
+        id: string;
+    };
+    gate?: string;
+    /** The label to start with; the kind's or the preset's when omitted. */
+    label?: string;
+}
+/**
+ * A new node with workable defaults. Labels come from the preset or gate kind
+ * when there is one, else from `label` (the caller's copy for the kind).
+ */
+export declare function createNode(template: WorkflowNodeTemplate, id: string, registry: WorkflowRegistry, label: string): WorkflowNode;
+/** Adds a node, chained after `after` (or the last node) when an exit there is free. */
+export declare function addNode(flow: WorkflowFlow, node: WorkflowNode, after?: string | null): WorkflowFlow;
+/** Removes a node and every edge touching it; a go-to or a condition pointing at it loses the reference. */
+export declare function removeNode(flow: WorkflowFlow, id: string): WorkflowFlow;
+/** Replaces a node's fields, then drops next edges from exits it no longer has. */
+export declare function updateNode(flow: WorkflowFlow, id: string, patch: Partial<WorkflowNode>): WorkflowFlow;
+/** Moves a node; positions are part of the document. */
+export declare function moveNode(flow: WorkflowFlow, id: string, at: WorkflowPosition): WorkflowFlow;
+export declare function removeEdge(flow: WorkflowFlow, id: string): WorkflowFlow;
+export declare function updateEdge(flow: WorkflowFlow, id: string, patch: Partial<WorkflowEdge>): WorkflowFlow;
+/** The definition with one flow replaced. */
+export declare function withFlow(definition: WorkflowDefinition, name: string, flow: WorkflowFlow): WorkflowDefinition;
+/** What is selected in the editor: a node or an edge (by `edgeId`) of one flow. */
+export interface WorkflowSelection {
+    type: "node" | "edge";
+    flow: string;
+    id: string;
+}
+export {};