Serialize an Entity as the expression it prints (#323)

[Rafael-SOWNet]

Roadmap #746 item 18, and
#323. See the end for whether #323 should
close — I have not touched it.

What was wrong

Measured on v2.3.0 (6b93b40), before any change:

JsonSerializer.Serialize(entity)
// JsonException: A possible object cycle was detected ...
// Path: $.DirectChildren.Nodes.Nodes.Nodes.Nodes ... (x32)

For (Entity)3 as much as for x + 2 * sin(y): Nodes is a node's enumeration of itself, so the
reflecting object converter walks it until it hits the depth limit. DataContractSerializer refuses
the types outright (InvalidDataContractException on Entity+Sumf) and
typeof(Entity).IsSerializable is false. So an Entity could not be a member of any serializable
type, which is what #323 asks for.

The position

The printed form is the serialization, and there is no second one.

The question worth answering is not "how does an Entity serialize" but "what does a caller need
that the printed form does not already give them". Stringize/FromString round trips by contract,
it is also the library's input format, and EveryNodeSurvivesEveryPipelineTest enumerates the node
types by reflection and fails the day a new one stops satisfying it. A structural JSON schema would
be a second description of the same tree — per-node code, a place in AddingNode.cs, a version story
of its own, and freedom to drift from the first with nothing detecting it.

What a structural format would buy is speed, and the number is measured rather than assumed. A
textbook-sized expression — 43 nodes, 97 characters — on net10.0 release, 2000 iterations after
warm-up, both arms in one process:

	time	allocated
Stringize()	45 us	115 kB
JsonSerializer.Serialize	41 us	115 kB
MathS.FromString (a fresh string, so the parse cache misses)	430 us	793 kB
JsonSerializer.Deserialize<Entity>	420 us	883 kB
the same tree built from constructors, no text at all	6.5 us	25 kB

The JSON layer costs nothing over printing and parsing — it is printing and parsing. Reading costs
about 65x what building the tree costs, and that last row is the floor a structural format could aim
at. It is a real gap, and it is an argument for a faster parser, which every caller who writes
Entity e = "..." would also get.

What is in it

• Core/Serialization/EntityJsonConverter.cs — a JsonConverter<Entity> writing Stringize() and
  reading MathS.FromString, plus ReadAsPropertyName/WriteAsPropertyName so an Entity works as
  a dictionary key.
• Core/Serialization/Entity.Serialization.cs — the attribute, on every public node type.
• Docs/Contributing/Serialization.md — the position and the measurements.
• EntitySerializationTest — 107 tests, comparing entities and never printed forms, except the one
  test that is about the text.

Zero configuration:

public sealed record Problem(string Title, Entity Body);
JsonSerializer.Serialize(new Problem("quadratic", "x ^ 2 - 3 * x + 2"));
// {"Title":"quadratic","Body":"x ^ 2 - 3 * x + 2"}

Why every node type and not only Entity

System.Text.Json looks a converter attribute up on the declared type with inherit: false. An
attribute on Entity alone leaves a member declared as Entity.Variable to the object converter and
the cycle above — measured, not assumed. So all 77 public node types carry it, in one file, and
EveryPublicNodeTypeCarriesItsConverter enumerates them and names any that is missing, so a node
added later cannot join silently. Step 11 of AddingNode.cs says the same in prose.

Trimming and AOT

Nothing reflects and nothing scans assemblies. JsonConverterAttribute would construct the converter
with Activator.CreateInstance; EntityJsonConverterAttribute overrides CreateConverter and
returns new EntityJsonConverter(), so the type is reached statically. Built with
EnableTrimAnalyzer and EnableAotAnalyzer, the only IL2xxx/IL3xxx warnings in the assembly are the
two that were already there, both in CompilationProtocol.cs.

Frameworks

net8.0 and later. netstandard2.0 has no System.Text.Json in the box, and adding the package
reference means editing AngouriMath.csproj, which another open PR owns right now. One conditional
PackageReference extends it whenever that is convenient.

What the printed form does not carry

Properties of printing, not of this converter, so fixing them there fixes them here. Measured over
115 shapes — every node type the reflective enumeration reaches, plus Lambda/Application with
bound names, Provided, ConditionalSet, matrices, the sum/product binders and pi/e/i —
112 round trip and 3 do not:

• Codomain. Nothing prints it, so domain(x, ZZ) prints as x and reads back with
  Domain.Any. Filed as #1022 — the same
  shape of defect as Stringize of a Rational parses back as a Divf, so the round trip is not an identity #873, and the parser already accepts domain(expr, SET), so only the printing
  half is absent. Pinned here by a test written to fail when Stringize drops a node's Codomain, so domain(x, ZZ) prints as x and does not round trip #1022 is fixed.
• Number.Complex with both parts non-zero, which prints as a sum and reads back as Sumf.
  Already recorded in EveryNodeSurvivesEveryPipelineTest, and this test carries the same list.

And one that is not about a node type but about how operands nest. An associative operator whose
operands nest to the right comes back nested to the left, because a right operand at its own
precedence is not bracketed:

MathS.FromString("1 + (2 + 3)").Stringize()   // "1 + 2 + 3", which reads back as (1 + 2) + 3

Same for *, and, or and xor. The node changes and the value does not, which is what makes it
an output choice rather than a defect. An operator that is not associative keeps its brackets,
since #1009 — AnOperatorThatIsNotAssociativeKeepsItsNesting asserts that here for implies,
provided, -, /, ^, mod and set minus.

I filed #1032 for the implies half of that before merging master, and #1009 had already fixed it —
I measured on v2.3.0, which was the tip when this branch was cut and stale by the time I wrote it up.
Closed with the re-measurement.

Two things worth a reviewer's eye

• Function and TrigonometricFunction in Entity.Continuous.Definition.cs had to become partial
  to be named in the attribute file. That is the whole of the change under Core/Entity/.
• The two new .cs files carry the 2019-2022 header, because Sources/.editorconfig opts a path
  into 2019-2026 per directory and editing it would have conflicted with an open PR. Two sections —
  [AngouriMath/Core/Serialization/*.cs] and [Tests/UnitTests/Common/EntitySerializationTest.cs] —
  and the headers bumped, is the follow-up.

Public surface

Seven lines in PublicApi.txt: AngouriMath.Core.Serialization.EntityJsonConverter, its
parameterless constructor and its five overrides. EntityJsonConverterAttribute is internal.

Measured

• dotnet test Sources/Tests/UnitTests -c Release — 7743 passed, 0 failed, 14 skipped (7757
  total), with master merged in. The branch adds 107 tests and changes no existing one: its diff
  against master is the six new files plus seven lines of PublicApi.txt.
• dotnet test Sources/Tests/FSharpWrapperUnitTests -c Release — 134 passed, 0 failed.
• dotnet build Sources/AngouriMath -c Release — clean for netstandard2.0, net8.0 and net10.0.

Should #323 close?

The issue asks for two things. Serialization is here. The second half — "and make FieldCache
non-serializable" — names a type that no longer exists; the memoisation is LazyPropertyA<T> fields
now, and no serializer reads a field of a node any more, because the expression is written as text.
So the reason for that half is gone rather than answered, which is worth a maintainer's word before
the issue is closed.

Happypig375's "why not an existing and widespread format like JSON" and "or not just
Parse/ToString?" are both what this does. WhiteBlackGoose's objection — "we don't guarantee
a.ToString().ToEntity() be parsable and equal to a", with 1 + 2 + 3 as the example — has
narrowed rather than gone. StringizeRoundTripTest and EveryNodeSurvivesEveryPipelineTest enforce
that guarantee for every node type today, and his example is precisely the part still standing:
1 + (2 + 3) does come back as (1 + 2) + 3. It is a change of shape and not of value, which is why
it is written down here rather than fixed.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Bjumi5K7fg8yx6UK1mZTQd