[PUBLIC API BREAKING CHANGE] Feature/cache enhancements

[blaze6950]

This pull request introduces several documentation updates and minor code changes to clarify and enhance the usage of the sliding window cache library, particularly around consistency modes, runtime configuration, and layered caching. The README now provides more comprehensive guidance on available consistency options, runtime option updates, data source implementation, and multi-layer cache usage. Minor code changes ensure correct namespace usage in benchmarks.

Documentation improvements:

• Added a new section on consistency modes, detailing eventual, hybrid, and strong consistency options, their guarantees, and usage patterns. The serialized access requirement for hybrid and strong modes is now clearly explained. (README.md, AGENTS.md) [1] [2]
• Expanded guidance on implementing data sources, including examples for unbounded and bounded sources via FuncDataSource and the contract for custom implementations. (README.md)
• Added instructions for updating runtime options at runtime using UpdateRuntimeOptions, including constraints and usage patterns, and how to inspect current runtime options via CurrentRuntimeOptions. (README.md)
• Enhanced multi-layer cache documentation, explaining how to access and update individual layers, recommended configuration patterns, and providing example code. (README.md) [1] [2]

Minor code and reference updates:

• Updated benchmark files to use correct namespaces for cache and configuration types. (ExecutionStrategyBenchmarks.cs, RebalanceFlowBenchmarks.cs, ScenarioBenchmarks.cs, UserFlowBenchmarks.cs) [1] [2] [3] [4]
• Clarified ownership and configuration reading responsibilities for cache and planner components in architecture and actor documentation. (docs/actors.md, docs/architecture.md) [1] [2] [3]

[Copilot]

Pull request overview

This PR evolves the SlidingWindowCache public API to support explicit consistency modes (eventual/hybrid/strong), runtime-updatable cache geometry/timing options, and improved layered-cache ergonomics, alongside large documentation updates to reflect the new API surface.

Changes:

• Introduces runtime option updates (UpdateRuntimeOptions) + inspection (CurrentRuntimeOptions) and the supporting snapshot/builder/validation infrastructure.
• Adds per-request cache efficiency classification (CacheInteraction) to RangeResult and updates user-path logic/tests/docs accordingly.
• Adds new fluent cache builders (WindowCacheBuilder, options builders) and reorganizes public cache types into SlidingWindowCache.Public.Cache, with broad doc/test/benchmark updates.

Reviewed changes

