Move inputDefaults under core/primitives

Author: j-sanaa

packages/agentflow/.eslintrc.js

@@ -119,8 +119,8 @@ module.exports = {
                     {
                         target: './src/atoms',
                         from: './src/core',
-                        except: ['./types', './theme', './utils'],
-                        message: 'Atoms can only import from core/types, core/theme, and core/utils.'
+                        except: ['./types', './theme', './primitives'],
+                        message: 'Atoms can only import from core/types, core/theme, and core/primitives.'
                     },
                     // core/ cannot import from anything (leaf node)
                     {

packages/agentflow/ARCHITECTURE.md

@@ -42,7 +42,7 @@ atoms/
 -   No API calls
 -   Stateless or minimal local state
 -   Imported by features, never the reverse
--   **Forbidden**: Importing from `features/` or `infrastructure/` (except types from `core/types` for prop definitions, design tokens from `core/theme`, and utilities from `core/utils`)
+-   **Forbidden**: Importing from `features/` or `infrastructure/` (except types from `core/types` for prop definitions, design tokens from `core/theme`, and primitives from `core/primitives`)
 
 **Goal:** 100% visual consistency.
 
@@ -110,6 +110,9 @@ features/
 core/
 ├── types/                  # Global interfaces (Node, Edge, Flow)
 │   └── index.ts
+├── primitives/             # Domain-free utilities (safe for atoms)
+│   ├── inputDefaults.ts    # getDefaultValueForType
+│   └── index.ts
 ├── node-config/            # Node configuration (icons, colors, default types)
 │   ├── nodeIcons.ts        # AGENTFLOW_ICONS, DEFAULT_AGENTFLOW_NODES
 │   └── ...
@@ -124,7 +127,7 @@ core/
 │   ├── flowValidation.ts   # validateFlow, validateNode
 │   ├── connectionValidation.ts  # isValidConnectionAgentflowV2
 │   └── ...
-├── utils/                  # Generic utilities
+├── utils/                  # Domain-aware utilities (NOT importable by atoms)
 │   ├── nodeFactory.ts      # initNode, getUniqueNodeId
 │   └── ...
 └── index.ts                # Barrel export (use sparingly)
@@ -138,6 +141,15 @@ core/
 -   Pure functions where possible
 -   Can be tested in isolation
 
+#### `core/primitives/` vs `core/utils/`
+
+`core/` contains two utility directories with different import permissions:
+
+-   **`primitives/`** — Domain-free, general-purpose functions with no knowledge of nodes, flows, or any business concept. These are pure data transformations (e.g., computing a default value from a type string). **Safe to import from `atoms/`.**
+-   **`utils/`** — Domain-aware utilities that understand node structures, flow data, or validation logic (e.g., `initNode`, `buildDynamicOutputAnchors`). **Only importable by `features/` and `infrastructure/`.**
+
+When adding a new utility, ask: _"Does this function need to know what a Node or Flow is?"_ If no → `primitives/`. If yes → `utils/`.
+
 **Goal:** To be the framework-agnostic source of truth.
 
 ---
@@ -210,7 +222,7 @@ infrastructure/
 
 -   `features` → `atoms`, `infrastructure`, `core` ✅
 -   `infrastructure` → `core` ✅
--   `atoms` → `core/types` and `core/theme` only (for type definitions and design tokens) ✅
+-   `atoms` → `core/types`, `core/theme`, and `core/primitives` only ✅
 -   `core` → nothing (leaf node) ✅
 -   **Atoms and Core are "leaf" nodes** - they cannot import from `features/` or `infrastructure/`
 

packages/agentflow/src/atoms/ArrayInput.tsx

@@ -4,8 +4,8 @@ import { Box, Button, Chip, IconButton } from '@mui/material'
 import { useTheme } from '@mui/material/styles'
 import { IconPlus, IconTrash } from '@tabler/icons-react'
 
+import { getDefaultValueForType } from '@/core/primitives'
 import type { InputParam, NodeData } from '@/core/types'
-import { getDefaultValueForType } from '@/core/utils/inputDefaults'
 
 import { type AsyncInputProps, type ConfigInputComponentProps, NodeInputHandler } from './NodeInputHandler'
 import { useStableKeys } from './useStableKeys'

packages/agentflow/src/atoms/ConditionBuilder.tsx

@@ -4,8 +4,8 @@ import { Box, Button, Chip, IconButton, Typography } from '@mui/material'
 import { useTheme } from '@mui/material/styles'
 import { IconPlus, IconTrash } from '@tabler/icons-react'
 
+import { getDefaultValueForType } from '@/core/primitives'
 import type { InputParam, NodeData } from '@/core/types'
-import { getDefaultValueForType } from '@/core/utils/inputDefaults'
 
 import { NodeInputHandler } from './NodeInputHandler'
 import { useStableKeys } from './useStableKeys'

packages/agentflow/src/core/primitives/index.ts

@@ -0,0 +1,2 @@
+// Domain-free utility functions safe for use in any layer (including atoms)
+export { getDefaultValueForType } from './inputDefaults'

…low/src/core/utils/inputDefaults.test.ts …rc/core/primitives/inputDefaults.test.tspackages/agentflow/src/core/utils/inputDefaults.test.ts renamed to packages/agentflow/src/core/primitives/inputDefaults.test.ts packages/agentflow/src/core/utils/inputDefaults.test.ts renamed to packages/agentflow/src/core/primitives/inputDefaults.test.ts

@@ -9,6 +9,3 @@ export { evaluateFieldVisibility, evaluateParamVisibility, stripHiddenFieldValue
 
 // Dynamic output anchor utilities
 export { buildDynamicOutputAnchors, parseOutputHandleIndex } from './dynamicOutputAnchors'
-
-// Input default value utilities
-export { getDefaultValueForType } from './inputDefaults'

…gentflow/src/core/utils/inputDefaults.ts …low/src/core/primitives/inputDefaults.tspackages/agentflow/src/core/utils/inputDefaults.ts renamed to packages/agentflow/src/core/primitives/inputDefaults.ts packages/agentflow/src/core/utils/inputDefaults.ts renamed to packages/agentflow/src/core/primitives/inputDefaults.ts

@@ -1,7 +1,7 @@
+import { getDefaultValueForType } from '../primitives'
 import type { FlowNode, NodeData, OutputAnchor } from '../types'
 
 import { buildDynamicOutputAnchors } from './dynamicOutputAnchors'
-import { getDefaultValueForType } from './inputDefaults'
 
 /**
  * Map from NodeData.type to the ReactFlow node type key.

packages/agentflow/src/core/utils/index.ts

@@ -6,8 +6,9 @@ import { alpha, useTheme } from '@mui/material/styles'
 import { IconSettings } from '@tabler/icons-react'
 
 import { type AsyncInputProps, NodeInputHandler } from '@/atoms'
+import { getDefaultValueForType } from '@/core/primitives'
 import type { InputParam, NodeData } from '@/core/types'
-import { evaluateFieldVisibility, getDefaultValueForType, initNode } from '@/core/utils'
+import { evaluateFieldVisibility, initNode } from '@/core/utils'
 import { useApiContext } from '@/infrastructure/store'
 
 // ─── Props ────────────────────────────────────────────────────────────────────