[fix](be) Fix Phase 2 no-PCH compilation (compile only) - #67579

### What problem does this PR solve?

Issue Number: None

Related PR: None

Problem Summary: A background hole-fill task can observe spare write capacity before its remote read and find the queue full at final handoff. Add a spare-capacity-only admission mode so this low-priority result is rejected instead of evicting an already queued foreground cache write. Normal submissions retain the existing oldest-queued replacement behavior.

### Release note

None

### Check List (For Author)

- Test: Unit Test
    - ./run-be-ut.sh -j100 --run '--filter=AsyncCacheWriteManagerTest.ReportsOnlyUnusedPendingCapacity:AsyncCacheWriteManagerTest.DropOldestReplacesOnlyOldestQueuedTaskAndKeepsInflightReaderAlive:AsyncCacheWriteManagerTest.SubmitOwnedBlockPreservesBufferIdentity'
- Behavior changed: No
- Does this need documentation: No

### What problem does this PR solve?

Issue Number: None

Related PR: apache#67292

Problem Summary: Query read-ahead can leave partially covered File Cache blocks that need bounded asynchronous completion before entering the cache writer. Add a BE-level manager that merges queued fragments, deduplicates active blocks, evicts the oldest queued block under pressure, fills block-local holes through dedicated remote-read workers, and hands completed buffers to the asynchronous cache writer without another copy. The worker set can grow or shrink at runtime; shrinking waits only for retiring workers to finish their active remote reads. Same-block submissions are detected before allocating another block buffer, and their fragment copies use a task-local lock so unrelated submissions do not hold the BE-wide queue lock behind a memcpy.

### Release note

None

### Check List (For Author)

- Test: Unit Test
    - ./run-be-ut.sh --run '--filter=PartialBlockWritebackManagerTest.*:PartialBlockWritebackOptionsTest.*' -j100
- Behavior changed: No; this commit adds an unwired internal component.
- Does this need documentation: No

### What problem does this PR solve?

Issue Number: None

Related PR: apache#67292

Problem Summary: Background partial-block writeback needs production defaults and a BE-owned lifetime bounded by the File Cache lifecycle. Add validated hole-fill configuration, create the manager after File Cache initialization, and stop it before File Cache teardown. Make hole_fill_workers_per_be mutable so a runtime configuration update resizes the dedicated remote-read workers without rebuilding the manager; allow 1 through 128 workers and keep the default at 32.

### Release note

Support runtime resizing of BE-wide hole-fill workers through hole_fill_workers_per_be.

### Check List (For Author)

- Test: Unit Test
    - ./run-be-ut.sh --run '--filter=PartialBlockWritebackOptionsTest.*' -j100
- Behavior changed: Yes; runtime updates to hole_fill_workers_per_be resize the active hole-fill worker set.
- Does this need documentation: No

### What problem does this PR solve?

Issue Number: None

Related PR: apache#67292

Problem Summary: Query read-ahead produces consumed variable-length buffers that can span complete and partial File Cache blocks. Add RangeCacheWriteback to split each consumed range, submit complete blocks directly to the existing asynchronous write path, and enqueue partial fragments for background hole filling under the same invalidation epoch captured before the remote read starts.

### Release note

None

### Check List (For Author)

- Test: Unit Test
    - ./run-be-ut.sh -j100 --run --filter=RangeCacheWritebackTest.*
- Behavior changed: No; this commit adds an internal writeback router that is not connected to SegmentIterator yet.
- Does this need documentation: No

Issue Number: None

Related PR: apache#67292

Problem Summary: Query read-ahead must publish only buffers that were actually consumed, preserve caller-visible IO statistics, and honor the original cache-write policy. Centralize query read-ahead construction so SegmentIterator and exact row-id readers share the same byte windows, range planner, page-cache probe, scheduler, and writeback setup. Each asynchronous submission owns its statistics and File Cache epoch; the first consumed page publishes the completed range once, while no-write and remote-only requests skip cache writeback.

Enable consumed query read-ahead ranges to populate File Cache when asynchronous cache writeback is enabled.

- Test: Unit Test
    - ./run-be-ut.sh --run --filter=AsyncCachedRemoteFileReaderTest.*:SegmentReadAheadTest.*:SegmentIteratorReadAheadTest.*:ColumnReaderTest.*ReadAhead* -j100
- Behavior changed: Yes; consumed successful query read-ahead ranges now contribute IO statistics and enter cache writeback when policy permits.
- Does this need documentation: Yes; covered by the read-ahead and hole-fill design document.

### What problem does this PR solve?

Issue Number: None

Related PR: apache#67292

Problem Summary: Short-circuit point queries read row-store data or missing column-store values through exact row IDs. Cold data pages previously followed the synchronous reader one page or column at a time. Create one request-scoped range-read context, initialize the row-store or all missing-column iterators against the shared read-ahead reader, submit the required data pages before decoding, and retain the existing row-cache and result-padding behavior. Read-ahead initialization or IO failure falls back to the original reader. Include the reusable row-id page preparation helpers, SegmentReadAhead exact-row entry point, and its tests in this point-query component. TopN second-stage integration remains unchanged from master and is outside this PR series.

### Release note

Use query range read-ahead for point-query data pages when enable_query_read_ahead is enabled.

### Check List (For Author)