Copilot reviewed 76 out of 76 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
tests/SlidingWindowCache.Unit.Tests/Public/FuncDataSourceTests.cs	Adds unit tests for new FuncDataSource.
tests/SlidingWindowCache.Unit.Tests/Public/Configuration/WindowCacheOptionsTests.cs	Updates equality/hash tests for WindowCacheOptions now being a class.
tests/SlidingWindowCache.Unit.Tests/Public/Configuration/RuntimeOptionsUpdateBuilderTests.cs	Adds tests for runtime update builder merge/validation behavior.
tests/SlidingWindowCache.Unit.Tests/Public/Configuration/RuntimeOptionsSnapshotTests.cs	Adds tests for runtime options snapshot DTO.
tests/SlidingWindowCache.Unit.Tests/Public/Cache/WindowCacheDisposalTests.cs	Updates namespaces/imports after moving cache types.
tests/SlidingWindowCache.Unit.Tests/Public/Cache/WindowCacheDataSourceAdapterTests.cs	Updates RangeResult construction to include CacheInteraction; namespace updates.
tests/SlidingWindowCache.Unit.Tests/Public/Cache/LayeredWindowCacheTests.cs	Adds tests for Layers and runtime option delegation; namespace updates.
tests/SlidingWindowCache.Unit.Tests/Infrastructure/Concurrency/TaskBasedRebalanceExecutionControllerTests.cs	Updates controller construction to use runtime options holder.
tests/SlidingWindowCache.Unit.Tests/Core/State/RuntimeOptionsValidatorTests.cs	Adds tests for shared runtime option validation rules.
tests/SlidingWindowCache.Unit.Tests/Core/State/RuntimeCacheOptionsTests.cs	Adds tests for internal runtime options snapshot type.
tests/SlidingWindowCache.Unit.Tests/Core/State/RuntimeCacheOptionsHolderTests.cs	Adds tests for atomic runtime options publication holder.
tests/SlidingWindowCache.Tests.Infrastructure/Helpers/TestHelpers.cs	Updates imports for moved public cache types.
tests/SlidingWindowCache.Invariants.Tests/WindowCacheInvariantTests.cs	Updates imports for moved types/extensions.
tests/SlidingWindowCache.Integration.Tests/UserPathExceptionHandlingTests.cs	Updates imports for moved cache types.
tests/SlidingWindowCache.Integration.Tests/StrongConsistencyModeTests.cs	Updates to renamed consistency extension type + updated cancellation semantics.
tests/SlidingWindowCache.Integration.Tests/RebalanceExceptionHandlingTests.cs	Updates imports for moved cache types.
tests/SlidingWindowCache.Integration.Tests/RangeSemanticsContractTests.cs	Updates imports for moved cache types.
tests/SlidingWindowCache.Integration.Tests/RandomRangeRobustnessTests.cs	Updates imports for moved cache types.
tests/SlidingWindowCache.Integration.Tests/LayeredCacheIntegrationTests.cs	Migrates layered builder usage to WindowCacheBuilder.Layered(...).
tests/SlidingWindowCache.Integration.Tests/ExecutionStrategySelectionTests.cs	Minor style updates + imports after namespace move.
tests/SlidingWindowCache.Integration.Tests/DataSourceRangePropagationTests.cs	Updates imports for moved cache types.
tests/SlidingWindowCache.Integration.Tests/ConcurrencyStabilityTests.cs	Updates imports for moved cache types.
tests/SlidingWindowCache.Integration.Tests/CacheDataSourceInteractionTests.cs	Updates imports for moved cache types.
tests/SlidingWindowCache.Integration.Tests/BoundaryHandlingTests.cs	Updates imports for moved cache types.
src/SlidingWindowCache/Public/WindowCacheExtensions.cs	Removes old extension class (replaced by new consistency extensions elsewhere).
src/SlidingWindowCache/Public/IWindowCache.cs	Adds runtime update API + current runtime options property.
src/SlidingWindowCache/Public/IDataSource.cs	Updates docs + recommends FuncDataSource.
src/SlidingWindowCache/Public/FuncDataSource.cs	Adds delegate-based data source implementation.
src/SlidingWindowCache/Public/Dto/RangeResult.cs	Adds CacheInteraction to result; makes ctor internal.
src/SlidingWindowCache/Public/Dto/CacheInteraction.cs	Adds new enum describing request fulfillment classification.
src/SlidingWindowCache/Public/Configuration/WindowCacheOptionsBuilder.cs	Adds fluent builder for WindowCacheOptions.
src/SlidingWindowCache/Public/Configuration/WindowCacheOptions.cs	Converts options from record → sealed class; centralizes validation; custom equality.
src/SlidingWindowCache/Public/Configuration/RuntimeOptionsUpdateBuilder.cs	Adds builder for partial runtime updates.
src/SlidingWindowCache/Public/Configuration/RuntimeOptionsSnapshot.cs	Adds public snapshot DTO for runtime-updatable options.
src/SlidingWindowCache/Public/Cache/WindowCacheDataSourceAdapter.cs	Moves adapter into Public.Cache namespace; updates docs.
src/SlidingWindowCache/Public/Cache/WindowCacheBuilder.cs	Adds non-generic entrypoint and fluent builders for cache construction.
src/SlidingWindowCache/Public/Cache/WindowCache.cs	Moves cache into Public.Cache; adds runtime option holder/update/snapshot plumbing.
src/SlidingWindowCache/Public/Cache/LayeredWindowCacheBuilder.cs	Moves to Public.Cache; supports inline options config; builder entrypoint changes.
src/SlidingWindowCache/Public/Cache/LayeredWindowCache.cs	Adds Layers property + runtime option delegation; moves namespace.
src/SlidingWindowCache/Core/UserPath/UserRequestHandler.cs	Sets CacheInteraction on every RangeResult.
src/SlidingWindowCache/Core/State/RuntimeOptionsValidator.cs	Adds shared validation helper for cache sizes/thresholds.
src/SlidingWindowCache/Core/State/RuntimeCacheOptionsHolder.cs	Adds lock-free publication holder for runtime options snapshots.
src/SlidingWindowCache/Core/State/RuntimeCacheOptions.cs	Adds internal runtime options snapshot + projection to public snapshot DTO.
src/SlidingWindowCache/Core/Rebalance/Intent/IntentController.cs	Minor style change (bool → var).
src/SlidingWindowCache/Core/Rebalance/Execution/TaskBasedRebalanceExecutionController.cs	Refactors into shared base pipeline and uses runtime options holder.
src/SlidingWindowCache/Core/Rebalance/Execution/RebalanceExecutionControllerBase.cs	Adds shared execution pipeline + disposal behavior for controllers.
src/SlidingWindowCache/Core/Rebalance/Execution/IRebalanceExecutionController.cs	Updates doc reference after namespace moves.
src/SlidingWindowCache/Core/Rebalance/Execution/ChannelBasedRebalanceExecutionController.cs	Refactors into shared base pipeline and uses runtime options holder.
src/SlidingWindowCache/Core/Rebalance/Execution/CacheDataExtensionService.cs	Minor style update (out bool → out var).
src/SlidingWindowCache/Core/Planning/ProportionalRangePlanner.cs	Switches to runtime options holder for live updates (type changed to class).
src/SlidingWindowCache/Core/Planning/NoRebalanceRangePlanner.cs	Switches to runtime options holder for live updates (type changed to class).
src/SlidingWindowCache.WasmValidation/WasmCompilationValidator.cs	Updates to new builder API + validates new consistency methods compile on WASM.
docs/storage-strategies.md	Updates layered builder usage.
docs/scenarios.md	Documents CacheInteraction in scenario traces.
docs/invariants.md	Adds/updates invariants for cache interaction + runtime options update semantics.
docs/glossary.md	Adds definitions for runtime options + consistency modes + cache interaction.
docs/diagnostics.md	Cross-links diagnostics counters with per-request CacheInteraction.
docs/components/user-path.md	Documents cache interaction classification in user path.
docs/components/public-api.md	Documents new APIs, consistency extensions, and updated layered builder usage.
docs/components/overview.md	Updates component map to include runtime options + execution controller base.
docs/boundary-handling.md	Updates RangeResult shape and semantics.
docs/architecture.md	Adds runtime-updatable option mechanism + consistency mode notes.
docs/actors.md	Updates ownership notes for runtime options holder and planners.
benchmarks/SlidingWindowCache.Benchmarks/Benchmarks/UserFlowBenchmarks.cs	Namespace updates for moved cache types.
benchmarks/SlidingWindowCache.Benchmarks/Benchmarks/ScenarioBenchmarks.cs	Namespace updates for moved cache types.
benchmarks/SlidingWindowCache.Benchmarks/Benchmarks/RebalanceFlowBenchmarks.cs	Namespace updates for moved cache types.
benchmarks/SlidingWindowCache.Benchmarks/Benchmarks/ExecutionStrategyBenchmarks.cs	Namespace updates for moved cache types.
README.md	Major documentation refresh for consistency modes, runtime options, layered caches, data sources.
AGENTS.md	Documents consistency modes + serialized-access requirement.

