Skip to content

Refactor WorkflowEngine into deep runtime domain modules #94

Description

@skylarbpayne

Problem

src/hermes_workflows/engine.py is doing too much for a launch/post-launch runtime core. It currently mixes the workflow facade, decider/replay behavior, SQLite schema/migrations, event append/read paths, command outbox leasing, Review Queue/approval state, child workflow orchestration, and status projections.

That makes the code harder to understand, harder to modify safely, and harder to explain as a clean domain model.

Desired outcome

Keep WorkflowEngine as a small orchestration facade and split the runtime into deep, domain-focused modules with explicit boundaries.

Suggested target modules:

  • event_store.py — event persistence/read APIs and typed event codecs
  • outbox.py — command schema, lease/claim/renew/complete/fail behavior
  • decider.py or runtime.py — workflow replay/activation logic
  • review_queue.py — review/approval request lifecycle
  • child_workflows.py — child workflow/generation orchestration
  • status_projection.py — workflow status/read projections
  • sqlite_schema.py — migrations/indexes/backcompat schema management

Scope / notes

This is a post-launch hardening/refactor issue, not a launch blocker. Avoid changing external behavior in the first slice. Prefer extraction with characterization tests over semantic rewrites.

Acceptance criteria

  • WorkflowEngine remains the public facade and existing public APIs keep working.
  • Persistence/event/outbox/review/status concerns are moved out of the monolithic engine.py into named modules.
  • Existing test suite passes unchanged or with only test import updates.
  • Add/keep regression coverage for workflow start/resume, worker command leasing, Review Queue/approval resume, child workflows, and status projection.
  • Docs/comments explain the new domain boundaries.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestroadmapPlanned or possible future workruntimeWorkflow runtime behavior

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions