@dypai-ai/workflow-core 0.1.0

package/src/ir/types.ts

@@ -0,0 +1,147 @@
+export const WORKFLOW_IR_VERSION = "workflow-ir.v1" as const;
+
+export type WorkflowIRVersion = typeof WORKFLOW_IR_VERSION;
+
+export type JsonSchema = Record<string, unknown>;
+
+export type SourceLocation = {
+  file?: string;
+  line?: number;
+  column?: number;
+  yamlPath?: string;
+  stepId?: string;
+};
+
+export type WorkflowSourceKind = "flow-ts" | "legacy-yaml" | "studio";
+
+export type WorkflowSource = {
+  kind: WorkflowSourceKind;
+  file: string;
+  compiledAt?: string;
+};
+
+export type RefIR =
+  | { kind: "input"; path: string[] }
+  | { kind: "currentUserId" }
+  | { kind: "step"; stepId: string; path?: string[] }
+  | { kind: "literal"; value: unknown }
+  | { kind: "env"; name: string };
+
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+export type TriggerIR =
+  | { type: "http"; method: HttpMethod }
+  | { type: "schedule"; cron: string }
+  | { type: "webhook"; provider?: string };
+
+export type AuthIR =
+  | { mode: "public" }
+  | { mode: "jwt"; allowedRoles: string[] }
+  | { mode: "api_key" };
+
+export type ResponseIR = {
+  cardinality?: "single" | "many" | "none";
+};
+
+export type ResourceIR = {
+  type: string;
+  name: string;
+  access: "read" | "write" | "readwrite";
+};
+
+export type WorkflowStepIR = {
+  id: string;
+  node: string;
+  operation: string;
+  version: number;
+  config: Record<string, unknown>;
+  refs?: Record<string, RefIR>;
+  outputSchema?: JsonSchema;
+  source?: SourceLocation;
+  return?: boolean;
+};
+
+export type WorkflowEdgeIR = {
+  from: string;
+  to: string;
+};
+
+export type WorkflowIR = {
+  version: WorkflowIRVersion;
+  name: string;
+  source?: WorkflowSource;
+  trigger: TriggerIR;
+  auth: AuthIR;
+  inputSchema: JsonSchema;
+  outputSchema: JsonSchema;
+  response: ResponseIR;
+  steps: WorkflowStepIR[];
+  edges?: WorkflowEdgeIR[];
+  responseMap: Record<string, RefIR>;
+  resources?: ResourceIR[];
+  executionPlan?: string[][];
+};
+
+export type IRDiagnosticSeverity = "error" | "warn";
+
+export type IRDiagnostic = {
+  severity: IRDiagnosticSeverity;
+  rule: string;
+  message: string;
+  fixHint?: string;
+  location?: SourceLocation;
+  path?: string;
+};
+
+export type IRValidationResult = {
+  ok: boolean;
+  diagnostics: IRDiagnostic[];
+  derivedResources?: ResourceIR[];
+  derivedSideEffects?: string[];
+};
+
+export type NodeOperationKey = `${string}@${string}@v${number}`;
+
+export type SideEffectKind =
+  | "db.read"
+  | "db.write"
+  | "email.send"
+  | "http.response";
+
+export type OperationDefinition = {
+  label?: string;
+  docs?: string;
+  inputSchema: JsonSchema;
+  outputSchema: JsonSchema;
+  sideEffects?: SideEffectKind[];
+  resources?: (config: Record<string, unknown>) => ResourceIR[];
+  validate?: (
+    config: Record<string, unknown>,
+    refs: Record<string, RefIR> | undefined,
+  ) => IRDiagnostic[];
+};
+
+export type NodeDefinition = {
+  id: string;
+  version: number;
+  label: string;
+  category: string;
+  operations: Record<string, OperationDefinition>;
+  sideEffects?: SideEffectKind[];
+  permissions?: string[];
+  ui?: Record<string, unknown>;
+  docs?: string;
+  adapters?: Record<string, unknown>;
+};
+
+export type AdapterTarget = "workflow_code.v2" | "engine.ir";
+
+export type NodeAdapterDeclaration = {
+  target: AdapterTarget;
+  implemented: boolean;
+};
+
+export type RegistryLookup = {
+  node: NodeDefinition;
+  operation: OperationDefinition;
+};

