[JingsongLi]

Purpose

Allow PyPaimon's existing file-scanner API to use Rust Core rather than constructing a Python executor. Preserve the separation between raw manifest metadata and query results.

Brief change log

• Add no-argument TableScan::plan_files() and FileScanPlan for complete manifest entries and the selected snapshot ID. File metadata planning precedes projection, LIMIT, row selection, global-index refinement and split distribution.
• Use the existing snapshot/time-travel selection and share incremental AUTO event-source selection with row planning. Keep merged ADD/DELETE entries, historical schema statistics, data-evolution column files and Blob metadata.
• Authorize all columns before reading metadata, require an unrestricted whole-table grant and recheck REST table identity after planning, including empty results.
• Configure independent level-zero and pending-bucket policies once with with_file_filters; both plan() and plan_files() use the explicit configuration. Unconfigured queries retain their current defaults; unconfigured raw file plans include L0 and pending buckets, matching the lower-level Java FileStoreScan. Explicit L0 reads keep overlapping primary-key versions together through split packing and sharding.
• Rename the complete split-planning method to plan_all() across Core, bindings and callers. It returns a split Plan; plan_files() returns complete manifest entries. Predicates, LIMIT and authorization behavior stay unchanged.
• Expose typed file plans and existing ManifestEntry values through the Python bindings. No custom Python manifest-source or follow-up-scanner callback is added.

Review follow-up

• Reuse merge-safe statistics pruning in raw file planning. Skipping L0 alone does not make per-file value statistics safe for overlapping deduplicate, partial-update or aggregation inputs. Keep the effective raw policy available so FirstRow's default raw scan and materialized-file pruning retain their proper behavior.
• Make plan_all() remove only L0 exclusion while preserving independently configured real/pending-bucket policies. Keep explicit false overrides and with_scan_all_files().plan_files() composition consistent, with the existing split-packing behavior.
• Added red/green regressions with real KV writes, old L2/new L1 inputs, FirstRow policies, pending buckets and explicit overrides. Independent follow-up review found no remaining actionable regressions.

Tests

• Final review regressions: 33 distinct Rust tests passed (snapshot suite 18, file-scan suite 5 with 2 overlapping tests, timestamp suite 7, REST suite 4 and binding suite 1).

• API rename follow-up: 5 passed, 0 failed, covering L0 policies, 11 mutation paths, REST authorization, all DE column files and the renamed Python binding (including LIMIT preservation).

• Rust 1.98.0 targeted runtime tests: 16 passed, 0 failed.

  • Core raw file metadata planning: 3 passed.
  • Explicit L0 key merging and sharding for FirstRow and deletion-vector deduplication, including pending buckets: 1 passed.
  • Incremental timestamp scans: 7 passed.
  • REST raw file planning and writer authorization: 4 passed.
  • Python binding typed metadata transport and independent policies: 1 passed.

• cargo +1.98.0 clippy --locked --all-targets --workspace --features fulltext,vortex -- -D warnings: passed.

• cargo +1.98.0 fmt --all -- --check and git diff --check: passed.

• No Native Python extension was built or installed for these tests.

API and Format

Adds TableScan::plan_files, TableScan::with_file_filters, FileScanPlan and corresponding Python bindings. No storage-format change or new configuration option.

Documentation

Rust API documentation and Python type stubs describe the file-planning and authorization boundary. PyPaimon's integration is in apache/paimon#10742.

[leaves12138]

LGTM