- Test: Unit Test
    - ./run-be-ut.sh --run --filter=SegmentReadAheadTest.*:RowCacheTest.*:LookupConnectionCacheTest.* -j100
- Behavior changed: Yes; point-query data-page reads use the range read-ahead path when the feature is enabled.
- Does this need documentation: Yes; covered by the read-ahead and hole-fill design document.

# Conflicts:
#	be/src/service/point_query_executor.cpp
#	be/src/storage/tablet/base_tablet.h

# Please enter the commit message for your changes. Lines starting
# with '#' will be kept; you may remove them yourself if you want to.
# An empty message aborts the commit.
#
# interactive rebase in progress; onto 3dc7341
# Last commands done (19 commands done):
#    pick b9396d9 # [feature](be) Connect read-ahead range writeback
#    pick 7ccfb97 # [feature](be) Extend range read-ahead to point queries
# Next commands to do (21 remaining commands):
#    pick 9a6bcd5 # [fix](be) Scope filesystem error-code imports to their functions
#    pick 06c0770 # [improvement](be) Add page read-ahead and hole-fill observability
# You are currently rebasing branch 'fix/phase2-no-pch-build' on '3dc73418a07'.
#
# Changes to be committed:
#	modified:   be/src/service/point_query_executor.cpp
#	new file:   be/src/storage/segment/rowid_read_ahead.cpp
#	new file:   be/src/storage/segment/rowid_read_ahead.h
#	modified:   be/src/storage/segment/segment_read_ahead.cpp
#	modified:   be/src/storage/segment/segment_read_ahead.h
#	modified:   be/src/storage/tablet/base_tablet.cpp
#	modified:   be/src/storage/tablet/base_tablet.h
#	modified:   be/test/storage/segment/segment_read_ahead_test.cpp
#
# Untracked files:
#	.codex
#

### What problem does this PR solve?

Issue Number: None

Related PR: apache#67292

Problem Summary: With ENABLE_PCH=OFF and unity builds enabled, the IO unity translation unit includes err_utils.cpp before file_meta_cache.cpp. The namespace-scope ErrorCode using-directive then makes LIMIT_REACH ambiguous when the latter includes the generated protobuf enum. Move the using-directive into the two localfs_error overloads that need it, preserving the existing error-code mappings while preventing it from affecting sibling source files.

### Release note

None

### Check List (For Author)

- Test: Manual test. Reproduced the original ENABLE_PCH=OFF compile failure with ./build.sh --be -j100; build-support/clang-format.sh, build-support/check-format.sh, build-support/check-build-hygiene.sh, and git diff --check passed. Post-fix BE compilation is tracked in the compilation-only Draft PR.
- Behavior changed: No
- Does this need documentation: No

### What problem does this PR solve?

Issue Number: apache#67611 (tracking; keep open)

Related PR: apache#67292

Problem Summary: Page read-ahead, IO coalescing and partial-block writeback lack query-level attribution and BE-wide capacity and IO signals. Add named RuntimeProfile counters for planning, compressed candidate and cache-hit bytes, submission outcomes, source IO, page consumption and foreground writeback. Distinguish Query/BE budget rejection and executor rejection from failures of accepted reads, and account queued cancellations only for accepted tasks. Add successful-source and BE cumulative IO/consumption bytes so asynchronous tail work remains observable after the final Profile snapshot without delaying query completion. Record synchronous data-page fallback attempts, requested bytes and time at PageIO, including decode retries while excluding Page Cache hits and index/dictionary reads. Add aggregate hole-fill failure/read-time metrics and keep detailed failure causes in logs. Use COUNTER_UPDATE and scoped timers, with statistics owned independently of the reporting profile so outstanding reads can finish safely. Append point-query statistics to the existing sampled diagnostic log.

### Release note

Expose PageReadAhead query profile counters and BE-wide metrics for read-ahead IO, data-page fallback, buffer capacity and background cache-block hole filling.

### Check List (For Author)

- Test: Unit Test
    - 131 targeted ASAN tests from 18 suites passed via run-be-ut.sh -j100 with PCH enabled, as recorded in the original accounting commit.
    - clang-format 16, check-format, build hygiene and git diff --check passed before squashing.
    - The historical results above predate removal of TopN-specific collection; current branch validation is recorded in apache#67611.
- Behavior changed: Yes (observability only; read scheduling, cancellation, fallback and writeback policies are unchanged)
- Does this need documentation: Yes (doris-io/phase2_page_prefetch_and_io_coalescing/observability.md)

### What problem does this PR solve?

Issue Number: apache#67611 (tracking; keep open)

Related PR: apache#67292

Problem Summary: Consuming a read-ahead range served from File Cache could enqueue partial-block writeback and reread the rest of an already cached block from remote storage. Downloaded blocks were only detected later by the cache writer, after the redundant remote reads. Skip range writeback for local/inflight hits and combine inflight-buffer lookup with the existing cache probe to deduplicate blocks already cached or being filled. Perform the combined check before partial-block admission and once when a worker starts the task, outside the hole-fill queue mutex. Execute the planned hole reads without per-GET probes. Preserve existing queues, concurrency, active-task fragment handling, and final cache-writer deduplication and invalidation checks.

### Release note

Avoid redundant remote hole-fill reads for blocks already cached or being filled.

### Check List (For Author)

