SchemaKit API design: a declaration the database would reject does not compile #61

Goal

Decided 2026-10-19 by the maintainer: SchemaKit gets an entirely new public API. It is not the 5.x API under new ids.

The rule is the one the CodoMetis.ValueRanges range types follow: a declaration PostgreSQL or SQL Server would reject must not compile. The design makes full use of what .NET 11 and C# 15 offer for that, closed hierarchies first of all.

The first SchemaKit preview carries this API. No preview ships the old API under the new ids (#38).

The design must answer

• Principles, each with an example of a declaration that no longer compiles. For example:
  • index methods as a closed hierarchy with method-specific options, so NULLS FIRST/LAST and INCLUDE exist only where the method allows them
  • builders that encode their stage in the type, so an exclusion constraint with no overlap element can't be built
  • predicates and operators typed by the column types
• Exhaustiveness. Declarations are closed unions, so a missing arm in the differ is a compile error. The ValueRanges ranges can only guarantee that at runtime.
• Closed inside, open at the seam. The kernel dispatches over contributors through an open interface (SchemaKit: a public plugin contract, so packages contribute to the model differ and migrations SQL generator instead of replacing them #56, so other CodoMetis packages can plug in). Each contributor owns its declarations as a closed union. The kernel never switches over another contributor's types.
• The ownership check (SchemaKit: fail at startup when another package has replaced the model differ or the migrations SQL generator #57) and the snapshot format v2 (SchemaKit: snapshot format v2 and CodoMetis: annotation keys ship in 11.0.0; the 5.x format is read forever (D11) #58) in this design.
• What is left out because EF Core 11 and Npgsql 11 do it natively (SchemaKit: leave out what EF Core 11 and Npgsql 11 do natively; keep what stays unique #39: complex-type indexes, temporal keys).
• A table mapping every 5.x API call to its new form, or to "native" or "dropped". This is the input for the migration guide and for SchemaKit: moving from EFCore.ComplexIndexes 5.x adds no migration, or exactly the one the guide documents #59. The DDL and the snapshot annotations stay compatible; the API doesn't.
• The first slice that 11.0.0-preview.1 ships (SchemaKit 11.0.0-preview.1: the first slice of the new API, on EF Core 11 / Npgsql 11 under the new ids #38): the kernel plus at least one feature end to end.

Done when

• design/schemakit-api.md is merged after the maintainer's review.
• Compile probes on the .NET 11 SDK show every "does not compile" claim of the doc: a test that compiles each forbidden declaration with Roslyn and asserts the diagnostic.
• SchemaKit 11.0.0-preview.1: the first slice of the new API, on EF Core 11 / Npgsql 11 under the new ids #38, SchemaKit: a public plugin contract, so packages contribute to the model differ and migrations SQL generator instead of replacing them #56, SchemaKit: fail at startup when another package has replaced the model differ or the migrations SQL generator #57 and SchemaKit: snapshot format v2 and CodoMetis: annotation keys ship in 11.0.0; the 5.x format is read forever (D11) #58 are rewritten against the design.
• The ROADMAP.md header says that section 5 is input to this design, no longer the plan.