Design document: which capabilities belong in the kernel package, and which ship separately (#746 item 78) #1008

Item 78 of #746, filed as its own issue because it is the one thing that roadmap names as "worth settling before v2.0 adds anything large, because published package boundaries cannot be moved afterwards" — and three releases have since added large subsystems to the kernel without it being settled.

"A Design document for the package split: which capabilities belong in the kernel package, which ship separately, and what the dependency rules between them are."

This is a request for a decision, not for code. Nothing here proposes moving anything yet.

Where we actually are

Measured on master at 6b93b401 (2.3.0).

Four packages are published, by .github/workflows/Nuget.yml: AngouriMath, AngouriMath.FSharp, AngouriMath.Interactive, AngouriMath.Terminal.

Two corrections to #746's own premise, which describes the existing split as "kernel, FSharp, Interactive, Terminal, CPP and Experimental":

• Experimental is not a package. It is Sources/AngouriMath/Convenience/Experimental/MathS.Experimental.cs, a folder inside the kernel.
• The C++ wrapper is not published. AngouriMath.CPP.Exporting and .Importing build and are tested in CI; neither is pushed to NuGet.

So the pattern the roadmap says to extend is narrower than it was described as, which is worth knowing before extending it.

The kernel is now 211 files and 53,665 lines, and this is what has arrived in it since the roadmap was written, none of it with a boundary decision in front of it:

Partial mitigation, and it is real: the polynomial and Gröbner layers are internal, so they add size without adding surface. That caps the compatibility cost of moving them later — it does not cap the download.

What the design document has to answer

1. What is the kernel? Goal: Math OS — a ten-year vision for AngouriMath as an open mathematical reasoning platform #746's architecture says "someone who wants only the expression tree and the rewrite engine gets a fast, boring, dependency-light library — and that must stay a supported way to use AngouriMath forever". That sentence is a package boundary if it is anything. Where is it drawn — does the kernel keep Simplify, or is even that a layer above the tree and the rules?
2. What ships separately, and what is the dependency rule between them? Goal: Math OS — a ten-year vision for AngouriMath as an open mathematical reasoning platform #746's second architectural rule is that no layer reaches around the layer below. A package split makes that mechanically checkable rather than aspirational, which is most of the value.
3. What is the cost, stated honestly? Goal: Math OS — a ten-year vision for AngouriMath as an open mathematical reasoning platform #746 states it: "every boundary widens the version matrix, the CI time and the number of ways a user can assemble something we never tested, so a split earns its place only where the boundary is load-bearing." A document that lists benefits and not that is not the document.
4. How does this interact with trimming? If the answer to "the common case pays for nothing it does not use" is a trimmer rather than a package boundary, that is a legitimate answer and a much cheaper one — but it is currently unavailable, because there is no PublishTrimmed, IsTrimmable or IsAotCompatible anywhere in the tree and the compilation path still resolves methods by string at run time (AOT-supported Linq compilation #363). Settling that may change the answer here, so the two want deciding together.
5. What does a knowledge package look like? Goal: Math OS — a ten-year vision for AngouriMath as an open mathematical reasoning platform #746 tier 9 needs statically declared contents rather than assembly scanning. Whatever boundary is chosen now is the one that shape has to fit through.

Acceptance criteria

• A written document — in Sources/AngouriMath/Docs/Contributing/, beside CanonicalForm.md and SimplificationContract.md, which are the precedent for a decision written down and checkable — naming, for every top-level area of the kernel, whether it stays or moves, and why.
• A stated dependency rule between packages, and a way to fail a build that violates it.
• The cost side written out: how many packages, what the version matrix becomes, what CI time it adds.
• An explicit answer on whether trimming makes some of the split unnecessary.
• No code. If the document concludes that the current single kernel is right and the boundary should not move, that is a successful outcome and closes the item.

Related

• Conditional compilation for feature subsets: use trait-based test selection and package seams instead #783 argues against #if as the mechanism for feature subsets and proposes trait-based test selection plus package-ready seams. It is adjacent and it does not answer this: it says how not to do it and how to stay ready, not where the line goes.
• AOT-supported Linq compilation #363 (AOT-supported Linq compilation) and Unity to be supported #552 (Unity) are the deployment cases that make item 4 above load-bearing.
• Self-contained terminal #539 touches trimming, but only as an obstacle to a single-file Terminal.

Raised originally by @darkfader in the #746 thread, and named there as a precondition rather than a task.