[xperiandri]

Proposed Changes

Adds docsSrc/Explanations/ADR_0002_EquatableArray.md, an architecture decision record for EquatableArray<'T>: a struct over one ImmutableArray<'T> with value semantics, for fields of records and unions, dictionary and set keys and persisted documents. It decides that the default value is the empty array, that equality and hashing cover all elements with EqualityComparer<'T>.Default (also for C# == and !=), and that comparison is by length first, in the order of F# generic comparison. For elements that are F# arrays, FlatLists or tuples that hold them, equality and comparison disagree on keys; the ADR accepts this explicitly and pins it with regression tests. It also covers O(1) conversion to and from ImmutableArray<'T>, C# collection expressions and ranges through Slice, a System.Text.Json converter, struct active patterns, a module that mirrors FlatList, and delivery in two steps.

Status: Accepted. The maintainers accepted every recommendation of §11 on 2026-10-18, and §11 now records the decisions. Step 1 of §6 is implemented in #28; the ADR now matches what it ships (unsafeOfArray in step 1, the test categories, a C# test project in CI, and the four differences the first consumer notices).

Types of changes

What types of changes does your code introduce to FSharp.Collections.Immutable?
Put an x in the boxes that apply

• 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)

Documentation only: the ADR describes a new type, which #28 adds; this pull request changes no code.

Checklist

Put an x in the boxes that apply. You can also fill these out after creating the PR. If you're unsure about any of them, don't hesitate to ask. We're here to help! This is simply a reminder of what we are going to look for before merging your code.

• Build and tests pass locally (not run for this pull request – it changes one Markdown file; CI builds it)
• I have added tests that prove my fix is effective or that my feature works (not applicable – documentation only)
• I have added necessary documentation (if appropriate)

Further comments

ADR 0002 meets ADR 0001 (#23) in §5 to §7, and the two documents are aligned: the module mirrors the FlatList module of ADR 0001 with its Option and Tuple override modules, the patterns are struct partial patterns in both, element comparison avoids culture-sensitive comparers in both, and the mirror is one link of the ADR 0001 pull request chain.

Facts marked (verified) were checked in dotnet fsi and on a prototype outside the repository. The C# range syntax through Slice was checked with a C# program against an F# struct. The tests of #28 now pin these facts in F# and C#.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

The differing key equivalence under equality and ordering needs an explicit design decision and test coverage plan.

1 open issue

• Align or document differing equality and ordering semantics · New

What changed in this PR

Adds a proposed ADR for EquatableArray<'T>, a value-semantic wrapper alongside FlatList. No library code changes.

Changes:

• Defines equality, ordering, default-value behavior and interop.
• Plans module integration, tests and staged delivery alongside ADR 0001.
• Records seven questions for maintainers.

File	Description
docsSrc/​Explanations/​ADR_0002_EquatableArray.md	Documents the proposed type, contracts and delivery plan.

_{Review effort: Balanced}