- Test: Unit Test
    - 105 targeted ASAN tests from 9 suites passed through run-be-ut.sh -j100 with PCH enabled on the same final source tree before squashing, including cached/downloading blocks, EOF, empty cells, queued and active completion races, inflight fast-path locking, mixed cached/uncached ranges, and local-hit read-ahead consumption.
    - clang-format 16, check-format, build hygiene, and git diff --check passed before squashing.
    - No cluster or regression workload was run. Clang-tidy was not run as requested.
- Behavior changed: Yes (skip redundant best-effort writeback and hole-fill IO; query results and scheduling limits are unchanged)
- Does this need documentation: No (cache-reuse fix with no configuration changes)

### What problem does this PR solve?

Issue Number: apache#67611 (tracking)

Related PR: apache#67292, apache#67579

Problem Summary: Column read-ahead uses paired high and low byte watermarks to decide when to extend its window. Pending-byte accounting also changes after Page Cache hits and rejected submissions, even when the scan has not advanced. Replace the watermarks with one compressed-byte window size per column role and a trigger page position. Each window uses its second selected page as the trigger, or its only page for a one-page window. First access and a jump beyond planned coverage establish a window through the same path. Process current-batch pages in scan order so a batch crossing the trigger can append the following window in the same plan. Keep mandatory current-batch pages, cache probing, IO coalescing, asynchronous reads, and writeback on their existing paths.

### Release note

Replace the eager/lazy high and low watermark settings with read_ahead_eager_window_bytes (4 MiB) and read_ahead_lazy_window_bytes (128 KiB). Query page read-ahead advances by scan position and retains its existing query and BE buffer budgets.

### Check List (For Author)

- Test: Unit Test — 132 targeted ASAN tests, including 24 ColumnReadAhead cases and related scanner, rowid/TopN, range IO, and cache-reader tests; clang-format 16, build hygiene, and git diff --check passed. No cluster or regression workload was run.
- Behavior changed: Yes — page-position triggers replace pending-byte watermarks; first access and large jumps share the same window initialization.
- Does this need documentation: Yes — configuration and component interface comments are updated in this commit.

### What problem does this PR solve?

Issue Number: apache#67611 (tracking)

Related PR: apache#67579, apache#67292

Problem Summary: Each hole-fill worker issued the source reads for a cache block sequentially. Keep block workers responsible for planning and writeback. Read a single hole range directly on its block worker and execute multiple disjoint ranges in a separate shared HoleFillRemoteReadPool. Each block worker reuses one concurrent ThreadPoolToken for multi-range blocks, joining accepted reads before either submitting the completed buffer or dropping the block. Destroy the token before signalling worker completion so the remote-read pool can be released safely. Preserve queued reads during shutdown and allow the remote-read pool to resize without interrupting active GETs. Make the shared S3 reader statistics atomic for concurrent foreground and background reads. Initialize both hole-fill and asynchronous cache-write worker pools with their configured worker counts as the minimum, and retain at least one remote-read pool thread.

### Release note

Partial File Cache blocks can fetch hole ranges concurrently. The new mutable BE setting hole_fill_remote_read_threads_per_be defaults to 64 and controls the shared pool for multi-range hole reads. Single-range hole reads execute directly on block workers, outside this pool's concurrency limit.

### Check List (For Author)

- Test: Unit Test — 62 existing BE unit tests passed through run-be-ut.sh with ASAN, PCH and -j100, covering AsyncCacheWriteManagerTest, PartialBlockWritebackManagerTest and PartialBlockWritebackOptionsTest. The follow-up refinements adapt existing cases without adding new tests. clang-format v16, check-format, build hygiene and git diff --check passed.
- Behavior changed: Yes — remote reads within one partial cache block can execute concurrently, and failed blocks are released after their accepted reads finish. Single-range hole reads execute directly on block workers. Worker pools start with nonzero minimum thread counts.
- Does this need documentation: Yes — the new BE setting and execution/lifecycle contracts are documented in code comments.

### What problem does this PR solve?

Issue Number: apache#67611 (tracking)

Related PR: apache#67579, apache#67292

Problem Summary: A partial block can become active immediately after its first fragment arrives, leaving little opportunity to absorb subsequent foreground fragments before planning remote hole reads. Keep tasks mergeable in the existing queue for a configurable minimum interval measured from successful admission. Later fragments preserve that timestamp. Workers skip tasks whose delay has not elapsed and wait on the existing condition variable until the earliest deadline or cache-writer capacity retry. Assert that a finite wakeup deadline has been selected before entering the timed wait. Runtime updates apply to queued tasks and wake workers without affecting active reads. Preserve complete-block direct writeback, queued-task eviction, cache invalidation checks, shutdown, and existing worker and remote-read concurrency.

### Release note

Add mutable BE configuration hole_fill_merge_delay_ms, defaulting to 10 ms. When partial-block writeback is enabled, this setting gives queued blocks a short interval to merge foreground fragments before hole filling. Set it to 0 to disable the delay. Changing it affects existing queued tasks; merging another fragment does not restart the interval.

### Check List (For Author)

