Architecture Boundaries
=======================

This page captures the intended separation of concerns in workflow orchestration.

Primary boundaries
------------------

- ``design_research_agents.workflow``: public construction surface for composing
  new workflow implementations from typed step objects.
- ``Workflow``: reusable facade for constructor-first step graphs with explicit
  input contracts and workflow-first output envelopes.
- ``WorkflowRuntime``: deterministic typed-step execution engine used by
  ``Workflow``.
- ``design_research_agents.patterns``: public prebuilt implementations built
  from workflow primitives.

Step primitives
---------------

- ``LogicStep``: deterministic local logic and optional branching map.
- ``ToolStep``: single tool call via ``ToolRuntime``.
- ``DelegateStep``: single delegate invocation via direct ``delegate`` object.
- ``LoopStep``: iterative nested workflow body with state transitions.
- ``DelegateBatchStep``: explicit multi-delegate fan-out step.
- ``MemoryReadStep`` and ``MemoryWriteStep``: workflow-native memory primitives.

Allowed composition patterns
----------------------------

- Use ``Workflow`` + step primitives to define reusable topology once and run
  repeatedly.
- Use ``design_research_agents.patterns`` when you want a prebuilt workflow
  implementation instead of authoring a graph from scratch.
- Keep prompt/model/tool policy concerns in step callbacks/delegates or pattern
  classes, not in workflow scheduling internals.

Anti-patterns to avoid
----------------------

- Mixing prebuilt pattern exports into the workflow construction module.
- Encoding loop-state schema assumptions ad hoc inside multiple modules.
- Adding duplicate request-id/dependency helper functions across prebuilt
  pattern implementations.
- Coupling deterministic example harness behavior to script filenames only.