@octaviaflow/flow-rules 0.4.0 → 0.6.0

package/dist/index.cjs

@@ -47,12 +47,15 @@ __export(exports_src, {
   ConditionConfig: () => ConditionConfig,
   DATABASE_CONNECTOR_IDS: () => DATABASE_CONNECTOR_IDS,
   DebugConfig: () => DebugConfig,
+  EdgeType: () => EdgeType,
   EmailConfig: () => EmailConfig,
   FieldType: () => FieldType,
   ForEachConfig: () => ForEachConfig,
   JoinType: () => JoinType,
   LogicalOperator: () => LogicalOperator,
+  MAX_STEP_CONFIG_BYTES: () => MAX_STEP_CONFIG_BYTES,
   ManualTriggerConfig: () => ManualTriggerConfig,
+  NodeStatus: () => NodeStatus,
   QueryMode: () => QueryMode,
   QueryType: () => QueryType,
   STORAGE_CONNECTOR_IDS: () => STORAGE_CONNECTOR_IDS,
@@ -64,7 +67,10 @@ __export(exports_src, {
   buildPathOptions: () => buildPathOptions,
   collectArrayPaths: () => collectArrayPaths,
   collectArrayPathsFromSample: () => collectArrayPathsFromSample,
+  configErrors: () => configErrors,
   emailDefinition: () => emailDefinition,
+  flattenNestedWorkflow: () => flattenNestedWorkflow,
+  generateConnectionsFromSteps: () => generateConnectionsFromSteps,
   generateEdgeId: () => generateEdgeId,
   generateStepId: () => generateStepId,
   generateUUIDv4: () => generateUUIDv4,
@@ -81,8 +87,14 @@ __export(exports_src, {
   migrateDelayConfig: () => migrateDelayConfig,
   queryDefinition: () => queryDefinition,
   storageConfigKeys: () => storageConfigKeys,
+  transformConnectionToEdge: () => transformConnectionToEdge,
+  transformFlowToWorkflow: () => transformFlowToWorkflow,
+  transformStepToNode: () => transformStepToNode,
   validateEdge: () => validateEdge,
+  validateFlowData: () => validateFlowData,
   validateNode: () => validateNode,
+  validateStepConfig: () => validateStepConfig,
+  validateStepConfigs: () => validateStepConfigs,
   validateWorkflow: () => validateWorkflow
 });
 module.exports = __toCommonJS(exports_src);
@@ -3781,3 +3793,462 @@ function storageConfigKeys() {
   }
   return [...keys];
 }
+// src/catalog/workflow.ts
+var NodeStatus;
+((NodeStatus) => {
+  NodeStatus["Idle"] = "idle";
+  NodeStatus["Running"] = "running";
+  NodeStatus["Success"] = "success";
+  NodeStatus["Error"] = "error";
+  NodeStatus["Warning"] = "warning";
+  NodeStatus["Disabled"] = "disabled";
+})(NodeStatus ||= {});
+var EdgeType;
+((EdgeType) => {
+  EdgeType["Default"] = "default";
+  EdgeType["Conditional"] = "conditional";
+  EdgeType["Loop"] = "loop";
+  EdgeType["Error"] = "error";
+})(EdgeType ||= {});
+// src/rules/flattenNestedWorkflow.ts
+function workflowIsNested(workflow) {
+  const stack = [...workflow.steps];
+  while (stack.length > 0) {
+    const s = stack.pop();
+    if (s.branches && Object.keys(s.branches).length > 0)
+      return true;
+  }
+  return false;
+}
+function flattenNestedWorkflow(workflow) {
+  if (!workflowIsNested(workflow))
+    return workflow;
+  const flatSteps = [];
+  const flatConns = [...workflow.connections];
+  const groups = [];
+  const walk = (steps, parentIdForSubflow) => {
+    for (const step of steps) {
+      const { branches, ...rest } = step;
+      const flatStep = {
+        ...rest,
+        ...parentIdForSubflow ? { parentId: parentIdForSubflow } : {}
+      };
+      flatSteps.push(flatStep);
+      if (!branches)
+        continue;
+      if (branches.body && step.type === "group") {
+        const body = branches.body;
+        groups.push({
+          group: flatStep,
+          bodyStepIds: body.steps.map((s) => s.id),
+          bodyConnections: body.connections
+        });
+        for (const c of body.connections)
+          flatConns.push(c);
+        walk(body.steps, step.id);
+      }
+      for (const branchKey of Object.keys(branches)) {
+        if (branchKey === "body" && step.type === "group")
+          continue;
+        const sub = branches[branchKey];
+        if (!sub)
+          continue;
+        for (const c of sub.connections)
+          flatConns.push(c);
+        walk(sub.steps, parentIdForSubflow);
+      }
+    }
+  };
+  walk(workflow.steps, undefined);
+  for (const g of groups) {
+    if (g.bodyStepIds.length === 0)
+      continue;
+    const bodyIdSet = new Set(g.bodyStepIds);
+    const inDeg = new Map;
+    const outDeg = new Map;
+    for (const id of g.bodyStepIds) {
+      inDeg.set(id, 0);
+      outDeg.set(id, 0);
+    }
+    for (const c of g.bodyConnections) {
+      if (bodyIdSet.has(c.sourceStepId)) {
+        outDeg.set(c.sourceStepId, (outDeg.get(c.sourceStepId) ?? 0) + 1);
+      }
+      if (bodyIdSet.has(c.targetStepId)) {
+        inDeg.set(c.targetStepId, (inDeg.get(c.targetStepId) ?? 0) + 1);
+      }
+    }
+    const roots = g.bodyStepIds.filter((id) => (inDeg.get(id) ?? 0) === 0);
+    const leaves = g.bodyStepIds.filter((id) => (outDeg.get(id) ?? 0) === 0);
+    for (const rootId of roots) {
+      flatConns.push({
+        id: `synth-inner-in-${g.group.id}-${rootId}`,
+        sourceStepId: g.group.id,
+        targetStepId: rootId,
+        sourcePort: "_inner_in"
+      });
+    }
+    for (const leafId of leaves) {
+      flatConns.push({
+        id: `synth-inner-out-${leafId}-${g.group.id}`,
+        sourceStepId: leafId,
+        targetStepId: g.group.id,
+        targetPort: "_inner_out"
+      });
+    }
+  }
+  return { ...workflow, steps: flatSteps, connections: flatConns };
+}
+
+// src/rules/flowShape.ts
+function transformStepToNode(step) {
+  const stepType = step.type;
+  const stepActionDefId = step.actionDefinitionId ?? "";
+  const nodeType = stepType === "trigger" ? "trigger" : stepType === "group" || stepActionDefId === "group" ? "group" : "action";
+  let nodeStatus = "idle" /* Idle */;
+  switch (step.status?.toLowerCase()) {
+    case "running":
+    case "executing":
+      nodeStatus = "running" /* Running */;
+      break;
+    case "completed":
+    case "success":
+      nodeStatus = "success" /* Success */;
+      break;
+    case "failed":
+    case "error":
+      nodeStatus = "error" /* Error */;
+      break;
+    case "pending":
+    case "waiting":
+      nodeStatus = "idle" /* Idle */;
+      break;
+    default:
+      nodeStatus = "idle" /* Idle */;
+  }
+  const position = step.position || { x: step.position_x || 0, y: step.position_y || 0 };
+  const posX = typeof position === "object" && position !== null && "x" in position ? position.x : step.position_x || 0;
+  const posY = typeof position === "object" && position !== null && "y" in position ? position.y : step.position_y || 0;
+  const config = step.config || {};
+  const configData = config.data || config || {};
+  const derivedFromName = step.name ? step.name.toLowerCase().replace(/\s+/g, "_") : undefined;
+  const resolvedActionDefinitionId = step.actionDefinitionId || config.connector_id || step.connector_id || derivedFromName || step.type;
+  const actionDef = getActionById(resolvedActionDefinitionId);
+  const node = {
+    id: step.id,
+    type: nodeType,
+    actionDefinitionId: resolvedActionDefinitionId,
+    actionDefinition: actionDef,
+    label: step.label || step.name,
+    description: step.description || config.description || actionDef?.description || "",
+    icon: actionDef?.icon ?? getIconForStepType(step.type),
+    position: {
+      x: posX,
+      y: posY
+    },
+    ...step.parentId ? { parentId: step.parentId } : {},
+    ...step.extent ? { extent: step.extent } : {},
+    ...step.disabled ? { disabled: true } : {},
+    ...step.dimensions && nodeType === "group" ? { dimensions: step.dimensions } : nodeType === "group" ? { dimensions: { width: 480, height: 240 } } : {},
+    config: {
+      ...configData,
+      timeout: step.timeout_seconds,
+      retryPolicy: step.retry_policy,
+      notes: step.notes,
+      tags: step.tags,
+      stepCount: step.step_count
+    },
+    ports: {
+      input: nodeType === "action" || nodeType === "group" ? [
+        {
+          id: `${step.id}-input`,
+          type: "input",
+          position: "top",
+          connected: false
+        }
+      ] : [],
+      output: (() => {
+        if (resolvedActionDefinitionId === "condition") {
+          return [
+            { id: `${step.id}_output_true`, type: "output", position: "bottom", label: "True", connected: false },
+            { id: `${step.id}_output_false`, type: "output", position: "bottom", label: "False", connected: false }
+          ];
+        }
+        if (resolvedActionDefinitionId === "for_each" || resolvedActionDefinitionId === "for-each") {
+          return [
+            { id: `${step.id}_output_each`, type: "output", position: "bottom", label: "Each", connected: false },
+            { id: `${step.id}_output_done`, type: "output", position: "bottom", label: "Done", connected: false }
+          ];
+        }
+        if (resolvedActionDefinitionId === "group") {
+          return [
+            { id: `${step.id}_output_0`, type: "output", position: "bottom", connected: false }
+          ];
+        }
+        return [
+          { id: `${step.id}-output`, type: "output", position: "bottom", connected: false }
+        ];
+      })()
+    },
+    configStatus: step.configStatus || undefined,
+    ...step.outputSchema ? { outputSchema: step.outputSchema } : {},
+    status: nodeStatus,
+    selected: false,
+    dragging: false,
+    isValid: step.configStatus ? step.configStatus === "valid" : true,
+    expanded: step.expanded,
+    minimized: false,
+    locked: false,
+    createdAt: step.created_at || new Date().toISOString(),
+    updatedAt: step.updated_at || new Date().toISOString()
+  };
+  return node;
+}
+function transformConnectionToEdge(connection) {
+  const sourceStepId = connection.sourceStepId || connection.source_step_id;
+  const targetStepId = connection.targetStepId || connection.target_step_id;
+  const sourcePort = connection.sourcePort || connection.source_port || `${sourceStepId}-output`;
+  const targetPort = connection.targetPort || connection.target_port || `${targetStepId}-input`;
+  let edgeType = "default" /* Default */;
+  if (connection.type === "success" || connection.type === "failure") {
+    edgeType = "conditional" /* Conditional */;
+  }
+  return {
+    id: connection.id,
+    source: sourceStepId,
+    target: targetStepId,
+    sourcePort,
+    targetPort,
+    type: edgeType,
+    label: connection.label,
+    selected: false,
+    animated: false,
+    createdAt: new Date().toISOString()
+  };
+}
+function generateConnectionsFromSteps(steps) {
+  const connections = [];
+  const sortedSteps = [...steps].sort((a, b) => a.step_count - b.step_count);
+  for (let i = 0;i < sortedSteps.length - 1; i++) {
+    const sourceStep = sortedSteps[i];
+    const targetStep = sortedSteps[i + 1];
+    connections.push({
+      id: `${sourceStep.id}-${targetStep.id}`,
+      source_step_id: sourceStep.id,
+      target_step_id: targetStep.id,
+      source_port: `${sourceStep.id}-output`,
+      target_port: `${targetStep.id}-input`,
+      type: "default"
+    });
+  }
+  return connections;
+}
+function getIconForStepType(type) {
+  const iconMap = {
+    trigger: "PlayOutline",
+    transform: "Transform",
+    action: "Application",
+    condition: "DecisionTree",
+    loop: "Repeat"
+  };
+  return iconMap[type] || "Application";
+}
+function transformFlowToWorkflow(flow) {
+  const flatWorkflow = flattenNestedWorkflow(flow.workflow);
+  const nodes = flatWorkflow.steps.map((step) => transformStepToNode(step));
+  let connections = flatWorkflow.connections;
+  if (connections === undefined || connections === null) {
+    connections = generateConnectionsFromSteps(flatWorkflow.steps);
+  } else {
+    connections = connections || [];
+  }
+  const edges = connections.map((conn, index) => {
+    if (!conn.id) {
+      conn.id = `edge-${conn.source_step_id}-${conn.target_step_id}-${index}`;
+    }
+    return transformConnectionToEdge(conn);
+  });
+  edges.forEach((edge) => {
+    const sourceNode = nodes.find((n) => n.id === edge.source);
+    const targetNode = nodes.find((n) => n.id === edge.target);
+    if (sourceNode) {
+      const port = sourceNode.ports.output.find((p) => p.id === edge.sourcePort);
+      if (port)
+        port.connected = true;
+    }
+    if (targetNode) {
+      const port = targetNode.ports.input.find((p) => p.id === edge.targetPort);
+      if (port)
+        port.connected = true;
+    }
+  });
+  return {
+    id: flow.workflow.id,
+    name: flow.workflow.name,
+    description: flow.workflow.description,
+    nodes,
+    edges,
+    workflowHistory: flow.workflowHistory || []
+  };
+}
+function validateFlowData(flow) {
+  if (!flow || typeof flow !== "object")
+    return false;
+  const f = flow;
+  return typeof f.id === "string" && typeof f.name === "string" && f.workflow !== undefined && typeof f.workflow === "object" && f.workflow !== null && Array.isArray(f.workflow.steps);
+}
+// src/rules/configSafety.ts
+var MAX_STEP_CONFIG_BYTES = 256 * 1024;
+var FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+var MAX_DEPTH = 12;
+function typeMatches(field, value) {
+  if (value === null || value === undefined || value === "")
+    return true;
+  switch (field.type) {
+    case "number" /* Number */:
+      return typeof value === "number" || typeof value === "string" && value.trim() !== "" && !Number.isNaN(Number(value));
+    case "boolean" /* Boolean */:
+      return typeof value === "boolean" || value === "true" || value === "false";
+    case "array" /* Array */:
+    case "multi_select" /* MultiSelect */:
+      return Array.isArray(value);
+    case "object" /* Object */:
+    case "mapping" /* Mapping */:
+      return typeof value === "object" && !Array.isArray(value);
+    case "string" /* String */:
+    case "code" /* Code */:
+    case "expression" /* Expression */:
+    case "select" /* Select */:
+    case "connection" /* Connection */:
+    case "secret" /* Secret */:
+    case "url" /* URL */:
+    case "email" /* Email */:
+    case "phone" /* Phone */:
+    case "color" /* Color */:
+    case "rich_text" /* RichText */:
+    case "markdown" /* Markdown */:
+    case "date" /* Date */:
+    case "datetime" /* DateTime */:
+      return typeof value !== "object";
+    default:
+      return true;
+  }
+}
+function walk(value, stepId, path, depth, issues) {
+  if (depth > MAX_DEPTH) {
+    issues.push({
+      severity: "error",
+      code: "CONFIG_TOO_DEEP",
+      stepId,
+      field: path || undefined,
+      message: `Configuration nests deeper than ${MAX_DEPTH} levels.`
+    });
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value)
+      walk(item, stepId, path, depth + 1, issues);
+    return;
+  }
+  if (value === null || typeof value !== "object")
+    return;
+  for (const key of Object.keys(value)) {
+    if (FORBIDDEN_KEYS.has(key)) {
+      issues.push({
+        severity: "error",
+        code: "FORBIDDEN_KEY",
+        stepId,
+        field: path ? `${path}.${key}` : key,
+        message: `\`${key}\` is not allowed in a step's configuration.`
+      });
+      continue;
+    }
+    walk(value[key], stepId, path ? `${path}.${key}` : key, depth + 1, issues);
+  }
+}
+function validateStepConfig(step) {
+  const issues = [];
+  const stepId = typeof step.id === "string" ? step.id : "(unknown step)";
+  const config = step.config;
+  if (config === null || config === undefined)
+    return issues;
+  if (typeof config !== "object" || Array.isArray(config)) {
+    issues.push({
+      severity: "error",
+      code: "FIELD_WRONG_TYPE",
+      stepId,
+      message: "A step's configuration must be an object."
+    });
+    return issues;
+  }
+  let serialised;
+  try {
+    serialised = JSON.stringify(config);
+  } catch {
+    issues.push({
+      severity: "error",
+      code: "FIELD_WRONG_TYPE",
+      stepId,
+      message: "A step's configuration must be plain JSON."
+    });
+    return issues;
+  }
+  if (serialised.length > MAX_STEP_CONFIG_BYTES) {
+    issues.push({
+      severity: "error",
+      code: "CONFIG_TOO_LARGE",
+      stepId,
+      message: `Configuration is ${Math.round(serialised.length / 1024)} KB; the limit is ${MAX_STEP_CONFIG_BYTES / 1024} KB.`
+    });
+  }
+  walk(config, stepId, "", 0, issues);
+  const definition = typeof step.actionDefinitionId === "string" ? getActionById(step.actionDefinitionId) : undefined;
+  if (!definition)
+    return issues;
+  const declared = new Map(definition.inputSchema.fields.map((f) => [f.key, f]));
+  const entries = Object.entries(config);
+  for (const [key, value] of entries) {
+    const field = declared.get(key);
+    if (!field) {
+      issues.push({
+        severity: "warning",
+        code: "UNDECLARED_FIELD",
+        stepId,
+        field: key,
+        message: `\`${key}\` is not declared by ${definition.id}.`
+      });
+      continue;
+    }
+    if (!typeMatches(field, value)) {
+      issues.push({
+        severity: "error",
+        code: "FIELD_WRONG_TYPE",
+        stepId,
+        field: key,
+        message: `\`${key}\` must be ${field.type}.`
+      });
+      continue;
+    }
+    if (field.options && field.options.length > 0 && value !== null && value !== undefined && value !== "") {
+      const allowed = new Set(field.options.map((o) => o.value));
+      const values = Array.isArray(value) ? value : [value];
+      const bad = values.filter((v) => (typeof v === "string" || typeof v === "number") && !allowed.has(v));
+      if (bad.length > 0) {
+        issues.push({
+          severity: "warning",
+          code: "FIELD_BAD_OPTION",
+          stepId,
+          field: key,
+          message: `\`${key}\` must be one of: ${[...allowed].join(", ")}.`
+        });
+      }
+    }
+  }
+  return issues;
+}
+function validateStepConfigs(steps) {
+  return steps.flatMap((s) => validateStepConfig(s));
+}
+function configErrors(steps) {
+  return validateStepConfigs(steps).filter((i) => i.severity === "error");
+}

package/dist/index.d.ts

@@ -40,3 +40,7 @@ export { DATABASE_CONNECTOR_IDS, type FieldMapping, TRANSFORM_OPERATIONS, Transf
 export { STORAGE_CONNECTOR_IDS, type StorageExtraField, type StoragePathField, getStorageProvider, storageConfigKeys, } from "./catalog/storage/storageCapabilities";
 export { ManualTriggerConfig } from "./catalog/triggers/manual-trigger/index";
 export { type ManualTriggerConfigType } from "./catalog/triggers/manual-trigger/config";
+export * from "./catalog/workflow";
+export { type FlowConnection, type FlowData, type FlowStep, generateConnectionsFromSteps, transformConnectionToEdge, transformFlowToWorkflow, transformStepToNode, validateFlowData, } from "./rules/flowShape";
+export { flattenNestedWorkflow } from "./rules/flattenNestedWorkflow";
+export { configErrors, MAX_STEP_CONFIG_BYTES, validateStepConfig, validateStepConfigs, type ConfigIssue, type ConfigIssueCode, } from "./rules/configSafety";

package/dist/index.js

@@ -3692,6 +3692,465 @@ function storageConfigKeys() {
   }
   return [...keys];
 }
+// src/catalog/workflow.ts
+var NodeStatus;
+((NodeStatus) => {
+  NodeStatus["Idle"] = "idle";
+  NodeStatus["Running"] = "running";
+  NodeStatus["Success"] = "success";
+  NodeStatus["Error"] = "error";
+  NodeStatus["Warning"] = "warning";
+  NodeStatus["Disabled"] = "disabled";
+})(NodeStatus ||= {});
+var EdgeType;
+((EdgeType) => {
+  EdgeType["Default"] = "default";
+  EdgeType["Conditional"] = "conditional";
+  EdgeType["Loop"] = "loop";
+  EdgeType["Error"] = "error";
+})(EdgeType ||= {});
+// src/rules/flattenNestedWorkflow.ts
+function workflowIsNested(workflow) {
+  const stack = [...workflow.steps];
+  while (stack.length > 0) {
+    const s = stack.pop();
+    if (s.branches && Object.keys(s.branches).length > 0)
+      return true;
+  }
+  return false;
+}
+function flattenNestedWorkflow(workflow) {
+  if (!workflowIsNested(workflow))
+    return workflow;
+  const flatSteps = [];
+  const flatConns = [...workflow.connections];
+  const groups = [];
+  const walk = (steps, parentIdForSubflow) => {
+    for (const step of steps) {
+      const { branches, ...rest } = step;
+      const flatStep = {
+        ...rest,
+        ...parentIdForSubflow ? { parentId: parentIdForSubflow } : {}
+      };
+      flatSteps.push(flatStep);
+      if (!branches)
+        continue;
+      if (branches.body && step.type === "group") {
+        const body = branches.body;
+        groups.push({
+          group: flatStep,
+          bodyStepIds: body.steps.map((s) => s.id),
+          bodyConnections: body.connections
+        });
+        for (const c of body.connections)
+          flatConns.push(c);
+        walk(body.steps, step.id);
+      }
+      for (const branchKey of Object.keys(branches)) {
+        if (branchKey === "body" && step.type === "group")
+          continue;
+        const sub = branches[branchKey];
+        if (!sub)
+          continue;
+        for (const c of sub.connections)
+          flatConns.push(c);
+        walk(sub.steps, parentIdForSubflow);
+      }
+    }
+  };
+  walk(workflow.steps, undefined);
+  for (const g of groups) {
+    if (g.bodyStepIds.length === 0)
+      continue;
+    const bodyIdSet = new Set(g.bodyStepIds);
+    const inDeg = new Map;
+    const outDeg = new Map;
+    for (const id of g.bodyStepIds) {
+      inDeg.set(id, 0);
+      outDeg.set(id, 0);
+    }
+    for (const c of g.bodyConnections) {
+      if (bodyIdSet.has(c.sourceStepId)) {
+        outDeg.set(c.sourceStepId, (outDeg.get(c.sourceStepId) ?? 0) + 1);
+      }
+      if (bodyIdSet.has(c.targetStepId)) {
+        inDeg.set(c.targetStepId, (inDeg.get(c.targetStepId) ?? 0) + 1);
+      }
+    }
+    const roots = g.bodyStepIds.filter((id) => (inDeg.get(id) ?? 0) === 0);
+    const leaves = g.bodyStepIds.filter((id) => (outDeg.get(id) ?? 0) === 0);
+    for (const rootId of roots) {
+      flatConns.push({
+        id: `synth-inner-in-${g.group.id}-${rootId}`,
+        sourceStepId: g.group.id,
+        targetStepId: rootId,
+        sourcePort: "_inner_in"
+      });
+    }
+    for (const leafId of leaves) {
+      flatConns.push({
+        id: `synth-inner-out-${leafId}-${g.group.id}`,
+        sourceStepId: leafId,
+        targetStepId: g.group.id,
+        targetPort: "_inner_out"
+      });
+    }
+  }
+  return { ...workflow, steps: flatSteps, connections: flatConns };
+}
+
+// src/rules/flowShape.ts
+function transformStepToNode(step) {
+  const stepType = step.type;
+  const stepActionDefId = step.actionDefinitionId ?? "";
+  const nodeType = stepType === "trigger" ? "trigger" : stepType === "group" || stepActionDefId === "group" ? "group" : "action";
+  let nodeStatus = "idle" /* Idle */;
+  switch (step.status?.toLowerCase()) {
+    case "running":
+    case "executing":
+      nodeStatus = "running" /* Running */;
+      break;
+    case "completed":
+    case "success":
+      nodeStatus = "success" /* Success */;
+      break;
+    case "failed":
+    case "error":
+      nodeStatus = "error" /* Error */;
+      break;
+    case "pending":
+    case "waiting":
+      nodeStatus = "idle" /* Idle */;
+      break;
+    default:
+      nodeStatus = "idle" /* Idle */;
+  }
+  const position = step.position || { x: step.position_x || 0, y: step.position_y || 0 };
+  const posX = typeof position === "object" && position !== null && "x" in position ? position.x : step.position_x || 0;
+  const posY = typeof position === "object" && position !== null && "y" in position ? position.y : step.position_y || 0;
+  const config = step.config || {};
+  const configData = config.data || config || {};
+  const derivedFromName = step.name ? step.name.toLowerCase().replace(/\s+/g, "_") : undefined;
+  const resolvedActionDefinitionId = step.actionDefinitionId || config.connector_id || step.connector_id || derivedFromName || step.type;
+  const actionDef = getActionById(resolvedActionDefinitionId);
+  const node = {
+    id: step.id,
+    type: nodeType,
+    actionDefinitionId: resolvedActionDefinitionId,
+    actionDefinition: actionDef,
+    label: step.label || step.name,
+    description: step.description || config.description || actionDef?.description || "",
+    icon: actionDef?.icon ?? getIconForStepType(step.type),
+    position: {
+      x: posX,
+      y: posY
+    },
+    ...step.parentId ? { parentId: step.parentId } : {},
+    ...step.extent ? { extent: step.extent } : {},
+    ...step.disabled ? { disabled: true } : {},
+    ...step.dimensions && nodeType === "group" ? { dimensions: step.dimensions } : nodeType === "group" ? { dimensions: { width: 480, height: 240 } } : {},
+    config: {
+      ...configData,
+      timeout: step.timeout_seconds,
+      retryPolicy: step.retry_policy,
+      notes: step.notes,
+      tags: step.tags,
+      stepCount: step.step_count
+    },
+    ports: {
+      input: nodeType === "action" || nodeType === "group" ? [
+        {
+          id: `${step.id}-input`,
+          type: "input",
+          position: "top",
+          connected: false
+        }
+      ] : [],
+      output: (() => {
+        if (resolvedActionDefinitionId === "condition") {
+          return [
+            { id: `${step.id}_output_true`, type: "output", position: "bottom", label: "True", connected: false },
+            { id: `${step.id}_output_false`, type: "output", position: "bottom", label: "False", connected: false }
+          ];
+        }
+        if (resolvedActionDefinitionId === "for_each" || resolvedActionDefinitionId === "for-each") {
+          return [
+            { id: `${step.id}_output_each`, type: "output", position: "bottom", label: "Each", connected: false },
+            { id: `${step.id}_output_done`, type: "output", position: "bottom", label: "Done", connected: false }
+          ];
+        }
+        if (resolvedActionDefinitionId === "group") {
+          return [
+            { id: `${step.id}_output_0`, type: "output", position: "bottom", connected: false }
+          ];
+        }
+        return [
+          { id: `${step.id}-output`, type: "output", position: "bottom", connected: false }
+        ];
+      })()
+    },
+    configStatus: step.configStatus || undefined,
+    ...step.outputSchema ? { outputSchema: step.outputSchema } : {},
+    status: nodeStatus,
+    selected: false,
+    dragging: false,
+    isValid: step.configStatus ? step.configStatus === "valid" : true,
+    expanded: step.expanded,
+    minimized: false,
+    locked: false,
+    createdAt: step.created_at || new Date().toISOString(),
+    updatedAt: step.updated_at || new Date().toISOString()
+  };
+  return node;
+}
+function transformConnectionToEdge(connection) {
+  const sourceStepId = connection.sourceStepId || connection.source_step_id;
+  const targetStepId = connection.targetStepId || connection.target_step_id;
+  const sourcePort = connection.sourcePort || connection.source_port || `${sourceStepId}-output`;
+  const targetPort = connection.targetPort || connection.target_port || `${targetStepId}-input`;
+  let edgeType = "default" /* Default */;
+  if (connection.type === "success" || connection.type === "failure") {
+    edgeType = "conditional" /* Conditional */;
+  }
+  return {
+    id: connection.id,
+    source: sourceStepId,
+    target: targetStepId,
+    sourcePort,
+    targetPort,
+    type: edgeType,
+    label: connection.label,
+    selected: false,
+    animated: false,
+    createdAt: new Date().toISOString()
+  };
+}
+function generateConnectionsFromSteps(steps) {
+  const connections = [];
+  const sortedSteps = [...steps].sort((a, b) => a.step_count - b.step_count);
+  for (let i = 0;i < sortedSteps.length - 1; i++) {
+    const sourceStep = sortedSteps[i];
+    const targetStep = sortedSteps[i + 1];
+    connections.push({
+      id: `${sourceStep.id}-${targetStep.id}`,
+      source_step_id: sourceStep.id,
+      target_step_id: targetStep.id,
+      source_port: `${sourceStep.id}-output`,
+      target_port: `${targetStep.id}-input`,
+      type: "default"
+    });
+  }
+  return connections;
+}
+function getIconForStepType(type) {
+  const iconMap = {
+    trigger: "PlayOutline",
+    transform: "Transform",
+    action: "Application",
+    condition: "DecisionTree",
+    loop: "Repeat"
+  };
+  return iconMap[type] || "Application";
+}
+function transformFlowToWorkflow(flow) {
+  const flatWorkflow = flattenNestedWorkflow(flow.workflow);
+  const nodes = flatWorkflow.steps.map((step) => transformStepToNode(step));
+  let connections = flatWorkflow.connections;
+  if (connections === undefined || connections === null) {
+    connections = generateConnectionsFromSteps(flatWorkflow.steps);
+  } else {
+    connections = connections || [];
+  }
+  const edges = connections.map((conn, index) => {
+    if (!conn.id) {
+      conn.id = `edge-${conn.source_step_id}-${conn.target_step_id}-${index}`;
+    }
+    return transformConnectionToEdge(conn);
+  });
+  edges.forEach((edge) => {
+    const sourceNode = nodes.find((n) => n.id === edge.source);
+    const targetNode = nodes.find((n) => n.id === edge.target);
+    if (sourceNode) {
+      const port = sourceNode.ports.output.find((p) => p.id === edge.sourcePort);
+      if (port)
+        port.connected = true;
+    }
+    if (targetNode) {
+      const port = targetNode.ports.input.find((p) => p.id === edge.targetPort);
+      if (port)
+        port.connected = true;
+    }
+  });
+  return {
+    id: flow.workflow.id,
+    name: flow.workflow.name,
+    description: flow.workflow.description,
+    nodes,
+    edges,
+    workflowHistory: flow.workflowHistory || []
+  };
+}
+function validateFlowData(flow) {
+  if (!flow || typeof flow !== "object")
+    return false;
+  const f = flow;
+  return typeof f.id === "string" && typeof f.name === "string" && f.workflow !== undefined && typeof f.workflow === "object" && f.workflow !== null && Array.isArray(f.workflow.steps);
+}
+// src/rules/configSafety.ts
+var MAX_STEP_CONFIG_BYTES = 256 * 1024;
+var FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+var MAX_DEPTH = 12;
+function typeMatches(field, value) {
+  if (value === null || value === undefined || value === "")
+    return true;
+  switch (field.type) {
+    case "number" /* Number */:
+      return typeof value === "number" || typeof value === "string" && value.trim() !== "" && !Number.isNaN(Number(value));
+    case "boolean" /* Boolean */:
+      return typeof value === "boolean" || value === "true" || value === "false";
+    case "array" /* Array */:
+    case "multi_select" /* MultiSelect */:
+      return Array.isArray(value);
+    case "object" /* Object */:
+    case "mapping" /* Mapping */:
+      return typeof value === "object" && !Array.isArray(value);
+    case "string" /* String */:
+    case "code" /* Code */:
+    case "expression" /* Expression */:
+    case "select" /* Select */:
+    case "connection" /* Connection */:
+    case "secret" /* Secret */:
+    case "url" /* URL */:
+    case "email" /* Email */:
+    case "phone" /* Phone */:
+    case "color" /* Color */:
+    case "rich_text" /* RichText */:
+    case "markdown" /* Markdown */:
+    case "date" /* Date */:
+    case "datetime" /* DateTime */:
+      return typeof value !== "object";
+    default:
+      return true;
+  }
+}
+function walk(value, stepId, path, depth, issues) {
+  if (depth > MAX_DEPTH) {
+    issues.push({
+      severity: "error",
+      code: "CONFIG_TOO_DEEP",
+      stepId,
+      field: path || undefined,
+      message: `Configuration nests deeper than ${MAX_DEPTH} levels.`
+    });
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value)
+      walk(item, stepId, path, depth + 1, issues);
+    return;
+  }
+  if (value === null || typeof value !== "object")
+    return;
+  for (const key of Object.keys(value)) {
+    if (FORBIDDEN_KEYS.has(key)) {
+      issues.push({
+        severity: "error",
+        code: "FORBIDDEN_KEY",
+        stepId,
+        field: path ? `${path}.${key}` : key,
+        message: `\`${key}\` is not allowed in a step's configuration.`
+      });
+      continue;
+    }
+    walk(value[key], stepId, path ? `${path}.${key}` : key, depth + 1, issues);
+  }
+}
+function validateStepConfig(step) {
+  const issues = [];
+  const stepId = typeof step.id === "string" ? step.id : "(unknown step)";
+  const config = step.config;
+  if (config === null || config === undefined)
+    return issues;
+  if (typeof config !== "object" || Array.isArray(config)) {
+    issues.push({
+      severity: "error",
+      code: "FIELD_WRONG_TYPE",
+      stepId,
+      message: "A step's configuration must be an object."
+    });
+    return issues;
+  }
+  let serialised;
+  try {
+    serialised = JSON.stringify(config);
+  } catch {
+    issues.push({
+      severity: "error",
+      code: "FIELD_WRONG_TYPE",
+      stepId,
+      message: "A step's configuration must be plain JSON."
+    });
+    return issues;
+  }
+  if (serialised.length > MAX_STEP_CONFIG_BYTES) {
+    issues.push({
+      severity: "error",
+      code: "CONFIG_TOO_LARGE",
+      stepId,
+      message: `Configuration is ${Math.round(serialised.length / 1024)} KB; the limit is ${MAX_STEP_CONFIG_BYTES / 1024} KB.`
+    });
+  }
+  walk(config, stepId, "", 0, issues);
+  const definition = typeof step.actionDefinitionId === "string" ? getActionById(step.actionDefinitionId) : undefined;
+  if (!definition)
+    return issues;
+  const declared = new Map(definition.inputSchema.fields.map((f) => [f.key, f]));
+  const entries = Object.entries(config);
+  for (const [key, value] of entries) {
+    const field = declared.get(key);
+    if (!field) {
+      issues.push({
+        severity: "warning",
+        code: "UNDECLARED_FIELD",
+        stepId,
+        field: key,
+        message: `\`${key}\` is not declared by ${definition.id}.`
+      });
+      continue;
+    }
+    if (!typeMatches(field, value)) {
+      issues.push({
+        severity: "error",
+        code: "FIELD_WRONG_TYPE",
+        stepId,
+        field: key,
+        message: `\`${key}\` must be ${field.type}.`
+      });
+      continue;
+    }
+    if (field.options && field.options.length > 0 && value !== null && value !== undefined && value !== "") {
+      const allowed = new Set(field.options.map((o) => o.value));
+      const values = Array.isArray(value) ? value : [value];
+      const bad = values.filter((v) => (typeof v === "string" || typeof v === "number") && !allowed.has(v));
+      if (bad.length > 0) {
+        issues.push({
+          severity: "warning",
+          code: "FIELD_BAD_OPTION",
+          stepId,
+          field: key,
+          message: `\`${key}\` must be one of: ${[...allowed].join(", ")}.`
+        });
+      }
+    }
+  }
+  return issues;
+}
+function validateStepConfigs(steps) {
+  return steps.flatMap((s) => validateStepConfig(s));
+}
+function configErrors(steps) {
+  return validateStepConfigs(steps).filter((i) => i.severity === "error");
+}
 export {
   ActionCategory,
   ActionStatus,
@@ -3701,12 +4160,15 @@ export {
   ConditionConfig,
   DATABASE_CONNECTOR_IDS,
   DebugConfig,
+  EdgeType,
   EmailConfig,
   FieldType,
   ForEachConfig,
   JoinType,
   LogicalOperator,
+  MAX_STEP_CONFIG_BYTES,
   ManualTriggerConfig,
+  NodeStatus,
   QueryMode,
   QueryType,
   STORAGE_CONNECTOR_IDS,
@@ -3718,7 +4180,10 @@ export {
   buildPathOptions,
   collectArrayPaths,
   collectArrayPathsFromSample,
+  configErrors,
   emailDefinition,
+  flattenNestedWorkflow,
+  generateConnectionsFromSteps,
   generateEdgeId,
   generateStepId,
   generateUUIDv4,
@@ -3735,7 +4200,13 @@ export {
   migrateDelayConfig,
   queryDefinition,
   storageConfigKeys,
+  transformConnectionToEdge,
+  transformFlowToWorkflow,
+  transformStepToNode,
   validateEdge,
+  validateFlowData,
   validateNode,
+  validateStepConfig,
+  validateStepConfigs,
   validateWorkflow
 };

package/dist/rules/configSafety.d.ts

@@ -0,0 +1,62 @@
+/**
+ * What a step's config may contain, enforced where a caller cannot skip it.
+ *
+ * The editor's rules run in a browser, so they are advice, not a fence. A
+ * request posted straight at the API — or modified on its way — reaches
+ * `PUT /flows/:id/workflow`, which validated STRUCTURE (ids, connections,
+ * cycles) and typed config as `z.record(z.string(), z.unknown())`. Any key,
+ * any value, stored verbatim.
+ *
+ * WHAT THIS DELIBERATELY DOES NOT DO: treat `inputSchema.fields` as an
+ * allow-list. Measured against the real estate, 71 of 131 distinct config
+ * keys in use are not declared there — `slack_message.text`,
+ * `query.visualConfig`, `transform.operation`, `flowId` on nearly every
+ * action. `inputSchema` describes the fields the config PANEL renders, and
+ * every action with a custom panel stores more than that. Rejecting undeclared
+ * keys would refuse most flows on the platform. So an unknown key is a
+ * WARNING, never an error.
+ *
+ * What it does enforce is the part a legitimate client never violates:
+ *
+ *   1. a declared field's declared TYPE;
+ *   2. keys that can poison an object prototype;
+ *   3. a size and depth bound, because a config is a form's worth of settings
+ *      and an unbounded one is a document every reader of that flow pays for
+ *      (the DEV-366 problem, in a different field).
+ *
+ * Every one of those was dry-run against all 295 steps of the 77 flows on
+ * beta before it was allowed to block anything: 0 oversized (largest 28 KB
+ * against a 256 KB cap), 0 deeper than 6 (limit 12), 0 forbidden keys, 0 type
+ * mismatches. A rule that refuses data the platform already holds is not a
+ * fence, it is an outage.
+ *
+ * An enumerated field's options are checked but only WARN, for the same
+ * reason — see the note at that check.
+ */
+/** Largest config a single step may carry, serialised. */
+export declare const MAX_STEP_CONFIG_BYTES: number;
+export type ConfigIssueCode = "FORBIDDEN_KEY" | "CONFIG_TOO_LARGE" | "CONFIG_TOO_DEEP" | "FIELD_WRONG_TYPE" | "FIELD_BAD_OPTION" | "UNDECLARED_FIELD";
+export interface ConfigIssue {
+    severity: "error" | "warning";
+    code: ConfigIssueCode;
+    stepId: string;
+    /** The config key, when the issue is about one. */
+    field?: string;
+    message: string;
+}
+export interface StepLike {
+    id?: unknown;
+    actionDefinitionId?: unknown;
+    config?: unknown;
+}
+/**
+ * Check one step's config.
+ *
+ * Errors block a save. Warnings never do — see the file header on why an
+ * undeclared key cannot be an error.
+ */
+export declare function validateStepConfig(step: StepLike): ConfigIssue[];
+/** Every step of a workflow. `steps` may be nested; flatten before calling. */
+export declare function validateStepConfigs(steps: readonly StepLike[]): ConfigIssue[];
+/** Just the blocking ones — what a save path refuses on. */
+export declare function configErrors(steps: readonly StepLike[]): ConfigIssue[];

package/dist/rules/flattenNestedWorkflow.d.ts

@@ -0,0 +1,25 @@
+type AnyConn = {
+    id?: string;
+    sourceStepId: string;
+    targetStepId: string;
+    sourcePort?: string;
+    targetPort?: string;
+    [k: string]: unknown;
+};
+type AnyStep = {
+    id: string;
+    type: string;
+    parentId?: string;
+    branches?: Record<string, {
+        steps: AnyStep[];
+        connections: AnyConn[];
+    }>;
+    [k: string]: unknown;
+};
+type AnyWorkflow = {
+    steps: AnyStep[];
+    connections: AnyConn[];
+    [k: string]: unknown;
+};
+export declare function flattenNestedWorkflow<W extends AnyWorkflow>(workflow: W): W;
+export {};

package/dist/rules/flowShape.d.ts

@@ -0,0 +1,122 @@
+/**
+ * The PERSISTED flow shape, and how it becomes the canvas shape.
+ *
+ * A flow is stored as `steps` + `connections`; the rules engine and anything
+ * that reasons about a flow work in `nodes` + `edges`. This is the ONE
+ * conversion between them.
+ *
+ * It lived in octaviaflow-ui because only the editor ever read a flow. The
+ * server has to now: `check_flow` runs the same rules against a STORED flow
+ * and cannot do that without converting it the same way. A second converter
+ * would make an agent's verdict quietly disagree with the editor's, which is
+ * the failure this package exists to prevent.
+ *
+ * Two UI-only pieces did not come: `loadFlowFromJSON` (an HTTP fetch) and
+ * `calculateFitViewport` (canvas geometry) stay in the editor.
+ */
+/**
+ * Flow Loader Utilities
+ *
+ * Utilities for loading, transforming, and managing workflow flows
+ * from various data sources (JSON files, APIs, etc.)
+ */
+import { type WorkflowNode, type WorkflowEdge } from "../catalog/workflow";
+/**
+ * Flow data structure from database/JSON
+ */
+export interface FlowData {
+    id: string;
+    name: string;
+    description: string;
+    status: string;
+    owner: {
+        user_id: string;
+        user_name: string;
+        user_email: string;
+        permissions: string[];
+    };
+    collaborators: Array<{
+        user_id: string;
+        user_name: string;
+        user_email: string;
+        permissions: string[];
+        added_at: string;
+        added_by: string;
+    }>;
+    workflow: {
+        id: string;
+        name: string;
+        description: string;
+        status: string;
+        steps: FlowStep[];
+        connections?: FlowConnection[];
+    };
+    created_at?: string;
+    updated_at?: string;
+}
+export interface FlowStep {
+    id: string;
+    name: string;
+    description: string;
+    type: 'trigger' | 'transform' | 'action' | 'condition' | 'loop';
+    config: {
+        connector_id?: string;
+        connection_id?: string;
+        data?: Record<string, unknown>;
+    };
+    step_count: number;
+    position_x: number;
+    position_y: number;
+    expanded: boolean;
+    timeout_seconds?: number;
+    retry_policy?: {
+        enabled: boolean;
+        max_retries: number;
+        retry_delay_seconds: number;
+        backoff_strategy: string;
+    };
+    status: string;
+    notes?: string;
+    tags?: string[];
+    created_at?: string;
+    created_by?: string;
+    updated_at?: string;
+    updated_by?: string;
+}
+export interface FlowConnection {
+    id: string;
+    source_step_id: string;
+    target_step_id: string;
+    source_port?: string;
+    target_port?: string;
+    condition?: string;
+    label?: string;
+    type?: 'default' | 'success' | 'failure';
+}
+/**
+ * Transform flow step to WorkflowNode
+ */
+export declare function transformStepToNode(step: FlowStep): WorkflowNode;
+/**
+ * Transform flow connection to WorkflowEdge
+ */
+export declare function transformConnectionToEdge(connection: FlowConnection): WorkflowEdge;
+/**
+ * Auto-generate connections from step order if not provided
+ */
+export declare function generateConnectionsFromSteps(steps: FlowStep[]): FlowConnection[];
+/**
+ * Transform complete flow data to workflow state
+ */
+export declare function transformFlowToWorkflow(flow: FlowData): {
+    id: string;
+    name: string;
+    description: string;
+    nodes: any;
+    edges: any;
+    workflowHistory: any;
+};
+/**
+ * Validate flow data structure
+ */
+export declare function validateFlowData(flow: unknown): flow is FlowData;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octaviaflow/flow-rules",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "The flow action catalog and the rules engine behind Flow Doctor \u2014 one definition of what a step accepts and what makes a flow valid, shared by the editor and the server",
   "type": "module",
   "main": "./dist/index.cjs",