test: record how the emulator evaluates the queries the translator needs

[xperiandri]

Proposed Changes

The planned translation of F# quotations into Cosmos DB SQL (ADR 0001, #34) has rules that depend on how Cosmos DB evaluates certain queries, and the documentation does not settle all of them. For example: can c.v = @p be true for a document where v is missing or null? Does ?? replace null? May a subquery contain TOP? This pull request adds tests that ask the emulator these questions and assert its exact answers. The translator's rules can then be written from facts, and a change in the engine shows up as a failing test.

tests/Cosmos.Tests/QuerySemanticsTests.fs (category QuerySemantics, 22 test methods, 52 cases with their data rows). Each test seeds the documents it needs as raw JSON into its own database, so a property can be missing, null or of another type. It then runs the query in one logical partition through the stream iterator and compares the raw JSON answer. No serializer sits in between, so a member missing from the answer means the engine returned undefined.

The Windows emulator (local) and the Linux vNext emulator (CI and the dev container) answered alike, except where noted:

• Equality. =, != and IN are false or true between different JSON types, null included, and undefined only when the value is missing. So c.v = @p never matches a missing or null value, while NOT (c.v = @p) matches null but not a missing value.
• Ordering. < and >= are undefined between different types and for arrays and objects.
• Coalesce. ?? replaces only a missing value: c.v ?? "default" stays null when v is null.
• Integer division. INTDIV and INTMOD truncate toward zero, like F# / and % on integers. A zero divisor or a fractional operand on either side gives undefined, where F# throws.
• Division by zero. 7 / 0 compares as infinity in a filter. A query that returns it fails with 400, because JSON has no infinity. The Windows emulator reports substatus 4001, the vNext emulator 0.
• Parameters. A parameter works as the ignore-case flag of STRINGEQUALS, CONTAINS, STARTSWITH and ENDSWITH, as the whole filter (WHERE @p0), and as an indexer (c.m[@key], c.arr[@index]).
• STRINGEQUALS is undefined unless both operands are strings.
• Case folding. On ten tricky pairs, the ignore-case flag of the Windows emulator agrees with .NET OrdinalIgnoreCase except for the Greek final sigma: ς against Σ is not equal, while .NET calls them equal. The vNext emulator also equates the dotted capital I, the Kelvin sign and the Angstrom sign with the letters they lowercase to.
• Objects and arrays. Object equality ignores the order of properties; array equality does not.
• Subqueries. TOP, ORDER BY and OFFSET LIMIT are rejected in every subquery (errors SC2203, SC2202 and SC2204). DISTINCT, GROUP BY, nested subqueries, and a filter, aggregate, DISTINCT, TOP, ORDER BY or OFFSET LIMIT outside a FROM subquery all run. A filter outside a GROUP BY subquery stands in for the missing HAVING. An ORDER BY outside a subquery sorts only by paths of the documents, not by a value the subquery computes.
• Sources of IN. The source must be a path or a subquery. kv IN ObjectToArray(c.m) and t IN [1, 2] are syntax errors, while kv IN (SELECT VALUE ObjectToArray(c.m)) and ARRAY_CONTAINS(ObjectToArray(c.m), {"v": 2}, true) work. The ADR's planned translation of a Map lookup used the invalid form; docs: add ADR 0001 for the FSharp.Azure.Cosmos.Quotations architecture #34 corrects it.
• ORDER BY keeps documents without the value, first in ascending order, and orders JSON types as undefined, null, booleans, numbers, strings, arrays, objects.
• ORDER BY over two properties. A composite index (/a ASC, /b ASC) keeps the documents that lack either value: in each key they come first, before null and numbers, and ORDER BY c.a DESC, c.b DESC, the inverse of the index, returns the exact reverse. The Windows emulator refuses ORDER BY c.a, c.b DESC, which no composite index serves, with 400 (does not have a corresponding composite index); the vNext emulator, which has no composite indexes yet, sorts it anyway.
• Spatial functions. With GeoJSON passed as raw JSON parameters, the form planned for captured geometry values, the Windows emulator measures ST_DISTANCE and ST_AREA in metres on the WGS-84 ellipsoid (110 574 m for one degree of latitude at the equator), tests points against a polygon with ST_INTERSECTS, ST_WITHIN and ST_ISVALID, explains an invalid point with ST_ISVALIDDETAILED, and filters stored points with ST_DISTANCE and ST_WITHIN. The vNext emulator fails a spatial function in the projection with 500, This query type isn't supported yet, and answers a spatial filter without documents, so the SDK throws while it reads the page.