package/src/ir/validate.test.ts

@@ -0,0 +1,181 @@
+import { describe, expect, test } from "bun:test";
+import {
+  createBookingWorkflowIR,
+  createBookingWorkflowIRMissingTable,
+  defaultNodeRegistry,
+  formatDiagnosticMessage,
+  formatSourceLocation,
+  minimalValidWorkflowIR,
+  validateWorkflowIR,
+  WORKFLOW_IR_VERSION,
+  type WorkflowIR,
+} from "../index";
+
+describe("validateWorkflowIR", () => {
+  test("accepts minimal valid IR", () => {
+    const result = validateWorkflowIR(minimalValidWorkflowIR());
+    expect(result.ok).toBe(true);
+    expect(result.diagnostics.filter((item) => item.severity === "error")).toHaveLength(0);
+  });
+
+  test("accepts hand-authored create-booking IR", () => {
+    const result = validateWorkflowIR(createBookingWorkflowIR);
+    expect(result.ok).toBe(true);
+    expect(result.derivedResources).toEqual([
+      { type: "postgres_table", name: "public.bookings", access: "write" },
+    ]);
+    expect(result.derivedSideEffects).toContain("db.write");
+    expect(result.derivedSideEffects).toContain("http.response");
+  });
+
+  test("rejects unknown node operation", () => {
+    const workflow: WorkflowIR = {
+      ...minimalValidWorkflowIR(),
+      steps: [
+        {
+          id: "bad",
+          node: "stripe.checkout",
+          operation: "create",
+          version: 1,
+          config: {},
+        },
+        {
+          id: "respond",
+          node: "dypai.flow",
+          operation: "return",
+          version: 1,
+          config: {},
+          return: true,
+        },
+      ],
+    };
+    const result = validateWorkflowIR(workflow);
+    expect(result.ok).toBe(false);
+    expect(result.diagnostics.some((item) => item.rule === "unknown_node_operation")).toBe(true);
+  });
+
+  test("rejects unknown operation on known node", () => {
+    const workflow: WorkflowIR = {
+      ...minimalValidWorkflowIR(),
+      steps: [
+        {
+          id: "bad",
+          node: "dypai.db",
+          operation: "upsert",
+          version: 1,
+          config: { table: "public.items", values: { name: "x" } },
+        },
+        {
+          id: "respond",
+          node: "dypai.flow",
+          operation: "return",
+          version: 1,
+          config: {},
+          return: true,
+        },
+      ],
+    };
+    const result = validateWorkflowIR(workflow);
+    expect(result.ok).toBe(false);
+    expect(result.diagnostics.some((item) => item.rule === "unknown_node_operation")).toBe(true);
+  });
+
+  test("rejects duplicate step ids", () => {
+    const workflow: WorkflowIR = {
+      ...minimalValidWorkflowIR(),
+      steps: [
+        {
+          id: "respond",
+          node: "dypai.flow",
+          operation: "return",
+          version: 1,
+          config: {},
+          return: true,
+        },
+        {
+          id: "respond",
+          node: "dypai.flow",
+          operation: "return",
+          version: 1,
+          config: {},
+          return: true,
+        },
+      ],
+    };
+    const result = validateWorkflowIR(workflow);
+    expect(result.ok).toBe(false);
+    expect(result.diagnostics.some((item) => item.rule === "duplicate_step_id")).toBe(true);
+  });
+
+  test("rejects invalid refs in responseMap", () => {
+    const workflow: WorkflowIR = {
+      ...minimalValidWorkflowIR(),
+      responseMap: {
+        ok: { kind: "step", stepId: "missing-step" },
+      },
+    };
+    const result = validateWorkflowIR(workflow);
+    expect(result.ok).toBe(false);
+    expect(result.diagnostics.some((item) => item.rule === "invalid_ref")).toBe(true);
+  });
+
+  test("allows JWT auth with empty allowedRoles (any authenticated user)", () => {
+    const workflow: WorkflowIR = {
+      ...minimalValidWorkflowIR(),
+      auth: { mode: "jwt", allowedRoles: [] },
+    };
+    const result = validateWorkflowIR(workflow);
+    expect(result.diagnostics.some((item) => item.rule === "jwt_missing_allowed_roles")).toBe(false);
+  });
+
+  test("preserves source maps in diagnostics for create-booking missing table", () => {
+    const result = validateWorkflowIR(createBookingWorkflowIRMissingTable);
+    expect(result.ok).toBe(false);
+    const tableDiagnostic = result.diagnostics.find((item) => item.rule === "db_insert_missing_table");
+    expect(tableDiagnostic).toBeDefined();
+    expect(formatSourceLocation(tableDiagnostic?.location)).toBe("dypai/flows/create-booking.flow.ts:17");
+    expect(formatDiagnosticMessage({
+      message: tableDiagnostic!.message,
+      location: tableDiagnostic!.location,
+    })).toContain("dypai/flows/create-booking.flow.ts:17");
+  });
+});
+
+describe("NodeRegistry v2", () => {
+  test("derives postgres resources for dypai.db.insert", () => {
+    const resources = defaultNodeRegistry.deriveResources("dypai.db", "insert", 1, {
+      table: "public.bookings",
+      values: { name: "Ada" },
+    });
+    expect(resources).toEqual([
+      { type: "postgres_table", name: "public.bookings", access: "write" },
+    ]);
+  });
+
+  test("derives email side effects for dypai.email.send", () => {
+    const effects = defaultNodeRegistry.deriveSideEffects("dypai.email", "send", 1);
+    expect(effects).toContain("email.send");
+  });
+
+  test("lists MVP node operations", () => {
+    const keys = defaultNodeRegistry.listOperationKeys();
+    expect(keys).toContain("dypai.db@query@v1");
+    expect(keys).toContain("dypai.db@insert@v1");
+    expect(keys).toContain("dypai.db@update@v1");
+    expect(keys).toContain("dypai.db@list@v1");
+    expect(keys).toContain("dypai.email@send@v1");
+    expect(keys).toContain("dypai.flow@return@v1");
+  });
+});
+
+describe("WorkflowIR schema helpers", () => {
+  test("detects non-IR payloads", () => {
+    const result = validateWorkflowIR({ version: "legacy" });
+    expect(result.ok).toBe(false);
+    expect(result.diagnostics[0]?.rule).toBe("invalid_workflow_ir");
+  });
+
+  test("requires workflow-ir.v1 version constant", () => {
+    expect(WORKFLOW_IR_VERSION).toBe("workflow-ir.v1");
+  });
+});

