[suxiaogang223]

Purpose

Related issue: #1382 (current-state audit portion; does not close the issue).

C consumers can execute ordinary externally planned splits but cannot invoke the core current-state audit reader. Expose audit planning, schema export and assigned-split execution so a native worker can retain winning delete rows and return rowkind through Arrow without replanning the entire table.

Brief change log

• Add paimon_read_builder_plan_audit, delegating to the core audit planner with the builder's table view, projection, case sensitivity and filters. Do not apply LIMIT pruning.
• Add paimon_table_export_audit_arrow_schema, exporting rowkind, the configured optional sequence number and user fields through the Arrow C Data Interface.
• Add paimon_table_read_to_audit_log_arrow, reusing AuditLogRead for selected complete splits, including a plan imported with the existing DataSplit byte API. Propagate read predicates and resource contexts.
• Prepend audit system fields to the ordinary read's user projection; an empty user projection selects only the system fields. Streams and exported schemas own the data they need after their source handles are freed.

External planners remain responsible for complete audit merge groups, including first-row and deletion-vector overlap boundaries. This binding does not repair a plan that already discarded required files. System-column residual filters and final LIMIT remain with the caller.

Tests

• cargo +1.95.0 test --locked -p paimon-c --lib: 101 passed.
• Four new tests cover retained deletes compared with ordinary reads, optional sequence output, schema/stream ownership after freeing source handles, imported split bytes, system-only projection, split-range saturation, value filters applied after merge, case-insensitive user projection, null arguments, empty tables and ignored LIMIT hints.
• Targeted Clippy passed with -D warnings -A clippy::nonminimal_bool. Strict Clippy's six existing nonminimal-bool errors were reproduced on unmodified main; no source lint suppressions were added.
• Generated the C header with cbindgen 0.29.4, verified the three exports, and checked it with cc -std=c11 -fsyntax-only.
• cargo +1.95.0 fmt --all -- --check and git diff --check: passed.

Local Cargo builds used debug info disabled and incremental compilation disabled. The new persisted-data tests exercise deduplicate primary-key Parquet reads. First-row/DV grouping and other format behavior are delegated to existing core implementations, rather than newly reimplemented or exhaustively retested here. Full workspace and cross-platform CI are not claimed as local validation.

API and Format

Three additive C functions; existing exported structs, signatures and storage formats are unchanged. Returned plans and readers use existing free functions. This is current-state audit output, not an event history or an incremental read API.

Snapshot-interval planning, incremental work-unit transport and Delta/Changelog/Diff execution remain open under #1382. No Java IncrementalSplit compatibility or Diff output equivalence is claimed by this PR.

Documentation

Document current-state planning and reading, external split requirements, output fields, lifetime rules and incremental scope in the C integration guide.

AI assistance: Codex helped develop the implementation, tests, and this description.