The five tests whose answers differ state both. They tell the emulators apart through Emulator.readKindAsync, added to tests/Cosmos.Tests.Infrastructure: the Windows emulator answers an unauthenticated request to its root with 401, the vNext emulator with a success status, which the CI setup of the emulator already relies on.

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)

Tests only; the package is 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

• Windows emulator: Debug 242/242 and Release 242/242 (the 190 tests of main plus the 52 new ones). The vNext emulator in CI runs the same tests. Fantomas is clean.
• The vNext emulator lays out the JSON of its errors with indentation, so a rejection is recognised by its quoted error code alone.
• ADR 0001 (docs: add ADR 0001 for the FSharp.Azure.Cosmos.Quotations architecture #34) records these facts as decision records, with the two rules that change: the re-nesting table of subqueries and the ObjectToArray lowering.

Changes after the review

Every change is folded into the commit it belongs to; the review threads are answered one by one.

• Assertions in Pascal case: the functions of QueryAssert are WantItems, Returns, ReturnsInAnyOrder, RejectsWith, RejectsSaying and Rejects, like the other assertions of the test projects.
• ImmutableArray for the shared test data: the four static collections of documents and geometries are a seq { } piped into ImmutableArray.CreateRange, and the lists written inside the tests are arrays.
• One module per pipeline: |> Seq.sort |> Seq.toArray in place of |> Seq.sort |> Array.ofSeq. The rule itself, for the agent instructions, is docs: add the pipeline harmony rule to the agent instructions #49.
• Sorted test categories: test: sort the test category attributes by name #51 sorted tests/Cosmos.Tests/TestCategories.fs and is merged. The category of this pull request, QuerySemanticsTestCategoryAttribute, is at its sorted place now, between PatchTestCategoryAttribute and ReadExtensionsTestCategoryAttribute, in the commit that adds it.
• The sub-status of the vNext emulator: a report for Azure/azure-cosmos-db-emulator-docker is prepared (x-ms-substatus is 0 where the Windows emulator sends 4001); see the comment below.
• Tests after the changes and the rebase onto main with refactor: return voption and struct tuples from the collection functions #47: 242 of 242 on the Windows emulator, in Debug and in Release.
• After the rebase onto main with test: compare SQL with golden baselines that can be rewritten #46, test: sort the test category attributes by name #51 and chore(deps): update FAKE to 6.1.5 #52 (2026-10-11): the 52 tests of this pull request pass on the Windows emulator in Release; the whole suite was left to CI this time, because the local emulator refused containers under load.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Two stated integer-division and substatus behaviors are not fully asserted by the tests.

1 open finding

• Cover fractional operands for INTDIV and INTMOD undefined cases · New

What changed in this PR

Adds emulator-backed integration tests that establish Cosmos DB query semantics needed by the planned quotation translator.

Changes:

• Adds 36 query-semantics cases across 17 test methods.
• Covers comparisons, operators, parameters, functions, subqueries, and ordering.
• Introduces a dedicated test category.

File	Description
TestCategories.fs	Adds the query-semantics category.
QuerySemanticsTests.fs	Adds emulator query behavior tests and helpers.
FSharp.Azure.Cosmos.Tests.fsproj	Includes the new test file.

🧠 Review effort: Balanced

---

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

[xperiandri]

Division by zero. 7 / 0 compares as infinity in a filter. A query that returns it fails with 400, because JSON has no infinity. The Windows emulator reports substatus 4001, the vNext emulator 0.

Issue to emulator repo

[xperiandri]

Issue to emulator repo

The issue for Azure/azure-cosmos-db-emulator-docker is written and open in your browser as a prefilled "Bug report for vNext Emulator", ready to submit:

vNext emulator: a query whose result cannot be represented in JSON fails with x-ms-substatus 0 instead of 4001

It states what the test here pins: SELECT VALUE {"quotient": 7 / 0} FROM c fails with HTTP 400 on both emulators, the Windows emulator with x-ms-substatus: 4001 and the error code 4001 in the body, the vNext emulator with x-ms-substatus: 0. It names the image digest that CI pulled today and refers to Azure/azure-cosmos-db-emulator-docker#310, where the emulator team confirmed that the service answers such a query with HTTP 400 and the code 4001 as well.

I captured the Windows answer in full for it. I could not capture the body of the vNext answer, only its status, the header and the text that the test asserts.

[xperiandri]

Fix