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.
Problem
src/hermes_workflows/engine.pyis 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
WorkflowEngineas 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 codecsoutbox.py— command schema, lease/claim/renew/complete/fail behaviordecider.pyorruntime.py— workflow replay/activation logicreview_queue.py— review/approval request lifecyclechild_workflows.py— child workflow/generation orchestrationstatus_projection.py— workflow status/read projectionssqlite_schema.py— migrations/indexes/backcompat schema managementScope / 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
WorkflowEngineremains the public facade and existing public APIs keep working.engine.pyinto named modules.