@dypai-ai/workflow-core 0.1.0

package/src/fixtures/createBooking.flow.ts

@@ -0,0 +1,64 @@
+import type { FlowDefinition } from "../adapters/flowDefinitionToIr";
+
+export const createBookingFlowDefinition: FlowDefinition = {
+  name: "create-booking",
+  source: {
+    kind: "flow-ts",
+    file: "dypai/flows/create-booking.flow.ts",
+  },
+  trigger: { type: "http", method: "POST" },
+  auth: { mode: "public" },
+  input: {
+    type: "object",
+    required: ["name", "email", "date"],
+    additionalProperties: false,
+    properties: {
+      name: { type: "string" },
+      email: { type: "string", format: "email" },
+      date: { type: "string", format: "date" },
+    },
+  },
+  output: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      booking: {
+        type: "object",
+        properties: {
+          id: { type: "string" },
+          name: { type: "string" },
+          email: { type: "string" },
+          date: { type: "string" },
+        },
+      },
+    },
+  },
+  response: { cardinality: "single" },
+  steps: [
+    {
+      id: "booking",
+      call: "db.insert",
+      config: {
+        table: "public.bookings",
+        values: {
+          name: { kind: "input", path: ["name"] },
+          email: { kind: "input", path: ["email"] },
+          date: { kind: "input", path: ["date"] },
+        },
+        returning: ["id", "name", "email", "date"],
+      },
+      source: {
+        file: "dypai/flows/create-booking.flow.ts",
+        line: 17,
+        stepId: "booking",
+      },
+    },
+  ],
+  returns: {
+    booking: { kind: "step", stepId: "booking", path: ["row"] },
+  },
+  edges: [
+    { from: "$trigger", to: "booking" },
+    { from: "booking", to: "return" },
+  ],
+};

package/src/fixtures/createBooking.ir.ts

@@ -0,0 +1,103 @@
+import type { WorkflowIR } from "../ir/types";
+import { WORKFLOW_IR_VERSION } from "../ir/types";
+
+export const createBookingWorkflowIR: WorkflowIR = {
+  version: WORKFLOW_IR_VERSION,
+  name: "create-booking",
+  source: {
+    kind: "flow-ts",
+    file: "dypai/flows/create-booking.flow.ts",
+    compiledAt: "2026-05-21T00:00:00.000Z",
+  },
+  trigger: { type: "http", method: "POST" },
+  auth: { mode: "public" },
+  inputSchema: {
+    type: "object",
+    required: ["name", "email", "date"],
+    additionalProperties: false,
+    properties: {
+      name: { type: "string" },
+      email: { type: "string", format: "email" },
+      date: { type: "string", format: "date" },
+    },
+  },
+  outputSchema: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      booking: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          id: { type: "string" },
+          name: { type: "string" },
+          email: { type: "string" },
+          date: { type: "string" },
+        },
+      },
+    },
+  },
+  response: { cardinality: "single" },
+  steps: [
+    {
+      id: "booking",
+      node: "dypai.db",
+      operation: "insert",
+      version: 1,
+      config: {
+        table: "public.bookings",
+        values: {
+          name: { kind: "input", path: ["name"] },
+          email: { kind: "input", path: ["email"] },
+          date: { kind: "input", path: ["date"] },
+        },
+        returning: ["id", "name", "email", "date"],
+      },
+      source: {
+        file: "dypai/flows/create-booking.flow.ts",
+        line: 17,
+        stepId: "booking",
+      },
+    },
+    {
+      id: "respond",
+      node: "dypai.flow",
+      operation: "return",
+      version: 1,
+      config: {},
+      return: true,
+      source: {
+        file: "dypai/flows/create-booking.flow.ts",
+        line: 28,
+        stepId: "respond",
+      },
+    },
+  ],
+  edges: [
+    { from: "$trigger", to: "booking" },
+    { from: "booking", to: "respond" },
+  ],
+  responseMap: {
+    booking: { kind: "step", stepId: "booking", path: ["row"] },
+  },
+};
+
+export const createBookingWorkflowIRMissingTable: WorkflowIR = {
+  ...createBookingWorkflowIR,
+  steps: [
+    {
+      ...createBookingWorkflowIR.steps[0],
+      config: {
+        values: {
+          name: { kind: "input", path: ["name"] },
+        },
+      },
+      source: {
+        file: "dypai/flows/create-booking.flow.ts",
+        line: 17,
+        stepId: "booking",
+      },
+    },
+    createBookingWorkflowIR.steps[1],
+  ],
+};

