feat(quotations): tell the values of a quotation from its shape

[xperiandri]

Proposed Changes

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

The third step of phase 1 of ADR 0001 (#34). Two runs of one query differ only in the values it was written with:

let adults (limit : int) (name : string) =
    <@ fun (p : Person) -> p.Age > limit && p.Name = name.Trim () @>

The text of the query is the same every time, … WHERE (p["age"] > @limit) AND (p["name"] = @p1); only the values of the two parameters change. So a query has to be translated once, and every later run only has to find that translation and supply the values. This pull request adds what tells the two apart, Parameterizer. For a quotation in the normal form of #58 it gives three things:

• The values that go into the query as parameters, each at a numbered place. The code calls such a place a slot. Here they are limit and what name.Trim () computes.
• The key (ShapeKey): everything else in the quotation, in a form that can be compared and hashed. Two quotations with equal keys give the same query text, so the key is what a cache of translations will be looked up by. A quotation cannot be its own key: it compares its variables by identity, and every evaluation of <@ … @> creates new variables; it also compares the captured values, which are what a key has to leave out.
• The template, for the first run of a query: the quotation with a variable at the place of every slot. It is what the translator, the next step, reads.

In the quotation	Becomes
a literal: 18, "vip", true, null, StringComparison.Ordinal, a value declared [<Literal>]	a part of the key, later of the query text
a decimal: 18m	a slot without a name. The compiler writes it as a call that makes the decimal, also when it is declared [<Literal>]; as a parameter it keeps its digits, where a number in the text of a query is read as a floating-point number
a captured value: limit	a slot named after the variable, at every place it is used
a part that reads nothing of the document, the largest one at its place: limit + 1, name.Trim (), settings.Tenant, DateTime.UtcNow.AddDays -30.0, a module-level value	computed by the evaluator of #59; a slot without a name
a tuple, record, union case or array that the quotation builds: Some name, [ a; b ], (limit, 1)	stays what it is, with its parts treated by the rows above
Query.parameter 18	a slot, although it is a literal
Query.constant kind	a part of the key, although it is captured. Only for a value of a type that a literal can have

Query.constant and Query.parameter are new public functions; outside a quotation each returns its argument.

What needed a decision

• A literal is a part of the text. The ADR made a literal a parameter by default and, in another place, wrote a value declared [<Literal>] into the text. Both cannot hold: the compiler writes such a value into the quotation exactly as it writes 18, so the two cannot be told apart. The rule here is the one of EF Core: what is written as a constant is a constant, what is captured is a parameter. It is also what the translator needs: it has to see that p.Name = null compares with null, and which StringComparison was written. Query.parameter is for the literal that should be a parameter all the same.

• A value that the quotation builds stays visible. The ADR computed every part that reads nothing of the document, Some name and [ a; b ] included, and each would have been one parameter. But the ADR also wants p.Nick = Some name to become "has a value, and the value is @name", and a list written item by item to become IN (@a, @b). The translator can do neither with a parameter that holds an option or a list. So what is computed is code — calls, readings of properties, constructors of classes — and what the quotation builds is left for the translator, part by part.

• A branch that is not taken is not computed. In

  <@ fun (p : Person) -> filter.IsNone || p.Name = filter.Value.Trim () @>

  compiled code never reads filter.Value when there is no filter. Computing every part beforehand raises NullReferenceException here, although the function is correct. So when the condition of a choice is known before the query runs, the parts of the branch it does not take are slots without a value. The key still holds both branches and does not depend on which one is taken, so the query text stays the same. The query does not take that branch either, so whatever stands in for the missing value changes no result.

• One node, one slot. A slot stands for one node of the quotation. The compiler writes every use of a captured variable as a node of its own, so p.Owner = userId || p.Editor = userId has two slots named userId. The first version of this pull request made them one slot, by name, type and value. But nothing in a quotation says that two such nodes are one variable: two quotations that are spliced together can each have captured a userId, and then telling by the values made the query text depend on them. byOwner a || byOwner b had one parameter when a and b happened to be equal and two when they were not (found by the review). The ADR rules that out, "SQL text never depends on run-time values", so the values decide nothing any more. This replaces the sentence of the ADR that identical captured values are one parameter. A value that has to be one parameter is bound inside the quotation, let id = userId in …: the normalizer writes a bound value at every place as the very same node.

• A value that is bound once is computed once, however often and wherever it is used, as in compiled code. let now = DateTime.UtcNow in p.From <= now && p.To >= now.AddDays 1.0 reads the clock once, although now and now.AddDays 1.0 are two parameters: what the parameterizer has computed is kept node by node for the whole quotation, by the evaluator of feat(quotations): compute the parts of a quotation that read no variable #59. The review led to two cases where this did not hold. With two lets the normalizer made two nodes of one of the values (fixed in feat(quotations): bring a quotation into its normal form #58), and a bound value inside two different computed parts ran its code once for each.

• The key is the key of the normal form. feat(quotations): bring a quotation into its normal form #58 left this open: a key of the quotation as it is written would spare normalizing a query that was seen before. Three things speak for the normal form. Two ways to write one condition share one translation. The slots are the ones the translator sees, with no mapping between two sets of them. And a value that a let binds is one slot because the normalizer writes it as one node. The price is the normalization on every run, 5 to 25 µs; evaluating the quotation literal itself costs more (24 to 75 µs, test(benchmarks): measure what a quotation query costs on the client #56). A query on a hot path is a compiled query of the ADR, which is normalized once.

• A function value is an error, CapturedFunctionValue: a compiled function can neither be read nor be the value of a parameter. feat(quotations): bring a quotation into its normal form #58 reports the function that is applied to a value of the document; this is the function that is passed, as in p.Tags |> List.exists isVip. It is refused by the type of its part before anything is computed, and by its value where the type cannot say what it is, as for a function passed as an obj. Query.constant refuses a function the same way. A function is told by its type also when the type is a class made of the type of F# functions, which code can declare and which the class of every compiled function is. The null and the default value of a function type, which only code can build into a quotation (Expr.Value (null, typeof<string -> bool>)), are refused the same way. (Found by the review: such a null looked like a literal and was written into the key before its type was asked.)

• Query.constant takes only what a literal can be: a boolean, a character, a string, an integer or a floating-point number of a built-in type, a value of an enumeration or null. The key holds the value, and equal keys have to mean one query text. Only such a value says by its equality what is written for it: an object is equal to itself after it has changed, an array is equal to nothing but itself, and two objects can be equal and be written differently. Any other value is reported and stays what it was without the function, a parameter. (Found by the review.) The type that a value is declared with decides, so a nullable is no literal, with a value or without one, and neither is the null of a union type: it is the case of the union that is represented by null, as the None of an option is, and the compiler writes a case as a case. (Found by the review too: a nullable with a value is boxed as that value, so Query.constant (Nullable 5) was taken, and a nullable that code put into a quotation as a value was a literal. And only the null of an option was told: the null of a union marked UseNullAsTrueValue was a literal.)

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), so 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: 410 for the parameterizer and 2 more for the evaluator (FSharp.Azure.Cosmos.Quotations.Tests has 877 now).

  • ParameterizerShapeTests: 47 functions of a person, every one of a shape of its own, written twice over two sets of captured values. With the second set every choice takes its other branch. Five laws: a function has one key whatever values it captured (and one hash code); no two of the 47 have one key; the key and the values are the same whether or not the template is asked for; the template holds a variable for every slot and no captured value; and the template with the values put back computes what the compiled code computes. As in feat(quotations): bring a quotation into its normal form #58, the compiler passes each function together with its quotation, and Unquote evaluates the template.
  • ParameterizerTests: what the laws cannot state. Which values are slots, under which names and with which values; what is a part of the key; that two nodes are two slots whatever they hold, with equal keys; that a value which is bound once is one slot and is computed once, also after a second let and inside two computed parts, and that a function with a definition that is called twice has the slots of each call; that a quotation which is spliced into two places is one slot with one value, also when the normalizer has to rewrite it (the review of feat(quotations): describe how the serializer writes a member #61 found that it came out as two nodes then, which feat(quotations): bring a quotation into its normal form #58 corrects); that a branch that is not taken is not computed, also under another such branch, and that a value used both inside and outside it is; the two functions of Query; the tokens of a small key, one by one; and every error.
  • EvaluatorTests: the check that tells which parts can be computed accepts every part the evaluator computes, refuses a function, a variable and a quotation, and runs no code to tell.

• Can the tests fail? 63 one-line defects are planted, one at a time, and reverted: a field left out of the comparison of keys, a captured value treated as a literal, two nodes made one slot because they hold one value, a node computed anew for every part that reads it, a branch computed that is not taken, the template built with its parts in another order, a function value let through, and others. Each of them fails at least one test. Where one did not when it was first planted, a test was missing and is added: the fields of a token one by one, the index of a slot, the kind of a tuple, a choice that is computed as a whole. Writing the defects down also found one in the code: a condition that is a captured variable used earlier in the quotation did not keep its branch from being computed. It is fixed and has a test.

• Cost, measured in a Release build on a machine under other load, so orders of magnitude. For a quotation in normal form:

  Quotation	Key and values	Template
  one comparison with a captured value	1 µs	1.2 µs
  four comparisons, three slots	3.5 µs	7 µs
  p.Created > DateTime.UtcNow.AddDays -30.0 && p.Age > limit + 1 && p.Tenant = settings.Tenant	4 µs	6.5 µs

  The template is built only for a query that has no translation yet: building a node of a quotation through FSharp.Core costs microseconds (feat(quotations): bring a quotation into its normal form #58), and a query that is found by its key needs no node built. One thing made a difference: to refuse a part as not computable, the evaluator has to walk down to the variable that is the reason, and the walk then asked about every part on that way again. The parts that were refused are remembered for the walk now (from about 4.6 to about 3.5 µs for the four comparisons).

• Where an error is. A captured value has no place in the source of its own, and a node that the normalizer built has the place of a part under it. An error about such a part gets the place of the nearest node around it that has one.

• Review of feat(quotations): compute the parts of a quotation that read no variable #59. Its five findings are fixed in the commits of feat(quotations): bring a quotation into its normal form #58 and feat(quotations): compute the parts of a quotation that read no variable #59, and this branch is built on the result.

• Not in this step: the cache that the key is for (phase 2 of the ADR); the EvaluationPolicy of the ADR, which comes with the options of the translator; the list of functions that must never be computed on the client, which comes with those functions (Cosmos.Functions); the names of the parameters in the query text, which the translator gives. A slot only carries the name of its variable.

• Verification: dotnet build FSharp.Azure.Cosmos.slnx in Debug and Release with the warnings main has and none in the two Quotations projects; 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; each of the three commits builds, and the last one passes the tests.

• No changelog entry: nothing is packed.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Decimal literals, constant function values, and invalid runtime coercions are currently handled incorrectly.

2 open findings

• Coerce skips runtime type checks for downcasts · New
• Decimal literals are incorrectly emitted as query parameters · New

What changed in this PR

Adds the quotation-processing pipeline that normalizes expressions, evaluates document-independent parts, and parameterizes values for future query translation and caching.

Changes:

• Adds normalization, evaluation, shape-key, template, and parameter-slot infrastructure.
• Adds Query.constant and Query.parameter.
• Adds extensive emulator-free MSTest coverage and project integration.

File	Description
.github/​copilot-instructions.md	Documents the quotation projects.
FSharp.Azure.Cosmos.slnf	Adds new projects to the filter.
FSharp.Azure.Cosmos.slnx	Adds new projects to the solution.
src/​Cosmos.Quotations/​AssemblyInfo.fs	Defines assembly metadata.
src/​Cosmos.Quotations/​Evaluator.fs	Evaluates document-independent expressions.
src/​Cosmos.Quotations/​FSharp.Azure.Cosmos.Quotations.fsproj	Configures the quotation library.
src/​Cosmos.Quotations/​InternalsVisibleTo.fs	Exposes internals to tests.
src/​Cosmos.Quotations/​Parameterizer.fs	Builds shape keys, slots, and templates.
src/​Cosmos.Quotations/​Query.fs	Adds constant/parameter markers.
src/​Cosmos.Quotations/​TranslationError.fs	Defines translation errors and locations.
tests/​Cosmos.Quotations.Tests/​EvaluatorTests.fs	Tests expression evaluation.
tests/​Cosmos.Quotations.Tests/​FSharp.Azure.Cosmos.Quotations.Tests.fsproj	Configures the unit-test project.
tests/​Cosmos.Quotations.Tests/​Model.fs	Supplies quotation test models.
tests/​Cosmos.Quotations.Tests/​NormalizerErrorTests.fs	Tests normalization failures.
tests/​Cosmos.Quotations.Tests/​NormalizerSpellingTests.fs	Tests equivalent expression forms.
tests/​Cosmos.Quotations.Tests/​NormalizerTests.fs	Tests normalization behavior.
tests/​Cosmos.Quotations.Tests/​ParameterizerShapeTests.fs	Tests shape and template laws.
tests/​Cosmos.Quotations.Tests/​ParameterizerTests.fs	Tests parameterization details.
tests/​Cosmos.Quotations.Tests/​QuotationAssert.fs	Adds quotation assertion helpers.
tests/​Cosmos.Quotations.Tests/​TestCategories.fs	Defines sorted test categories.
tests/​Cosmos.Quotations.Tests/​testconfig.json	Enables method-level parallelism.

🧠 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

Function values can bypass parameter validation when boxed or supplied through Query.constant.

2 open findings

• Reject function values hidden behind obj-typed query parameters · New
• Document CapturedFunctionValue for parameterized functions · New

2 resolved since last review

• Decimal literals are incorrectly emitted as query parameters
• Coerce skips runtime type checks for downcasts

🧠 Review effort: Balanced

[Copilot]

🟡 Changes recommended

Boolean Query.constant conditions can incorrectly evaluate an untaken branch.

3 open findings

• Track constant Boolean conditions to preserve branch liveness · New
• Use shared struct-tuple Seq.zip instead of FSharp.Core Seq.zip · New
• Use shared voption functions instead of FSharp.Core option functions · New

2 resolved since last review

• Reject function values hidden behind obj-typed query parameters
• Document CapturedFunctionValue for parameterized functions

🧠 Review effort: Balanced

[Copilot]

🟡 Changes recommended

Slot identity and delegate substitution currently permit value-dependent cache keys and semantic changes.

3 open findings

• Distinct spliced expressions are incorrectly merged · New
• Delegate parameters are missed during binding and substitution · New
• Capture slot reuse changes with runtime values · New

3 resolved since last review

• Track constant Boolean conditions to preserve branch liveness
• Use shared voption functions instead of FSharp.Core option functions
• Use shared struct-tuple Seq.zip instead of FSharp.Core Seq.zip

🧠 Review effort: Balanced

[Copilot]

🟡 Changes recommended

Function subclasses can escape validation, and arbitrary constant equality can make cache keys inconsistent with query text.

2 open findings

• Reject custom subclasses of FSharpFunc as query parameters · New
• Ensure constant cache keys match rendered SQL literals · New

3 resolved since last review

• Distinct spliced expressions are incorrectly merged
• Capture slot reuse changes with runtime values
• Delegate parameters are missed during binding and substitution

🧠 Review effort: Balanced

[Copilot]

🔵 Needs a closer look

The reflection-heavy quotation transformations and cache-key invariants warrant final human review despite extensive tests.

1 open finding

• Clarify that FSharpOption None is excluded from valid constants · New

🧠 Review effort: Balanced

[Copilot]

🟡 Changes recommended

Function-typed null and default expression nodes can bypass parameterizer validation and reach translation.

1 open finding

• Reject null function values before literal classification · New

1 resolved since last review

• Clarify that FSharpOption None is excluded from valid constants

🧠 Review effort: Balanced

[Copilot]

🟡 Changes recommended

Null-represented custom union cases are incorrectly classified as SQL null literals.

1 open finding

• Avoid treating null-valued F# unions as SQL null literals · New

1 resolved since last review

• Reject null function values before literal classification

🧠 Review effort: Balanced

[Copilot]

🟡 Changes recommended

Boolean DefaultValue conditions can cause unreachable branches to be evaluated during parameterization.

1 open finding

• Treat Boolean DefaultValue as constant to eliminate dead branches · New

1 resolved since last review

• Avoid treating null-valued F# unions as SQL null literals

🧠 Review effort: Balanced

[Copilot]

🟡 Changes recommended

Non-finite floating-point values are accepted as Cosmos SQL literals despite not having valid literal syntax.

1 open finding

• Reject non-finite floating-point values as Cosmos SQL literals · New

1 resolved since last review

• Treat Boolean DefaultValue as constant to eliminate dead branches

🧠 Review effort: Balanced