@synergenius/flow-weaver 0.8.3 → 0.9.1

package/dist/cli/index.js

@@ -31,6 +31,8 @@ import { migrateCommand } from './commands/migrate.js';
 import { changelogCommand } from './commands/changelog.js';
 import { stripCommand } from './commands/strip.js';
 import { docsListCommand, docsReadCommand, docsSearchCommand } from './commands/docs.js';
+import { statusCommand } from './commands/status.js';
+import { implementCommand } from './commands/implement.js';
 import { marketInitCommand, marketPackCommand, marketPublishCommand, marketInstallCommand, marketSearchCommand, marketListCommand, } from './commands/market.js';
 import { logger } from './utils/logger.js';
 import { getErrorMessage } from '../utils/error-utils.js';
@@ -589,6 +591,36 @@ program
         process.exit(1);
     }
 });
+// Status command
+program
+    .command('status <input>')
+    .description('Report implementation progress for stub workflows')
+    .option('-w, --workflow-name <name>', 'Specific workflow name')
+    .option('--json', 'Output as JSON', false)
+    .action(async (input, options) => {
+    try {
+        await statusCommand(input, options);
+    }
+    catch (error) {
+        logger.error(`Command failed: ${getErrorMessage(error)}`);
+        process.exit(1);
+    }
+});
+// Implement command
+program
+    .command('implement <input> <node>')
+    .description('Replace a stub node with a real function skeleton')
+    .option('-w, --workflow-name <name>', 'Specific workflow name')
+    .option('-p, --preview', 'Preview the generated code without writing', false)
+    .action(async (input, node, options) => {
+    try {
+        await implementCommand(input, node, options);
+    }
+    catch (error) {
+        logger.error(`Command failed: ${getErrorMessage(error)}`);
+        process.exit(1);
+    }
+});
 // Changelog command
 program
     .command('changelog')

package/dist/diagram/html-viewer.js

@@ -266,43 +266,79 @@ body.node-active .connections path.dimmed { opacity: 0.15; }
     else if (e.key === 'Escape') deselectNode();
   });
 
-  // ---- Port label visibility via JS (since CSS sibling selectors can't reach .labels group) ----
-  var labelEls = content.querySelectorAll('.labels g[data-port-label]');
-  var nodeEls = content.querySelectorAll('.nodes g[data-node-id]');
+  // ---- Port label visibility ----
+  var labelMap = {};
+  content.querySelectorAll('.labels g[data-port-label]').forEach(function(lbl) {
+    labelMap[lbl.getAttribute('data-port-label')] = lbl;
+  });
 
