@synergenius/flow-weaver 0.33.1 → 0.44.0

package/dist/testing/replayer.d.ts

@@ -1,24 +1,23 @@
 /**
- * Replay LLM Provider — creates a mock provider from a recorded session.
+ * Replay LLM Provider: creates a mock provider from a recorded session.
  *
  * Usage:
  * ```typescript
- * import { createReplayProvider, loadRecording } from 'flow-weaver/testing';
+ * import { createReplayProvider, loadRecording } from '@synergenius/flow-weaver/testing';
  *
  * const recording = loadRecording(jsonFixture);
  * const replay = createReplayProvider(recording);
  *
- * // Use as LLM provider — calls are replayed in order
- * (globalThis as unknown as { __fw_llm_provider__?: LLMProvider }).__fw_llm_provider__ = replay;
+ * // Pass replay to the node or adapter under test; calls replay in order.
  *
- * // Run workflow — LLM calls return recorded responses, no network calls
+ * // Run workflow. LLM calls return recorded responses, no network calls
  *
  * // All MockLlmProvider methods work: getCalls(), getTotalTokens(), etc.
  * expect(replay.getCallCount()).toBe(3);
  * ```
  */
-import type { LLMTokenUsage, MockLlmProvider } from './mock-llm.js';
-import type { LlmRecording } from './recorder.js';
+import type { LLMTokenUsage, MockLlmProvider } from './mock-llm';
+import type { LlmRecording } from './recorder';
 export interface ReplayOptions {
     /**
      * In strict mode, throws an error if more calls are made than were recorded.

package/dist/testing/run-store-check.d.ts

@@ -0,0 +1,3 @@
+import type { RunStore } from '../coordinator/store.js';
+export declare function checkRunStore(make: () => RunStore | Promise<RunStore>): Promise<void>;
+//# sourceMappingURL=run-store-check.d.ts.map

package/dist/testing/token-tracker.d.ts

@@ -6,7 +6,7 @@
  *
  * Usage:
  * ```typescript
- * import { TokenTracker, createMockLlmProvider } from 'flow-weaver/testing';
+ * import { TokenTracker, createMockLlmProvider } from '@synergenius/flow-weaver/testing';
  *
  * const tracker = new TokenTracker();
  * const mockLlm = createMockLlmProvider([...]);
@@ -19,7 +19,7 @@
  * tracker.assertBelow(10000); // Fail if total exceeds budget
  * ```
  */
-import type { LLMTokenUsage } from './mock-llm.js';
+import type { LLMTokenUsage } from './mock-llm';
 export interface TrackedStep {
     /** Identifier for this step (e.g., node name, call index) */
     step: string;

package/dist/{type-mappings.d.ts → types/type-mappings.d.ts}

@@ -1,4 +1,4 @@
-import type { TDataType } from './ast/types.js';
+import type { TDataType } from '../ast/types';
 export type TypeScriptType = 'string' | 'number' | 'boolean' | 'unknown' | 'unknown[]' | 'void' | 'Function' | 'Record<string, unknown>' | '(...args: unknown[]) => unknown';
 export interface PortTypeMapping {
     readonly typescript: TypeScriptType;
@@ -25,5 +25,17 @@ export declare function getPortTypeDescription(portType: TDataType): string | un
  * inferDataTypeFromTS("Map<string, User>") // → "OBJECT"
  * inferDataTypeFromTS("(x: number) => string") // → "FUNCTION"
  */
+/**
+ * Strip a trailing `| undefined` that ts-morph appends to an optional
+ * parameter's type. Optionality is tracked separately by the port's `optional`
+ * flag, so the captured `tsType` should be the base type without it. ts-morph 28
+ * started including `| undefined` in `Parameter.getType().getText()` for `?`
+ * params (ts-morph 27 did not), which otherwise leaks into generated code and
+ * makes JSDoc signatures (`@input x - string`) mismatch the inferred type.
+ *
+ * Only call this for params/fields already known to be optional; a required
+ * `string | undefined` union is left intact.
+ */
+export declare function stripOptionalUndefined(tsType: string): string;
 export declare function inferDataTypeFromTS(tsType: string): TDataType;
 //# sourceMappingURL=type-mappings.d.ts.map

package/dist/utils/error-utils.d.ts

@@ -1,6 +1,8 @@
 /**
- * Utility functions for consistent error handling across the codebase.
- * Replaces 60+ occurrences of: error instanceof Error ? error.message : String(error)
+ * Error helpers used across the codebase. Use getErrorMessage rather than
+ * writing `e instanceof Error ? e.message : String(e)` out; only code copied
+ * into compiled workflows (the durable engine, the built-in nodes, generated
+ * text) carries its own copy.
  */
 /**
  * Extracts a string message from any error value.

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

@@ -1,8 +1,8 @@
 /**
  * Shared port ordering utilities
- * Extracted from parser.ts for reuse across the codebase
+ * Extracted from parser/annotation-parser.ts for reuse across the codebase
  */
-import type { TPortDefinition } from "../ast/types.js";
+import type { TPortDefinition } from "../ast/types";
 /**
  * Check if a port is mandatory.
  * External ports: execute, onSuccess, onFailure

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

@@ -2,7 +2,7 @@
  * Port tag validation utilities
  * Shared logic for determining port tag types (@input, @output, @step)
  */
-import type { TPortDefinition } from "../ast/types.js";
+import type { TPortDefinition } from "../ast/types";
 /**
  * Check if a port name is a reserved STEP port.
  * Includes both external (execute, onSuccess, onFailure) and scoped (start, success, failure).

package/dist/validation/agent-detection.d.ts

@@ -4,7 +4,7 @@
  * Multi-signal detection to classify workflow nodes by their agent role.
  * Uses a priority hierarchy: port signatures > visual annotations > name heuristics.
  */
-import type { TNodeTypeAST } from '../ast/types.js';
+import type { TNodeTypeAST } from '../ast/types';
 /**
  * Recognized agent node roles.
  * - llm: Calls a language model (has messages/toolCalls/content ports)
@@ -17,14 +17,26 @@ export type AgentNodeRole = 'llm' | 'tool-executor' | 'human-approval' | 'memory
  * Detect the agent role of a node type using multi-signal analysis.
  *
  * Priority:
- * 1. Port signature patterns (strongest — defines the contract)
- * 2. @icon annotation (strong — explicit visual intent)
- * 3. @color annotation (weak — only used to break ties)
- * 4. Function name heuristics (weakest — fallback only)
+ * 1. Port signature patterns (strongest, defines the contract)
+ * 2. @icon annotation (strong, explicit visual intent)
+ * 3. @color annotation (weak, only used to break ties)
+ * 4. Function name heuristics (weakest, fallback only)
  *
  * @returns The detected role, or null if the node is not an agent node
  */
 export declare function detectNodeRole(nodeType: TNodeTypeAST): AgentNodeRole | null;
+/** Which signal produced a detected role, strongest first. */
+export type AgentRoleSignal = 'port' | 'icon' | 'color' | 'name';
+/**
+ * Like detectNodeRole, but also reports which signal decided it, so a rule
+ * can weigh its response. A role that rests only on `@color` or a name
+ * pattern is a guess about a cosmetic choice, not evidence that the node
+ * calls a model. Rules that would block on it should downgrade to a warning.
+ */
+export declare function detectNodeRoleSignal(nodeType: TNodeTypeAST): {
+    role: AgentNodeRole;
+    signal: AgentRoleSignal;
+} | null;
 /**
  * Convenience: find all node types in a workflow that match a specific role.
  * Returns array of [instanceId, nodeType] pairs for all instances with that role.

package/dist/validation/agent-rules.d.ts

@@ -11,7 +11,7 @@
  * 4. AGENT_LLM_NO_FALLBACK - LLM onFailure goes directly to Exit
  * 5. AGENT_TOOL_NO_OUTPUT_HANDLING - Tool executor outputs are all unconnected
  */
-import type { TValidationRule } from '../ast/types.js';
+import type { TValidationRule } from '../ast/types';
 /**
  * LLM nodes should have their onFailure port connected.
  * LLM calls are inherently unreliable (rate limits, timeouts, model errors).
@@ -20,7 +20,7 @@ import type { TValidationRule } from '../ast/types.js';
 export declare const missingErrorHandlerRule: TValidationRule;
 /**
  * Tool executors that perform actions should have a human-approval node upstream.
- * This is a warning, not an error — read-only tools may not need approval.
+ * This is a warning, not an error, because read-only tools may not need approval.
  */
 export declare const unguardedToolExecutorRule: TValidationRule;
 /**
@@ -29,17 +29,16 @@ export declare const unguardedToolExecutorRule: TValidationRule;
  */
 export declare const missingMemoryInLoopRule: TValidationRule;
 /**
- * An LLM node whose onFailure goes directly to Exit.onFailure means
- * any LLM error immediately aborts the workflow. Consider a retry or fallback.
+ * An LLM node whose onFailure goes directly to Exit.onFailure means any LLM
+ * error immediately aborts the workflow, unless the adapter explicitly declares
+ * its internal retry/fallback contract with @resilience.
  */
 export declare const llmWithoutFallbackRule: TValidationRule;
 /**
  * A tool executor whose non-STEP output ports are all unconnected means
- * tool results are computed but never used — likely a wiring mistake.
+ * tool results are computed but never used, likely a wiring mistake.
  */
 export declare const toolNoOutputHandlingRule: TValidationRule;
-/** All agent validation rules */
-export declare const agentValidationRules: TValidationRule[];
 /**
  * Get all agent validation rules.
  * Convenience function for passing to validateWorkflow().

package/dist/validation/core-rules.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Core validation rules for WorkflowValidator.
+ *
+ * Each rule is a free function taking a ValidationContext (the mutable
+ * errors/warnings arrays + mode flags) plus the workflow and any precomputed
+ * maps. WorkflowValidator.validate() builds the context and invokes these in
+ * a fixed order; the cascading-error filter there depends on that order.
+ *
+ * This module is the index of the rules. The short ones live here; the
+ * larger ones have a module of their own under ./rules/ and are re-exported:
+ *
+ * - rules/connections.ts: known endpoints, duplicates, one value per input
+ * - rules/type-compatibility.ts: data types and coercions across connections
+ * - rules/data-flow.ts: unused outputs, Exit ports, @http route params
+ * - rules/cycles.ts: loops within each scope layer
+ * - rules/scope-topology.ts: the inner graph of nodes with scoped ports
+ */
+import type { TNodeTypeAST, TWorkflowAST } from '../ast/types';
+import type { ValidationContext } from './rules/context.js';
+export type { ValidationContext } from './rules/context.js';
+export { validateConnections, validateDuplicateConnections, validateMultipleInputConnections, } from './rules/connections.js';
+export { validateTypeCompatibility } from './rules/type-compatibility.js';
+export { validateDataFlow } from './rules/data-flow.js';
+export { validateCycles } from './rules/cycles.js';
+export { validateScopeTopology } from './rules/scope-topology.js';
+export declare function validateStructure(ctx: ValidationContext, workflow: TWorkflowAST): void;
+export declare function validateDuplicateNodeNames(ctx: ValidationContext, workflow: TWorkflowAST): void;
+export declare function validateMutableBindings(ctx: ValidationContext, workflow: TWorkflowAST): void;
+export declare function validateReservedNames(ctx: ValidationContext, workflow: TWorkflowAST, nodeTypeMap: Map<string, TNodeTypeAST>): void;
+/**
+ * Scope names become identifiers in generated code (`l_<scope>_scopeFn`), so
+ * a `scope:my-scope` port would compile into a syntax error.
+ */
+export declare function validateScopeNames(ctx: ValidationContext, workflow: TWorkflowAST): void;
+export declare function validateRequiredInputs(ctx: ValidationContext, workflow: TWorkflowAST, instanceMap: Map<string, TNodeTypeAST>): void;
+export declare function detectUnusedNodes(ctx: ValidationContext, workflow: TWorkflowAST, instanceMap: Map<string, TNodeTypeAST>): void;
+export declare function validateStartAndExit(ctx: ValidationContext, workflow: TWorkflowAST): void;
+/**
+ * Cross-check @input annotations against TypeScript function signatures.
+ * Warns on optionality and type mismatches between annotations and actual code.
+ */
+export declare function validateAnnotationSignatureConsistency(ctx: ValidationContext, workflow: TWorkflowAST): void;
+export declare function validateDuplicateInstanceIds(ctx: ValidationContext, workflow: TWorkflowAST): void;
+export declare function validateVisualAnnotations(ctx: ValidationContext, workflow: TWorkflowAST, _instanceMap: Map<string, TNodeTypeAST>): void;
+export declare function validatePortTypes(ctx: ValidationContext, workflow: TWorkflowAST): void;
+export declare function validatePortConfigReferences(ctx: ValidationContext, workflow: TWorkflowAST, instanceMap: Map<string, TNodeTypeAST>): void;
+export declare function validateExpressionSyntax(ctx: ValidationContext, workflow: TWorkflowAST): void;
+export declare function validateExecuteWhen(ctx: ValidationContext, workflow: TWorkflowAST): void;
+//# sourceMappingURL=core-rules.d.ts.map

package/dist/validation/design-rules.d.ts

@@ -17,10 +17,17 @@
  * 6. DESIGN_PULL_CANDIDATE - Node with no incoming step but consumed data outputs
  * 7. DESIGN_PULL_UNUSED - Node marked pullExecution but no downstream reads its output
  */
-import type { TValidationRule } from '../ast/types.js';
+import type { TValidationRule } from '../ast/types';
 /**
  * Async nodes (network, disk, AI) can fail. If onFailure is unconnected,
- * failures may be silently swallowed or crash the workflow.
+ * a normal-mode node's failure is silently swallowed.
+ *
+ * The message says what actually happens for each mode. A normal-mode node
+ * returns `onFailure: true`, which is routed, so wiring `onFailure` handles
+ * it. An expression node fails by throwing, and the generated code marks
+ * the node failed and rethrows: the error aborts the run whether or not
+ * `onFailure` is wired. Telling an author to wire `onFailure` on an
+ * expression node would send them to a change that does nothing.
  */
 export declare const asyncNoErrorPathRule: TValidationRule;
 /**
@@ -56,6 +63,5 @@ export declare const pullCandidateRule: TValidationRule;
  * The node will never execute since pull execution requires a consumer.
  */
 export declare const pullUnusedRule: TValidationRule;
-export declare const designValidationRules: TValidationRule[];
 export declare function getDesignValidationRules(): TValidationRule[];
 //# sourceMappingURL=design-rules.d.ts.map

package/dist/validation/rule-registry.d.ts

@@ -1,11 +1,11 @@
 /**
  * ValidationRuleRegistry: dynamic dispatch for pack-contributed validation rules.
  *
- * Replaces the hardcoded `isCICDWorkflow() ? getCICDValidationRules() : []`
+ * Replaces a former hardcoded per-domain rule-set lookup
  * pattern. Each registered rule set has a detect predicate and a lazy rule loader.
  * The validate API calls `getApplicableRules(ast)` and merges results.
  */
-import type { TValidationRule, TWorkflowAST } from '../ast/types.js';
+import type { TValidationRule, TWorkflowAST } from '../ast/types';
 export type TValidationRuleSet = {
     /** Human-readable name for this rule set */
     name: string;
@@ -18,7 +18,7 @@ export type TValidationRuleSet = {
 };
 /**
  * Registry for dynamically contributed validation rule sets.
- * Core rule sets (like CI/CD) register themselves at startup.
+ * Core and pack rule sets register themselves at startup.
  * Pack-contributed rule sets are loaded from manifests.
  */
 export declare class ValidationRuleRegistry {

package/dist/validation/rules/connections.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Connection rules: every `@connect` must name real nodes and real ports, may
+ * appear once, and may be the only value flowing into a data input.
+ *
+ * These run before the type, data-flow and scope rules, which skip any
+ * connection whose endpoints do not resolve and rely on the errors here to
+ * report it. The cascading-error filter in WorkflowValidator.validate() also
+ * drops the UNKNOWN_SOURCE_NODE / UNKNOWN_TARGET_NODE errors raised here when
+ * the node's type itself is unknown.
+ */
+import type { TNodeTypeAST, TWorkflowAST } from '../../ast/types';
+import type { ValidationContext } from './context.js';
+/**
+ * Every connection must join known nodes through ports they declare. Per
+ * connection the errors come in a fixed order: source node, target node,
+ * source port, target port.
+ */
+export declare function validateConnections(ctx: ValidationContext, workflow: TWorkflowAST, instanceMap: Map<string, TNodeTypeAST>): void;
+/** The same `from.port -> to.port` pair written twice is an error on the second copy. */
+export declare function validateDuplicateConnections(ctx: ValidationContext, workflow: TWorkflowAST): void;
+/**
+ * Validate that no input port has multiple connections.
+ * Only one value can be received per input port.
+ * (STEP ports can have multiple connections as they're control flow)
+ */
+export declare function validateMultipleInputConnections(ctx: ValidationContext, workflow: TWorkflowAST, instanceMap: Map<string, TNodeTypeAST>): void;
+//# sourceMappingURL=connections.d.ts.map

package/dist/validation/rules/context.d.ts

@@ -0,0 +1,11 @@
+import type { TValidationError } from '../../ast/types';
+/**
+ * Mutable state shared across validation rules.
+ */
+export interface ValidationContext {
+    errors: TValidationError[];
+    warnings: TValidationError[];
+    strictMode: boolean;
+    draftMode: boolean;
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/validation/rules/cycles.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Cycle detection. The generated code runs nodes in topological order, so a
+ * loop between nodes has no order to run in; iteration belongs in a scoped
+ * node (forEach and the like), which runs its children once per item.
+ *
+ * Each scope layer (the root, and every parent's children) is checked on its
+ * own, over the connections whose ends share that layer. A node connected to
+ * itself is allowed (an iteration pattern) and never starts a reported loop.
+ * The same loop found from several entry points is reported once.
+ */
+import type { TWorkflowAST } from '../../ast/types';
+import type { ValidationContext } from './context.js';
+/**
+ * Validate for cycles (loops) in the workflow graph, one scope layer at a time.
+ */
+export declare function validateCycles(ctx: ValidationContext, workflow: TWorkflowAST): void;
+//# sourceMappingURL=cycles.d.ts.map

package/dist/validation/rules/data-flow.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Data flow: values that are produced but go nowhere, and workflow outputs
+ * that nothing produces or that several producers race for.
+ *
+ * Checks, in order:
+ * - unused output ports: data a node produces that no connection reads
+ * - unreachable Exit ports: a declared return value with no incoming connection
+ * - multiple connections into one Exit data port, unless the sources sit on
+ *   opposite branches (onSuccess / onFailure) of the same branching node, so
+ *   at most one of them runs
+ * - `@http` route `:params` that name no workflow parameter
+ */
+import type { TNodeTypeAST, TWorkflowAST } from '../../ast/types';
+import type { ValidationContext } from './context.js';
+/**
+ * Validate data flow in the workflow. See the module comment for the checks.
+ */
+export declare function validateDataFlow(ctx: ValidationContext, workflow: TWorkflowAST, instanceMap: Map<string, TNodeTypeAST>): void;
+//# sourceMappingURL=data-flow.d.ts.map

package/dist/validation/rules/scope-topology.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Scope topology: the inner graph of nodes with scoped ports.
+ *
+ * A node type with scoped ports (forEach and the like) runs its children as a
+ * callback, once per scope invocation. Its scoped OUTPUT ports become the
+ * callback's parameters (data flowing to the children) and its scoped INPUT
+ * ports the callback's return value (data flowing back). The children run in
+ * that callback's context and nowhere else, so the connections around them
+ * must respect the boundary or the generated code has nothing to read.
+ *
+ * Checks, in order:
+ * - an instance listed in two scopes of `workflow.scopes` (error)
+ * then for each instance with scoped ports:
+ * - a `:scope` qualifier naming a scope the node does not define (error)
+ * - and for each of its scopes:
+ *   - a scope with no children (warning, nothing more is checked for it)
+ *   - scoped connections naming a parent port that does not exist, or that
+ *     belongs to another scope or to none (error)
+ *   - scoped connections leaving the scope (error)
+ *   - data type mismatches between parent and child ports (warning)
+ *   - children with unconnected required inputs (error)
+ *   - scoped input ports nothing returns into (warning)
+ *   - children with no scoped connection to or from the parent (warning)
+ * and last, over all plain connections:
+ * - connections that cross the boundary of a per-port scope (error). Flat
+ *   grouping scopes, whose parent has no scoped ports, may be crossed.
+ */
+import type { TNodeTypeAST, TWorkflowAST } from '../../ast/types';
+import type { ValidationContext } from './context.js';
+/**
+ * Validate the inner graph topology of nodes that have scoped ports. See the
+ * module comment for the checks and their order.
+ */
+export declare function validateScopeTopology(ctx: ValidationContext, workflow: TWorkflowAST, instanceMap: Map<string, TNodeTypeAST>): void;
+//# sourceMappingURL=scope-topology.d.ts.map

package/dist/validation/rules/type-compatibility.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Type compatibility of data connections, with coercion support.
+ *
+ * A connection carries a value from an output port to an input port, and the
+ * generated code passes it through as is, or through the `as <type>` coercion
+ * the author wrote. This rule says when that value may not be what the target
+ * expects, so the author sees it before run time.
+ *
+ * Checks, in order, stopping at the first that settles the connection:
+ * - STEP ports connect only to STEP ports (error)
+ * - no `as <type>` on FUNCTION ports (error)
+ * - same data type: a coercion is redundant; OBJECT ports compare their tsType
+ * - ANY on either side is always compatible
+ * - an explicit coercion must produce the target type
+ * - safe coercions (NUMBER to STRING, BOOLEAN to STRING) pass silently
+ * - lossy coercions (STRING to NUMBER, OBJECT to STRING, ...) warn
+ * - unusual coercions (NUMBER to BOOLEAN, STRING to OBJECT, ...) warn
+ * - every other pair is a TYPE_MISMATCH warning
+ *
+ * With `@strictTypes` on the workflow, or strict mode, the last four are
+ * reported as TYPE_INCOMPATIBLE errors instead of warnings.
+ */
+import type { TNodeTypeAST, TWorkflowAST } from '../../ast/types';
+import type { ValidationContext } from './context.js';
+/**
+ * Validate type compatibility for connections with coercion support.
+ * See the module comment for the order of checks.
+ */
+export declare function validateTypeCompatibility(ctx: ValidationContext, workflow: TWorkflowAST, instanceMap: Map<string, TNodeTypeAST>): void;
+//# sourceMappingURL=type-compatibility.d.ts.map

package/dist/validation/type-checker.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Type Checker Module
+ *
+ * String-based type compatibility checking for port connections. Ports carry
+ * their TypeScript type as text (the AST is serialisable), so the checks here
+ * work on that text.
+ */
+import type { TTypeCompatibility } from "../ast/types";
+/**
+ * Safe runtime coercions that JavaScript handles automatically, as
+ * source -> target data type pairs. A connection between these types needs no
+ * warning: Number.toString() and Boolean.toString() are predictable.
+ */
+export declare const SAFE_COERCIONS: ReadonlyArray<readonly [string, string]>;
+/**
+ * Check if a source type can be safely coerced to a target type at runtime.
+ * Accepts data types (`NUMBER`) and TypeScript primitives (`number`) alike.
+ *
+ * @param sourceText - The source type as a string
+ * @param targetText - The target type as a string
+ * @returns true if the coercion is safe
+ */
+export declare function isRuntimeCoercible(sourceText: string, targetText: string): boolean;
+/**
+ * True for a type text that names "some object" without describing its shape.
+ * Whitespace is ignored so `Record<string, unknown>` and `Record<string,unknown>`
+ * are the same type.
+ */
+export declare function isOpaqueObjectType(typeText: string): boolean;
+/**
+ * Check type compatibility using string representations.
+ * Fallback for JSON-loaded workflows without ts-morph Type objects.
+ *
+ * @param sourceText - The source type as a string
+ * @param targetText - The target type as a string
+ * @returns TTypeCompatibility result
+ */
+export declare function checkTypeCompatibilityFromStrings(sourceText: string, targetText: string): TTypeCompatibility;
+//# sourceMappingURL=type-checker.d.ts.map

package/dist/validation/validator-helpers.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Pure, state-free helpers shared by the validation rules.
+ *
+ * Nothing here depends on validator instance state (errors, warnings, mode).
+ */
+import type { TNodeTypeAST, TWorkflowAST, TSourceLocation, TConnectionAST, TNodeInstanceAST, TCoerceTargetType } from '../ast/types';
+/** The data type each `@connect ... as <type>` coercion produces. */
+export declare const COERCE_OUTPUT_TYPE: Record<TCoerceTargetType, string>;
+/** The `as <type>` that produces a given data type, for suggestions. `json` also gives STRING and is never suggested. */
+export declare const COERCE_TYPE_FOR_DATA_TYPE: Record<string, TCoerceTargetType>;
+/** Suggest the correct `as <type>` for a given target dataType. */
+export declare function suggestCoerceType(targetType: string): string;
+/** Resolve a node instance to its node type definition, by name or function name. */
+export declare function resolveNodeType(ast: TWorkflowAST, instance: TNodeInstanceAST): TNodeTypeAST | undefined;
+/** All outgoing connections from a node, or from one of its ports when `portName` is given. */
+export declare function getOutgoing(ast: TWorkflowAST, nodeId: string, portName?: string): TConnectionAST[];
+/** Look up instance sourceLocation by instance ID. */
+export declare function getInstanceLocation(workflow: TWorkflowAST, instanceId: string): TSourceLocation | undefined;
+/** Look up connection sourceLocation. */
+export declare function getConnectionLocation(conn: TConnectionAST): TSourceLocation | undefined;
+/** Format a data type for display, including its TS type when available. */
+export declare function formatType(dataType: string, tsType?: string): string;
+/** Normalize a type string for case-insensitive, whitespace-insensitive compare. */
+export declare function normalizeTypeString(type: string): string;
+/**
+ * Determine whether the given source nodes are mutually exclusive — i.e. they
+ * all trace back to different branches (onSuccess/onFailure) of the same
+ * branching ancestor, so at most one executes.
+ */
+export declare function areMutuallyExclusive(sourceNodes: string[], workflow: TWorkflowAST, instanceMap: Map<string, TNodeTypeAST>): boolean;
+//# sourceMappingURL=validator-helpers.d.ts.map

package/dist/validation/validator.d.ts

@@ -0,0 +1,30 @@
+import type { TNodeTypeAST, TWorkflowAST, TValidationError } from '../ast/types';
+export type { TValidationError } from '../ast/types';
+export declare class WorkflowValidator {
+    private ctx;
+    /**
+     * The scope-name problems of a single node type, as messages. The same
+     * check runs inside validate() as the INVALID_SCOPE_NAME rule; this is the
+     * standalone form for callers that hold a node type and no workflow.
+     *
+     * Scoped OUTPUT ports become callback parameters (data flows to children)
+     * and scoped INPUT ports become callback return values (data flows from
+     * children); the ports may carry any data type.
+     */
+    validateNodeType(nodeType: TNodeTypeAST): string[];
+    /**
+     * Validate a workflow: resolve its instances, run the core rules in their
+     * fixed order, then post-process the diagnostics (drop cascading errors,
+     * demote stub errors in draft mode, apply suppressions, attach doc URLs).
+     */
+    validate(workflow: TWorkflowAST, options?: {
+        strictMode?: boolean;
+        mode?: 'strict' | 'draft';
+    }): {
+        valid: boolean;
+        errors: TValidationError[];
+        warnings: TValidationError[];
+    };
+}
+export declare const validator: WorkflowValidator;
+//# sourceMappingURL=validator.d.ts.map