feat(schema): scan context support set table schema

[gripleaf]

Purpose

Add ScanContextBuilder::SetTableSchema so scan operations can reuse a pre-loaded table schema instead of always loading the latest schema from table metadata.

For main branch data table scans, TableScan now parses the provided schema JSON via TableSchema::CreateFromJson(...) and skips SchemaManager::Latest(). If no schema is provided, or the scan targets a non-main branch, the existing latest-schema loading behavior is preserved.

Tests

• cmake --build build --target paimon-core-test
• ctest -R paimon-core-test --output-on-failure

API and Format

This change adds a public API in include/paimon/scan_context.h:

• ScanContextBuilder& SetTableSchema(const std::string& table_schema)

No storage format or protocol changes.

Documentation

This introduces a new scan-side optimization API. Inline API documentation is added in scan_context.h.

Generative AI tooling

Generated-by: OpenAI Codex GPT-5

[lxy-9602]

+1

[lszskye]

Why split out the RefreshReadRangesAfterCleanUp() function?

[gripleaf]

I split out RefreshReadRangesAfterCleanUp() because SetReadSchema() needs a different ordering now:

CleanUp();
reader->SetReadSchema(...);
RefreshReadRangesAfterCleanUp();

The original RefreshReadRanges() always calls CleanUp() internally. If SetReadSchema() called it directly after stopping the prefetch thread, we would either reset schemas before cleanup, which caused the ORC crash, or call CleanUp() twice.

So the split keeps the behavior clear:

RefreshReadRanges()
-> CleanUp()
-> RefreshReadRangesAfterCleanUp()

SetReadSchema()
-> CleanUp()
-> reset reader schemas
-> RefreshReadRangesAfterCleanUp()

This lets us reuse the range-refresh logic while guaranteeing that schema reset happens only after the background prefetch thread has fully stopped.