-  function showLabelsFor(id) {
-    labelEls.forEach(function(lbl) {
-      var portId = lbl.getAttribute('data-port-label') || '';
-      if (portId.indexOf(id + '.') === 0) {
-        lbl.style.opacity = '1';
-        lbl.style.pointerEvents = 'auto';
-      }
+  // Build adjacency: portId → array of connected portIds
+  var portConnections = {};
+  content.querySelectorAll('.connections path').forEach(function(p) {
+    var src = p.getAttribute('data-source');
+    var tgt = p.getAttribute('data-target');
+    if (!src || !tgt) return;
+    if (!portConnections[src]) portConnections[src] = [];
+    if (!portConnections[tgt]) portConnections[tgt] = [];
+    portConnections[src].push(tgt);
+    portConnections[tgt].push(src);
+  });
+
+  var allLabelIds = Object.keys(labelMap);
+  var hoveredPort = null;
+
+  function showLabel(id) { var l = labelMap[id]; if (l) { l.style.opacity = '1'; l.style.pointerEvents = 'auto'; } }
+  function hideLabel(id) { var l = labelMap[id]; if (l) { l.style.opacity = '0'; l.style.pointerEvents = 'none'; } }
+
+  function showLabelsFor(nodeId) {
+    allLabelIds.forEach(function(id) {
+      if (id.indexOf(nodeId + '.') === 0) showLabel(id);
     });
   }
-  function hideLabelsFor(id) {
-    labelEls.forEach(function(lbl) {
-      var portId = lbl.getAttribute('data-port-label') || '';
-      if (portId.indexOf(id + '.') === 0) {
-        lbl.style.opacity = '0';
-        lbl.style.pointerEvents = 'none';
-      }
+  function hideLabelsFor(nodeId) {
+    allLabelIds.forEach(function(id) {
+      if (id.indexOf(nodeId + '.') === 0) hideLabel(id);
     });
   }
 
+  // Node hover: show all port labels for the hovered node
+  var nodeEls = content.querySelectorAll('.nodes g[data-node-id]');
   nodeEls.forEach(function(nodeG) {
     var nodeId = nodeG.getAttribute('data-node-id');
     var parentNodeG = nodeG.parentElement ? nodeG.parentElement.closest('g[data-node-id]') : null;
     var parentId = parentNodeG ? parentNodeG.getAttribute('data-node-id') : null;
     nodeG.addEventListener('mouseenter', function() {
+      if (hoveredPort) return; // port hover takes priority
       if (parentId) hideLabelsFor(parentId);
       showLabelsFor(nodeId);
     });
     nodeG.addEventListener('mouseleave', function() {
+      if (hoveredPort) return;
       hideLabelsFor(nodeId);
       if (parentId) showLabelsFor(parentId);
     });
   });
 
+  // Port hover: show this port's label + all connected port labels
+  content.querySelectorAll('[data-port-id]').forEach(function(portEl) {
+    var portId = portEl.getAttribute('data-port-id');
+    var nodeId = portId.split('.')[0];
+    var peers = (portConnections[portId] || []).concat(portId);
+
+    portEl.addEventListener('mouseenter', function() {
+      hoveredPort = portId;
+      // Hide all labels for this node first, then show only the relevant ones
+      hideLabelsFor(nodeId);
+      peers.forEach(showLabel);
+    });
+    portEl.addEventListener('mouseleave', function() {
+      hoveredPort = null;
+      peers.forEach(hideLabel);
+      // Restore all labels for the node since we're still inside it
+      showLabelsFor(nodeId);
+    });
+  });
+
   // ---- Click to inspect node ----
   function deselectNode() {
     selectedNodeId = null;
@@ -329,7 +365,7 @@ body.node-active .connections path.dimmed { opacity: 0.15; }
     ports.forEach(function(p) {
       var id = p.getAttribute('data-port-id');
       var dir = p.getAttribute('data-direction');
-      var name = id.split('.').slice(1).join('.');
+      var name = id.split('.').slice(1).join('.').replace(/:(?:input|output)$/, '');
       if (dir === 'input') inputs.push(name);
       else outputs.push(name);
     });

package/dist/diagram/renderer.js

@@ -90,14 +90,14 @@ export function renderSVG(graph, options = {}) {
 // ---- Connection rendering ----
 function renderConnection(parts, conn, gradIndex) {
     const dashAttr = conn.isStepConnection ? '' : ' stroke-dasharray="8 4"';
-    parts.push(`  <path d="${conn.path}" fill="none" stroke="url(#conn-grad-${gradIndex})" stroke-width="3"${dashAttr} stroke-linecap="round" data-source="${escapeXml(conn.fromNode)}.${escapeXml(conn.fromPort)}" data-target="${escapeXml(conn.toNode)}.${escapeXml(conn.toPort)}"/>`);
+    parts.push(`  <path d="${conn.path}" fill="none" stroke="url(#conn-grad-${gradIndex})" stroke-width="3"${dashAttr} stroke-linecap="round" data-source="${escapeXml(conn.fromNode)}.${escapeXml(conn.fromPort)}:output" data-target="${escapeXml(conn.toNode)}.${escapeXml(conn.toPort)}:input"/>`);
 }
 function renderScopeConnection(parts, conn, allConnections) {
     const gradIndex = allConnections.indexOf(conn);
     if (gradIndex < 0)
         return;
     const dashAttr = conn.isStepConnection ? '' : ' stroke-dasharray="8 4"';
-    parts.push(`    <path d="${conn.path}" fill="none" stroke="url(#conn-grad-${gradIndex})" stroke-width="2.5"${dashAttr} stroke-linecap="round" data-source="${escapeXml(conn.fromNode)}.${escapeXml(conn.fromPort)}" data-target="${escapeXml(conn.toNode)}.${escapeXml(conn.toPort)}"/>`);
+    parts.push(`    <path d="${conn.path}" fill="none" stroke="url(#conn-grad-${gradIndex})" stroke-width="2.5"${dashAttr} stroke-linecap="round" data-source="${escapeXml(conn.fromNode)}.${escapeXml(conn.fromPort)}:output" data-target="${escapeXml(conn.toNode)}.${escapeXml(conn.toPort)}:input"/>`);
 }
 // ---- Node rendering ----
 /** Render node body rect + icon */
@@ -183,7 +183,7 @@ function renderPortDots(parts, nodeId, inputs, outputs, themeName) {
         const color = getPortColor(port.dataType, port.isFailure, themeName);
         const ringColor = getPortRingColor(port.dataType, port.isFailure, themeName);
         const dir = port.direction === 'INPUT' ? 'input' : 'output';
-        parts.push(`    <circle cx="${port.cx}" cy="${port.cy}" r="${PORT_RADIUS}" fill="${color}" stroke="${ringColor}" stroke-width="2" data-port-id="${escapeXml(nodeId)}.${escapeXml(port.name)}" data-direction="${dir}"/>`);
+        parts.push(`    <circle cx="${port.cx}" cy="${port.cy}" r="${PORT_RADIUS}" fill="${color}" stroke="${ringColor}" stroke-width="2" data-port-id="${escapeXml(nodeId)}.${escapeXml(port.name)}:${dir}" data-direction="${dir}"/>`);
     }
 }
 /** Render only port label badges (no dots) */
@@ -192,7 +192,8 @@ function renderPortLabels(parts, nodeId, inputs, outputs, theme, themeName) {
         const color = getPortColor(port.dataType, port.isFailure, themeName);
         const isInput = port.direction === 'INPUT';
         const abbrev = TYPE_ABBREVIATIONS[port.dataType] ?? port.dataType;
-        const portId = `${escapeXml(nodeId)}.${escapeXml(port.name)}`;
+        const dir = isInput ? 'input' : 'output';
+        const portId = `${escapeXml(nodeId)}.${escapeXml(port.name)}:${dir}`;
         const portLabel = port.label;
         const typeWidth = measureText(abbrev);
         const labelWidth = measureText(portLabel);

package/dist/generator/unified.js

@@ -1487,7 +1487,11 @@ branchingNodes = new Set() // Branching nodes set for port-aware STEP guards
     });
     const resultVar = `${safeId}Result`;
     const awaitKeyword = nodeType.isAsync ? 'await ' : '';
-    if (nodeType.variant === 'COERCION') {
+    if (nodeType.variant === 'STUB') {
+        // Stub node: emit a runtime throw. The workflow was generated with generateStubs: true.
+        lines.push(`${indent}  throw new Error('Node "${instanceId}" uses stub type "${functionName}" which has no implementation.');`);
+    }
+    else if (nodeType.variant === 'COERCION') {
         // Coercion node: inline JS expression instead of function call
         const coerceExprMap = {
             __fw_toString: 'String',

package/dist/mcp/server.js

@@ -12,6 +12,7 @@ import { registerExportTools } from './tools-export.js';
 import { registerMarketplaceTools } from './tools-marketplace.js';
 import { registerDiagramTools } from './tools-diagram.js';
 import { registerDocsTools } from './tools-docs.js';
+import { registerModelTools } from './tools-model.js';
 import { registerResources } from './resources.js';
 function parseEventFilterFromEnv() {
     const filter = {};
@@ -72,6 +73,7 @@ export async function startMcpServer(options) {
     registerMarketplaceTools(mcp);
     registerDiagramTools(mcp);
     registerDocsTools(mcp);
+    registerModelTools(mcp);
     registerResources(mcp, connection, buffer);
     // Connect transport (only in stdio MCP mode)
     if (!options._testDeps && options.stdio) {

package/dist/mcp/tools-model.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerModelTools(mcp: McpServer): void;
+//# sourceMappingURL=tools-model.d.ts.map

package/dist/mcp/tools-model.js

@@ -0,0 +1,253 @@
+import { z } from 'zod';
+import * as fs from 'fs';
+import * as path from 'path';
+import { parseWorkflow, validateWorkflow } from '../api/index.js';
+import { generateFunctionSignature } from '../annotation-generator.js';
+import { makeToolResult, makeErrorResult } from './response-utils.js';
+const stepSchema = z.object({
+    name: z.string().describe('Function name for this node'),
+    description: z.string().optional().describe('Brief description of what this node does'),
+    inputs: z.record(z.string()).describe('Input ports as { portName: dataType } (e.g. { email: "STRING" })'),
+    outputs: z.record(z.string()).describe('Output ports as { portName: dataType }'),
+});
+/**
+ * Find a `declare function <name>(...): ...;` declaration in source text,
+ * handling multiline signatures. Returns the full matched text and its
+ * leading indentation, or null if not found.
+ */
+function findDeclareFunction(source, functionName) {
+    const lines = source.split('\n');
+    const startPattern = new RegExp(`^(\\s*)declare\\s+function\\s+${escapeRegex(functionName)}\\s*\\(`);
+    for (let i = 0; i < lines.length; i++) {
+        const m = lines[i].match(startPattern);
+        if (!m)
+            continue;
+        const indent = m[1] || '';
+        // Accumulate lines until we find one ending with ;
+        let accumulated = lines[i];
+        let j = i;
+        while (!accumulated.trimEnd().endsWith(';') && j < lines.length - 1) {
+            j++;
+            accumulated += '\n' + lines[j];
+        }
+        return { match: accumulated, indent };
+    }
+    return null;
+}
+export function registerModelTools(mcp) {
+    mcp.tool('fw_create_model', 'Create a new stub workflow model from a structured description. ' +
+        'Generates a TypeScript file with declare function stubs and workflow annotations. ' +
+        'The model can be validated structurally before any node is implemented.', {
+        name: z.string().describe('Workflow name (used as export name)'),
+        description: z.string().optional().describe('Workflow description'),
+        steps: z.array(stepSchema).min(1).describe('Node definitions in execution order'),
+        flow: z
+            .string()
+            .describe('Execution path, e.g. "Start -> validateEmail -> checkUserExists -> Exit"'),
+        filePath: z.string().describe('Output file path'),
+    }, async (args) => {
+        try {
+            const outputPath = path.resolve(args.filePath);
+            const lines = [];
+            // Generate declare function stubs
+            for (const step of args.steps) {
+                lines.push('/** @flowWeaver node */');
+                const params = Object.entries(step.inputs)
+                    .map(([name, type]) => `${name}: ${mapTypeToTS(type)}`)
+                    .join(', ');
+                const outputEntries = Object.entries(step.outputs);
+                const returnType = outputEntries.length === 1
+                    ? mapTypeToTS(outputEntries[0][1])
+                    : `{ ${outputEntries.map(([name, type]) => `${name}: ${mapTypeToTS(type)}`).join('; ')} }`;
+                lines.push(`declare function ${step.name}(${params}): ${returnType};`);
+                lines.push('');
+            }
+            // Parse the flow string — use full function names as instance IDs
+            const flowSteps = args.flow
+                .split('->')
+                .map((s) => s.trim())
+                .filter(Boolean);
+            // Build @node annotations using full name as both ID and type
+            const nodeAnnotations = args.steps.map((step) => `@node ${step.name} ${step.name}`);
+            // @path uses the same full names directly from the flow string
+            const pathAnnotation = `@path ${flowSteps.join(' -> ')}`;
+            // Generate workflow annotation
+            const jsdocLines = ['/**'];
+            if (args.description) {
+                jsdocLines.push(` * ${args.description}`);
+                jsdocLines.push(' *');
+            }
+            jsdocLines.push(' * @flowWeaver workflow @autoConnect');
+            for (const nodeAnn of nodeAnnotations) {
+                jsdocLines.push(` * ${nodeAnn}`);
+            }
+            jsdocLines.push(` * ${pathAnnotation}`);
+            jsdocLines.push(' */');
+            jsdocLines.push(`export const ${args.name} = 'flowWeaver:draft';`);
+            lines.push(...jsdocLines);
+            lines.push('');
+            const content = lines.join('\n');
+            const dir = path.dirname(outputPath);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            fs.writeFileSync(outputPath, content, 'utf8');
+            return makeToolResult({
+                filePath: outputPath,
+                workflowName: args.name,
+                stubCount: args.steps.length,
+                nodes: args.steps.map((s) => s.name),
+            });
+        }
+        catch (err) {
+            return makeErrorResult('CREATE_MODEL_ERROR', `fw_create_model failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+    mcp.tool('fw_workflow_status', 'Report implementation progress for a workflow — which nodes are stubs, ' +
+        'which are implemented, and whether the graph structure is valid.', {
+        filePath: z.string().describe('Path to the workflow file'),
+        workflowName: z.string().optional().describe('Specific workflow name if file has multiple'),
+    }, async (args) => {
+        try {
+            const filePath = path.resolve(args.filePath);
+            const parseResult = await parseWorkflow(filePath, { workflowName: args.workflowName });
+            if (parseResult.errors.length > 0) {
+                return makeErrorResult('PARSE_ERROR', `Parse errors:\n${parseResult.errors.join('\n')}`);
+            }
+            const ast = parseResult.ast;
+            const instanceTypeMap = new Map();
+            for (const nt of ast.nodeTypes) {
+                instanceTypeMap.set(nt.name, nt);
+                if (nt.functionName !== nt.name) {
+                    instanceTypeMap.set(nt.functionName, nt);
+                }
+            }
+            const nodes = [];
+            const seen = new Set();
+            for (const instance of ast.instances) {
+                const nt = instanceTypeMap.get(instance.nodeType);
+                if (!nt || seen.has(nt.functionName))
+                    continue;
+                seen.add(nt.functionName);
+                const inputs = {};
+                const outputs = {};
+                for (const [name, port] of Object.entries(nt.inputs)) {
+                    if (name === 'execute')
+                        continue;
+                    inputs[name] = port.dataType;
+                }
+                for (const [name, port] of Object.entries(nt.outputs)) {
+                    if (name === 'onSuccess' || name === 'onFailure')
+                        continue;
+                    outputs[name] = port.dataType;
+                }
+                nodes.push({
+                    name: nt.functionName,
+                    status: nt.variant === 'STUB' ? 'stub' : 'implemented',
+                    inputs,
+                    outputs,
+                });
+            }
+            const implemented = nodes.filter((n) => n.status === 'implemented').length;
+            const total = nodes.length;
+            // Draft validation for structural issues
+            const validation = validateWorkflow(ast, { mode: 'draft' });
+            const structuralErrors = validation.errors
+                .filter((e) => e.code !== 'STUB_NODE')
+                .map((e) => ({ message: e.message, code: e.code, node: e.node }));
+            return makeToolResult({
+                workflowName: ast.name,
+                implemented,
+                total,
+                percentage: total > 0 ? Math.round((implemented / total) * 100) : 100,
+                nodes,
+                structurallyValid: structuralErrors.length === 0,
+                structuralErrors,
+            });
+        }
+        catch (err) {
+            return makeErrorResult('STATUS_ERROR', `fw_workflow_status failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+    mcp.tool('fw_implement_node', 'Replace a stub node (declare function) with a real function skeleton, ' +
+        'or write a provided implementation directly. Preserves existing JSDoc annotations.', {
+        filePath: z.string().describe('Path to the workflow file'),
+        nodeName: z.string().describe('Function name of the stub node to implement'),
+        implementation: z
+            .string()
+            .optional()
+            .describe('Full function body to write. If omitted, generates a skeleton.'),
+        workflowName: z.string().optional().describe('Specific workflow name'),
+    }, async (args) => {
+        try {
+            const filePath = path.resolve(args.filePath);
+            if (!fs.existsSync(filePath)) {
+                return makeErrorResult('FILE_NOT_FOUND', `File not found: ${args.filePath}`);
+            }
+            const parseResult = await parseWorkflow(filePath, { workflowName: args.workflowName });
+            if (parseResult.errors.length > 0) {
+                return makeErrorResult('PARSE_ERROR', `Parse errors:\n${parseResult.errors.join('\n')}`);
+            }
+            const ast = parseResult.ast;
+            const stubNt = ast.nodeTypes.find((nt) => nt.variant === 'STUB' && (nt.functionName === args.nodeName || nt.name === args.nodeName));
+            if (!stubNt) {
+                const existing = ast.nodeTypes.find((nt) => nt.functionName === args.nodeName || nt.name === args.nodeName);
+                if (existing) {
+                    return makeErrorResult('ALREADY_IMPLEMENTED', `Node "${args.nodeName}" is already implemented.`);
+                }
+                const stubs = ast.nodeTypes
+                    .filter((nt) => nt.variant === 'STUB')
+                    .map((nt) => nt.functionName);
+                return makeErrorResult('NODE_NOT_FOUND', `Stub "${args.nodeName}" not found. Available stubs: ${stubs.join(', ') || 'none'}`);
+            }
+            const source = fs.readFileSync(filePath, 'utf8');
+            const found = findDeclareFunction(source, stubNt.functionName);
+            if (!found) {
+                return makeErrorResult('SOURCE_MISMATCH', `Could not find "declare function ${stubNt.functionName}" in source file.`);
+            }
+            let replacement;
+            if (args.implementation) {
+                replacement = args.implementation
+                    .split('\n')
+                    .map((line) => found.indent + line)
+                    .join('\n');
+            }
+            else {
+                const implementedType = { ...stubNt, variant: 'FUNCTION' };
+                const signatureLines = generateFunctionSignature(implementedType);
+                replacement = signatureLines.map((line) => found.indent + line).join('\n');
+            }
+            const updated = source.replace(found.match, replacement);
+            fs.writeFileSync(filePath, updated, 'utf8');
+            return makeToolResult({
+                nodeName: stubNt.functionName,
+                filePath,
+                action: args.implementation ? 'implemented' : 'scaffolded',
+            });
+        }
+        catch (err) {
+            return makeErrorResult('IMPLEMENT_ERROR', `fw_implement_node failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+}
+function mapTypeToTS(dataType) {
+    const upper = dataType.toUpperCase();
+    switch (upper) {
+        case 'STRING':
+            return 'string';
+        case 'NUMBER':
+            return 'number';
+        case 'BOOLEAN':
+            return 'boolean';
+        case 'OBJECT':
+            return 'Record<string, unknown>';
+        case 'ARRAY':
+            return 'unknown[]';
+        default:
+            return 'unknown';
+    }
+}
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+//# sourceMappingURL=tools-model.js.map

package/dist/utils/port-ordering.d.ts

@@ -14,11 +14,11 @@ export declare function isMandatoryPort(portName: string, isScoped: boolean): bo
  *
  * Rules:
  * 1. Ports are grouped by scope (undefined = external, string = scoped)
- * 2. Within each scope group:
- *    - Mandatory ports (execute, onSuccess, onFailure) get lower order values
- *    - Regular ports get higher order values
- * 3. Explicit order metadata is always preserved
- * 4. If a regular port has explicit order 0, mandatory ports are pushed to order >= 1
+ * 2. Explicit order metadata is always preserved
+ * 3. Mandatory ports without explicit orders get negative slots (-N, ..., -1)
+ *    so they always sort before any user-specified [order:0] data port
+ * 4. Regular ports without explicit orders fill non-negative slots (0+),
+ *    skipping any slots already occupied by explicit orders
  *
  * @param ports - Record of port definitions to process (mutated in place)
  */

package/dist/utils/port-ordering.js

@@ -19,11 +19,11 @@ export function isMandatoryPort(portName, isScoped) {
  *
  * Rules:
  * 1. Ports are grouped by scope (undefined = external, string = scoped)
- * 2. Within each scope group:
- *    - Mandatory ports (execute, onSuccess, onFailure) get lower order values
- *    - Regular ports get higher order values
- * 3. Explicit order metadata is always preserved
- * 4. If a regular port has explicit order 0, mandatory ports are pushed to order >= 1
+ * 2. Explicit order metadata is always preserved
+ * 3. Mandatory ports without explicit orders get negative slots (-N, ..., -1)
+ *    so they always sort before any user-specified [order:0] data port
+ * 4. Regular ports without explicit orders fill non-negative slots (0+),
+ *    skipping any slots already occupied by explicit orders
  *
  * @param ports - Record of port definitions to process (mutated in place)
  */
@@ -40,48 +40,41 @@ export function assignImplicitPortOrders(ports) {
     // Process each scope group independently
     for (const [scope, portsInScope] of scopeGroups.entries()) {
         const isScoped = scope !== undefined;
-        // Separate mandatory from regular ports
-        const mandatoryPorts = portsInScope.filter(([name]) => isMandatoryPort(name, isScoped));
-        const regularPorts = portsInScope.filter(([name]) => !isMandatoryPort(name, isScoped));
-        // Find minimum explicit order among regular ports (if any)
-        let minRegularExplicitOrder = Infinity;
-        for (const [, portDef] of regularPorts) {
+        // Collect all explicitly occupied order slots
+        const occupied = new Set();
+        for (const [, portDef] of portsInScope) {
             const order = portDef.metadata?.order;
             if (typeof order === "number") {
-                minRegularExplicitOrder = Math.min(minRegularExplicitOrder, order);
+                occupied.add(order);
             }
         }
-        // Determine starting order for mandatory ports
-        let mandatoryStartOrder = 0;
-        // If a regular port has explicit order 0 (or any low value),
-        // mandatory ports should be pushed after it
-        if (minRegularExplicitOrder !== Infinity && minRegularExplicitOrder === 0) {
-            // Count how many regular ports have explicit order 0
-            const regularPortsWithOrder0 = regularPorts.filter(([, p]) => p.metadata?.order === 0);
-            mandatoryStartOrder = regularPortsWithOrder0.length;
+        // Helper: find next available slot starting from `from`
+        function nextSlot(from) {
+            while (occupied.has(from))
+                from++;
+            occupied.add(from);
+            return from;
         }
-        // Assign orders to mandatory ports (if they don't have explicit order)
-        let currentMandatoryOrder = mandatoryStartOrder;
-        for (const [, portDef] of mandatoryPorts) {
-            if (portDef.metadata?.order === undefined) {
-                // Assign implicit order
-                if (!portDef.metadata) {
-                    portDef.metadata = {};
-                }
-                portDef.metadata.order = currentMandatoryOrder++;
-            }
+        // Separate mandatory from regular ports (only those needing implicit orders)
+        const mandatoryNeedOrder = portsInScope.filter(([name, def]) => isMandatoryPort(name, isScoped) && def.metadata?.order === undefined);
+        const regularNeedOrder = portsInScope.filter(([name, def]) => !isMandatoryPort(name, isScoped) && def.metadata?.order === undefined);
+        // Mandatory ports fill negative slots so they always sort before [order:0] data ports
+        let slot = -mandatoryNeedOrder.length;
+        for (const [, portDef] of mandatoryNeedOrder) {
+            if (!portDef.metadata)
+                portDef.metadata = {};
+            slot = nextSlot(slot);
+            portDef.metadata.order = slot;
+            slot++;
         }
-        // Assign orders to regular ports (if they don't have explicit order)
-        // Regular ports start after mandatory ports
-        let currentRegularOrder = currentMandatoryOrder;
-        for (const [, portDef] of regularPorts) {
-            if (portDef.metadata?.order === undefined) {
-                // Assign implicit order
-                if (!portDef.metadata) {
-                    portDef.metadata = {};
-                }
-                portDef.metadata.order = currentRegularOrder++;
-            }
+        // Regular ports fill non-negative slots, skipping occupied ones
+        slot = Math.max(slot, 0);
+        for (const [, portDef] of regularNeedOrder) {
+            if (!portDef.metadata)
+                portDef.metadata = {};
+            slot = nextSlot(slot);
+            portDef.metadata.order = slot;
+            slot++;
         }
     }
 }

package/dist/validator.d.ts

@@ -4,6 +4,7 @@ export declare class WorkflowValidator {
     private errors;
     private warnings;
     private strictMode;
+    private draftMode;
     /** Look up instance sourceLocation by instance ID */
     private getInstanceLocation;
     /** Look up connection sourceLocation */
@@ -26,6 +27,7 @@ export declare class WorkflowValidator {
     validateNodeType(nodeType: TNodeTypeAST): string[];
     validate(workflow: TWorkflowAST, options?: {
         strictMode?: boolean;
+        mode?: 'strict' | 'draft';
     }): {
         valid: boolean;
         errors: TValidationError[];