package/src/fixtures/listBookings.ir.ts

@@ -0,0 +1,61 @@
+import type { WorkflowIR } from "../ir/types";
+import { WORKFLOW_IR_VERSION } from "../ir/types";
+
+export const listBookingsWorkflowIR: WorkflowIR = {
+  version: WORKFLOW_IR_VERSION,
+  name: "list-bookings",
+  source: {
+    kind: "flow-ts",
+    file: "dypai/flows/list-bookings.flow.ts",
+  },
+  trigger: { type: "http", method: "GET" },
+  auth: { mode: "jwt", allowedRoles: ["authenticated"] },
+  inputSchema: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      limit: { type: "integer" },
+      offset: { type: "integer" },
+    },
+  },
+  outputSchema: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      bookings: { type: "array" },
+      limit: { type: "integer" },
+      offset: { type: "integer" },
+    },
+  },
+  response: { cardinality: "many" },
+  steps: [
+    {
+      id: "bookings",
+      node: "dypai.db",
+      operation: "list",
+      version: 1,
+      config: {
+        table: "public.bookings",
+        where: {
+          user_id: { kind: "currentUserId" },
+        },
+        orderBy: "created_at DESC",
+        limit: { kind: "input", path: ["limit"] },
+        offset: { kind: "input", path: ["offset"] },
+      },
+    },
+    {
+      id: "respond",
+      node: "dypai.flow",
+      operation: "return",
+      version: 1,
+      config: {},
+      return: true,
+    },
+  ],
+  responseMap: {
+    bookings: { kind: "step", stepId: "bookings", path: ["rows"] },
+    limit: { kind: "input", path: ["limit"] },
+    offset: { kind: "input", path: ["offset"] },
+  },
+};

package/src/index.ts