- Test: Unit Test — 77 existing tests passed through run-be-ut.sh with ASAN, PCH, and -j100, covering AsyncCacheWriteManagerTest, PartialBlockWritebackManagerTest, PartialBlockWritebackOptionsTest, HoleFillPlannerTest, RangeCacheWritebackTest, and RangeWritebackDispatcherTest. Extended existing cases for minimum delay, stable admission deadlines, dynamic updates, active-task isolation, eviction, and shutdown. clang-format v16, check-format, build hygiene, and git diff --check passed. The subsequent DCHECK/comment-only addition passed formatting and static path review; build and unit tests were not rerun for that addition. No cluster tests or clang-tidy were run.
- Behavior changed: Yes — queued partial blocks wait for the configured aggregation interval before becoming active; complete-block writeback and active tasks keep their existing behavior.
- Does this need documentation: Yes — the new configuration and queue timing contract are documented in code comments.

### What problem does this PR solve?

Issue Number: apache#67611 (tracking)

Related PR: apache#67579

Problem Summary: ReadAheadPlanTime starts in SegmentReadAhead::apply_plans after physical-column preparation. It therefore omits initialization, request validation, per-row page lookup and window maintenance, including work that produces an empty plan. Add elapsed-time counters for physical-column preparation, its initialization and validation stage, window discard, current-batch planning and nested window extension. Collect the inner durations per column call and report them before empty plans are dropped. Keep the existing range-planning timer unchanged for comparison with earlier profiles. Timers are scoped to column calls and window operations rather than individual row lookups. No read-ahead, IO coalescing, cache writeback or hole-fill decisions change.

### Release note

Add ReadAheadColumnPlanTime and nested initialization, window-discard, current-batch and window-extension elapsed timers under PageReadAhead in query profiles. Parent timers include their children; the existing ReadAheadPlanTime retains its range-planning and submission scope. No configuration or bvar metrics change.

### Check List (For Author)

- Test: Unit Test — 50 tests from 5 suites passed through run-be-ut.sh with ASAN and -j100, covering ReadAheadMetricsTest, ColumnReadAheadTest, SegmentReadAheadTest, SegmentIteratorReadAheadTest and the relevant ColumnReaderTest cases. Extended existing tests for timer hierarchy, delta reporting, reused plan outputs and empty-plan accounting. clang-format v16, check-format, build hygiene and git diff --check passed. No cluster tests or clang-tidy were run.
- Behavior changed: No — timing collection and Profile output only.
- Does this need documentation: No — timer boundaries and nesting are documented inline and represented in the Profile hierarchy.

### What problem does this PR solve?

Issue Number: apache#67611 (tracking)

Related PR: apache#67579

Problem Summary: The SSB Flat SF1000 planning-delay0 comparison attributed 5,242.6 seconds of accumulated column-planning elapsed time to the current-rowid loop excluding window extension, or 91.6% of column planning. Each scanner batch repeatedly validates rowids, locates the same physical pages for every row, and walks the existing window for every column. Window extension itself accounted for only 6.7 seconds. These are accumulated elapsed counters, not query wall time or thread CPU time.

Build each scan column's candidate-page sequence once after segment pruning and submit the initial eager/lazy windows together. Advance subsequent windows directly from the ordinal page index at the data-page read entry, including Page Cache hits and sparse seeks. Retain high-page predictions while reverse scanners read an ascending batch. Keep point reads and dependent nested-column reads on the exact-rowid path, grouping rows by page. Reuse already buffered physical pages when column windows advance independently. Keep IO coalescing, cache-block completion, hole filling and all existing configuration defaults unchanged. Report page advancement separately through ReadAheadPageAdvanceTime; initialization includes candidate selection, while window-discard and window-extension counters remain sub-timers. This change has not yet been benchmarked on the SSB cluster.

### Release note

Reduce query read-ahead planning work by preparing candidate pages once and advancing windows on data-page reads. Add ReadAheadPageAdvanceTime to the query Profile; ReadAheadWindowExtendTime is now a shared sub-timer under ReadAheadColumnPlanTime rather than a child of current-batch planning.

### Check List (For Author)

- Test: Unit Test — 190 tests from 10 suites passed through run-be-ut.sh with ASAN and -j100, covering complete ColumnReaderTest, column/segment read-ahead, metrics, IO coalescing, range planning, asynchronous read scheduling, range writeback and hole filling. Added dense-scan, sparse/reverse progression, Page Cache, admission fallback and independent-window buffer-reuse coverage. clang-format v16, check-format, build hygiene and git diff --check passed. No cluster tests or clang-tidy were run.
- Behavior changed: Yes — common scans plan once after pruning and advance on physical page reads instead of planning every rowid batch. Query results and synchronous fallback semantics are preserved.
- Does this need documentation: Yes — the scan planning flow and Profile timer scope need a follow-up synchronization in the design repository.

### What problem does this PR solve?

Issue Number: apache#67611 (tracking)

Related PR: apache#67579, apache#67292, apache#67612

Problem Summary: Plan reset and timing aggregation, asynchronous read result construction and terminal-state checks, and partial-block request validation were implemented outside the objects whose state they describe. Move these operations to ColumnReadAheadPlan, FileRangeReadSubmitResult, FileRangeRead, and PartialBlockWritebackRequest. Keep partial-block buffer creation and remote reads on Task, while the manager retains queue admission, worker scheduling, and lifecycle accounting. Preserve vector capacity during plan reset, per-call statistics, lock boundaries, and the join of accepted remote reads before task cleanup.

