refactor: composition root, per-cycle regime, tests, docs

uv migrations

add core logic