feat(worker-bottomup): graph_migration_wf Hatchet workflow (Phase 7 #57)

[charlie83Gs]

Summary

The durable Hatchet workflow that wraps the Phase 7 primitives
(`begin_migration` / `run_hop` / `commit_migration` / `fail_migration`)
with per-hop commits, so a worker crash mid-plan leaves earlier audit
rows + flipped graph state persisted, and the next dispatch resumes via
`run_hop`'s idempotent-replay path.

The executor helper (`kt_db.migration_executor.execute_migration`) is a
single-session composition — no between-hop commits, so it can't give
crash durability. The workflow layer is exactly where that durability
lives. This PR re-composes the primitives around per-hop sessions.

Orchestration body lives in `run_graph_migration` (framework-agnostic)
so integration tests hit it directly against a real DB without Hatchet.

What's here

• `GraphMigrationInput` / `GraphMigrationOutput` Pydantic models in
  `kt_hatchet.models`
• `run_graph_migration` helper + `graph_migration_wf` Hatchet task in
  `services/worker-bottomup/src/kt_worker_bottomup/workflows/graph_migration.py`
• Registered on the orchestrator worker and `worker-all`
• 7 integration tests:
  • `test_single_hop_success_commits_per_hop` — fresh session after run proves persistence
  • `test_multi_hop_success_audit_rows_visible_between_hops` — hop2 peeks at hop1's committed row mid-plan
  • `test_failure_stamps_last_applied_and_error_state` — v2 not v3, status=error, read_only
  • `test_remigrate_resumes_and_skips_completed_hops` — first-run hop1 audit row makes second-run short-circuit
  • `test_unknown_plugin_fails_cleanly` — no graph state touched
  • `test_already_at_target_is_noop` — no read_only flip
  • `test_target_ahead_of_plugin_trims_plan` — dispatcher/plugin drift

Test plan

• `uv run --project services/worker-bottomup pytest services/worker-bottomup/tests/integration/ -x` — 7/7
• `uv run --project services/worker-bottomup pytest services/worker-bottomup/tests/test_bottom_up.py services/worker-bottomup/tests/test_wave_planner.py -x` — 34/34
• CI green

What's NOT here (follow-ups)

• feat(worker-synthesis): store synthesis errors and add regeneration #58 startup auto-dispatch — calls `plan_auto_dispatch` and dispatches this workflow per plan
• feat: add Knowledge Tree logo across all sites #59 `POST /graphs/{slug}/re-migrate` — API trigger for the workflow
• feat: differentiate sites with unique logo background colors #60 `DefaultGraphTypePlugin` v2 bump + noop migration — first real use
• docs: add early development disclaimers and README #62 End-to-end test through the full auto-dispatch → workflow pipe
• chore: replace personal email and add docker-compose dev warning #63 Umbrella PR fix(ci): set allow_zero_version and reset to 0.1.0 #7

🤖 Generated with Claude Code

[charlie83Gs]

Applied review fixes in 00df51b:

Bug 1 — failed audit row never persisted: Fixed in the workflow by catching inside the session's async-with, committing the flushed failed-row write, then re-raising into the outer handler that does fail_migration. New test test_failed_hop_persists_failed_audit_row reads the audit row from a fresh session to prove durability (exactly what the history API endpoint does).

Bug 2 — trimmed plan stamped wrong version: Fixed by adding an up-front abort when target_version > plugin.current_version. The graph stays untouched (no begin_migration, no audit rows, no read_only flip). Dispatcher is expected to re-dispatch at the real plugin.current_version. Updated test test_target_ahead_of_plugin_aborts_before_any_hop asserts the abort end-to-end: result.success=False, final_version=1, error mentions "tops out at v2", migration.calls == [], and the graph row is unchanged.

Bug 3 — misleading comment: Removed. Per-hop refresh_timeout wiring isn't needed for the no-op migrations we have today; can add via a callback param if we start seeing long-running hops.

Reviewer's minors:

• Whole-workflow advisory-lock gap: noted — find_in_flight_for_graph mitigates at the dispatcher side (PR feat(kt-db): startup auto-dispatch for out-of-date graphs (Phase 7 #58) #269).
• repr(exc) SSE sanitization: leaving as-is for the internal operator stream.
• PipelineContext reuse across hops: confirmed stateless — WorkerCoreServices opens its own sessions per graph_engine() / write_engine() call, nothing cached between hops.

All 8 tests in test_graph_migration_workflow.py pass.

[github-actions]

Thank you for your submission, we really appreciate it. Like many open-source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution. You can sign the CLA by just posting a Pull Request Comment same as the below format.

---

I have read the CLA Document and I hereby sign the CLA

---

_{You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.}