MigrationFeature never executes discovered KatalystMigration classes (1.0.0-alpha05)

[darkryh]

Summary

On 1.0.0-alpha05, KatalystMigration classes that are correctly discovered under scanPackages(...) are never executed at startup. MigrationFeature.onReady completes without running any migration, regardless of the runAtStartup setting.

Observed behavior

• A KatalystMigration (via SqlMigration) placed under a scanned package is discovered and registered by the DI container — but only under its own concrete class.
• KatalystMigration::class is included in AutoBindingRegistrar's reserved secondary-binding filter, and it is also absent from multiBindingSecondaryTypes.
• As a result, context.getAll<KatalystMigration>() inside the migration feature always returns an empty list, so no migration is ever looked up or executed. There is no error, no warning — the boot log simply shows no migration activity.

Reproduction

1. Consumer app on 1.0.0-alpha05 with features { enableMigrations() } (and the migrations starter on the classpath).
2. Add any KatalystMigration/SqlMigration under a scanPackages(...) root.
3. Boot against an empty database.
4. The migration never runs and the migration history table records nothing, even though DI discovery logs show the class was found. Verified by tracing katalyst-di's AutoBindingRegistrar and the boot log of a real application.

Impact

• Any consumer relying on runAtStartup migrations silently gets no schema management. Apps using schema { createMissing() } mask the problem (DDL still appears, created by the schema policy instead), which makes the failure easy to miss.
• Apps using validateOnStartup()/none() with migration-managed schemas would fail boot or run against a missing schema.
• Direct MigrationRunner usage is unaffected (executing the same migration through MigrationRunner in a test works and is how this was isolated).

Environment

• io.github.darkryh.katalyst:*:1.0.0-alpha05 (Maven Central)
• JDK 21, Kotlin 2.4.x, Ktor 3.5.x, PostgreSQL (also reproducible in tests against H2)

Found while shipping the first KatalystMigration in a downstream application; as far as we can tell this affects every discovered migration on this version, not an edge case.

[darkryh]

Fixed in 1.0.0-alpha06 (on Maven Central).

Confirmed

Reproduced against source. context.getAll<KatalystMigration>() returned an empty list for every
discovered migration, so MigrationFeature.onReady always took the "no migrations were discovered"
branch and never reached MigrationRunner. The report's description of the impact was accurate,
including that schema { createMissing() } masked it and that direct MigrationRunner use was
unaffected.

One correction to the stated root cause

The report attributes the failure to KatalystMigration::class sitting in AutoBindingRegistrar's
reserved secondary-binding filter. That entry was redundant — deleting it alone changes nothing
(verified by removing it and re-running). Either of two other conditions in computeSecondaryTypes
independently drops the binding:

• candidate != baseType — baseType is KatalystMigration::class, so a direct implementor's
  marker is excluded.
• candidate.java.isInterface — clazz.supertypes returns only direct supertypes, so
  class AddUsers : SqlMigration() yields the abstract class and KatalystMigration is never even a
  candidate.

So a fix that only removed the reserved entry would not have worked. Marker types are now derived
from the instance with a runtime isInstance check, which is depth-independent and survives
abstract intermediates, and multibinding markers are registered as container secondary types.

The underlying defect

The facts describing an extension point lived in ~15 places — a discovery list, three when blocks,
two hardcoded sets, three isAssignableFrom checks, an ordering special case — with nothing forcing
them to agree. KatalystMigration was wired into some and not others: it landed in the reserved set
(excluded from container bindings) without landing in the multibinding set (which is what grants a
lookup path), and fell between the two mechanisms.

Those sites now read one declarative catalog, so adding an extension point is a single entry and
wiring one into discovery while forgetting lookup is no longer expressible.

Also fixed, found while fixing this

• Framework registries were never cleared, so a second bootstrap in the same JVM re-ran lifecycle
  hooks belonging to an already-stopped container. Making lookups work would have exposed this as
  every hook running twice.
• Two call sites unioned a registry with the container without deduplicating. Left alone, this fix
  would have caused every domain event to be handled twice.
• Schema initialization opened a second HikariCP pool that was never closed.
• The migrations feature now warns instead of logging at INFO when it is enabled with
  runAtStartup = true and finds nothing to run, and a new warning fires when migrations are found
  but enableMigrations() was never called. The INFO line is the reason this shipped at all — a boot
  that managed no schema read exactly like a healthy one.

Regression coverage

MigrationBootRegressionTest boots the real container once per schema policy and asserts against the
real database — deliberately never with CREATE_MISSING, which is what masked the bug. Reverting the
fix fails all six.

ExtensionPointCatalogTest checks multibinding reachability across three implementation shapes
(direct interface, abstract intermediate, two-level chain) and asserts the catalog agrees with
KatalystConventions, so an extension point added to discovery but not to lookup is now a build
failure.

The existing migration tests could not have caught this: they all drive MigrationRunner with an
explicit list, which is precisely the path that kept working.

Full write-up in docs/issues/.