Expose runtime batch message indexes

[Kian Thompson (kian-thompson)]

Description

Runtime messages currently use clientSequenceNumber as an ordering key, but that value does not consistently represent a logical message's position after grouped batches are unpacked. This change introduces an explicit runtime batch index and forwards it through the container runtime, data store runtime, and shared object event layers.

What is changing

• Add the legacy-beta ISequencedRuntimeMessage type with an optional indexInBatch property.
• Populate and preserve indexInBatch for grouped, ungrouped, and singleton runtime batches.
• Expose the new message type through data store and shared object op events, including the fluid-framework legacy surface.
• Update SharedDirectory ordering to prefer indexInBatch, with clientSequenceNumber retained as a compatibility fallback.
• Add focused tests for batch processing, compatibility boundaries, event propagation, and test-runtime mocks.

Rollout plan

indexInBatch remains optional so newer data store packages can operate across older runtime package boundaries. Runtime generation 10 advertises support when available, and all generation 11 runtimes are expected to provide the field. Consumers should temporarily fall back to clientSequenceNumber only when the new field is absent.

After the three-generation compatibility window excludes runtimes without this capability, the feature can become required and the runtime-layer clientSequenceNumber fallback can be removed in an eligible beta-breaking release, no earlier than 3.10.

Reviewer Guidance

The review process is outlined in the pull request guidelines.

The main areas to review are the batch-index assignment in the container runtime, preservation across runtime-layer boundaries, and the compatibility fallback used by SharedDirectory.

[github-actions]

Hi! Thank you for opening this PR. Want me to review it?

Based on the diff (571 lines, 40 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

How this works

• Adjust the reviewer set by ticking/unticking boxes above. Reviewer toggles alone don't trigger anything.

• Tick Start review below to dispatch the review fleet.

• After review finishes, tick Start review again to request another run — it auto-resets after each dispatch.

• This comment updates as new commits land; your reviewer selections are preserved.

• Start review

[github-actions]

🔗 No broken links found! ✅

Your attention to detail is admirable.

linkcheck output

$ start-server-and-test "npm run serve -- --host 127.0.0.1 --no-open" http://127.0.0.1:3000 check-links
1: starting server using command "npm run serve -- --host 127.0.0.1 --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-website@0.0.0 serve
> docusaurus serve --host 127.0.0.1 --no-open

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

> fluid-framework-website@0.0.0 check-links
> linkcheck http://127.0.0.1:3000 --skip-file skipped-urls.txt

Crawling...

Stats:
  658102 links
    3579 destination URLs
    3898 URLs ignored
       0 warnings
       0 errors

[github-actions]

Bundle size comparison

Base commit: 66d337c9fc338cbb3d7db50e0797b9bd62ca7ba7
Head commit: bb61058da64c483488b49f28562ab77df0e5f902

Notable changes

• 🔴 odspClient.js: parsed 606600 → 607203 (+603), gzip 163052 → 163304 (+252)
• 🔴 aqueduct.js: parsed 533117 → 533620 (+503), gzip 143294 → 143444 (+150)

Per-bundle deltas

@fluid-example/bundle-size-tests

• fluidFrameworkAllAlpha.js: parsed 801533 → 801743 (+210), gzip 220527 → 220625 (+98)
• azureClient.js: parsed 634336 → 634823 (+487), gzip 169989 → 170184 (+195)
• 🔴 odspClient.js: parsed 606600 → 607203 (+603), gzip 163052 → 163304 (+252)
• 🔴 aqueduct.js: parsed 533117 → 533620 (+503), gzip 143294 → 143444 (+150)
• fluidFramework.js: parsed 415378 → 415471 (+93), gzip 117810 → 117854 (+44)
• sharedTree.js: parsed 404757 → 404843 (+86), gzip 115252 → 115288 (+36)
• containerRuntime.js: parsed 315027 → 315347 (+320), gzip 86438 → 86530 (+92)
• sharedString.js: parsed 170105 → 170172 (+67), gzip 48455 → 48475 (+20)
• experimentalSharedTree.js: parsed 161846 → 161906 (+60), gzip 46722 → 46737 (+15)
• matrix.js: parsed 153720 → 153787 (+67), gzip 44381 → 44406 (+25)
• loader.js: parsed 147328 → 147344 (+16), gzip 40038 → 40049 (+11)
• odspDriver.js: parsed 106695 → 106753 (+58), gzip 33227 → 33293 (+66)
• directory.js: parsed 65669 → 65772 (+103), gzip 18493 → 18510 (+17)
• 578.js: parsed 58686 → 58686 (0), gzip 17657 → 17657 (0)
• odspPrefetchSnapshot.js: parsed 46463 → 46444 (-19), gzip 15512 → 15522 (+10)
• map.js: parsed 45820 → 45887 (+67), gzip 14120 → 14142 (+22)
• 252.js: parsed 44384 → 44384 (0), gzip 13741 → 13741 (0)
• summarizerDelayLoadedModule.js: parsed 31287 → 31287 (0), gzip 7929 → 7929 (0)
• socketModule.js: parsed 27108 → 27078 (-30), gzip 8069 → 8103 (+34)
• createNewModule.js: parsed 12464 → 12464 (0), gzip 4792 → 4805 (+13)
• summaryModule.js: parsed 3888 → 3888 (0), gzip 1874 → 1874 (0)
• connectionState.js: parsed 909 → 909 (0), gzip 500 → 500 (0)
• sharedTreeAttributes.js: parsed 845 → 852 (+7), gzip 496 → 505 (+9)
• debugAssert.js: parsed 429 → 429 (0), gzip 299 → 299 (0)
• FluidFramework-HashFallback.js: parsed 419 → 419 (0), gzip 313 → 313 (0)