Comments suppressed due to low confidence (2)

src/SlidingWindowCache/Public/Cache/WindowCache.cs:284

• UpdateRuntimeOptions doesn't validate configure for null. If a caller passes null, this will throw a NullReferenceException at configure(builder) instead of an ArgumentNullException. Add an explicit null check (or ArgumentNullException.ThrowIfNull(configure)) before use to keep public API behavior predictable.
  src/SlidingWindowCache/Public/Configuration/WindowCacheOptions.cs:75
• WindowCacheOptions accepts a debounceDelay but never validates it. Passing a negative delay will succeed at construction time and later crash background rebalance execution when Task.Delay is invoked. Consider validating debounceDelay (when provided) to be non-negative and throwing ArgumentOutOfRangeException early.

---

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

You can also share your feedback on Copilot code review. Take the survey.

[codecov-commenter]

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

Codecov Report

❌ Patch coverage is 94.10188% with 22 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...ance/Execution/RebalanceExecutionControllerBase.cs	84.00%	6 Missing and 2 partials ⚠️
...cution/ChannelBasedRebalanceExecutionController.cs	66.66%	2 Missing and 1 partial ⚠️
...idingWindowCache/Core/State/RuntimeCacheOptions.cs	86.95%	2 Missing and 1 partial ⚠️
src/SlidingWindowCache/Public/Cache/WindowCache.cs	91.42%	2 Missing and 1 partial ⚠️
...Execution/TaskBasedRebalanceExecutionController.cs	77.77%	1 Missing and 1 partial ⚠️
...owCache/Public/Configuration/WindowCacheOptions.cs	90.00%	1 Missing and 1 partial ⚠️
src/SlidingWindowCache/Public/Dto/RangeResult.cs	88.88%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

Copilot reviewed 76 out of 76 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (2)

src/SlidingWindowCache/Public/Cache/WindowCache.cs:284

• UpdateRuntimeOptions should validate configure is non-null and throw ArgumentNullException (with param name configure). As written, passing null will throw a NullReferenceException at configure(builder), which is inconsistent with the rest of the public API's argument validation.
  src/SlidingWindowCache/Public/Cache/LayeredWindowCache.cs:161
• UpdateRuntimeOptions should defensively validate configure is non-null and throw ArgumentNullException. Currently a null delegate would be forwarded to the inner cache, which may surface as a NullReferenceException (and the param name would be lost).

---

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

You can also share your feedback on Copilot code review. Take the survey.