package/src/ir/validate.ts

@@ -0,0 +1,365 @@
+import type { NodeRegistry } from "../registry/nodeRegistry";
+import { defaultNodeRegistry, NodeRegistry as NodeRegistryClass } from "../registry/nodeRegistry";
+import type { CapabilityCatalog } from "../capabilities/types";
+import { collectRefs, isRefIR, validateRefIR } from "./refs";
+import {
+  isRecord,
+  isValidEndpointName,
+  isValidHttpMethod,
+  isWorkflowIR,
+  schemaPropertyNames,
+  validateJsonValueAgainstSchema,
+} from "./schema";
+import { stepLocation, withSourceLocation } from "./sourceMap";
+import type {
+  IRDiagnostic,
+  IRValidationResult,
+  RefIR,
+  ResourceIR,
+  SideEffectKind,
+  SourceLocation,
+  WorkflowIR,
+  WorkflowStepIR,
+} from "./types";
+import { WORKFLOW_IR_VERSION } from "./types";
+
+function pushDiagnostic(
+  diagnostics: IRDiagnostic[],
+  diagnostic: IRDiagnostic,
+  location?: SourceLocation,
+): void {
+  diagnostics.push(location ? withSourceLocation(diagnostic, location) : diagnostic);
+}
+
+function sanitizeConfigForSchema(config: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(config)) {
+    if (isRefIR(value)) {
+      out[key] = "__ref__";
+      continue;
+    }
+    if (Array.isArray(value)) {
+      out[key] = value.map((item) => (isRefIR(item) ? "__ref__" : item));
+      continue;
+    }
+    if (isRecord(value)) {
+      out[key] = sanitizeConfigForSchema(value);
+      continue;
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+function validateStepRefs(
+  step: WorkflowStepIR,
+  ctx: { inputProperties: Set<string>; stepIds: Set<string> },
+  workflowSource?: SourceLocation,
+): IRDiagnostic[] {
+  const diagnostics: IRDiagnostic[] = [];
+  const location = stepLocation(workflowSource, step);
+  const refSources: Array<{ ref: RefIR; path: string }> = [];
+
+  if (step.refs) {
+    for (const [name, ref] of Object.entries(step.refs)) {
+      refSources.push({ ref, path: `steps.${step.id}.refs.${name}` });
+    }
+  }
+
+  for (const ref of collectRefs(step.config)) {
+    refSources.push({ ref, path: `steps.${step.id}.config` });
+  }
+
+  for (const { ref, path } of refSources) {
+    const message = validateRefIR(ref, {
+      inputSchemaProperties: ctx.inputProperties,
+      stepIds: ctx.stepIds,
+    }, path);
+    if (message) {
+      pushDiagnostic(diagnostics, {
+        severity: "error",
+        rule: "invalid_ref",
+        message,
+        path,
+      }, location);
+    }
+  }
+
+  return diagnostics;
+}
+
+function validateResponseMap(
+  workflow: WorkflowIR,
+  workflowSource?: SourceLocation,
+): IRDiagnostic[] {
+  const diagnostics: IRDiagnostic[] = [];
+  const outputProperties = schemaPropertyNames(workflow.outputSchema);
+  const stepIds = new Set(workflow.steps.map((step) => step.id));
+  const inputProperties = schemaPropertyNames(workflow.inputSchema);
+
+  for (const [key, ref] of Object.entries(workflow.responseMap)) {
+    const path = `responseMap.${key}`;
+    const location: SourceLocation = {
+      file: workflowSource?.file,
+      yamlPath: workflow.source?.kind === "legacy-yaml"
+        ? `workflow.output.${key}`
+        : undefined,
+    };
+
+    if (!outputProperties.has(key)) {
+      pushDiagnostic(diagnostics, {
+        severity: "error",
+        rule: "response_map_unknown_output_key",
+        message: `responseMap key '${key}' is not declared in outputSchema.properties.`,
+        fixHint: `Add '${key}' to outputSchema.properties or remove it from responseMap.`,
+        path,
+      }, location);
+    }
+
+    const refError = validateRefIR(ref, {
+      inputSchemaProperties: inputProperties,
+      stepIds,
+    }, path);
+    if (refError) {
+      pushDiagnostic(diagnostics, {
+        severity: "error",
+        rule: "invalid_ref",
+        message: refError,
+        path,
+      }, location);
+    }
+  }
+
+  for (const key of outputProperties) {
+    if (!(key in workflow.responseMap)) {
+      pushDiagnostic(diagnostics, {
+        severity: "warn",
+        rule: "output_key_not_mapped",
+        message: `outputSchema declares '${key}' but responseMap does not map it.`,
+        path: `outputSchema.properties.${key}`,
+      }, workflowSource);
+    }
+  }
+
+  return diagnostics;
+}
+
+function countPublicReturnSteps(steps: WorkflowStepIR[]): number {
+  return steps.filter((step) =>
+    step.return === true
+    || (step.node === "dypai.flow" && step.operation === "return"),
+  ).length;
+}
+
+export type ValidateWorkflowOptions = {
+  registry?: NodeRegistry;
+  capabilityCatalog?: CapabilityCatalog;
+};
+
+function resolveRegistry(options?: ValidateWorkflowOptions | NodeRegistry): NodeRegistry {
+  if (options instanceof NodeRegistryClass) return options;
+  if (options?.registry) return options.registry;
+  if (options?.capabilityCatalog) return NodeRegistryClass.withCatalog(options.capabilityCatalog);
+  return defaultNodeRegistry;
+}
+
+export function validateWorkflowIR(
+  workflow: unknown,
+  options?: ValidateWorkflowOptions | NodeRegistry,
+): IRValidationResult {
+  const registry = resolveRegistry(options);
+  const diagnostics: IRDiagnostic[] = [];
+
+  if (!isWorkflowIR(workflow)) {
+    return {
+      ok: false,
+      diagnostics: [{
+        severity: "error",
+        rule: "invalid_workflow_ir",
+        message: "Value is not a WorkflowIR v1 document.",
+        fixHint: `Expected version '${WORKFLOW_IR_VERSION}' with trigger, auth, schemas, steps, and responseMap.`,
+      }],
+    };
+  }
+
+  const workflowSource: SourceLocation | undefined = workflow.source
+    ? { file: workflow.source.file }
+    : undefined;
+
+  if (workflow.version !== WORKFLOW_IR_VERSION) {
+    pushDiagnostic(diagnostics, {
+      severity: "error",
+      rule: "unsupported_version",
+      message: `Unsupported WorkflowIR version '${workflow.version}'.`,
+      fixHint: `Use version '${WORKFLOW_IR_VERSION}'.`,
+      path: "version",
+    }, workflowSource);
+  }
+
+  if (!isValidEndpointName(workflow.name)) {
+    pushDiagnostic(diagnostics, {
+      severity: "error",
+      rule: "invalid_name",
+      message: `Workflow name '${workflow.name}' must be a kebab-case slug.`,
+      fixHint: "Use names like create-booking or list-slots.",
+      path: "name",
+    }, workflowSource);
+  }
+
+  if (workflow.trigger.type === "http") {
+    if (!isValidHttpMethod(workflow.trigger.method)) {
+      pushDiagnostic(diagnostics, {
+        severity: "error",
+        rule: "invalid_http_method",
+        message: `Unsupported HTTP method '${workflow.trigger.method}'.`,
+        fixHint: "Use GET, POST, PUT, PATCH, or DELETE.",
+        path: "trigger.method",
+      }, workflowSource);
+    }
+  } else if (workflow.trigger.type === "schedule") {
+    if (!workflow.trigger.cron?.trim()) {
+      pushDiagnostic(diagnostics, {
+        severity: "error",
+        rule: "schedule_missing_cron",
+        message: "Schedule trigger requires cron.",
+        path: "trigger.cron",
+      }, workflowSource);
+    }
+  }
+
+  const stepIds = new Set<string>();
+  for (const step of workflow.steps) {
+    if (stepIds.has(step.id)) {
+      pushDiagnostic(diagnostics, {
+        severity: "error",
+        rule: "duplicate_step_id",
+        message: `Duplicate step id '${step.id}'.`,
+        path: `steps.${step.id}`,
+      }, stepLocation(workflowSource, step));
+    }
+    stepIds.add(step.id);
+  }
+
+  const inputProperties = schemaPropertyNames(workflow.inputSchema);
+  const derivedResources: ResourceIR[] = [];
+  const derivedSideEffects = new Set<SideEffectKind>();
+
+  for (const step of workflow.steps) {
+    const location = stepLocation(workflowSource, step);
+    const resolved = registry.lookup(step.node, step.operation, step.version);
+
+    if (!resolved) {
+      const nodeDef = registry.getNode(step.node);
+      const availableOps = nodeDef ? Object.keys(nodeDef.operations).sort() : [];
+      pushDiagnostic(diagnostics, {
+        severity: "error",
+        rule: "unknown_node_operation",
+        message: `Step '${step.id}' uses unknown node operation ${step.node}.${step.operation}@v${step.version}.`,
+        fixHint: availableOps.length
+          ? `Available operations for ${step.node}: ${availableOps.join(", ")}`
+          : "Register the node in Node Registry v2 or fix node/operation/version.",
+        path: `steps.${step.id}`,
+      }, location);
+      continue;
+    }
+
+    const schemaIssues = validateJsonValueAgainstSchema(
+      sanitizeConfigForSchema(step.config),
+      resolved.operation.inputSchema,
+      `steps.${step.id}.config`,
+    );
+    for (const issue of schemaIssues) {
+      pushDiagnostic(diagnostics, {
+        severity: "error",
+        rule: "step_config_schema_mismatch",
+        message: `Step '${step.id}' config ${issue.message} at ${issue.path}.`,
+        path: issue.path,
+      }, location);
+    }
+
+    if (resolved.operation.validate) {
+      for (const diagnostic of resolved.operation.validate(step.config, step.refs)) {
+        pushDiagnostic(diagnostics, {
+          ...diagnostic,
+          path: diagnostic.path ?? `steps.${step.id}.config`,
+        }, location);
+      }
+    }
+
+    diagnostics.push(...validateStepRefs(step, {
+      inputProperties,
+      stepIds,
+    }, workflowSource));
+
+    for (const resource of registry.deriveResources(step.node, step.operation, step.version, step.config)) {
+      derivedResources.push(resource);
+    }
+    for (const effect of registry.deriveSideEffects(step.node, step.operation, step.version)) {
+      derivedSideEffects.add(effect);
+    }
+  }
+
+  diagnostics.push(...validateResponseMap(workflow, workflowSource));
+
+  const returnSteps = countPublicReturnSteps(workflow.steps);
+  if (returnSteps === 0) {
+    pushDiagnostic(diagnostics, {
+      severity: "error",
+      rule: "missing_public_return",
+      message: "Workflow must declare exactly one public return step.",
+      fixHint: "Add a dypai.flow.return step with return: true.",
+      path: "steps",
+    }, workflowSource);
+  } else if (returnSteps > 1) {
+    pushDiagnostic(diagnostics, {
+      severity: "error",
+      rule: "multiple_public_returns",
+      message: `Workflow declares ${returnSteps} public return steps; expected exactly one.`,
+      path: "steps",
+    }, workflowSource);
+  }
+
+  if (workflow.edges?.length) {
+    for (const edge of workflow.edges) {
+      if (edge.from !== "$trigger" && !stepIds.has(edge.from)) {
+        pushDiagnostic(diagnostics, {
+          severity: "error",
+          rule: "edge_unknown_from_step",
+          message: `Edge from '${edge.from}' references an unknown step.`,
+          path: "edges",
+        }, workflowSource);
+      }
+      if (!stepIds.has(edge.to)) {
+        pushDiagnostic(diagnostics, {
+          severity: "error",
+          rule: "edge_unknown_to_step",
+          message: `Edge to '${edge.to}' references an unknown step.`,
+          path: "edges",
+        }, workflowSource);
+      }
+    }
+  }
+
+  const hasErrors = diagnostics.some((item) => item.severity === "error");
+  return {
+    ok: !hasErrors,
+    diagnostics,
+    derivedResources,
+    derivedSideEffects: [...derivedSideEffects].sort(),
+  };
+}
+
+export function assertValidWorkflowIR(
+  workflow: unknown,
+  options?: ValidateWorkflowOptions | NodeRegistry,
+): WorkflowIR {
+  const result = validateWorkflowIR(workflow, options);
+  if (!result.ok || !isWorkflowIR(workflow)) {
+    const message = result.diagnostics
+      .filter((item) => item.severity === "error")
+      .map((item) => item.message)
+      .join("\n");
+    throw new Error(message || "Invalid WorkflowIR");
+  }
+  return workflow;
+}

package/src/registry/defineNode.ts

@@ -0,0 +1,19 @@
+import type { IRDiagnostic, NodeDefinition, OperationDefinition } from "../ir/types";
+
+export function defineOperation(definition: OperationDefinition): OperationDefinition {
+  return definition;
+}
+
+export function defineNode(definition: NodeDefinition): NodeDefinition {
+  return definition;
+}
+
+export function operationKey(nodeId: string, operation: string, version: number): string {
+  return `${nodeId}@${operation}@v${version}`;
+}
+
+export function mergeDiagnostics(
+  ...groups: Array<IRDiagnostic[] | undefined>
+): IRDiagnostic[] {
+  return groups.flatMap((group) => group ?? []);
+}