[PUBLIC API BREAKING CHANGE] Fix/properly handle requests that are out of physical data bounds

[blaze6950]

This pull request introduces explicit boundary handling and data availability contracts for the cache system, centered around the new RangeResult<TRange, TData> return type for GetDataAsync. The documentation is updated to explain these changes, and code across the benchmarks and validation projects is refactored to use RangeResult and RangeChunk instead of raw data collections. The cache now gracefully handles partial fulfillment and out-of-bounds requests without exceptions, and the merging logic ensures only contiguous, available data is stored.

Boundary Handling & Data Availability:

• Introduced RangeResult<TRange, TData> as the return type for GetDataAsync, enabling explicit signaling of fulfilled ranges, partial fulfillment, and unavailability (null range). This is documented in the README and invariants with usage examples and rationale. [1] [2] [3]
• Updated documentation and guides to include a new section on boundary handling, partial fulfillment, and bounded data sources, with references to a dedicated guide. [1] [2]

Codebase Refactoring for Boundary Contracts:

• Refactored all benchmark and validation data sources (SlowDataSource, SynchronousDataSource, SimpleDataSource) to return RangeChunk<TRange, TData> instead of IEnumerable<TData>, and updated all usages to access .Data from RangeResult. [1] [2] [3] [4] [5] [6] [7]
• Refactored benchmark code to work with nullable options and updated all cache access patterns to retrieve .Data from RangeResult. [1] [2] [3] [4] [5] [6]

Cache Merging Logic Improvements:

• Enhanced UnionAll in CacheDataExtensionService to filter out segments with null ranges, ensuring cache contiguity and compliance with architectural invariants. Added remarks and diagnostics for unavailable segments. [1] [2]

Miscellaneous:

• Fixed minor issues such as unnecessary using statements and file encoding. [1] [2]

These changes provide a clearer, safer, and more flexible interface for cache consumers, especially when dealing with bounded or partially available data sources.

[Copilot]

Pull request overview

This PR introduces explicit boundary/data-availability semantics for the sliding window cache by making GetDataAsync return a RangeResult<TRange, TData>, and by updating IDataSource to return RangeChunk so bounded sources can signal partial fulfillment or “no data available” without throwing.

Changes:

• Public API breaking change: GetDataAsync now returns ValueTask<RangeResult<TRange, TData>>; IDataSource.FetchAsync now returns RangeChunk<TRange, TData>.
• Cache/user-path and rebalance merge logic updated to handle out-of-bounds/unavailable segments (including diagnostics for unavailable segments).
• Broad refactor of tests/benchmarks/docs to use RangeResult/RangeChunk, plus new integration tests for boundary handling.

Reviewed changes

