docs: add ADR 0001 for the per-collection module rewrite

[xperiandri]

Proposed Changes

Adds docsSrc/Explanations/ADR_0001_Collection_Modules.md, an architecture decision record for rewriting the collection modules before any code lands.

It decides:

• one folder per collection, with root modules and .fsi signature files;
• new FrozenMap/FrozenSet modules, with the alternate lookup on net10.0;
• a nested FlatList.Parallel module;
• voption results and struct tuples by default, with Option/Tuple override namespaces;
• comparers only through one struct per map (CustomComparers*) and per set (CustomComparer*), which the modules create with forComparers/forKeyComparer/forComparer;
• map functions that take bindings in every shape: creation through overloads for KeyValuePairs, reference tuples and struct tuples; addRange/setItems over KeyValuePairs with Tuple/ValueTuple submodules;
• test categories on the test classes only.

It also fixes:

• a category-based function order, checked by a script;
• an implementation that uses the BCL and System.Linq first and keeps the FSharp.Core semantics of exceptions and sort stability;
• contract test suites shared between collections;
• delivery as one pull request per collection.

The appendices are the function-by-collection support matrices for sequence-like collections, maps and sets. fsdocs publishes the page next to Background.

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 breaking changes that the following pull requests will make, but this one 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

The matrices are the contract every following pull request implements, so wrong cells are cheapest to fix here.

The fixes for both Copilot reviews are folded into the commits that introduced the text:

• the Option namespace is defined by representation, with the exact FSharp.Core signature only where FSharp.Core has the function; the Tuple namespace holds every function whose signature mentions a struct tuple;
• FlatList ranges copy, because ImmutableArray.Slice allocates unless the range is empty or whole; IndexedList ranges cost time and memory in proportion to their length, because ImmutableList.GetRange builds a new tree;
• every Stack constructor pushes from the end, because the BCL Create/CreateRange leave the last element on top;
• sort stability follows the mirrored FSharp.Core module (FlatList unstable like Array.sort*, the others stable through LINQ OrderBy), all sorts using F# structural comparison;
• each function throws what the FSharp.Core function of the mirrored module throws for the same input, with a measured table and the deliberate deviations;
• transformations keep each comparer whose type does not change, and map and choose give the result the default comparer of the new type;
• the alternate lookup section states why F#-declared wrappers cannot take ReadOnlySpan<char> (F# consumes, but cannot declare, allows ref struct).

Each point was checked at runtime against System.Collections.Immutable 10.0.8 and FSharp.Core 10.

Three later commits redesign parts after the review of #30.

• e49a394:
  • D2: root modules, and a types file per folder, because a root module cannot declare a type of its namespace.
  • D12: the comparer structs.
  • D13: the static extension overloads of map creation.
• d81372c: D8 puts the test categories on the test classes only, as the instructions on main now say.
• 4c822eb:
  • D12: the structs are named CustomComparers* (maps) and CustomComparer* (sets), and the modules create them with forComparers/forKeyComparer/forComparer.
  • D13: addRange/setItems take KeyValuePairs, with Tuple/ValueTuple submodules for reference and struct tuples.
  • D2: the types file is XTypes.fs without a signature file. A signature file alone fails with FS0240.

A prototype with F# 10 checked these points:

• overload resolution through the type abbreviation, including pipelines;
• that a module function of the same name hides the extension members;
• FS0816: curried members cannot be overloaded;
• FS0340: a member cannot constrain the type parameters of the extended type, so the sorted map extensions declare their own;
• that the Tuple/ValueTuple submodules resolve after open FSharp.Collections.Immutable.Tuple;
• that a types file without a signature file works.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Several documented contracts conflict with underlying collection behavior, and the ADR is future-dated.

4 open findings

• Separate representation conventions from exact FSharp.Core signatures · New
• ImmutableArray ranges cannot provide shared backing storage · New
• Span stack construction reverses the promised top-item order · New
• Stability guarantee conflicts with unstable Array.sortWith delegation · New

What changed in this PR

Adds ADR 0001 to define the planned per-collection module rewrite.

Changes:

• Defines API, layout, implementation, and testing decisions.
• Introduces Frozen collection support and value-type defaults.
• Documents per-collection support matrices and delivery plan.

File	Description
docsSrc/​Explanations/​ADR_0001_Collection_Modules.md	Adds the architectural decision record and API matrices.

🧠 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

Exception and comparer contracts need clarification before they guide implementation and shared tests.

4 open issues

• Specify operation-specific validation and exception behavior · New
• Clarify comparer handling for type-changing map and choose · New
• Correct ImmutableList.GetRange complexity and allocation documentation · New
• Remove tuple conversion entries for unfold and tryUncons · New

4 resolved since last review

• Stability guarantee conflicts with unstable Array.sortWith delegation
• Span stack construction reverses the promised top-item order
• ImmutableArray ranges cannot provide shared backing storage
• Separate representation conventions from exact FSharp.Core signatures

_{Review effort: Balanced}