feat(scan): serve pinned entries through the split_provider machinery via a pinned-serving mode on the format ingestibles (#819 PR2)

[bwyogatama]

Part of #819 (query-time MVCC delta merge for pinned caches) — the serving reorg that PR3 (DELETE masks) and PR4 (INSERT delta) build on. Behavior-identical: no MVCC logic in this PR.

What

Pinned/cached-entry serving moves off its dedicated coalescer-direct path and onto the same split_provider / metadata-task machinery disk scans use. On a pin hit, prepare_for_query switches the operator's format ingestible into pinned-serving mode (gpu_ingestible::serve_from_pinned_chunks, default-false virtual) and the plain, unmodified split_provider fans the resident chunks out as work items on the scan manager's dispatcher threads. The serving tail is now uniform — cached and disk scans both live in _providers_by_op and are driven by start_metadata_processing; the entire databatch_provider / use_cached_entries_for_pipeline / process_cached_entries bypass is deleted.

Pieces

• pinned_chunk_source (op/scan): self-contained chunk inventory built by the scan manager from a matched pinned entry (shared_ptr copies, no reference into the pinned-entries map); lock-free chunk claim + per-chunk resident batch assembly (GPU column wrap stamped with the chunk's memory_space / HOST slice), with per-batch telemetry attribution (Add data_batch telemetry #1068's quent_data_batch_probe) preserved.
• cached_scan_info: the format-neutral resident-split carrier. The sequencer's emit path unwraps it into a resident scan_operator_input and skips the balancer call, so task_creator keeps routing pinned scans by the batch's memory_space (home-GPU / NUMA locality) and the shared round-robin cursor stays untouched for disk pipelines in mixed queries.
• cached_batch_coalescer: pass-through slot coalescer — pinned chunks were already batch-sized at pin time. flush() emits nothing, so a zero-chunk pin still closes its connector with zero splits.
• Format ingestibles: duckdb_native_gpu_ingestible and parquet_gpu_ingestible each gain the override plus three one-line pinned-mode forks in has_processed_all_metadata / next_split_provider / create_batch_coalescer.
• build_pinned_chunk_source validates the entry shape and throws (caught → disk fallback) where the old path silently truncated the scan mid-stream; work-item exceptions now surface as clean query errors (try_t → connector->close(exception)) instead of an unclosed-connector hang.

Why this shape (for #819)

MVCC is DuckDB-specific, so the serving seam is deliberately placed such that all MVCC work lands in duckdb_native_gpu_ingestible's pinned mode in PR3/PR4 — visibility work items on dispatcher threads, a mask-join coalescer variant, and delta splits decoded by its own materialize_metadata_to_table — next to the DuckDB table handles, serial-prep discipline, and decode machinery it needs. The shared pieces (pinned_chunk_source, cached_scan_info, the pass-through coalescer) stay format-neutral and MVCC-free permanently; parquet's pinned mode is trivial forever. This also follows the IO-framework refactor's direction: split_provider stays a concrete class composing gpu_ingestible (no provider subclasses).

Intentional divergences (all edge-case, all strictly better)

• A work-item exception used to be swallowed (connector never closed → query hang, later pipelines starved); it now propagates as a query error.
• A malformed pinned entry (uneven per-column chunk counts, short chunk_memory_spaces, null host chunk) used to truncate the scan silently; it now throws in the builder and falls back to the disk read.
• Chunk emission order within one scan is completion-order instead of index-order (splits are independent tasks; cross-pipeline order is still sequencer-enforced).
• Cached serving is now stop-token-aware during teardown.

Verification

• New [pinned_chunk_source] gates (9 cases, 130 assertions): source claim/assembly with a permuted column subset, per-chunk memory_space preservation, HOST slice, zero-chunk close, builder validation throws, coalescer pass-through/foreign-drop/empty-flush, the unmodified split_provider::run driving pinned work items on pool threads with the end-of-stream sentinel, and an end-to-end pin → SELECT gate asserting the pinned-serving log marker.
• Behavior-identical suites pass unchanged: [pin_table], [pin_table_host], [pin_table_duckdb], [pin_table_duckdb_host], [pin_table_cols_subset], [pin_table_host_streaming] (GPU high-water preserved), [host_serve] (served-from-pin-not-disk proof), merge and column-order regressions, [can_serve].
• Disk-path regressions: [duckdb_native], [overflow_string], [parquet_schema_mapping], [scan][batch_coalescer].

Draft until the multi-GPU gates ([pin_mgpu]) run on a 2-GPU box (this branch was validated on a single-GPU GB10).

🤖 Generated with Claude Code

[bwyogatama]

Closing in favor of keeping dev's coalescer-direct pinned serving (design revision, 2026-07-08).

The MVCC CPU work for #819 (PR3 delete-visibility masks, PR4 insert-delta staging) will instead run as ad-hoc prepare-time tasks on the scan manager's dispatcher — launched from prepare_for_query right after try_assign_cached_entries detects a pin hit, and joined before start_metadata_processing(), so masks are finished buffers before serving begins. At that point the dispatcher is fresh and idle, and it already accepts ad-hoc tasks (spawn_workers precedent) — this reorg bought parallelism the dispatcher offers directly, at the cost of migrating a proven serving path and adding a pinned-serving mode to every format ingestible. A second constraint reinforced the pivot: the coalescer's single serial sequencer can never wait on masks (head-of-line stall across all scan ops), so gating emission at the coalescer stage bought nothing over joining in prepare.

The three cached-path hardening fixes that were entangled in this reorg (silent query hang on provider throw, silent truncation on malformed pinned entries, ignored stop token) land separately as a small PR2-lite against dev — see #819's updated PR ladder.

Design record: #819 (updated). This branch stays frozen as the historical record of the serving-reorg approach.

🤖 Generated with Claude Code