feat: add FSharp.Azure.Cosmos.Sql with EquatableArray and the ImmutableArray patterns

[xperiandri]

Proposed Changes

This is the first part of #42, split off as asked there: the project FSharp.Azure.Cosmos.Sql with nothing but the two collection helpers that the syntax tree of the Cosmos DB SQL model (ADR 0001, #34) is built from, so that they can be reviewed on their own. #42 now builds on this branch and adds the syntax tree, the printer, the function catalog and the validator.

• EquatableArray<'T> (src/Cosmos.Sql/EquatableArray.fs) is an immutable array whose equality compares the elements. ImmutableArray<'T> cannot hold the children of a syntax node: its own Equals compares the reference of the array it wraps. Two separately built nodes with equal children would then be equal only under the comparers that go through IStructuralEquatable, such as the equality F# generates for records and unions, and unequal inside a struct tuple, in a HashSet with the default comparer or for a C# caller. EquatableArray is a struct over an ImmutableArray with element-wise equality and a combined hash code; its default value behaves as an empty array and equals one. The EquatableArray module creates and maps the arrays: empty, ofImmutableArray, ofArray, unsafeOfArray, ofSeq, singleton, toImmutableArray, map. ofArray copies the array; unsafeOfArray wraps it without a copy, as ImmutableCollectionsMarshal.AsImmutableArray does, for a caller that gives the array away and never writes to it again. Two implicit conversions (op_Implicit), to and from ImmutableArray<'T>, wrap and unwrap without copying, so either type can be given where the other is expected. F# applies them without a warning only at method arguments; in a union case, a record field, an annotated binding or an argument of a let-bound function it applies them with warning FS3391, so F# code there keeps calling ofImmutableArray and toImmutableArray. C# applies them everywhere.
• Arr0, Arr1, Arr2, Arr3, ArrN (src/Cosmos.Sql/ImmutableArrayPatterns.fs) are active patterns that match an ImmutableArray by its length, so that code over the children of a node reads like a list pattern without converting to an F# list. Each one returns a struct value option, or a bool, and its payload is a struct tuple, so a match allocates nothing.

The rest is the frame for these two files: the library project, the emulator-free MSTest project tests/Cosmos.Sql.Tests, the entries in the solution and the solution filter, and the solution tree of the agent instructions.

The library is not packed yet: IsPackable is false. A push to main publishes every packable project to GitHub Packages, and the two collection types alone are no package. #42 removes the setting in the commit that gives the package its metadata.

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)

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: 15, category Collections, no emulator, in a file for the struct (EquatableArrayTests.fs), one for the module (EquatableArrayModuleTests.fs) and one for the patterns (ImmutableArrayPatternsTests.fs): equality and hashing, the default value, equality under the default comparer, in a struct tuple and in a HashSet, the read-only list view, the functions of the module, the implicit conversions (that they do not copy, and that a default array becomes an empty one in both directions), ToString, and the patterns for every length including a default array.
• Moved to feat: add FSharp.Azure.Cosmos.Sql, a syntax tree, printer, validator and function catalog for Cosmos DB SQL #42: the two tests that compare whole syntax trees were part of EquatableArrayTests; they need the tree, so they are SyntaxTests there.
• Review of feat: add FSharp.Azure.Cosmos.Sql, a syntax tree, printer, validator and function catalog for Cosmos DB SQL #42 applied here too: a documentation comment without tags is plain /// lines, and the test categories are sorted by name.
• Verification: dotnet build FSharp.Azure.Cosmos.slnx in Debug and Release, 15 of 15 tests in both, Fantomas clean, the documentation builds with --strict, and dotnet pack produces no package for the project.
• Review of 2026-10-11: the hash set is asserted with Assert.Contains, which asks the set itself and so still goes through the hash code; the tests are split into the three files above; unsafeOfArray is added, and the tests create their arrays with it, except the test that checks that ofArray and ofSeq copy.
• Review (Copilot, 2026-10-11): the hash code test no longer asks unequal arrays to hash differently, which a hash code does not promise. It checks that every element is asked for its hash code once, first to last.
• No changelog entry: nothing ships until feat: add FSharp.Azure.Cosmos.Sql, a syntax tree, printer, validator and function catalog for Cosmos DB SQL #42.

🤖 Generated with Claude Code

[Copilot]

🟢 Approval recommended

The focused implementation, documentation, project integration, and tests are consistent and complete.

0 open findings

What changed in this PR

Introduces the foundational collection helpers and project structure for the forthcoming Cosmos SQL model.

Changes:

• Adds structurally equatable immutable arrays and allocation-free ImmutableArray active patterns.
• Adds comprehensive emulator-free MSTest coverage.
• Registers the new library and test projects in the solution.

File	Description
.github/​copilot-instructions.md	Documents the new project structure.
FSharp.Azure.Cosmos.slnf	Adds projects to the solution filter.
FSharp.Azure.Cosmos.slnx	Adds projects to the solution.
src/​Cosmos.Sql/​AssemblyInfo.fs	Defines generated assembly metadata.
src/​Cosmos.Sql/​EquatableArray.fs	Implements structural immutable arrays.
src/​Cosmos.Sql/​FSharp.Azure.Cosmos.Sql.fsproj	Configures the non-packable library.
src/​Cosmos.Sql/​ImmutableArrayPatterns.fs	Adds length-based active patterns.
tests/​Cosmos.Sql.Tests/​EquatableArrayTests.fs	Tests collections and patterns.
tests/​Cosmos.Sql.Tests/​FSharp.Azure.Cosmos.Sql.Tests.fsproj	Configures the unit-test project.
tests/​Cosmos.Sql.Tests/​TestCategories.fs	Defines the collections test category.
tests/​Cosmos.Sql.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

The hash-code tests incorrectly require unequal values to produce distinct randomized hash codes, making them potentially nondeterministic.

1 open finding

• Avoid asserting distinct hash codes for unequal values · New

🧠 Review effort: Balanced