asc-community / asc-community/AngouriMath
A node type cannot be defined outside the kernel assembly: five of Entity's abstract members are internal
- Dominant language
- C#
- Stars
- 831
- Forks
- 79
- Avg merge
- 3h 23m
- Merged PRs (30d)
- 309
Description
### What is wrong
`Entity` is `public abstract partial record`, and its constructor is `protected`, which reads as an
invitation to derive from it. But a subclass in another assembly does not compile. Five of its
abstract members are `internal` or `private protected`, so an external type can never satisfy them:
| member | accessibility | where |
|---|---|---|
| `Priority` | `internal abstract` | `Core/Entity/Entity.Definition.cs:378` |
| `SortHashName(SortLevel)` | `private protected abstract` | `Functions/TreeAnalyzer/Sort.Definition.cs:19` |
| `IntrinsicCondition` | `private protected abstract` | `Functions/Evaluation/Evaluation.Definition.cs:72` |
| `ToSymPy()` | `internal abstract` | `Functions/Output/ToSympy.Definition.cs:13` |
| `InvertNode(Entity, Entity)` | `private protected abstract` | `Functions/Continuous/Solvers/InvertNode.Definition.cs:30` |
Deriving from `Entity` in a separate assembly fails with `CS0534`, naming each of those five among
the members it cannot implement. This is not a policy that could be relaxed by an
`InternalsVisibleTo`: a published extension package cannot be on that list.
### Why it matters, and what is behind it
This is the concrete blocker under several roadmap items, and it is not the one they name.
[#746](https://github.com/asc-community/AngouriMath/issues/746) item 56 says the extensibility seam
is [#338](https://github.com/asc-community/AngouriMath/issues/338) — *looking a type up so it can be
parsed from a string*. That is the second half. The first half is being able to **write** the type at
all, and today you cannot. The same wall sits under item 53 (groups, rings and fields as
first-class, [#440](https://github.com/asc-community/AngouriMath/issues/440)) and under the whole
tier-9 domain-package idea, which assumes a geometry or statistics pack can contribute node types.
It also means one thing the packaging decision cannot decide. `Docs/Contributing/Packaging.md`
(#746 item 78) works out which capabilities belong in the kernel and which ship separately, and its
answer for domain packages is **blocked, not decided** — because a package boundary is not what is
in the way here. Moving the LaTeX printer or the SymPy exporter out of the kernel runs into the same
five members from the other side: they are abstract members of `Entity`, so moving them means either
this contract becoming extensible or a visitor over all 68 node types.
### Scope
This is a design decision before it is an implementation, and it should be argued before it is
built. The shape of the question:
- Which of the five are genuinely part of a node's public contract, and which are engine internals
that a visitor or a registry should own instead? `ToSymPy` and `SortHashName` look like the second
kind; `Priority` and `IntrinsicCondition` look like the first.
- If a member becomes `public` or `protected`, it becomes a compatibility surface — every future
change to `SortLevel`, `Priority` or the `InvertNode` signature is then breaking. That is the real
cost and it should be stated before the change, not discovered after.
- Is the answer instead a **sealed** node hierarchy plus an explicit extension point — a node kind
that carries a name and an operation table — so that a domain package contributes data rather than
a subclass? That keeps `Entity` closed, which is what makes exhaustive matching and the
`EveryNodeSurvivesEveryPipelineTest` reflection sweep work today.
- Whatever is chosen must be trimming- and NativeAOT-safe: explicit registration, no runtime assembly
scanning. See [#363](https://github.com/asc-community/AngouriMath/issues/363),
[#552](https://github.com/asc-community/AngouriMath/issues/552) and
`Docs/Contributing/Trimming.md`.
### Acceptance criteria
1. A written decision in `Docs/Contributing/`, saying what a node type outside the kernel may and may
not do, and which of the five members are part of the contract.
2. A test that **compiles** a node type from a separate assembly and puts it through the pipeline —
parse is not required, but `ToString`, `Latexize`, `InnerSimplified`, substitution and structural
equality are. A test that only asserts the type exists proves nothing; this has to build.
3. `EveryNodeSurvivesEveryPipelineTest` still passes, and it is stated whether an external node is
in scope for it.
4. No new reflection on a hot path, and the trimming/AOT gate stays green.
### Dependencies
Independent of everything currently open. It does **not** depend on
[#338](https://github.com/asc-community/AngouriMath/issues/338) — it is what #338 needs, not the
reverse. It is a prerequisite for #746 items 53 and 56 and for tier 9.
Found while measuring package boundaries for #746 item 78.
Contributor guide
Research direction
Start by reading the five member definitions named in Core/Entity/Entity.Definition.cs, Functions/TreeAnalyzer/Sort.Definition.cs, Functions/Evaluation/Evaluation.Definition.cs, Functions/Output/ToSympy.Definition.cs, and Functions/Continuous/Solvers/InvertNode.Definition.cs, along with Docs/Contributing/Packaging.md and Docs/Contributing/Trimming.md. Run EveryNodeSurvivesEveryPipelineTest and inspect the trimming/AOT gate. Done means a documented contract, a separate-assembly pipeline test, and preserved reflection and AOT checks.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp
- Domain
- backend-api-design
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 35/100