feat(map): add opt-in sort-key iteration to SharedDirectory

[tylerbutler]

Summary

Adds a replicated, opt-in custom iteration order to SharedDirectory driven by string "sort keys" attached to individual keys and child subdirectories. The existing default iteration order is unchanged.

What's new

API additions on IDirectory / ISharedDirectory:

• setSortKey(key, sortKey | undefined) / setSubDirectorySortKey(name, sortKey | undefined) — set or clear (via undefined) a sort key.
• keysByOrder() / valuesByOrder() / entriesByOrder() — iterate entries in sort-key order.
• subdirectoriesByOrder() — iterate child subdirectories in sort-key order.
• New events sortKeyChanged / subDirectorySortKeyChanged (path-carrying) on ISharedDirectoryEvents; containedSortKeyChanged / containedSubDirectorySortKeyChanged on IDirectoryEvents.

Semantics

Sort-keyed entries iterate first, in lexicographic order of the sort key (JS <, UTF-16 code points). Entries without a sort key follow, in the existing iteration order. Ties on sort key break by the default iteration order — so ordering is deterministic across clients.

Sort keys live alongside the entry they annotate: delete(k) clears the entry's sort key, clear() clears all sort keys in the directory, and deleteSubDirectory(name) clears the child's sort key on the parent.

Replication and back-compat

• Two new ops (setSortKey, setSubDirectorySortKey) are wired through the existing pending/sequenced model with reference-identity ack matching. Rollback, reconnect-resubmit, and applyStashedOp paths are extended symmetrically.
• Snapshot gains optional additive fields sortKeys? / subdirectorySortKeys? on IDirectoryDataObject. The directory snapshot format stays at 0.1 — older readers silently ignore the new fields.
• Adding methods to IDirectory is a forward-compat break; declared in package.json typeValidation.broken. Back-compat is preserved.

Docs and plan

• Full plan and test specification in packages/dds/map/SORT-KEYS-PLAN.md (includes implementation status, deviations from the original design, and a resume-in-fresh-session guide).
• Internal architecture notes in packages/dds/map/ARCHITECTURE.md §9.4 + §11.

Status

47 of 67 planned tests landed in packages/dds/map/src/test/mocha/directory.sortKey.spec.ts. 20 follow-on tests (deferred rollback / snapshot round-trip / fuzz, plus a few edge-case spec entries) are enumerated at the top of SORT-KEYS-PLAN.md for a follow-up PR; all their implementation paths are covered by the landed code.

Draft — API Council review required (surfaces @public @legacy and @beta @legacy types).

[github-actions]

Hey! You look nice today! Want me to review this PR?

Based on the diff (4007 lines, 15 files), I've queued these reviewers:

• Correctness — logic errors, race conditions, lifecycle issues
• Security — vulnerabilities, secret exposure, injection
• API Compatibility — breaking changes, release tags, type design
• Performance — algorithmic regressions, memory leaks
• Testing — coverage gaps, hollow tests

Toggle checkboxes to adjust, then reply yes to start — or ask me anything!

[tylerbutler]

yes

[github-actions]

🔗 No broken links found! ✅

Your attention to detail is admirable.

linkcheck output

> fluid-framework-docs-site@0.0.0 ci:check-links /home/runner/work/FluidFramework/FluidFramework/docs
> start-server-and-test "npm run serve -- --no-open" 3000 check-links

1: starting server using command "npm run serve -- --no-open"
and when url "[ 'http://127.0.0.1:3000' ]" is responding with HTTP status code 200
running tests using command "npm run check-links"


> fluid-framework-docs-site@0.0.0 serve
> docusaurus serve --no-open

[SUCCESS] Serving "build" directory at: http://localhost:3000/

> fluid-framework-docs-site@0.0.0 check-links
> linkcheck http://localhost:3000 --skip-file skipped-urls.txt

Crawling...

Stats:
  287071 links
    1898 destination URLs
    2148 URLs ignored
       0 warnings
       0 errors