@@ -0,0 +1,172 @@
+export {
+  WORKFLOW_IR_VERSION,
+  type AuthIR,
+  type IRDiagnostic,
+  type IRValidationResult,
+  type JsonSchema,
+  type NodeDefinition,
+  type OperationDefinition,
+  type RefIR,
+  type RegistryLookup,
+  type ResourceIR,
+  type ResponseIR,
+  type SideEffectKind,
+  type SourceLocation,
+  type TriggerIR,
+  type WorkflowEdgeIR,
+  type WorkflowIR,
+  type WorkflowIRVersion,
+  type WorkflowSource,
+  type WorkflowStepIR,
+} from "./ir/types";
+
+export {
+  collectRefs,
+  describeRef,
+  isRefIR,
+  refToPlaceholder,
+  validateRefIR,
+  type RefValidationContext,
+} from "./ir/refs";
+
+export {
+  formatDiagnosticMessage,
+  formatSourceLocation,
+  stepLocation,
+  withSourceLocation,
+} from "./ir/sourceMap";
+
+export {
+  isRecord,
+  isValidEndpointName,
+  isValidHttpMethod,
+  isWorkflowIR,
+  minimalValidWorkflowIR,
+  schemaPropertyNames,
+  schemaRequired,
+  validateJsonValueAgainstSchema,
+  type JsonSchemaIssue,
+} from "./ir/schema";
+
+export {
+  assertValidWorkflowIR,
+  validateWorkflowIR,
+  type ValidateWorkflowOptions,
+} from "./ir/validate";
+
+export {
+  defineNode,
+  defineOperation,
+  mergeDiagnostics,
+  operationKey,
+} from "./registry/defineNode";
+
+export {
+  defaultNodeRegistry,
+  dypaiDbNode,
+  dypaiEmailNode,
+  dypaiFlowNode,
+  legacyWorkflowNode,
+  NodeRegistry,
+} from "./registry/nodeRegistry";
+
+export {
+  createBookingWorkflowIR,
+  createBookingWorkflowIRMissingTable,
+} from "./fixtures/createBooking.ir";
+
+export {
+  pendingAdapters,
+  type AdapterDeclaration,
+  type AdapterRegistry,
+} from "./adapters/types";
+
+export type {
+  AdaptWorkflowCodeResult,
+  AdapterResult,
+  EngineWorkflowEdge,
+  EngineWorkflowNode,
+  ImportYamlResult,
+  WorkflowCodeV2,
+} from "./adapters/workflowCodeTypes";
+
+export {
+  legacyYamlDocumentToIr,
+  legacyYamlToIr,
+} from "./adapters/legacyYamlToIr";
+
+export {
+  flowDefinitionToIr,
+  resolveFlowAlias,
+  type FlowDefinition,
+  type FlowStepDefinition,
+} from "./adapters/flowDefinitionToIr";
+
+export {
+  irToWorkflowCodeV2,
+  stableStringifyWorkflowCode,
+} from "./adapters/irToWorkflowCodeV2";
+
+export {
+  refToLegacyPlaceholder,
+  responseMapToComposeFields,
+  serializeConfig,
+  serializeConfigValue,
+} from "./adapters/refToLegacyPlaceholder";
+
+export {
+  buildInsertSql,
+  buildListSql,
+  buildUpdateSql,
+} from "./adapters/sqlBuilders";
+
+export {
+  composeFieldsToResponseMap,
+  mapObjectPlaceholdersToRefs,
+  placeholderToRef,
+} from "./adapters/placeholderToRef";
+
+export {
+  authFromLegacyTrigger,
+  normalizeHttpMethod,
+  responseCardinalityFromLegacy,
+  triggerFromLegacyDoc,
+  triggersToEngineConfig,
+} from "./adapters/triggers";
+
+export {
+  createBookingFlowDefinition,
+} from "./fixtures/createBooking.flow";
+
+export {
+  listBookingsWorkflowIR,
+} from "./fixtures/listBookings.ir";
+
+export type {
+  CapabilityCallResolution,
+  CapabilityCatalog,
+  CapabilityGroupJson,
+  CapabilityLookup,
+  CapabilityOperationJson,
+  EngineBindingJson,
+} from "./capabilities";
+
+export {
+  CapabilityRegistry,
+  createCapabilityRegistry,
+  flattenCapabilityOperations,
+  generateCapabilityBrief,
+  generateCapabilityBriefFromCatalog,
+  isCapabilityCatalog,
+  mergeNodeRegistryDefinitions,
+  nodeDefinitionsFromCatalog,
+  resolveCapabilityCall,
+} from "./capabilities";
+
+export type { AdaptWorkflowCodeOptions } from "./adapters/irToWorkflowCodeV2";
+export type { FlowCompileContext } from "./adapters/flowDefinitionToIr";
+
+export {
+  applyParameterMap,
+  buildEngineParameters,
+} from "./adapters/engineBinding";

package/src/ir/refs.ts

@@ -0,0 +1,103 @@
+import type { RefIR } from "./types";
+
+const REF_KINDS = new Set(["input", "currentUserId", "step", "literal", "env"]);
+
+export function isRefIR(value: unknown): value is RefIR {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const kind = (value as Record<string, unknown>).kind;
+  return typeof kind === "string" && REF_KINDS.has(kind);
+}
+
+export function refToPlaceholder(ref: RefIR): string {
+  switch (ref.kind) {
+    case "input":
+      return `\${input.${ref.path.join(".")}}`;
+    case "currentUserId":
+      return "${current_user_id}";
+    case "step":
+      return ref.path?.length
+        ? `\${vars.${ref.stepId}.${ref.path.join(".")}}`
+        : `\${vars.${ref.stepId}}`;
+    case "literal":
+      return typeof ref.value === "string" ? ref.value : JSON.stringify(ref.value);
+    case "env":
+      return `\${env.${ref.name}}`;
+    default:
+      return "${unknown}";
+  }
+}
+
+export function describeRef(ref: RefIR): string {
+  switch (ref.kind) {
+    case "input":
+      return `input.${ref.path.join(".")}`;
+    case "currentUserId":
+      return "currentUser.id";
+    case "step":
+      return ref.path?.length
+        ? `steps.${ref.stepId}.${ref.path.join(".")}`
+        : `steps.${ref.stepId}`;
+    case "literal":
+      return `literal(${JSON.stringify(ref.value)})`;
+    case "env":
+      return `env.${ref.name}`;
+    default:
+      return "unknown ref";
+  }
+}
+
+export function collectRefs(value: unknown, out: RefIR[] = []): RefIR[] {
+  if (isRefIR(value)) {
+    out.push(value);
+    return out;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) collectRefs(item, out);
+    return out;
+  }
+  if (value && typeof value === "object") {
+    for (const nested of Object.values(value as Record<string, unknown>)) {
+      collectRefs(nested, out);
+    }
+  }
+  return out;
+}
+
+export type RefValidationContext = {
+  inputSchemaProperties: Set<string>;
+  stepIds: Set<string>;
+};
+
+export function validateRefIR(
+  ref: RefIR,
+  ctx: RefValidationContext,
+  path: string,
+): string | null {
+  switch (ref.kind) {
+    case "input": {
+      if (!ref.path.length) return `${path}: input ref requires at least one path segment`;
+      const root = ref.path[0];
+      if (!ctx.inputSchemaProperties.has(root)) {
+        return `${path}: input ref '${ref.path.join(".")}' is not declared in inputSchema`;
+      }
+      return null;
+    }
+    case "currentUserId":
+      return null;
+    case "step": {
+      if (!ref.stepId.trim()) return `${path}: step ref requires stepId`;
+      if (!ctx.stepIds.has(ref.stepId)) {
+        return `${path}: step ref '${ref.stepId}' does not match any workflow step`;
+      }
+      return null;
+    }
+    case "literal":
+      return null;
+    case "env": {
+      if (!ref.name.trim()) return `${path}: env ref requires name`;
+      return null;
+    }
+    default:
+      return `${path}: unknown ref kind`;
+  }
+}

