refactor: separate cache lifecycle, runtime, and persistence

[tisonkun]

Summary

Separate cache lifecycle, request execution, live L2 state, and persistence into CacheSession, CacheRuntime, RegionStore, and RegionPersistence. Remove the single-implementation RegionBackend trait and the FileRegionRuntime forwarding wrapper, and move modules, methods, fields, and fixtures to match their actual roles.

Split positioned I/O from file ownership and filesystem path operations. DataFileHandles now implements positioned I/O directly. Use RegionDesc and ReadDesc, consistent append/read/write vocabulary, and distinct names for persistent session state and background I/O recovery. Document the resulting ownership and naming boundaries.

Design Notes

• Keep public APIs, configuration, snapshots, persistent encodings, resource bounds, and recovery semantics unchanged relative to main. RUNNING remains durable before workers start; CLEAN remains the final publication after quiescence and a durable image. Unfenced writes retain file ownership.
• Keep fault injection at actual file and filesystem operations, with session fixtures following the production startup path.
• Keep FillController and IoRecovery as independent runtime-owned policies. BackgroundIoAttempt borrows both through observation, recovery, validation, and publication. Flush budgets explicitly count records and byte units separately from observed I/O requests.

Validation: cargo x check, cargo x test (including extended recovery, process-kill, and fill/recovery fence tests), cargo x lint, and cargo check --target x86_64-unknown-linux-gnu --features io-uring --all-targets.

[tisonkun]

@leiysky could you review the ownership boundaries and naming below, especially the lifecycle/persistence split and the I/O interfaces?

This summarizes the final migration against main. Public APIs, configuration, snapshot fields, and on-disk formats remain unchanged.

Main responsibilities

Before	After	Responsibility
RegionStore<B: RegionBackend>	CacheSession	Orders open, recovery, startup, shutdown, and durable state publication.
RegionDataPlane	CacheRuntime	Executes L1/L2 requests and owns I/O engines, staging, and background workers; moved from region/runtime/ to cache/runtime/.
FileRegionCore	RegionStore	Holds the live L2 index, Region manager, append gates, generation checks, and health latch.
FileRegionBackend	RegionPersistence	Owns files and locks, loads recovery state, and persists recovery images.
FileRegionRuntime	Removed	Its wrapper and forwarding responsibilities are absorbed by the concrete types above.
RegionBackend	Removed	There is one concrete Region storage implementation; lifecycle no longer needs a backend protocol.

The old and new RegionStore have different responsibilities: the old lifecycle coordinator becomes CacheSession; the new name replaces FileRegionCore.

flowchart TD
    C[Cache] -->|requests| R[CacheRuntime]
    C -->|close| S[CacheSession]
    S -->|start / shutdown| R
    S -->|recover / persist| P[RegionPersistence]
    R -->|L2 operations| L[RegionStore]
    R --> W[L1 / staging / workers / I/O engines]
    L --> I[RegionIndex]
    L --> M[RegionManager]

Loading

Method ownership

• FileRegionRuntime::install → RegionStore::from_recovery.
• anonymous_runtime / map_clean_runtime → RegionPersistence::cold_regions / recover_regions; these construct L2 state, not a complete runtime.
• start_runtime / attach_data_plane → CacheSession directly calls CacheRuntime::start.
• stop_fast / freeze_warm → CacheSession orders CacheRuntime::shutdown, then, for warm close, RegionStore::freeze → RegionPersistence::persist_frozen → publish_clean.

The barriers remain: durable RUNNING before workers start; durable data and recovery image before CLEAN. An unfenced issued write still prevents CLEAN publication and requires retaining the lock.

I/O and domain names

Before	After	Meaning
IoBackend	PositionedIo	Offset-based reads/writes only.
ControlIoBackend + file-management methods from IoBackend	StorageFile	Adds size, allocation, sync, locking, identity, and handle duplication.
FileBackend / RuntimeFileSet	CacheFile / DataFileHandles	Owned OS file vs. engine handles; the forwarding RuntimeFileBackend wrapper is removed.
RegionFileSystem / SystemRegionFileSystem	FileSystem / OsFileSystem	Path operations, moved to io/fs.rs. Handle duplication moves to StorageFile.
RegionRuntime / ReadDescriptor	RegionDesc / ReadDesc	Descriptive data, rather than execution objects.
RegionMetadataState	RegionState	The same Free/Active/Sealed state applies to live and persisted Regions.
RegionStaging / RegionShard / ShardMutation	AppendStaging / AppendShardGate / AppendShardState	Distinguishes append buffers, synchronization, and mutation state.
RegionSpanFlight / RegionSpanCompletion	PendingWrite / WriteCompletion	Matches PendingRead / ReadCompletion; submit_span becomes submit_write.

The narrow I/O interfaces remain useful for capability boundaries and fault injection.

RecoveryState → SessionState clarifies that EMPTY/RUNNING/CLEAN describes the durable cache open/close lifecycle, not recovery progress. Values and encoding are unchanged; CLEAN remains only a prerequisite for validating a restart image.

Background timeout recovery is separate: BackgroundRecovery → IoRecovery no longer owns fill control. CacheRuntime owns IoRecovery and FillController independently, while RecoveryAttempt → BackgroundIoAttempt borrows both through observation, validation, and publication. wait_with_recovery becomes wait_background.

Fill-control methods now state their actual operation: try_flush / refund_flush → try_acquire_flush_budget / refund_flush_budget. Budget ops / units become records / byte_units, distinguishing record credits from observed I/O request counts. Pacing and recovery policies are preserved.

Suggested review order: cache/session.rs → cache/runtime/mod.rs → region/mod.rs → region/persistence/mod.rs, then io/file.rs and io/background.rs.

[tisonkun]

@leiysky I'm going to merge this PR but you may take a look to avoid concept mismatch or further conflicts.