feat(workflow): add engine core — execution model, graph, and node registry (Part 2)

[kalenkevich]

Please ensure you have read the contribution guide before creating a pull request.

Link to Issue or Description of Change

1. Link to an existing issue (if applicable):

• Related: Support for Workflows #366

2. Or, if no issue exists, describe the change:

Problem:
Continuing the split of the large feature/workflows branch into small, stacked, reviewable PRs. The workflow engine's core files form a tightly-connected import cycle (graph → graph_parser → workflow_graph_utils → concrete node classes → base_node → node_context → graph), which would otherwise force the entire engine and every node type to land in one giant PR.

Solution:
This is Part 2 of 9 — the engine core — stacked on Part 1. It adds the execution model, the graph layer, and a decoupling refactor that breaks the cycle so each node family can ship as its own downstream PR.

Stacked on: #part1_pr_number (Part 1 — events & shared primitives). Please merge Part 1 first.

Included:

• base_node.ts — the BaseNode abstract class and the START sentinel.
• node_context.ts / node_runner.ts — per-node execution context and the run loop (retry, timeout/cancellation, streaming via EventChannel).
• graph.ts + utils/graph_parser.ts + utils/graph_validation.ts — chain/edge parsing, routing maps, and structural validation (START reachability, duplicate node names/edges, DEFAULT_ROUTE rules, unconditional-cycle detection).
• schedule_dynamic_node.ts — the dynamic-scheduling primitive node_context depends on.
• request_input.ts + utils/hitl_utils.ts — the human-in-the-loop request primitives BaseNode consumes (the HITL processors/tools that use them arrive in Part 8).

Decoupling refactor (the key change to review):
utils/workflow_graph_utils.ts no longer statically imports the concrete node classes (FunctionNode, ToolNode, ParallelWorker, LLMAgentWrapper). Instead, buildNode() / isNodeLike() consult a self-registration registry:

• registerNodeBuilder({match, build}) — node modules register how to build themselves from a NodeLike value.
• registerParallelWorkerFactory(...) — the parallel worker registers its wrapping behavior.
• The 'START' sentinel and existing BaseNode instances remain built-in (no registration needed).

Node modules self-register at import time (added in Parts 3+); the public workflow barrel (Part 6) imports them all, so registration is guaranteed for real usage. This breaks the engine↔nodes cycle without changing observable behavior.

Builds on Part 1's review-driven APIs: the engine streams events through the shared AsyncQueue (Part 1 folded EventChannel into it), resolves branches via the createSubBranch util function, and reads BaseNode.preparedRetryConfig (retry config normalized once at construction) so the run loop never re-normalizes or throws mid-retry.

Note for reviewers (follow-up in a later part): because BaseTool also exposes runAsync, the agent builder's match predicate must exclude tools so the original tool-before-agent precedence is preserved regardless of registration order. This is handled where the agent builder is added (Part 7).

Intentionally deferred: the node() user API (node.ts) lands with the first concrete node builders in Part 3; node/tool/parallel/agent node classes in Parts 3, 4, 7; the node_api_test and routing_test suites move to Part 6 because they require concrete nodes and the runner.

Testing Plan

Unit Tests:

• I have added or updated unit tests for my change.
• All unit tests pass locally.

Bundled tests (28): workflow/node_execution_test.ts, workflow/graph_parser_test.ts, workflow/graph_validation_test.ts (plus shared workflow/test_helpers.ts). They exercise the engine using test-local BaseNode subclasses, so they validate the core without any concrete node types registered.

$ npx vitest run --project unit:core \
    core/test/workflow/node_execution_test.ts \
    core/test/workflow/graph_parser_test.ts \
    core/test/workflow/graph_validation_test.ts

 ✓ core/test/workflow/graph_validation_test.ts (9 tests)
 ✓ core/test/workflow/graph_parser_test.ts     (10 tests)
 ✓ core/test/workflow/node_execution_test.ts   (9 tests)

 Test Files  3 passed (3)
      Tests  28 passed (28)

Typecheck is clean: npx tsc --noEmit -p core/tsconfig.json.

Manual End-to-End (E2E) Tests:

N/A — no user-facing surface yet (the node() API and public barrel arrive in Parts 3 and 6). End-to-end coverage lands with the runner integration in Part 6.

Checklist

• I have read the CONTRIBUTING.md document.
• I have performed a self-review of my own code.
• I have commented my code, particularly in hard-to-understand areas.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes.
• I have manually tested my changes end-to-end.
• Any dependent changes have been merged and published in downstream modules.

Additional context

[AmaadMartin]

Reviewed the Part 2 delta only (base is feat/workflows_part1). The timeout cancellation in runOnce is genuinely well done — the abort-signal plumbing, the single reused aborted promise so no listener leaks per step, and the iterator.return() in finally are all correct, and node_execution_test.ts:230 proves post-deadline events are dropped rather than leaking into the next node. I also checked two things the stack made me suspicious of and both are clean: the for (;;) retry loop is bounded by maxAttempts ?? DEFAULT_MAX_ATTEMPTS (utils/retry_utils.ts:51-55), and everything the engine writes — event.output, event.actions.agentState, functionCall.args — is already in PRESERVE_KEYS (events/event.ts:359), so nothing gets key-mangled on a session round-trip. The findings below cluster on three things: a graph that is fully usable before it is validated, module-global registry state, and instanceof where this package already has a copy-safe guard pattern.

[AmaadMartin]

Re-reviewed at b136d83b. Eight of the ten findings from my earlier pass are genuinely fixed, and I verified each against the head tree rather than trusting the commit subjects:

• Graph is validated before use — validateGraph now runs on the construction path and populates terminalNodeNames, so a malformed graph fails at build time instead of silently yielding an empty terminal set.
• instanceof is gone — replaced with brand symbols on nodes, edges and RequestInput. Every remaining occurrence of the word is a doc comment explaining why the brand is used instead, which is exactly the cross-package-copy argument from #364. The HITL path was the load-bearing one and it is now copy-safe.
• Route keys match symmetrically — String(route) on both sides, so a numeric-looking string key can no longer normalize into a value the matcher never compares equal to. The residual ambiguity ('2' vs 2 being indistinguishable) is documented at the type rather than left implicit, which is the right call.
• Retry no longer leaks partial writes — actions.stateDelta is cleared alongside output/route/interrupts, so a failed attempt cannot commit state.
• The double cast and lossy spread in the sub-branch path are gone, and enrichEvent no longer clobbers nodeInfo.path.

CI is green on ubuntu/macOS/Windows — I checked the individual jobs rather than the rollup, since a rollup on this repo can read green when only check-changes and the CLA actually ran.

Approving, with two things I would not want lost — neither blocks this part, but both get harder to change once Parts 3-8 stack on it:

1. No runtime step cap. The cycle rule permits routed cycles, and the validation doc no longer claims a conditional edge prevents an infinite loop — correct, but nothing bounds iterations at run time either. This is invisible today because the engine is not user-reachable until the runner lands in Part 5; it becomes reachable exactly when it does. A scheduler-level max-steps guard is a small localized change now and an awkward one later.
2. The node registry is still process-global. The new guard against registering a conflicting parallelWorkerFactory removes the worst failure mode, so this is no longer a correctness trap — but two workflows in one process still share builder state, and nothing scopes it per workflow.

Worth filing #1 against Part 5 so it is not discovered by an agent that loops.