Collect the rewrites that fire, for a caller who asks (#28)

[Rafael-SOWNet]

Addresses #28. Stacked on #818, which is stacked on #816 — merge those first.

What it does

using var recording = RewriteRecording.Start();
var simplified = ((Entity)"a / (b / c)").Simplify();
foreach (var step in recording.Steps)
    Console.WriteLine(step);      // Common: a / (b / c) -> a * c / b

A RewriteStep is the rule set, the subexpression it matched, and what replaced it — plus the relation and soundness tier that set declares. This is only possible because #818 gave every rule set the simplifier applies a name; a rewrite reached through Patterns directly has nothing to be attributed to.

The subexpression rather than the whole expression: a pass walks bottom-up and rewrites nodes as it goes, so there is no moment at which a partly-rewritten whole expression exists to photograph. #28's example shows whole-expression snapshots; producing those would mean constructing something the engine never held.

Free when off — measured, not asserted

Against b2e3c428 (the parent), net10.0/Release, with no recording open:

	parent	this branch
SimplifyEasy	125.8 KB	125.8 KB
SimplifyCommon	6867.8 KB	6867.6 KB
Limit	7516.4 KB	7516.0 KB
Expand / Factorize / Differentiate / ParseEasy	unchanged	unchanged

The first version of this was not free, and the benchmark is what caught it. The recording path's closure captures the rule set and the recording; the compiler allocates the object holding them where they come into scope, so writing it inline behind an early return still allocated on every rewrite in the library whether or not anyone was recording. It cost Simplify a fifth of its allocation — 125.8 → 151.3 KB — while the code read as though the fast path returned before any of it. The recording path is a separate method now, and the ordinary path is a thread-static read and a branch.

That is the reason this is a scope rather than a MathS.Settings entry: a setting is something a caller can leave on.

Threading

Per thread, like MathS.Settings. A synchronous scope: do not await inside one. The recording follows the thread, not the call, so yielding lets whatever else that thread picks up be recorded as if it were the caller's — which is precisely what the parallel test runner did to the first version of the thread-isolation test, and it is worth knowing that it fails that way rather than loudly.

Closing is written to survive being done from another thread: it restores only its own thread's chain, and a closed recording ignores whatever it is still handed. So a stray reference left on a thread does nothing, rather than growing a list nobody will read or appending to a result already handed back. There is a test for exactly that, driven through the public API with two threads and a pair of events.

Recordings nest; an inner one hides the outer until it closes.

What this is not

These are the rewrites, not everything Simplify did, and the type's own documentation says so. Simplification also expands, factorises, divides polynomials, minimises boolean expressions, and then chooses among the candidates by a complexity metric. The steps are every rewrite that fired across every candidate that was generated — including the candidates that lost. Reading them as a route from the input to the returned answer would be reading in something that is not there. That route is the derivation work in #746's v5.0 tier, and it needs the candidate search to be attributable, not just the rewrites.

So #28 gets a comment, not a close: it asks for per-rule attribution (any1 / (any2 / any3) -> any1 * any3 / any2) and this gives per-rule-set. The finer grain is item 50 on #746 and wants a design document first, because splitting each switch case into an object trades one dispatch per node for one delegate call per rule per node on the hottest path there is.

Tests

5784 passing, 0 failed, 15 skipped. F# 130 passing.

The new tests cover: that rewrites are collected and every step is a real change by a registered set; that a step carries its set's relation and tier; that recording does not change the answer; determinism across two identical runs; closing; double disposal; nesting not feeding the outer recording; thread isolation; and a recording closed from a different thread going inert.

Two notes on how they are written, both learned the hard way here:

• The parse cache is off in these tests. An Entity memoises InnerSimplified on itself, so a cached tree handed back a second time has already done part of the work and records fewer steps for the same input.
• The thread-isolation test joins a real thread instead of awaiting a task, for the reason in Threading above.

🤖 Generated with Claude Code

[Rafael-SOWNet]

Two things added since the description above, both from the same question: are there benchmarks for any of this?

There were not. Every number reported about this layer came from a throwaway harness outside the repo, so nothing stood behind the claims and a regression would have been silent — despite two of them having already been broken once each while it was being written.

DotnetBenchmark gains a TransformationLayer class covering the 1.x entry points that now route through the layer, the layer reached directly, a single rewrite pass, and Simplify with and without a recording open. Registered in Program.cs, reporting Allocated alongside Mean — allocation is deterministic and reproduces to the tenth of a kilobyte, where timings on an ordinary machine vary by ten percent and hide exactly what this exists to catch.

Benchmarks are not run in CI, so the "free when off" claim gets a test. RewriteAllocationTest applies a rule set to a leaf — no rule matches, no nodes are rebuilt — so a stray per-call allocation dominates the measurement rather than hiding inside it, which is what makes the budget safe to assert across runtimes instead of a source of flakes.

It was verified by putting the bug back: 640000 bytes over 20000 calls, exactly 32 per call, four times the budget, with a failure message naming the cause and the fix. A second test asserts that recording does allocate, so the budget cannot be passing because the measurement is broken.

Also, on the base branch: FactorizationAtLevel was swept across levels while the other two levelled transformations were checked at the default only — three tests of one shape written three ways. All three are swept now, including negative levels and levels outside the -4..4 range the catalogue keeps built.