### Release note

None

### Check List (For Author)

- Test: Unit Test — 198 tests from 11 suites passed through run-be-ut.sh with ASAN and -j100. Added plan-reset capacity/ownership, empty-plan timing aggregation, and rejected-result coverage. Existing read-ahead, scheduler, cache-writeback and hole-fill tests passed, including concurrent reads, failed submission/read cleanup, and shutdown. clang-format v16, check-format, build hygiene, and git diff --check passed. No cluster tests or clang-tidy were run.
- Behavior changed: No — move object-local operations without changing read-ahead, IO, or writeback mechanisms.
- Does this need documentation: No — internal responsibility cleanup; configuration and metric meanings are unchanged.

### What problem does this PR solve?

Issue Number: apache#67611 (tracking)

Related PR: apache#67292, apache#67579

Problem Summary: Adjust the opt-in read-ahead and hole-fill defaults together: use a 1 MiB lazy-column window, a 1.0 background hole-fill amplification limit, a 1 GiB BE-wide pending partial-block budget, and zero deliberate fragment-aggregation delay. Align PartialBlockWritebackOptions and the existing production-default test with the registered settings. Keep planning, queueing, concurrency, validators, and configuration mutability unchanged.

### Release note

For query read-ahead, which remains disabled by default, set read_ahead_lazy_window_bytes to 1048576 (1 MiB), hole_fill_max_read_amplification_ratio to 1.0, hole_fill_max_pending_bytes_per_be to 1073741824 (1 GiB), and hole_fill_merge_delay_ms to 0.

### Check List (For Author)

- Test: Unit Test
    - 75 existing tests from 5 focused ASAN/PCH read-ahead and hole-fill suites passed via run-be-ut.sh -j100; no new tests.
    - clang-format 16 formatting/check, BE build hygiene, and git diff --check.
- Behavior changed: Yes; adjust four defaults for opt-in read-ahead and hole filling without changing the mechanisms.
- Does this need documentation: Yes; synchronize configuration values and commit mappings in apache#67292, apache#67579, and apache#67611.

### What problem does this PR solve?

Issue Number: apache#67611 (tracking; this diagnostic does not complete the feature)

Related PR: apache#67579

Problem Summary: Aggregate S3 and hole-fill byte counters cannot establish whether foreground reads and background hole filling fetched the same object intervals. Add disabled-by-default, bounded JSON tracing at actual S3 GETs and the read-ahead consumption / partial-block lifecycle boundaries. Carry stable range/task identities and source labels through IOContext, and take read-only cache/inflight coverage snapshots before whole-range misses. Provide an offline interval-sweep analyzer that counts extra successful transfers once, distinguishes within-source and cross-source overlap, links representative GETs to late fragments, and checks capture continuity and S3 byte reconciliation. Keep IO planning, merging, admission, concurrency and writeback decisions unchanged. No cluster or benchmark is run by this change.

### Release note

Add mutable BE settings enable_read_io_trace=false and read_io_trace_max_events=1000000 for temporary S3/read-ahead/hole-fill diagnostics. The diagnostic logs can affect timing when enabled and are intended for isolated captures, not performance comparisons. See tools/read_io_trace/README.md for capture and analysis instructions.

### Check List (For Author)

- Test: Unit Test
    - 73 targeted ASAN/PCH BE tests from 6 suites passed through run-be-ut.sh -j100.
    - 9 offline analyzer tests passed, including interval-union arithmetic, triple reads, source/query isolation, temporal examples, missing logs and reconciliation failure.
    - Repository clang-format 16, formatting check, BE header hygiene and git diff --check passed.
    - No cluster, external object storage workload, performance benchmark or clang-tidy run.
- Behavior changed: Yes; opt-in diagnostic logging and coverage probes only. Read and writeback mechanisms are unchanged.
- Does this need documentation: Yes; tools/read_io_trace/README.md is included in this commit.

### What problem does this PR solve?

Issue Number: None

Related PR: apache#67579

Problem Summary: Read-overlap diagnostics currently put every event in be.INFO and stop recording after a process-wide event limit, mixing diagnostic records with operational logs and truncating complete workload captures. Append serialized records to an owned memory batch and let a lazy background writer flush it to dedicated JSONL files by byte threshold or interval. Remove the event limit without adding queue-capacity limits or backpressure. Drain submitted records during normal and fast BE shutdown. Add flush checkpoints and pending-byte visibility so the offline analyzer can check complete captures and reported file errors.

### Release note

