# Node implementation rules

These instructions apply to `nodes/` and override broader guidance where more specific.

- Preserve released node IDs, input IDs, output order, and widget ordering unless a tested workflow migration is included.
- Root `NODE_CLASS_MAPPINGS` in `../__init__.py` is the canonical public registry. Keep `nodes/__init__.py` exports synchronized with it.
- V1 and V3 nodes currently coexist. Follow the API style already used by the target node; do not migrate unrelated nodes opportunistically.
- V3 `node_id` must match the root mapping key. Return `io.NodeOutput` from V3 execution methods.
- Validate user inputs before uploads or paid API calls. Check interruption during polling, retries, and long downloads.
- Do not store API keys or resolved authorization data in node attributes that can enter serialized workflows.
- Put reusable HTTP behavior, retry logic, uploads, media validation, and response parsing in `clients/` or `utils/`.
- If widget layout changes, update `../web/js/migrateWorkflow.js` and add a regression test for legacy `widgets_values`.
- Add new node tests under `../tests/` and run them through `../tests/run_all.py`.