feat(quotations): compute the parts of a quotation that read no variable

[xperiandri]

Proposed Changes

Depends on #58. The branch is built on the branch of #58, so until that is merged this pull request also shows its three commits; its own are the last two. It targets main because the build workflow runs only for pull requests into main.

The second step of phase 1 of ADR 0001 (#34). A query has parts that do not depend on the document:

<@ fun p -> p.Created > DateTime.UtcNow.AddDays -30.0 && p.Age > limit + 1 && p.Tenant = settings.Tenant @>
//                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^           ^^^^^^^^^              ^^^^^^^^^^^^^^^

Their values are known before the query runs, so they become its parameters. This pull request adds what computes such a value: Evaluator.tryEvaluate : Expr -> Result<objnull, TranslationError>. Which parts of a query are computed, and under which parameter names, is the next step.

How. By reflection over a quotation in the normal form of #58: properties and fields are read, methods and constructors called, tuples, records, unions and arrays built and taken apart, types and union cases tested, a captured function applied. Nothing is compiled: turning a quotation into a delegate costs hundreds of microseconds (#56 measured 98 to 705 µs for two small expressions).

What needed care

• A choice computes one branch. &&, || and if are computed the way compiled code computes them, so nick.IsSome && nick.Value.Length > 0 over a captured None is false and raises nothing.
• 37 operators of FSharp.Core cannot be called by reflection: -, /, %, the unary minus and plus, the bitwise operators, the shifts, the conversions between number types (float, int64, byte, …) and the checked forms. They are compiled into the code that uses them, and their own methods raise NotSupportedException, "Dynamic invocation of op_Subtraction is not supported". +, * and the comparisons can be called, which makes the gap easy to miss: limit + 1 works and limit - 1 does not. For every one of the 37, FSharp.Core has a function that does the same for operands of any types (LanguagePrimitives.SubtractionDynamic and its siblings). The compiler passes that function to the operator as a hidden argument, and the evaluator takes the pairs from there instead of from a hand-written list.
• The checked operators are paired by hand. The compiler passes Checked.byte the unchecked conversion function; with it Checked.byte 300 would give 44 instead of raising OverflowException. The evaluator pairs the checked operators with the checked functions, so they raise as they do in compiled code.
• Enumeration values. Those functions fail for an enumeration type, also behind int day, whose own method can be called for other types. The evaluator calls them for the number type under the enumeration and makes a result that is an enumeration value one again, so BindingFlags.Public ||| BindingFlags.Static is a BindingFlags value and not the number 24: a parameter of a query is written by the type its value has.
• A receiver that is null raises NullReferenceException, as compiled code does, not the TargetException of reflection. So does a function that is null when it is applied. Compiled code finds the null after it has computed the arguments, so an argument that raises comes first here as well. (Found by the review: the null was reported before the arguments were computed.)
• A coercion is a cast. The compiler writes one only for :> and for an argument that is passed as a base type, where the cast cannot fail. A quotation built through the API can hold one that fails; its value is then refused with the InvalidCastException of the cast and not passed on as a value of a type it does not have. A cast converts nothing: a boxed int is no byte, in compiled code either. (Found by the review.)
• A node is computed once. The normalizer writes a value that a let bound at every place it is used, as the very same node, and the code computes a bound value once: let made = obj () in (made, made) is a pair of one object. The evaluator keeps the values of the nodes it computed, by their identity, so it is one object here too. tryEvaluate keeps them for one part; tryEvaluateOnce takes them from its caller, who computes several parts of one quotation (feat(quotations): tell the values of a quotation from its shape #60). (Found by the review.)
• The default value of a struct is its zeroed value, for which no constructor runs. A struct of another language can declare a constructor without parameters, and Activator.CreateInstance runs it: for a struct whose constructor sets a field to 7 it gives 7 where the default value is 0. So the value comes from RuntimeHelpers.GetUninitializedObject; a nullable without a value stays null as an object, because that function gives a boxed value of the type under it for a nullable. (Found by the review.)
• A member of a nullable is computed by a function that takes the nullable as an argument. Reflection has nothing to call such a member on: a nullable is boxed as its value or, when it has none, as null, never as itself. Called on the box, settings.Limit.HasValue of a nullable without a value raised instead of giving false. As an argument, null is taken for the nullable without a value. (Found by the review.)

Errors. An exception of the code that is run becomes a TranslationError with the new code ClientEvaluationFailed and the exception itself in the new field Cause, taken out of the TargetInvocationException that reflection wraps it in. A part that holds a function written in the quotation, a variable or another quotation has no value and is Unsupported.

Types of changes

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)

The assembly is not packed yet (#58); the packages are unchanged.

Checklist

• Build and tests pass locally
• I have added tests that prove my fix is effective or that my feature works (if appropriate)
• I have added necessary documentation (if appropriate)

Further comments

• Tests: 148 in EvaluatorTests (FSharp.Azure.Cosmos.Quotations.Tests has 450 now).
  • 129 computations, each a piece of code that reads no variable. The compiler passes the code together with its quotation (a parameter marked [<ReflectedDefinition(true)>], as in feat(quotations): bring a quotation into its normal form #58), so the expected value is what the code gives when it runs. There is one for every kind of node, for every one of the 37 operators, for every member of a nullable with a value and without one, and for enumeration values. One is a call of a function with a reflected definition that calls itself, which the normalizer leaves a call when it reads nothing of the document (feat(quotations): bring a quotation into its normal form #58).
  • 11 failures: code that raises, checked for the error it becomes — the code, the exception as the cause, its name in the message, the place in the source.
  • One test builds coercions through the API: a value of the target type is given, any other is the exception of the failed cast.
  • One test makes a struct with a constructor without parameters at run time, which F# does not declare, and checks that its default value is the zeroed one.
  • Two tests count how often the code of a bound value runs: once for two places of one part, and once for two parts when the caller keeps what was computed.
  • One test asks FSharp.Core which operators it marks as not callable (NoDynamicInvocationAttribute) and fails when one of them has no function to stand in for it. A new version of FSharp.Core cannot add such an operator unnoticed.
• Can the tests fail? 26 one-line defects were planted in the evaluator, one at a time, and reverted: both branches of a choice computed, a null receiver passed on, the wrong item of a tuple, an inverted case test, a checked operator computed unchecked, an enumeration type passed as it is, a member of a nullable called on its box, a function that is null passed on, a coercion that gives any value, the wrapper of reflection reported as the cause, and others. Every one of them fails at least one test. The first run found two that none failed; both are closed (a struct made without arguments had no test, and the type of a computed enumeration value was not checked).
• Cost, measured in a Release build on a machine under other load, so orders of magnitude: a captured value 0.1 µs, a field of a captured record 0.3 µs, limit + 1 0.5 µs, DateTime.UtcNow.AddDays -30.0 0.4 µs, a record or tuple that is built 0.3 µs. Keeping the values of the nodes adds about 0.1 µs to a part that runs code. The functions of FSharp.Reflection that are called for every value (MakeRecord, MakeTuple, GetTupleField) cost 3 to 9 µs each; the evaluator asks for their precomputed forms once per type and keeps them for the process.
• Found on the way: the compiler refuses to read a member of a captured local of a value type in a quotation (FS3155): date.Year for a captured DateTime. The ADR has this; the tests keep their date in a field of a captured record.
• Not in this step: which parts of a query are computed and what the policy for that is (EvaluationPolicy of the ADR) — the evaluator computes what it is given.
• Verification: dotnet build FSharp.Azure.Cosmos.slnx in Debug and Release with the warnings main has and none in the two Quotations projects, also with -p:WarnOn=3390; the tests pass in both configurations; Fantomas clean; the strict documentation build passes; every cref of the changed library files names a member that a documentation file declares; both commits build, and the second passes the tests.
• No changelog entry: nothing is packed.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Nullable receivers, null function application, and unreachable constant branches currently produce incorrect behavior.

4 open findings

• Handle nullable property access from boxed nullable values · New
• Handle nullable instance methods without invalid reflection targets · New
• Preserve NullReferenceException for null captured function calls · New
• Avoid normalizing unreachable branches after constant condition selection · New

What changed in this PR

Adds the staged quotation translator foundation and reflection-based evaluation of document-independent expressions.

Changes:

• Adds quotation normalization and client-side evaluation.
• Extends translation errors with evaluation failures and causes.
• Adds comprehensive unit tests and solution integration.

File	Description
.github/​copilot-instructions.md	Documents the new projects.
FSharp.Azure.Cosmos.slnf	Adds projects to the solution filter.
FSharp.Azure.Cosmos.slnx	Adds library and test projects.
src/​Cosmos.Quotations/​AssemblyInfo.fs	Defines assembly metadata.
src/​Cosmos.Quotations/​Evaluator.fs	Evaluates variable-independent quotation parts.
src/​Cosmos.Quotations/​FSharp.Azure.Cosmos.Quotations.fsproj	Configures the new library.
src/​Cosmos.Quotations/​InternalsVisibleTo.fs	Exposes internals to tests.
src/​Cosmos.Quotations/​Normalizer.fs	Normalizes quotation expressions.
src/​Cosmos.Quotations/​TranslationError.fs	Defines translation error contracts.
tests/​Cosmos.Quotations.Tests/​EvaluatorTests.fs	Tests evaluator behavior and failures.
tests/​Cosmos.Quotations.Tests/​FSharp.Azure.Cosmos.Quotations.Tests.fsproj	Configures the test project.
tests/​Cosmos.Quotations.Tests/​Model.fs	Supplies quotation test models.
tests/​Cosmos.Quotations.Tests/​NormalizerErrorTests.fs	Tests normalization errors.
tests/​Cosmos.Quotations.Tests/​NormalizerSpellingTests.fs	Tests equivalent quotation forms.
tests/​Cosmos.Quotations.Tests/​NormalizerTests.fs	Tests normalization invariants.
tests/​Cosmos.Quotations.Tests/​QuotationAssert.fs	Adds quotation test helpers.
tests/​Cosmos.Quotations.Tests/​TestCategories.fs	Defines test categories.
tests/​Cosmos.Quotations.Tests/​testconfig.json	Enables parallel test execution.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

Coercion evaluation can return an incorrectly typed or valued query parameter.

1 open finding

• Apply target-type conversion for Coerce expressions · New

4 resolved since last review

• Avoid normalizing unreachable branches after constant condition selection
• Preserve NullReferenceException for null captured function calls
• Handle nullable instance methods without invalid reflection targets
• Handle nullable property access from boxed nullable values

🧠 Review effort: Balanced

[Copilot]

🔵 Needs a closer look

The extensive reflection-based evaluator and stacked normalizer changes require final human validation despite comprehensive tests.

0 open findings

1 resolved since last review

• Apply target-type conversion for Coerce expressions

🧠 Review effort: Balanced

[Copilot]

🟡 Changes recommended

Evaluation currently recomputes normalized let-bound expressions used at multiple locations, changing observable results.

1 open finding

• Preserve shared binding evaluation in valueOf · New

🧠 Review effort: Balanced

[Copilot]

🔵 Needs a closer look

The large reflection-heavy normalization and evaluation engine warrants final human validation despite extensive tests.

0 open findings

1 resolved since last review

• Preserve shared binding evaluation in valueOf

🧠 Review effort: Balanced

[Copilot]

🔵 Needs a closer look

The combined dependency and extensive reflection-heavy normalization and evaluation semantics warrant final human validation.

0 open findings

🧠 Review effort: Balanced

[Copilot]

🟡 Changes recommended

Null targets are rejected before their arguments are evaluated, diverging from compiled call semantics.

1 open finding

• Defer null target check until after evaluating call arguments · New

🧠 Review effort: Balanced

[Copilot]

🔵 Needs a closer look

The extensive reflection and quotation-rewriting logic warrants final human review despite broad test coverage.

0 open findings

1 resolved since last review

• Defer null target check until after evaluating call arguments

🧠 Review effort: Balanced

[Copilot]

🟡 Changes recommended

Default-value evaluation incorrectly invokes explicit parameterless struct constructors instead of producing zero-initialized values.

1 open finding

• DefaultValue incorrectly invokes value-type constructors · New

🧠 Review effort: Balanced