Copilot reviewed 29 out of 36 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
tests/SlidingWindowCache.Unit.Tests/Public/WindowCacheDisposalTests.cs	Updates test data source + assertions for RangeResult.Data.
tests/SlidingWindowCache.Invariants.Tests/WindowCacheInvariantTests.cs	Refactors invariant tests to use .Data from RangeResult.
tests/SlidingWindowCache.Invariants.Tests/TestInfrastructure/TestHelpers.cs	Updates mocks/helpers to return RangeChunk and unwrap RangeResult.Data.
tests/SlidingWindowCache.Integration.Tests/TestInfrastructure/SpyDataSource.cs	Updates spy data source to return RangeChunk.
tests/SlidingWindowCache.Integration.Tests/TestInfrastructure/BoundedDataSource.cs	Adds bounded test data source that returns null ranges when out-of-bounds.
tests/SlidingWindowCache.Integration.Tests/RebalanceExceptionHandlingTests.cs	Updates faulty data source and assertions for RangeChunk/RangeResult.
tests/SlidingWindowCache.Integration.Tests/RangeSemanticsContractTests.cs	Updates range semantics assertions to use RangeResult.Data.
tests/SlidingWindowCache.Integration.Tests/RandomRangeRobustnessTests.cs	Updates robustness assertions to use RangeResult.Data.
tests/SlidingWindowCache.Integration.Tests/ExecutionStrategySelectionTests.cs	Updates test data source and assertions for new return types.
tests/SlidingWindowCache.Integration.Tests/DataSourceRangePropagationTests.cs	Updates propagation assertions to use RangeResult.Data.
tests/SlidingWindowCache.Integration.Tests/ConcurrencyStabilityTests.cs	Updates concurrency tests to unwrap RangeResult.Data.
tests/SlidingWindowCache.Integration.Tests/CacheDataSourceInteractionTests.cs	Updates interaction tests to unwrap RangeResult.Data.
tests/SlidingWindowCache.Integration.Tests/BoundaryHandlingTests.cs	Adds new integration test suite validating bounded-source behavior.
src/SlidingWindowCache/Public/WindowCache.cs	Changes public interface + facade to return RangeResult and updates docs/error message.
src/SlidingWindowCache/Public/IDataSource.cs	Changes single-range fetch to return RangeChunk; updates batch contract language.
src/SlidingWindowCache/Public/Dto/RangeResult.cs	Adds RangeResult DTO for fulfilled-range + data payload.
src/SlidingWindowCache/Public/Dto/RangeChunk.cs	Updates RangeChunk to allow Range = null for unavailable segments and documents contract.
src/SlidingWindowCache/Public/Configuration/WindowCacheOptions.cs	Minor formatting tweak in validation logic.
src/SlidingWindowCache/Infrastructure/Instrumentation/NoOpDiagnostics.cs	Adds no-op implementation for new diagnostic hook.
src/SlidingWindowCache/Infrastructure/Instrumentation/ICacheDiagnostics.cs	Adds DataSegmentUnavailable() contract for boundary/unavailable segments.
src/SlidingWindowCache/Infrastructure/Instrumentation/EventCounterCacheDiagnostics.cs	Adds counter + implementation for DataSegmentUnavailable.
src/SlidingWindowCache/Infrastructure/Concurrency/AsyncActivityCounter.cs	Minor whitespace-only cleanup.
src/SlidingWindowCache/Core/UserPath/UserRequestHandler.cs	Implements RangeResult return and boundary-aware fetching behavior on user path.
src/SlidingWindowCache/Core/Rebalance/Intent/IntentController.cs	Minor whitespace-only cleanup.
src/SlidingWindowCache/Core/Rebalance/Execution/TaskBasedRebalanceExecutionController.cs	Minor whitespace-only cleanup.
src/SlidingWindowCache/Core/Rebalance/Execution/RebalanceExecutor.cs	Comment indentation/formatting update.
src/SlidingWindowCache/Core/Rebalance/Execution/ChannelBasedRebalanceExecutionController.cs	Minor whitespace-only cleanup.
src/SlidingWindowCache/Core/Rebalance/Execution/CacheDataExtensionService.cs	Updates union logic to skip null-range chunks and emit diagnostics.
src/SlidingWindowCache.WasmValidation/WasmCompilationValidator.cs	Updates validation data source + usage for RangeChunk/RangeResult.
docs/invariants.md	Adds invariant documenting RangeResult boundary semantics.
docs/boundary-handling.md	Adds new guide explaining boundary handling and usage patterns.
benchmarks/SlidingWindowCache.Benchmarks/Infrastructure/SynchronousDataSource.cs	Updates benchmark data source to return RangeChunk.
benchmarks/SlidingWindowCache.Benchmarks/Infrastructure/SlowDataSource.cs	Updates benchmark data source to return RangeChunk.
benchmarks/SlidingWindowCache.Benchmarks/Benchmarks/UserFlowBenchmarks.cs	Updates benchmarks to unwrap RangeResult.Data; nullable options adjustments.
benchmarks/SlidingWindowCache.Benchmarks/Benchmarks/ExecutionStrategyBenchmarks.cs	Minor formatting tweak.
README.md	Updates examples and adds boundary-handling section for new API surface.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 83.01887% with 9 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...ingWindowCache/Core/UserPath/UserRequestHandler.cs	80.55%	5 Missing and 2 partials ⚠️
...re/Instrumentation/EventCounterCacheDiagnostics.cs	66.66%	1 Missing ⚠️
.../Infrastructure/Instrumentation/NoOpDiagnostics.cs	0.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

Copilot reviewed 29 out of 36 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (1)

docs/boundary-handling.md:307

• This doc claims “Test Coverage (15 tests)”, but BoundaryHandlingTests.cs currently contains 10 [Fact] tests. Please update the number and/or the listed categories so the documentation stays accurate.

The cache includes comprehensive boundary handling tests in `BoundaryHandlingTests.cs`:

### Test Coverage (15 tests)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 34 out of 41 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (5)

tests/SlidingWindowCache.Invariants.Tests/WindowCacheInvariantTests.cs:1101

• The documentation comment still references the removed storageName parameter at line 1100. This should be removed to match the actual method signature.
  tests/SlidingWindowCache.Invariants.Tests/WindowCacheInvariantTests.cs:317
• The test data A3_8_TestData includes both storage[0] (storageName) and storage[1] (readMode) at positions 5 and 6 in the yielded array (lines 105-106), but the test method signature removed the scenario and storageName parameters and now only accepts the numeric parameters and readMode. This creates a parameter count mismatch - the test data yields 8 values but the method now expects only 6. This will cause test failures at runtime. Either remove storage[0] from the test data or keep the storageName parameter (even if unused) to maintain the parameter count.
  tests/SlidingWindowCache.Invariants.Tests/WindowCacheInvariantTests.cs:1104
• The test method signature has removed the storageName parameter but the StorageStrategyTestData still provides it at position 0. The test data yields both storage[0] (storageName) and storage[1] (readMode), but the method signature now only accepts readMode. This creates a parameter count mismatch - the test data yields 2 values but the method expects only 1. This will cause test failures at runtime. Either remove storage[0] from the test data or keep the storageName parameter (even if unused).
  tests/SlidingWindowCache.Invariants.Tests/WindowCacheInvariantTests.cs:1135
• The test method signature has removed the storageName parameter but the documentation comment still references it at line 1134. The parameter documentation should be removed to match the actual method signature.
  tests/SlidingWindowCache.Invariants.Tests/WindowCacheInvariantTests.cs:1138
• Same issue as the other test methods - the test method signature has removed the storageName parameter but StorageStrategyTestData still provides it at position 0. This creates a parameter count mismatch that will cause test failures at runtime.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.