Opt-in read IO diagnostics now use read_io_trace_dir (default: the BE log directory's read_io_trace subdirectory). read_io_trace_max_events is removed. New startup settings read_io_trace_flush_bytes and read_io_trace_flush_interval_ms default to 1 MiB and 1000 ms. enable_read_io_trace remains dynamically switchable and disabled by default.

### Check List (For Author)

- Test: Unit Test
    - Incremental ASAN/PCH run-be-ut.sh -j100: 81 tests from 8 suites passed, including dedicated-file batching, interval flushing, concurrent producers, shutdown and actual file-error recovery.
    - Offline analyzer: 12 Python unit tests passed.
    - clang-format 16, BE header hygiene and git diff --check passed. No cluster workload or clang-tidy run.
- Behavior changed: Yes; enabled diagnostic events go to batched standalone JSONL files instead of be.INFO, without a cumulative event limit. Read-ahead and hole-fill mechanisms are unchanged.
- Does this need documentation: Yes; tools/read_io_trace/README.md is updated in this commit.

### What problem does this PR solve?

Issue Number: None

Related PR: apache#67579

Problem Summary: A longer hole-fill fragment aggregation window reduced duplicate foreground/background reads in the q4.1 experiment, but foreground writeback submission time increased. The existing Profile and interval trace cannot distinguish shared queue mutex contention from cache probes, buffer allocation, fragment merging, copies or diagnostic recording. Add complete/partial dispatch Profile timers and opt-in typed timing records for foreground submissions and locked worker scans. Serialize scan summaries outside the queue mutex and keep condition-variable sleeps outside scan timings. Extend the offline analyzer with stage totals, percentiles, queue-depth groups and slow examples, preserving process scope for scans shared by queries. Read, merge, admission and persistence decisions remain unchanged.

### Release note

The existing enable_read_io_trace switch now also records writeback submission stages and hole-fill queue scans in the dedicated JSONL trace. Two lightweight Profile timers separate complete-block and partial-block submission even with tracing disabled. The doris_read_io_trace_record_time_ns counter measures diagnostic serialization and memory-append overhead. No new settings or default changes.

### Check List (For Author)

- Test: Unit Test
    - Incremental ASAN/PCH run-be-ut.sh -j100: 87 tests from 9 suites passed.
    - Python offline analyzer: 15 tests passed.
    - Repository clang-format 16, check-format, BE header hygiene and git diff --check passed.
    - No cluster, external-object-store benchmark or clang-tidy run.
- Behavior changed: Yes, additional diagnostic output and Profile counters; IO and queue mechanisms unchanged.
- Does this need documentation: Yes, capture boundaries, timing interpretation and comparison workflow are documented in tools/read_io_trace/README.md in this commit.

### What problem does this PR solve?

Issue Number: None

Related PR: apache#67579

Problem Summary: With a 2000 ms hole-fill merge window, the archived q4.1 trace measured 389.63 s of cumulative foreground queue-mutex wait and 78.40 s of locked worker scans; 99.984% of examined tasks had not reached their merge deadline. Workers repeatedly probed every delayed task under the same mutex needed by foreground fragment submission. Keep the existing list ordered by admission time, moving stale-epoch replacements to the tail with a fresh merge window. Check the deadline before epoch/inflight probes and stop at the first delayed entry. A fully delayed queue now requires one examined entry per scan, verified with 1024 queued tasks. Continue past capacity-blocked due tasks so another cache writer can make progress. Preserve runtime delay updates, worker concurrency, fragment merging and hole-read planning. Workload latency gains have not been measured after this change.

### Release note

Reduce foreground writeback contention when hole-fill fragment aggregation uses a delay, without adding configuration or changing its defaults.

### Check List (For Author)

- Test: Unit Test
    - Incremental ASAN/PCH run-be-ut.sh -j100: 107 tests from 9 suites passed.
    - Coverage includes a 1024-task delayed queue, stale-epoch replacement order and renewed delay, runtime delay changes, cross-writer capacity bypass, active merges, eviction and shutdown.
    - Python trace analyzer: 15 tests passed.
    - Repository clang-format 16, check-format, BE header hygiene and git diff --check passed.
    - No cluster, external-object-store benchmark or clang-tidy run.
- Behavior changed: Yes, delayed tasks are no longer repeatedly scanned or probed; stale replacements join the queue tail. Due-task checks, memory bounds, shutdown cleanup and concurrency limits remain in place.
- Does this need documentation: Yes, visited-entry semantics are documented in tools/read_io_trace/README.md in this commit.

### What problem does this PR solve?

Issue Number: None

Related PR: apache#67579

Problem Summary: The archived q4.1 deadline-scan run removed queue-lock contention but still recorded 1,053,030 scans for about 34,479 activated blocks with 32 workers; 1,018,551 scans encountered an unexpired head. Multiple workers independently waited for the same deadline. Introduce one HoleFillDispatch thread for deadline and capacity decisions and keep block workers dedicated to execution with reusable remote-read tokens. Bound dispatched plus executing tasks by worker count, transfer queue nodes with splice, and suppress notifications that cannot advance the current wait. Preserve queued fragment merging, dynamic resizing and cross-writer capacity bypass, and cancel undelivered tasks at shutdown. No post-change workload speedup is claimed.

Remove the offline tools/read_io_trace analyzer and its tests from this feature; retain the BE-side trace capture and diagnostic settings.

### Release note

Use a single hole-fill dispatcher to avoid redundant deadline wakeups while preserving configured read concurrency and queued fragment aggregation. No new configuration or default changes.

### Check List (For Author)

- Test: Unit Test
    - Pre-change incremental ASAN/PCH run-be-ut.sh -j100: 110 tests from 9 suites passed.
    - Coverage includes 32 workers with 1024 delayed tasks, full 32-way execution with overflow merging, idle and active resizing, handoff cancellation, epoch replacement, cache-writer capacity, eviction and remote reads.
    - Repository clang-format 16, check-format, BE header hygiene and git diff --check passed.
    - No cluster, external-object-store benchmark or clang-tidy run.
- Behavior changed: Yes, one dispatcher owns timing and hands off at most the configured worker slots; queued and undelivered tasks are cancelled at shutdown.
- Does this need documentation: Yes, dispatcher architecture and BE tracing are described in the active PRs.

### What problem does this PR solve?

Issue Number: Part of apache#67611

Related PR: apache#67292, apache#67579

Problem Summary: Partial-block writeback should collect foreground fragments
for 2000 ms by default and allow 4 GiB of pending buffers per BE. Default
foreground range planning should introduce no gap or partial-block completion
bytes, so set its amplification ratio and block-fill coverage to 1.0.

Keep the existing 1 MiB lazy window, 4 MiB eager window, 1.0 hole-fill
amplification ratio, 32 hole-fill workers and 64 remote read threads. Align
PartialBlockWritebackOptions with the configured merge delay and retain explicit
zero-delay scheduling in the existing immediate-writeback test fixture.
No scheduling or IO algorithm changes.

### Release note

When query read-ahead and partial-block writeback are enabled, the default
merge delay is 2000 ms and pending-buffer budget is 4 GiB per BE. Foreground
range merging and block completion default to a 1.0 amplification ratio and
1.0 minimum coverage respectively. Query read-ahead remains disabled by default.

### Check List (For Author)

- Test: ASAN BE unit tests via run-be-ut.sh -j100; 121 tests from 9 suites passed.
    - Formatting, build hygiene and git diff --check passed.
- Behavior changed: Yes, the four configurable defaults above.
- Does this need documentation: Yes, synchronize the related PR descriptions and tracking issue.

### What problem does this PR solve?

Issue Number: Part of apache#67611

Related PR: apache#67579, apache#67292

Problem Summary: The P0 regression aborts in MapFileColumnIterator::next_batch when a nested STRUCT/MAP lazy read leaves one child pruned. A skipped child retains its old ordinal while the active sibling seeks to the required items; the newly added prefetch assertion incorrectly requires their ordinals to match, even with query read-ahead disabled. Restrict the new read-ahead path to top-level scalar columns, remove complex-column preparation and dependent-item hooks, and restore the upstream ARRAY/MAP/STRUCT read implementations. Select the reader per column and retain the original segment prefetchers for complex columns. Point-query preparation likewise leaves complex iterators on Segment's existing path. Add coverage for divergent nested MAP ordinals, mixed scalar/complex scan routing, and complex point-query preparation.

### Release note

Keep ARRAY/MAP/STRUCT on the existing read path when query read-ahead is enabled and prevent an abort during nested lazy materialization.

### Check List (For Author)

- Test: Unit Test — 134 tests from 4 suites passed on the integrated apache#67579 tree with ./run-be-ut.sh -j100 --run (ASAN/PCH, no clean). Repository clang-format 16, header hygiene and git diff --check passed. No cluster or clang-tidy run.
- Behavior changed: Yes — only top-level scalar columns use the new page read-ahead; legacy complex-column prefetch and common IO/writeback mechanisms are preserved.
- Does this need documentation: Yes — scope and synchronization are recorded in apache#67611 and the related PR descriptions.

### What problem does this PR solve?

Issue Number: Part of apache#67611

Related PR: apache#67292

Problem Summary: Read-ahead fetches with NO_WRITE and depends on asynchronous writeback after consumption. Enabling it without the asynchronous cache writer silently prevents cold data pages from filling File Cache. Gate both scan and point-query read-ahead on the async-write switch so this configuration retains synchronous cache filling.

### Release note

Query read-ahead takes effect only when asynchronous File Cache writes are also enabled.

### Check List (For Author)

- Test: Unit Test added for the disabled-writer combination and synchronous cold-read cache reuse; run as part of the repair-series validation.
- Behavior changed: Yes, read-ahead remains inactive while asynchronous File Cache writes are disabled.
- Does this need documentation: Yes, dependency is recorded in the PR description.

### What problem does this PR solve?

Issue Number: Part of apache#67611

Related PR: apache#67292

Problem Summary: A delayed hole-fill task retained the inner remote reader, while destruction of its CachedRemoteFileReader wrapper closed that same inner reader. Later reads failed on HDFS and could abort DCHECK-enabled S3 builds. Use an aliasing shared_ptr whose pointer is the remote reader and whose owner is the cached wrapper, retaining that owner through each background task.

### Release note

Keep background cache hole-fill readers open until their tasks finish.

### Check List (For Author)

- Test: Unit Test added for submitting a delayed fragment, releasing the wrapper and writeback context, and completing cache fill; run as part of the repair-series validation.
- Behavior changed: Yes, queued hole fills retain their cached reader's lifetime.
- Does this need documentation: No, internal lifetime correction.

### What problem does this PR solve?

Issue Number: apache#67611

Related PR: apache#67292

Problem Summary: A point request can pass the read-ahead enable check and then observe either mutable feature switch disabled while loading its segment. The row-store helper asserted that the factory still returned a read-ahead object, aborting the BE. Reuse the already loaded segment and the original synchronous column iterator when the factory returns no object. A deterministic test closes each switch between segment loading and factory creation, reproduces SIGABRT before the fix, and verifies identical row-store bytes after the fix.

### Release note

Prevent BE aborts when query read-ahead or asynchronous File Cache writes are disabled during row-store point queries.

### Check List (For Author)

- Test: ASAN/PCH BE unit test PointQueryReadAheadTest.RowStoreFallsBackWhenReadAheadSwitchChanges passed; the same test reproduced SIGABRT before the fix. Build hygiene and clang-format 16 passed.
- Behavior changed: Yes; a runtime switch change falls back to the original reader.
- Does this need documentation: No; preserve the existing dynamic switch contract.

# Conflicts:
#	be/test/service/point_query_exector_test.cpp

# Please enter the commit message for your changes. Lines starting
# with '#' will be kept; you may remove them yourself if you want to.
# An empty message aborts the commit.
#
# interactive rebase in progress; onto 3dc7341
# Last commands done (39 commands done):
#    pick 47d9e5e # [fix](be) Keep cached readers alive during background hole filling
#    pick 60f0f2e # [fix](be) Fall back when row-store read-ahead is disabled
# Next command to do (1 remaining command):
#    pick 1d9b406 # [improvement](be) Admit read-ahead ranges within remaining byte budgets
# You are currently rebasing branch 'fix/phase2-no-pch-build' on '3dc73418a07'.
#
# Changes to be committed:
#	modified:   be/src/storage/tablet/base_tablet.cpp
#	modified:   be/test/service/point_query_exector_test.cpp
#
# Untracked files:
#	.codex
#

### What problem does this PR solve?

Issue Number: apache#67611

Related PR: apache#67292

Problem Summary: A wide scan submits the initial windows of all columns together. Whole-batch byte admission rejected every range when their aggregate size exceeded a query or BE budget, discarding useful concurrency even when many ranges could fit. Admit ranges in input order with one linear pass under both budget locks, skip ranges that do not fit, and allocate only admitted buffers. Return null handles at skipped input positions so the existing planner mapping remains intact. Segment coordination registers admitted page slices and completes skipped pages for synchronous fallback. Preserve per-buffer reservation lifetime, allocation rollback, executor failures, and cancellation. Count partially budget-rejected batches without double-counting an executor rejection; configuration defaults, windows, coalescing, and hole filling are unchanged.

### Release note

Retain partial read-ahead concurrency when a planned range batch exceeds its query or BE byte budget.

### Check List (For Author)

- Test: ASAN/PCH BE unit tests through ./run-be-ut.sh --run -j100: 141 tests from 8 suites passed. Coverage includes partial query/BE admission, oversized ranges followed by smaller ranges, original page offsets, consumed-range callbacks, cancellation during allocation, allocation rollback, and executor rejection accounting. Clang-format 16, header hygiene and git diff --check passed.
- Behavior changed: Yes; ranges that fit remain asynchronous while skipped ranges use the original synchronous path.
- Does this need documentation: Yes; update the component behavior in the existing PR and tracking descriptions.

### What problem does this PR solve?

Issue Number: None

Related PR: apache#67292, apache#67579

Problem Summary: File Cache initialization rejects an S3 upload buffer size that is smaller than a cache block or not a multiple of the block size. The buffer size is mutable, but runtime updates did not register the same validation, so a later update could violate the layout assumed by cached reads and hole-fill deduplication. Register the existing alignment constraint as a config validator and cover accepted updates, rejected updates with value rollback, invalid block sizes, and File Cache disabled behavior. Cache probing, read-ahead, and hole-fill algorithms remain unchanged.

### Release note

Reject S3 upload buffer configuration updates that violate File Cache block alignment while File Cache is enabled.

### Check List (For Author)

- Test: Unit Test — 66 tests from 4 suites pass with ./run-be-ut.sh --run -j100 (ASAN/PCH), including configuration validation and partial-block/async cache writeback. Direct Release/PCH BE build passes with ./build.sh --be -j100. Clang-format 16, build hygiene, and diff checks pass. No cluster or clang-tidy run.
- Behavior changed: Yes — invalid runtime S3 upload buffer updates return INVALID_ARGUMENT and retain the previous value; defaults and IO mechanisms are unchanged.
- Does this need documentation: No — applies the existing File Cache startup constraint to runtime configuration updates.

### What problem does this PR solve?

Issue Number: None

Related PR: apache#67292, apache#67579

Problem Summary: Older binaries could persist non-aligned File Cache blocks after a runtime S3 upload-buffer update. These intervals survive cache reopening even after the buffer setting is corrected. Partial-block writeback deduplication used a grid-only cache probe, so encountering a restored irregular interval could abort the BE. Check coverage using the actual cached intervals, accepting contiguous DOWNLOADED or DOWNLOADING blocks without allocating cache cells or changing LRU state. Keep the inflight shortcut and the existing grid probe unchanged.

### Release note

Avoid a BE abort during partial-block writeback when File Cache restores historical non-aligned blocks.

### Check List (For Author)

- Test: The restored-cache regression test reproduced SIGABRT before the fix. All 92 related tests in 5 suites passed with run-be-ut.sh --run -j100 (ASAN/PCH), including restored irregular cache gaps and mixed downloaded/downloading coverage. A direct Release/PCH BE build passed with build.sh --be -j100. Clang-format 16, build hygiene and git diff --check passed. No cluster or clang-tidy run.
- Behavior changed: Yes. Optional writeback deduplication supports actual cached block boundaries, including restored irregular blocks.
- Does this need documentation: No. The PR descriptions record this compatibility fix; public configuration semantics are unchanged.