feat(kt-db): find_out_of_date_graphs helper (Phase 7 #58)

[charlie83Gs]

Summary

Pure-ish helper for the Phase 7 startup auto-dispatch hook. Given a DB session + plugin registry, returns every active graph whose `graph_type_id` resolves to a registered `GraphTypePlugin` with a higher `current_version` than the graph's `graph_type_version`.

Split from the eventual dispatcher so discovery is unit-testable without Hatchet. The auto-dispatch call site will compose this with:

• `plan_migrations` (feat(kt-config): GraphMigration planner (Phase 7 #56) #254, merged) — hop list per graph
• `GraphMigrationRunRepository.most_recent_for_graph` (PR feat(kt-db): GraphMigrationRunRepository for audit-table access #258, pending) — "is anything already in flight?"
• `graph_migration_wf` dispatch (feat(wiki-frontend): add homepage tabs, synthesis views, and fix definition rendering #57)

Once all three land, the startup hook is ~20 lines of orchestration.

Filtering decisions

Condition	Behaviour
`status='deleted'`	skip (don't resurrect banner)
`status='provisioning'` or `'error'`	skip (don't migrate on top of half-built schemas)
`version >= current` (at-current or rollback)	skip
`graph_type_id` unregistered	log + skip, not raise

Unregistered-plugin posture is deliberate: the runtime resolver falls back to `'default'` for the live pipeline, so writes keep flowing. Auto-dispatch shouldn't fail the whole sweep over one stale pointer. Per CLAUDE.md fail-fast rule this is NOT silent data drop — the WARNING line surfaces the stale id so ops can fix it.

Ordering

Results ordered by `created_at` for deterministic output. Operator tailing logs during a migration rollout sees the same order every boot.

Test plan

• 10 new integration tests: empty, detects behind, skips at-current, skips ahead-of-plugin (rollback), skips deleted/provisioning/error statuses, unregistered plugin logs + skips without raising, unregistered does not abort other graphs, deterministic ordering
• `libs/kt-db` unit: 57 pass; integration: 162 pass (10 new)
• `ruff` + pre-push lefthook green

🤖 Generated with Claude Code

[charlie83Gs]

Review fixes applied

1. Status filter drift — inverted from `status == 'active'` to `status.not_in(('deleted', 'provisioning', 'error'))`. Docstring and code now match; a future status (`archived`, `suspended`, …) is auto-included in auto-dispatch unless we explicitly skip it, which forces the decision at review time. New test `test_unknown_status_is_auto_included` pins the contract so nobody silently narrows back to `== 'active'` later.

2. `created_at.replace(microsecond=…)` flake — swapped for `first.created_at + timedelta(microseconds=1)`. Same fix pattern as PR #258.

3. `_M` stub "dead code" claim — actually load-bearing. Discovery tests don't call the planner, but they DO call `PluginRegistry.register_graph_type`, which validates (via PR #253) that every hop from v1 to `current_version` has at least one migration declared. Without `_V2Plugin.migrations()` returning the stub, registration would raise and every test for v2 plugin scenarios would fail setup. Added a comment on both the `migrations()` override and the `_M` class explaining this.

4. Load-all-active-graphs — noted as future concern for world-graph vision. No fix this PR (per your note).

5. Plugin ref on `OutOfDateGraph` — bootup-scoped use; kept as-is per your note.

11/11 tests pass (1 new).

[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.}