package/src/ir/schema.ts

@@ -0,0 +1,149 @@
+import { WORKFLOW_IR_VERSION } from "./types";
+import type { JsonSchema, WorkflowIR } from "./types";
+
+const ENDPOINT_NAME_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const HTTP_METHODS = new Set(["GET", "POST", "PUT", "PATCH", "DELETE"]);
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+export function isWorkflowIR(value: unknown): value is WorkflowIR {
+  if (!isRecord(value)) return false;
+  return value.version === WORKFLOW_IR_VERSION
+    && typeof value.name === "string"
+    && isRecord(value.trigger)
+    && isRecord(value.auth)
+    && isRecord(value.inputSchema)
+    && isRecord(value.outputSchema)
+    && isRecord(value.response)
+    && Array.isArray(value.steps)
+    && isRecord(value.responseMap);
+}
+
+export function isValidEndpointName(name: string): boolean {
+  return ENDPOINT_NAME_PATTERN.test(name);
+}
+
+export function isValidHttpMethod(method: string): method is "GET" | "POST" | "PUT" | "PATCH" | "DELETE" {
+  return HTTP_METHODS.has(method);
+}
+
+export function schemaPropertyNames(schema: JsonSchema): Set<string> {
+  const properties = schema.properties;
+  if (!isRecord(properties)) return new Set();
+  return new Set(Object.keys(properties));
+}
+
+export function schemaRequired(schema: JsonSchema): string[] {
+  const required = schema.required;
+  if (!Array.isArray(required)) return [];
+  return required.filter((item): item is string => typeof item === "string");
+}
+
+export type JsonSchemaIssue = {
+  path: string;
+  message: string;
+};
+
+export function validateJsonValueAgainstSchema(
+  value: unknown,
+  schema: JsonSchema,
+  path = "$",
+): JsonSchemaIssue[] {
+  const issues: JsonSchemaIssue[] = [];
+
+  if (schema.const !== undefined && value !== schema.const) {
+    issues.push({ path, message: `expected const ${JSON.stringify(schema.const)}` });
+    return issues;
+  }
+
+  const declaredType = typeof schema.type === "string" ? schema.type : undefined;
+  if (declaredType === "object") {
+    if (!isRecord(value)) {
+      issues.push({ path, message: "expected object" });
+      return issues;
+    }
+    for (const key of schemaRequired(schema)) {
+      if (!(key in value)) {
+        issues.push({ path: `${path}.${key}`, message: "required property is missing" });
+      }
+    }
+    const properties = isRecord(schema.properties) ? schema.properties : {};
+    for (const [key, propertySchema] of Object.entries(properties)) {
+      if (!(key in value)) continue;
+      if (!isRecord(propertySchema)) continue;
+      issues.push(...validateJsonValueAgainstSchema(value[key], propertySchema, `${path}.${key}`));
+    }
+    if (schema.additionalProperties === false) {
+      for (const key of Object.keys(value)) {
+        if (!(key in properties)) {
+          issues.push({ path: `${path}.${key}`, message: "additional property is not allowed" });
+        }
+      }
+    }
+    return issues;
+  }
+
+  if (declaredType === "array") {
+    if (!Array.isArray(value)) {
+      issues.push({ path, message: "expected array" });
+      return issues;
+    }
+    const items = isRecord(schema.items) ? schema.items : null;
+    if (items) {
+      value.forEach((item, index) => {
+        issues.push(...validateJsonValueAgainstSchema(item, items, `${path}[${index}]`));
+      });
+    }
+    return issues;
+  }
+
+  if (declaredType === "string") {
+    if (typeof value !== "string") issues.push({ path, message: "expected string" });
+    return issues;
+  }
+
+  if (declaredType === "number" || declaredType === "integer") {
+    if (typeof value !== "number" || Number.isNaN(value)) {
+      issues.push({ path, message: `expected ${declaredType}` });
+    }
+    return issues;
+  }
+
+  if (declaredType === "boolean") {
+    if (typeof value !== "boolean") issues.push({ path, message: "expected boolean" });
+    return issues;
+  }
+
+  return issues;
+}
+
+export function minimalValidWorkflowIR(): WorkflowIR {
+  return {
+    version: WORKFLOW_IR_VERSION,
+    name: "ping",
+    trigger: { type: "http", method: "GET" },
+    auth: { mode: "public" },
+    inputSchema: { type: "object", properties: {} },
+    outputSchema: {
+      type: "object",
+      additionalProperties: false,
+      properties: { ok: { type: "boolean" } },
+    },
+    response: { cardinality: "single" },
+    steps: [
+      {
+        id: "respond",
+        node: "dypai.flow",
+        operation: "return",
+        version: 1,
+        config: {},
+        return: true,
+      },
+    ],
+    responseMap: {
+      ok: { kind: "literal", value: true },
+    },
+  };
+}

