chore(v3.0): roadmap

v3.0 — Foundation (all breaking changes)

The hard cut. Every consumer reacts. Ships as a single 3.0.0 (no pre-releases).
Migration is supported by MIGRATION-v3.md; the codemod follows in v3.1.

Calling convention

The dominant break in v3. Every multi-arg function moves to data-first +
options-object: the first positional argument is the primary data, every
subsequent argument folds into a single options object.

Carve-out (functions whose multiple args are all primary data of equal
status — they keep both positional, no options object):
intersection, union, except, symmetricDifference, setEquals,
isSubset, isSuperset, isDisjoint, exists, existsAll, existsAny.

Per-function Options types are exported alongside each rewritten function
(e.g. FindByOptions<T, P>, GroupByOptions<T, P>).

• AGENTS.md amendment (process change; lands first)
• feat!(v3): named options + dot-paths everywhere — sweeping API rewrite across every multi-arg function in collections, numerical, positional, transformations (one PR or split per category)

Dot-paths everywhere

• extract rewritten to take dot-paths via paths: readonly Path[]; result objects keyed by the leaf segment of each path (last path wins on collisions)
• AGENTS.md "Dot-path key access" rule promoted to "all key/path access in the public API"

Typing (Theme C)

• C1 — Hand-rolled Get<T, Path> and Paths<T> in src/shared/types.ts; applied to findBy, where, pluck, keyBy, groupBy, countBy, minBy, maxBy, sumBy, averageBy, uniqueBy, extract
• C2 — flat(values, { depth }) returns FlatArray<T, D>[]

Contract fixes (Theme A)

• A1 — existsAll(_, []) returns true (vacuous truth); fix the source.length === 0 edge case
• A2 — min / max throw TypeError on empty input (align with subtract / product / median / range)
• A3 — Remove compact. Keep compactNullish (drops null/undefined). Add compactFalsy (drops all falsy)

Naming & placement (Theme B)

• B1 — Move hasEvenLength from numerical to positional
• B2 — Rename equals → setEquals
• B4 — Add nth(values, { index }) (negative index = from end). Remove second and third. Keep first and last
• B5 — occurrences returns Map<T, number> instead of [T, number][]

Internals & packaging (Theme D)

• D1 — Delete src/shared/index.ts (dead at the public surface)
• D2 — Route findBy and where through pathResolver (AGENTS.md compliance)
• D4 — Bump tsup target and tsconfig target to es2023
• D5 — Drop the CJS build. Pure ESM only. Remove .d.cts shadows and require exports

Release artifacts

• MIGRATION-v3.md aggregating the per-PR migration sections
• README "Upgrading from v2" pointer
• CHANGELOG.md ## [3.0.0] entry
• chore(release): 3.0.0 PR

Process notes

• v2.x is in patch-only mode for the duration of v3 work
• Every PR in this milestone uses Conventional Commits with !, both
  breaking-change and v3-accepted labels, includes a Migration
  section in the body, and references this issue (Refs #N)
• No published pre-releases. Single 3.0.0 tag at the end
• During v3 development, package.json is 3.0.0-dev from the
  cut-over commit until the release PR