Investigation: workflow engine boundary is overcomplicated (executor.ts + dag-executor.ts)

Issue: Draft
Type: ARCHITECTURE
Investigated: 2026-04-12

Problem

The workflow execution layer is carrying too many concerns across two overlapping entrypoints:

• packages/workflows/src/executor.ts
• packages/workflows/src/dag-executor.ts

Today the engine owns:

• execution order / orchestration
• provider resolution and capability warnings
• platform message delivery
• tool-call formatting
• approval / cancel / timeout handling
• workflow event persistence
• structured-output fallback behavior
• retry classification

This makes workflow behavior harder to extend safely, and it duplicates policy in more than one place. The biggest smell is that both executor.ts and dag-executor.ts define their own safe message-delivery wrappers and adjacent execution policy.

First Principles

The workflow engine should primarily own:

1. node scheduling
2. state transitions
3. execution results

It should not also be the place where platform delivery policy, provider-specific user warnings, and every edge-case message path are embedded.

Evidence

• Duplicate message delivery primitives:
  • executor.ts
  • dag-executor.ts
• Provider resolution and workflow/platform concerns are mixed in the DAG layer:
  • dag-executor.ts
  • dag-executor.ts
  • dag-executor.ts
• dag-executor.ts is very large and now serves as both engine and delivery adapter:
  • file length ~2779 LOC

Desired End State

Split the workflow execution system into clearer layers:

1. execution kernel

   • node ordering
   • dependency handling
   • retries / cancellation semantics
   • execution results

2. provider execution adapter

   • invoke providers
   • consume normalized MessageChunks
   • map provider outcomes into node results

3. platform delivery layer

   • best-effort message sending
   • tool formatting
   • SSE / chat delivery policy
   • user-facing warnings

This does not require a rewrite. The goal is to stop accumulating more delivery/policy logic inside the engine.

Scope

In scope:

• reduce duplication between executor.ts and dag-executor.ts
• extract shared message-delivery policy
• make workflow-engine responsibilities more explicit
• keep provider-specific logic out of the scheduling layer

Out of scope:

• changing workflow YAML semantics
• provider registry / Phase 2 work
• large UI changes

Acceptance Criteria

• shared workflow delivery logic is not duplicated across executor.ts and dag-executor.ts
• engine code is easier to read as execution/state logic first
• provider-agnostic workflow behavior remains preserved
• tests continue to cover retries, approvals, cancellation, and structured output

Validation

bun run type-check
bun --filter @archon/workflows test
bun run lint

Metadata

• Investigated by: Codex
• Timestamp: 2026-04-12
• Artifact: .claude/PRPs/issues/issue-workflow-engine-boundary-refactor.md