package/src/ir/sourceMap.ts

@@ -0,0 +1,59 @@
+import type { IRDiagnostic, SourceLocation } from "./types";
+
+export function formatSourceLocation(location: SourceLocation | undefined): string | undefined {
+  if (!location) return undefined;
+  if (location.file && location.line) {
+    const column = location.column ? `:${location.column}` : "";
+    return `${location.file}:${location.line}${column}`;
+  }
+  if (location.file && location.yamlPath) {
+    return `${location.file} ${location.yamlPath}`;
+  }
+  if (location.yamlPath) return location.yamlPath;
+  if (location.file) return location.file;
+  if (location.stepId) return `step "${location.stepId}"`;
+  return undefined;
+}
+
+export function diagnosticLocation(
+  base: SourceLocation | undefined,
+  stepSource?: SourceLocation,
+): SourceLocation | undefined {
+  return {
+    ...base,
+    ...stepSource,
+    file: stepSource?.file ?? base?.file,
+    line: stepSource?.line ?? base?.line,
+    column: stepSource?.column ?? base?.column,
+    yamlPath: stepSource?.yamlPath ?? base?.yamlPath,
+    stepId: stepSource?.stepId ?? base?.stepId,
+  };
+}
+
+export function formatDiagnosticMessage(
+  diagnostic: Pick<IRDiagnostic, "message" | "location">,
+): string {
+  const where = formatSourceLocation(diagnostic.location);
+  return where ? `${where}\n${diagnostic.message}` : diagnostic.message;
+}
+
+export function withSourceLocation(
+  diagnostic: IRDiagnostic,
+  location: SourceLocation | undefined,
+): IRDiagnostic {
+  if (!location) return diagnostic;
+  return {
+    ...diagnostic,
+    location: diagnosticLocation(diagnostic.location, location),
+  };
+}
+
+export function stepLocation(
+  workflowSource: SourceLocation | undefined,
+  step: { id: string; source?: SourceLocation },
+): SourceLocation {
+  return diagnosticLocation(workflowSource, {
+    stepId: step.id,
+    ...step.source,
+  }) ?? { stepId: step.id };
+}